Skip to main content
An Agent can delegate work to subagents. It can expose a subagent to the Client as a child session: a session with its own sessionId that the Agent creates and owns. The child’s messages, thoughts, plans, tool calls, and state arrive as ordinary session/update notifications with the child’s sessionId, so the Client can show them apart from the parent session. Exposing subagents is optional for Agents. An Agent can use subagents without exposing them and report their results through the parent session. Subagents need no capability. Every Client MUST: A Client can choose not to show a dedicated subagent view. It cannot ignore subagent_update as an unknown update.

Announcing a child session

The Agent announces a child with a subagent_update on the parent session. The outer sessionId names the parent, and update.sessionId names the child:
The first subagent_update for a child sessionId announces that the parent created and owns the child. Later updates for the same child patch its fields. They do not create another child or move the child to another parent. The Agent MUST send the announcing subagent_update before any request or notification that carries the child’s sessionId. This covers:
  • session/update notifications for the child
  • a session_message that names the child as sender or recipient
  • a session content item that references the child
  • a background list that names the child
  • session/request_permission and elicitation/create requests for the child
The rule also applies to short-lived work. A Client SDK may buffer traffic for a child it does not know yet, but that does not release the Agent from the rule.
SessionId
required
The child session’s ID. It is unique on the connection and identifies the same child across repeated delegations. The Agent MUST NOT reuse it for an unrelated session.
string
The parent’s display label for the child. It need not be unique. If none is set, the Client chooses a fallback.
string
The parent’s description of the child’s role or purpose. It is current display text, not a record of the instructions sent to the child.
SubagentSessionCapabilities
What the Client may send for this child. cancel is the only capability defined. See Restricted methods.
StateUpdate
The child’s foreground state, mirrored from the child’s own state_update. See Work state.
string
The child’s working directory, as an absolute path. See Working directories.
string[]
Additional directories the child works in, each as an absolute path.
Every field except sessionId is a patch. An omitted field leaves the stored value unchanged, null clears it, and a value replaces the whole previous value. A _meta object is a metadata patch.
  • Clearing title or description removes the parent’s label for the child.
  • capabilities is replaced as a whole and is not merged. capabilities: null and capabilities: {} both permit nothing. Inside the object, an omitted or null cancel means unsupported, not unchanged. A child whose capabilities was never sent permits nothing.
  • state is replaced as a whole. Clearing it leaves the child’s activity unconfirmed. It does not report idle.
  • Clearing cwd or additionalDirectories makes the child inherit that value from its parent again.
title and description are the parent’s labels for the child, so a Client can list a session’s subagents from the parent’s updates alone. The child’s own session_info_update describes the child’s conversation and does not change them. A change to either title does not rewrite earlier messages or tool calls.

Parents and nesting

The outer sessionId is the child’s immediate parent. When a child creates a subagent of its own, the Agent sends subagent_update with that child’s ID as the outer sessionId, so sessions can nest to any depth. A child has one parent. A subagent_update cannot move an existing session to another parent, name its own outer session as the child, or create a cycle. The association records which session owns the child. It does not limit which sessions exchange messages with it. A child sessionId identifies a conversation, not one task, turn, or tool call. Finishing or cancelling work does not end the association, and the parent can give the same child more work. Reuse is not required. An Agent whose runtime creates a new worker for each delegation announces a new child each time and sends nothing more for it once its work ends. That child keeps its last reported state and history.

What the Agent exposes

  • If the Agent learns of a child’s activity before it knows the child’s parent, it announces the child once it knows both, or holds the activity until then. It MUST NOT guess the parent or announce a nested child under the root session in the meantime.
  • If the Agent cannot identify a child and its parent without blocking an operation, it MAY leave that operation unexposed and report it through the parent. It MUST NOT later move a request or update it already sent to a different session.
  • Once a child is exposed, new requests and updates that the Agent knows belong to that child’s work MUST carry the child’s sessionId. The Agent does not fall back to the root session for them.
  • A parent’s request for permission to create or delegate to a child belongs to the parent. It does not require the child to be announced first.
