Skip to content

feat(unstable): Intial RFD and schema for subagents #1992

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Ololoshechkin wants to merge 11 commits into
base: main
Choose a base branch
from
Open

feat(unstable): Intial RFD and schema for subagents #1992

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
ccf4d55
Add subagents RFD draft
Ololoshechkin Aug 20, 2026
223d917
Add to schema.unstable.json and to Rust client
Ololoshechkin Aug 20, 2026
b978a27
Fixup
Ololoshechkin Aug 25, 2026
4315189
fixes after review
Ololoshechkin Aug 31, 2026
182be75
docs(rfd): rework subagents RFD to a single upsert-style subagent_update
Ololoshechkin Sep 15, 2026
ee65f9c
feat(unstable): merge subagent session updates into upsert-style suba…
Ololoshechkin Sep 15, 2026
a06ecf2
feat(unstable-v2): add subagent_update to the v2 schema
Ololoshechkin Sep 15, 2026
905d8fd
feat(unstable): refine subagent session model
benbrandt Sep 25, 2026
a9d2206
chore: merge main into subagents RFD
benbrandt Sep 25, 2026
414baf3
fix(unstable): gate subagent usage import on both features
benbrandt Sep 25, 2026
b132944
feat(unstable): add session-directed message updates
benbrandt Sep 28, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions agent-client-protocol-schema/Cargo.toml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ unstable = [
"unstable_nes",
"unstable_plan_operations",
"unstable_session_fork",
"unstable_subagents",
"unstable_session_compaction",
"unstable_session_notices",
"unstable_end_turn_token_usage",
Expand All @@ -47,6 +48,7 @@ unstable_plan_operations = []
unstable_session_fork = []
unstable_session_compaction = []
unstable_session_notices = []
unstable_subagents = []
unstable_end_turn_token_usage = []

# Emit `tracing::warn!` events when `VecSkipError` drops a malformed list
Expand Down
1,595 changes: 1,572 additions & 23 deletions agent-client-protocol-schema/src/v1/client.rs
View file
Open in desktop

Large diffs are not rendered by default.

1,281 changes: 1,232 additions & 49 deletions agent-client-protocol-schema/src/v2/client.rs
View file
Open in desktop

Large diffs are not rendered by default.

3 changes: 2 additions & 1 deletion docs/docs.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -194,7 +194,8 @@
"rfds/custom-llm-endpoint",
"rfds/plan-operations",
"rfds/end-turn-token-usage",
"rfds/get-auth-state"
"rfds/get-auth-state",
"rfds/subagents"
]
},
{
Expand Down
85 changes: 67 additions & 18 deletions docs/protocol/v1/draft/prompt-turn.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,29 +11,78 @@ Before sending prompts, Clients **MUST** first complete the [initialization](/pr

Agents send `session/update` notifications to report streamed content, tool activity, and changes to session state. The `sessionUpdate` field inside `params.update` identifies the variant:

| `sessionUpdate` value | Description |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_message_chunk` | A streamed chunk of a user message. |
| `agent_message_chunk` | A streamed chunk of the Agent's response. |
| `agent_thought_chunk` | A streamed chunk of the Agent's reasoning. |
| `tool_call` | A new [tool call](/protocol/v1/draft/tool-calls#creating). |
| `tool_call_update` | A change to a [tool call's status or results](/protocol/v1/draft/tool-calls#updating). |
| `plan` | The Agent's [execution plan](/protocol/v1/draft/agent-plan). |
| `plan_update` | **Draft only.** A [content update for a plan](/protocol/v1/draft/agent-plan#plan-operations) identified by ID. Requires the Client's `plan` capability. |
| `plan_removed` | **Draft only.** [Removal of a plan](/protocol/v1/draft/agent-plan#removing-plans) identified by ID. Requires the Client's `plan` capability. |
| `available_commands_update` | The set of [available slash commands](/protocol/v1/draft/slash-commands) is ready or has changed. |
| `current_mode_update` | The current [session mode](/protocol/v1/draft/session-modes#from-the-agent) has changed. |
| `config_option_update` | The session's [configuration options](/protocol/v1/draft/session-config-options#from-the-agent) have changed. |
| `session_info_update` | [Session metadata](/protocol/v1/draft/session-list#updating-session-metadata), such as the title or last update time, has changed. |
| `usage_update` | The session's [context window usage and cumulative cost](#session-usage-updates). |
| `notice` | **Draft only.** A live [advisory notice](#session-notices) that is not part of session history. Requires the Client's `session.notices` capability. |
| `compaction_update` | **Draft only.** Creates or updates a [context compaction](#session-compaction). Requires the Client's `session.compaction` capability. |
| `compaction_summary_chunk` | **Draft only.** Appends content to a [compaction's retained summary](#session-compaction). Requires the Client's `session.compaction` capability. |
| `sessionUpdate` value | Description |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user_message_chunk` | A streamed chunk of a user message. |
| `agent_message_chunk` | A streamed chunk of the Agent's response. |
| `agent_thought_chunk` | A streamed chunk of the Agent's reasoning. |
| `subagent_update` | **Draft only.** Announces an owned child session or updates its parent-owned metadata and work state. Requires the Client's `subagents` capability. |
| `session_message` | **Draft only.** Creates or updates a [message addressed to another session](#session-directed-messages-unstable). Requires the Client's `subagents` capability. |
| `session_message_chunk` | **Draft only.** Appends content to a [session-directed message](#session-directed-messages-unstable). Requires the Client's `subagents` capability. |
| `tool_call` | A new [tool call](/protocol/v1/draft/tool-calls#creating). |
| `tool_call_update` | A change to a [tool call's status or results](/protocol/v1/draft/tool-calls#updating). |
| `plan` | The Agent's [execution plan](/protocol/v1/draft/agent-plan). |
| `plan_update` | **Draft only.** A [content update for a plan](/protocol/v1/draft/agent-plan#plan-operations) identified by ID. Requires the Client's `plan` capability. |
| `plan_removed` | **Draft only.** [Removal of a plan](/protocol/v1/draft/agent-plan#removing-plans) identified by ID. Requires the Client's `plan` capability. |
| `available_commands_update` | The set of [available slash commands](/protocol/v1/draft/slash-commands) is ready or has changed. |
| `current_mode_update` | The current [session mode](/protocol/v1/draft/session-modes#from-the-agent) has changed. |
| `config_option_update` | The session's [configuration options](/protocol/v1/draft/session-config-options#from-the-agent) have changed. |
| `session_info_update` | [Session metadata](/protocol/v1/draft/session-list#updating-session-metadata), such as the title or last update time, has changed. |
| `usage_update` | The session's [context window usage and cumulative cost](#session-usage-updates). |
| `notice` | **Draft only.** A live [advisory notice](#session-notices) that is not part of session history. Requires the Client's `session.notices` capability. |
| `compaction_update` | **Draft only.** Creates or updates a [context compaction](#session-compaction). Requires the Client's `session.compaction` capability. |
| `compaction_summary_chunk` | **Draft only.** Appends content to a [compaction's retained summary](#session-compaction). Requires the Client's `session.compaction` capability. |

This is the complete set of variants defined in the current draft [`SessionUpdate` schema](/protocol/v1/draft/schema#sessionupdate), which describes each payload in detail. Draft-only variants are unstable and may change or be removed. The walkthrough below illustrates common uses of these updates.

Session updates are not limited to active prompt turns. For example, Agents may advertise commands after creating a session, and replay user and Agent messages when [loading a session](/protocol/v1/draft/session-setup#loading-sessions).

### Session-directed messages (unstable)

When the Client advertises `subagents: {}`, the Agent may report outgoing and
incoming messages between sessions, separately from user-facing responses and
tool calls. The outer `params.sessionId` identifies the transcript being
updated. Every message and chunk requires a `messageId` scoped to that
transcript. Optional `senderSessionId` and `recipientSessionId` metadata
identify the participants. Include them on the first update when available;
later updates may omit them or add missing identities.

For example, an incoming message in the child can begin with a streamed chunk:

```json
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "child_session",
"update": {
"sessionUpdate": "session_message_chunk",
"messageId": "received_message_1",
"senderSessionId": "parent_session",
"recipientSessionId": "child_session",
"content": { "type": "text", "text": "Please investigate " }
}
}
}
```

Every chunk carries one normal `ContentBlock`; later chunks append content
for the same `messageId`. `session_message` can supply a whole
`content` array to replace accumulated content. Its optional `content` and
`_meta` fields leave prior values unchanged when omitted; `null` clears them.
`content: []` also clears content. Chunk metadata is local to the chunk, not a
message-level patch.

Clients can render "To …" with a recipient link or "From …" with a sender link.
Without sufficient participant metadata, use a generic inter-session
presentation and add links when the metadata arrives. Omitted or `null`
participant IDs mean not supplied and leave previously known identities intact.
The two views have independent message IDs. The Agent reports each side only
when observed; Clients must not synthesize an incoming entry from an outgoing
one or forward the content themselves. Neither view acknowledges completed
recipient processing. See the [Subagent Sessions RFD](/rfds/subagents#session-directed-messages)
for participant registration, history gaps, and ownership rules.

## The Prompt Turn Lifecycle

A prompt turn follows a structured flow that enables rich interactions between the user, Agent, and any connected tools.
Expand Down
Loading
Loading