Docs · Internals
How an agent that spawns agents stays inside its limits
A session opened by an agent, such as a sub-agent or a delegated task, gets a bound and revocable token, and an envelope that can only narrow what its parent may do.
What it does
Each agent session receives a signed token scoped to that session, with a permission ceiling and a tool profile. The token works only while it is registered, and closing the session revokes it.
Some routes are reserved to a human (configuration, providers, roles, model policy, permission answers), and an agent gets no WebSocket.
A child session can never be more permissive than its parent: same project and workspace, directories inside the parent, depth 1, at most 4 live children.
The diagram
Drag to move. Pinch, Ctrl + wheel or the + and - keys to zoom; arrow keys to move; 0 to fit; double-click to fit. Select a node to light up its links.
Text description of the diagram
Flow diagram in three parts. First, a session token is minted with a signed scope, registered in an in-memory allow-list and revoked when the session closes. Second, every request carrying an agent token is checked in order: the token must still be registered or the answer is 401; the WebSocket ticket route is refused with 403; human-only mutations are refused with 403; routes behind tools that the profile withholds are refused with tool_not_in_profile. Third, the caller is identified from the signed token, then the envelope of the child is checked: depth, number of live children, permission ceiling, directories, project and workspace, and finally the permission mode, which can only be narrowed. The child session is created and records its parent.
Guided reading
Step 1. Mint
At launch the backend signs a token whose scope names the session, its permission ceiling and its tool profile, with a unique identifier.
Step 2. Register
The identifier goes into an in-memory allow-list. A new token for a session replaces the previous ones, and a token minted before a restart is unknown, so it is refused.
Step 3. Check every request
Is the identifier still registered? If not, 401. Is it the WebSocket ticket route? 403: an agent gets no socket. Is it a human-only mutation other than a read? 403. Does the route sit behind a tool the profile withholds? 403 tool_not_in_profile.
Step 4. Profiles are allow-lists
The restricted profile is a list of allowed tools. In REST the default is to refuse: only the route prefixes of allowed tools are open, and the test suite fails if a route is left unclassified. The vault routes are closed to it. Providers other than Claude Code always get the restricted profile.
Step 5. Who is asking?
The parent comes from the signed token, and the X-Session-Id header is ignored. An agent token with no session is refused (envelope_unbound_token). Any other token is a human, with no envelope. Only when authentication is off does the header name the parent, as a hint and not as a boundary.
Step 6. The envelope
In order: is the parent already a child (envelope_depth_exceeded), are 4 children already alive (envelope_too_many_children), the ceiling is the lower of the live mode and the signed ceiling, the directories must sit inside the parent, the project and workspace must match, and the permission mode is the requested one restricted by the ceiling (plan, default, acceptEdits, auto, bypassPermissions, from least to most permissive).
Step 7. Delegation and reach
Delegating a task asks for bypassPermissions but is clamped by the ceiling: a session in ask mode cannot delegate to a bypass child. An agent can only write to sessions it spawned itself.
Step 8. Native sub-agents
The native engine offers its Agent tool only to a local native session that was not itself spawned. An Agent call runs as a child session under the envelope above, and that child is a depth-1 session to which AskUserQuestion is denied: it cannot ask you a question. An ACP agent has no sub-agents.
Why it is built this way
Signed, not asserted
The parent and the ceiling come from the signed token, not from something the caller says. A header would be a claim, a signature is evidence.
Revocation is immediate
An allow-list entry disappears when the session closes. A token that merely expires would stay usable until its deadline.
Narrowing only
Every check can only reduce what the child may do. There is no path where spawning widens permissions.
New tools are closed by default
Because the restricted profile is an allow-list and routes are refused unless classified, a tool added tomorrow is withheld until someone decides to open it.
What is not established
- Not established: there is no end-to-end test with a real CLI; the rules are tested on their functions and on the middleware. A child budget equal to the rest of the parent, cascading cancellation and the cost of descendants are not written yet.
Public sources
Where to check each statement, in the public repositories.