The Agent chooses the child’s working directory, MCP servers, and tools, and they can differ from the parent’s. Requests the Agent sends for a child, such as session/request_permission, pass through the same Client capabilities and permission checks as the parent’s. The Agent MUST NOT use a child to get around a restriction the Client placed on the parent session.

Child session updates

Announcing a child registers it on the connection. The Agent then sends the child’s updates and requests with the child’s sessionId, without another request from the Client. There is no method to attach or subscribe to a child, and Clients MUST NOT send session/resume for a child to start receiving its updates. A child uses the same updates as any session, with its own sessionId as the outer sessionId. For example, a tool call that the child runs:
Requests work the same way. If that tool call needs permission, the permission request carries the child’s sessionId, and the Client presents it as the child’s request:
Entity IDs such as toolCallId and messageId are scoped to the session that reports them. call_001 in the child and call_001 in the parent are different tool calls. Updates for a parent and its children can interleave. Updates are ordered within each session, and a child’s first update follows its announcement. The Client did not set up the child, so the Agent reports the child’s context: The Client cannot prompt a child, so a child’s slash commands cannot be run. Agents need not send available_commands_update for a child, and Clients MUST NOT offer a child’s commands as input to the child or its parent. A child’s MCP servers, tools, and system prompt are not reported.

Working directories

cwd and additionalDirectories on subagent_update report where the Agent placed the child. They have the same meaning as the session setup fields of the same names, and every path MUST be absolute. additionalDirectories: [] reports that the child has no additional directories. A list replaces the previous list and is not merged. A field that was never reported, or was cleared, is inherited: the child’s effective value is its immediate parent’s current effective value. For a root session, that is the value from session setup. The two fields are inherited separately. A child that moves to its own worktree and should not keep the parent’s additional directories reports additionalDirectories: [] with its cwd:
  • The Agent MUST report a value that differs from the parent’s before it sends child updates or requests that depend on it.
  • An Agent that cannot determine a child’s directories SHOULD NOT expose that child as sharing the parent’s workspace. It can leave the child’s work unexposed instead.
  • Agents SHOULD report the narrowest directories the child needs, such as the worktree and not the temporary directory that contains it.
  • The Agent can change a child’s directories, for example with a new worktree for each task. It reports the new values before child updates or requests that depend on them. A change does not rewrite earlier messages or tool calls, whose paths are already absolute.
The fields are informational. The Client does not check requests against them, and they do not ask the Client to create, check out, or clean up a directory. Reporting them does not depend on the Agent’s session.additionalDirectories capability, which covers the directories a Client sends in session setup.

Configuration

Agents SHOULD report a child’s configuration, when it is available, with config_option_update on the child session. They send it after the announcement and again when the configuration changes, including between tasks for the same child. Each update carries the complete list, as for any session.
  • A child’s configuration can differ from its parent’s. If the Agent does not report it, the Client MUST NOT infer values from the parent or invent options.
  • Reporting options does not permit session/set_config_option for the child, even to set an option to its current value. No capability defined today permits it.
  • For a child whose configuration the Client cannot change, Agents SHOULD limit each select option’s values to its current value. Clients SHOULD show such an option as a label or a disabled selector, and show boolean options as read-only.

Messages between sessions

Sessions exchange session-directed messages, which the Agent reports with session_message and session_message_chunk. A message can go from a parent to a child, from a child back to its parent, or between other known sessions. It does not change which session owns a child. The Agent delivers these messages itself. The Client does not forward their content or send session/prompt because it received one.

Messages from a parent to a child

A parent directs a child with session-directed messages. This includes the first message, which starts the child’s work, and later messages to the same child.
  • Agents SHOULD report each message as the incoming view in the child’s transcript: a session_message with the outer sessionId set to the child and senderSessionId set to the parent. They send it before the child’s response to it.
  • If the parent’s conversation also records the message, Agents SHOULD report the outgoing view in the parent’s transcript and link the two views with senderMessageId and recipientMessageId.
  • Agents SHOULD NOT report the message as a user_message or user_message_chunk in the child’s transcript. A user message attributes it to the human user.
  • When the Agent has no evidence of who sent a message the child received, it omits senderSessionId and MUST NOT assume the parent. It can add the sender in a later session_message. Clients show such an entry as a message from another session, not as a user message.
For example, the incoming view in the child’s transcript:
The description on subagent_update describes the child’s role and does not replace the message. A parent that sends the message through a tool can also report it in that tool call’s input. The tool call reports the operation, and the child’s session_message reports what the child received.

Session references in tool calls

A tool call that spawns, waits on, or otherwise operates on a session can link to it with a session content item. The reference is for display. It does not establish ownership, permit the Client to send anything for the referenced session, or report that session’s state.

Session IDs in an update

An update for a subagent can carry several session IDs. Each one has its own purpose:

Work state

A child reports its foreground state with ordinary state_update notifications on its own sessionId, with the same meaning as for any session. There is no separate subagent lifecycle. Work can start and stop many times in one child, and idle does not end the association.
Agents SHOULD also mirror each reported child state in the state field of the immediate parent’s subagent_update. The field holds the same snapshot as the child’s state_update, without sessionUpdate:
  • The two reports describe one state. Clients apply them idempotently: a second copy is not more work, another completion, or more usage.
  • The Agent sends both copies of a transition before a later transition on either path, so a late mirror cannot overwrite newer state.
  • subagent_update.state is replaced as a whole. For example, { "state": "running" } replaces an earlier idle snapshot together with its stop reason. A subagent_update that omits state leaves the snapshot as it was.
  • If no state was reported, or the snapshot was cleared, the Client has no confirmed state for the child. Neither the announcement nor clearing the field means running, idle, or cancelled.
  • idle is not a successful outcome and does not release the child. A failure that ends the child’s foreground work is idle with stopReason: "error". It does not close the child or fail its parent.
Neither the parent’s session/prompt response nor the parent’s idle state means that its children have finished. A child that keeps running independently of the parent’s foreground work is background work, and the parent’s state snapshots list it as { "type": "subagent", "sessionId": "…" }.

Unknown state

When the Agent can no longer observe a child’s foreground work, it MUST report the unknown state: a state_update with "state": "unknown" on the child, mirrored in the parent’s subagent_update. Silence alone is not lost observability. Observability is also lost when the Agent itself stops tracking a child that may still be working, for example when its runtime starts a new conversation and drops the association.
  • The Client MUST NOT keep presenting an earlier running or requires_action as confirmed activity. It can keep the last known state for context.
  • A later running, requires_action, or idle replaces unknown for the same child.
  • unknown does not close or cancel the child, does not resolve its pending requests, and does not withdraw its capabilities. If a capability is no longer available, the Agent sends new capabilities.
  • The child’s unfinished tool calls, terminals, and background list stay as last reported. The Agent MUST NOT invent a final status for them. The Client MUST NOT present them as confirmed activity or treat them as failed or cancelled. If the Agent later learns that the work ended, it reports the final statuses and the child’s idle state as usual.

Restricted methods

A Client observes a child session and answers the requests the Agent sends for it. It cannot give the child new work. A Client-initiated request or notification that changes a child session or its runtime is not permitted unless that child’s capabilities enable it. This is an allowlist: Clients MUST NOT send such a method for a child only because the Agent supports it for ordinary sessions. That includes methods added in later protocol versions.
  • cancel is the only capability defined for a child session. It enables session/cancel and nothing else. A cancellable tool call or terminal enables its own cancel request and nothing else on the child.
  • The Client can name a child in these requests from the child’s announcement until the child’s root session stops being active on the connection.
  • The Agent ignores a session/cancel for a child that does not advertise cancel. It SHOULD reject any other request that is not permitted for a child with -32602. This includes session/close and session/delete, which do not report success for a child.
  • session/list does not return child sessions. A Client learns of them from subagent_update.
  • The parent’s own communication with its children is not Client-initiated, and these capabilities do not limit it.

Cancellation

While a child’s capabilities.cancel is an object, the Client MAY send session/cancel with the child’s sessionId:
It cancels the child’s foreground work, not the work of its parent or siblings. The capability governs what the Client can cancel. The Agent can cancel work it delegated at any time.
  • Cancellation follows the ordinary cancellation rules. The Agent stops the work, sends its pending updates, and then confirms with an idle state_update with stopReason: "cancelled" on the child, mirrored in the parent’s subagent_update. A child has no session/prompt response for the Client to wait for.
  • A provider that accepts a stop command has not yet stopped the work. The Agent reports cancelled when it observes that the work stopped. If it can no longer observe the child, it reports unknown.
  • A cancellation that arrives after the work ended does not change that work’s outcome.
  • Cancellation does not close the child. The parent can give it more work afterwards.
Cancelling a session’s foreground work, whether the session is a parent or a child, also cancels the descendant work that the cancelled work is waiting on, such as a child whose result a pending tool call needs. Whether other descendants keep running is up to the Agent. A background child that the cancelled work did not wait on can continue. A child that does not advertise cancel is still stopped when an ancestor’s cancellation covers it. The Client learns which descendants stopped from their reported state, not from the cancellation. To stop a background child, the Client cancels that child’s session if it advertises cancel, or closes the root session. The Client SHOULD mark the cancelled session’s unfinished tool calls as cancelled, as Cancellation describes, and skip tool calls in that session’s latest background list and tool calls that reference a listed terminal. It SHOULD do the same for a descendant once that descendant reports idle with stopReason: "cancelled". It SHOULD still accept later updates for those tool calls.

Pending requests

A request the Agent sends for a child, such as session/request_permission or elicitation/create, carries the child’s sessionId. It stays attributed to that child and MUST NOT move to the parent or to later work of the same child. The rules for pending requests in Cancellation and Elicitation cancellation apply to each session separately:
  • When the Agent stops a session’s cancelled work, it stops waiting for that work’s pending permission requests and SHOULD cancel each of them with $/cancel_request. This includes the requests of descendants that the cancellation stopped.
  • session/cancel on a parent does not resolve the requests of a child that keeps running. The user can still answer them.
  • The Client MAY answer a child’s pending permission request with the cancelled outcome once that child reports idle with stopReason: "cancelled". Before that, it leaves the request open.
  • A response that arrives after the work was cancelled still resolves its request. The Agent MUST NOT use it to restart cancelled or abandoned work, or to permit a new task for the same child. A request MUST NOT get more than one response.
  • The Agent does not wait for a child’s pending requests to resolve before it reports the child’s state.

Closing the parent

The Agent owns child resources. session/close on a session stops the work of all its descendants, background children included, and frees their active resources. Clients MUST NOT send session/close for a child.
  • Before it responds, the Agent MUST cancel the pending permission requests and elicitations of the closed session’s descendants with $/cancel_request, as it does for the closed session’s own.
  • Closing does not erase child history, and the Agent need not send a final update for each child.
  • After the close response, the Client can no longer name the closed session’s descendants in requests on that connection.
  • Whether a later session/resume of the parent restores the children is up to the Agent.

Connection loss

After the connection ends, the Client MUST NOT keep presenting a child’s last running or requires_action state as confirmed activity, and MUST NOT infer that unfinished work succeeded, failed, or was cancelled. It can show the child as disconnected, or its activity as unknown, and keep the outcomes it recorded. This is local display. It is not the unknown state, which an Agent reports on a live connection. State that the Agent reports after a later resume replaces it and can be running again for the same child.

Resuming

The Client reconnects through the session it created or resumed, with session/resume. It MUST NOT send session/resume for a child. The Agent decides whether resuming a parent reattaches its children’s runtimes, restores them, or only makes their recorded history available.

What the Client keeps

When the Client sends session/resume for a session, it MUST discard the state and capabilities it holds for that session’s children:
  • Each child’s effective capabilities start empty, and its state starts unconfirmed. History the Client already shows can stay visible.
  • The Client MUST NOT send session/cancel for a child until the resume succeeds and a current subagent_update advertises cancel.
  • If the resume fails, the Client discards the child state and capabilities it received during that request.
Which subagent_update notifications are current depends on the request:
  • Resume without replay. Every subagent_update and every child update is current. They can arrive before or after the response.
  • Resume with replay. Each session has its own replay_complete, which separates that session’s replayed history from its current updates. No session waits for another.
    • A child’s own updates follow the child’s replay_complete. A state_update on the child is never replayed, so it is always current.
    • A subagent_update is an update for the child’s immediate parent, so that parent’s replay_complete is the boundary for it. The capabilities and state in a replayed subagent_update are historical. They never become the child’s effective capabilities, and they do not confirm that the child is working. A subagent_update after that replay_complete is current.

What the Agent sends

  • Ancestors first. The announcement rule applies again on every resume, because the Client need not keep the session tree from an earlier connection. Before the Agent sends live updates or requests for a child, it has announced every ancestor of that child during this resume, parent before child. A replayed subagent_update counts. An ancestor whose runtime was not restored is still announced. Its subagent_update can omit capabilities and state.
  • Current state. The Agent SHOULD report each child’s current state when it can determine it. For each child in the resumed session’s background list, it MUST send a current subagent_update before the state snapshot that lists the child. After a replay, that update follows the parent’s replay_complete and carries the child’s current capabilities and state.
  • Capabilities. The Agent can omit capabilities for a child that permits nothing, because the effective set starts empty.
  • No invented outcomes. The Agent MUST NOT report a failure, a cancellation, or a permanently lost child only because the stored history has no final update or the child’s runtime could not be restored. A child with history only stays visible, with unconfirmed state and no capabilities.
  • Directories. Replayed cwd and additionalDirectories values describe the recorded context. Agents SHOULD send current values after the resume when they differ, and MUST report a new value or null when a child’s directory no longer exists.
  • Configuration. The Client MUST NOT present configuration it held before the resume as the child’s confirmed current configuration. Agents SHOULD send a current config_option_update for a restored child when it is available.
For example, root owns coordinator, which owns worker, and only worker is still running after a resume. The Agent announces coordinator under root, then worker under coordinator, before it sends new updates for worker. A replay may already have delivered both announcements. The subagent_update for coordinator can omit capabilities and state. The Agent does not announce worker directly under root.

Replayed child history

A resume with replay replays the parent’s history as Replay contents describes. The Agent SHOULD also replay the associations and child history it still has. Child history can be incomplete or missing. Complete child history is not required to expose subagents.
  • Replayed child updates MUST keep their original sessionId, their known parent, and their order within each session. A child’s subagent_update precedes its other replayed updates.
  • If the Agent can recover a child’s identity and parent but not its conversation, it can replay only the subagent_update. That is history. It does not show that the child is running or that its transcript is complete.
  • If the Agent cannot reconstruct an association truthfully, it MUST NOT guess the parent or send updates for a child it has not announced. It can omit that child’s history.
  • A recorded session_message can still be replayed with the participant IDs and content the Agent has, even when the other participant’s association or history is unavailable. Clients MUST NOT infer ownership, activity, or capabilities from such a message, and can show the other participant as unavailable. Agents MUST NOT invent a participant ID or report the content as a message to or from the user.
  • The Agent MUST send all history it selected for the replay before the response. Each child it announces during the request gets its own replay_complete. See Child sessions.
  • The Agent SHOULD report known gaps, for example with a notice after replay_complete. Missing history does not show that a child never existed, stopped, failed, or was cancelled.
  • Replay MUST NOT send a recorded session/request_permission, elicitation/create, or other Agent request again. A new request for a child is live. It follows the child’s announcement, and it SHOULD wait for the child’s replay_complete like any other Agent request.

Usage and cost

A child reports its context window usage and cost with usage_update on its own sessionId. Cost reporting stays optional, and exposing subagents does not change what a session’s reported cost covers.
  • A parent’s cost can already include its children’s work. Child costs can overlap the parent’s.
  • A missing child cost is unknown, not zero.
  • Agents MUST NOT derive an exclusive parent or child amount from incomplete token counts or from an aggregate total.
  • Clients MUST NOT add parent and child costs into a total for the tree, or subtract them to get exclusive costs. They can show each session’s latest reported value.
  • Context window usage belongs to each session and is not summed across sessions.
For example, a parent’s reported USD 1.20 may already include a child’s USD 0.30. A Client can show both values. It does not show USD 1.50 as the combined cost.