feat(unstable): Intial RFD and schema for subagents by Ololoshechkin · Pull Request #1992 · agentclientprotocol/agent-client-protocol

Ololoshechkin · 2026-08-20T00:39:04Z

Add subagents RFD

nikita-ashihmin · 2026-08-26T14:10:51Z

Implementation feedback from AIR and the reference adapter branches:

The canonical capability and lifecycle shape works for both adapters. We only needed _meta.jetbrains.air.capabilities = ["nativeSubagentSessions"] as a temporary negotiation bridge because the released SDKs currently remove the draft subagents fields. We treat this metadata as a compatibility bridge, not as an alternative protocol. It may help to make SDK preservation of the draft fields an explicit rollout prerequisite.

Two edge cases still seem underspecified:

The RFD defines orphan recovery during session/load, but it does not define the immediate Client state when a live connection ends or session/prompt returns without the required terminal update. Clients can otherwise choose failed, keep running forever, or show disconnected. Could the RFD require a local disconnected state for an unknown outcome and clarify whether the Client emits no wire update?
A child can own pending session/request_permission or session/create_elicitation requests when the child or its parent is cancelled. Could the RFD require those requests to resolve or cancel before subagent_state_update, and define how a Client handles a response that races with the terminal update? This prevents a terminal child from retaining a live control or moving that control to the wrong history.

One smaller compatibility note: the current RFD requires task. AIR now treats the older description field only as a temporary input fallback. New adapters emit task.

Ololoshechkin · 2026-08-31T14:29:25Z

@nikita-ashihmin please check again :)

benbrandt · 2026-09-01T17:18:30Z

I would like to keep the RFD + protocol changes in separate PRs because it is easier to accept an RFD without having to do rounds on the Rust code at the same time to get a merge

benbrandt

I think this is going in the right direction overall, but still have several questions I think we need to resolve.

Thanks for kicking this off!

benbrandt · 2026-09-01T17:19:29Z

+    /// A short, human-readable label for the subagent.
+    pub name: String,
+    /// A human-readable summary of the work delegated to the subagent.
+    pub task: String,
+    /// Client-to-agent operations permitted for this subagent session.
+    pub capabilities: SubagentSessionCapabilities,


I would imaging several of these should be optional

Done in ee65f9c — only subagentSessionId is required now. name/task/capabilities/state are optional with patch semantics: omitted (or null) means unchanged, and never-supplied has defined defaults (client-chosen label, no permitted operations, running).

benbrandt · 2026-09-01T17:21:43Z

+#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+#[non_exhaustive]
+pub enum SubagentState {


My inclination is we should treat this similarly to how we are treating tool calls, messages, and terminals in v2 where we continuously update a given subagent "entity" so we only have one notification type with clear upsert/update semantics

Agreed — merged subagent_spawned + subagent_state_update into a single upsert-style subagent_update modeled on v2's TerminalUpdate/ToolCallUpdate: only the ID is required, the first update announces the child, later ones patch it, and one of them carries the terminal state (ee65f9c). Also mirrored the same type into the v2 schema — capability-free, MaybeUndefined patch semantics, open state enum — so the shape carries into v2 unchanged (a06ecf2).

benbrandt · 2026-09-01T17:23:28Z

+```json
+{
+  "clientCapabilities": {
+    "subagents": {}


I think this is good for v1, but just a note, I think for v2 we can assume support

Why do you think so? Not all possible agents even support subagents (and not all of them plan/should do so afaik)

Resolving my own question above after implementing it: “assume support” turned out fine — it doesn't force Agents to have subagents; an Agent without them simply never sends the update. What v2 removes is only the negotiation handshake: unknown sessionUpdate types flow into OtherSessionUpdate, which Clients preserve and otherwise ignore. The RFD now has a “Subagents in ACP v2” section, and the v2 schema carries subagent_update behind the same unstable flag (a06ecf2).

benbrandt · 2026-09-01T17:23:57Z

+this RFD. The field is optional and non-nullable. An omitted field means the
+capability is not supported; `{}` means it is supported.
+
+Add an optional `subagents` object to `AgentCapabilities.sessionCapabilities`.


Why does the agent need to express support? Wouldn't the notifications inherently handle it?

You're right — dropped the Agent-side capability entirely (182be75, ee65f9c). Subagent traffic only flows Agent → Client, so the Client capability alone prevents sending updates the other side can't understand; a Client learns that an Agent exposes subagents by receiving the first update.

benbrandt · 2026-09-01T17:25:33Z

+When an Agent creates a subagent that it wants to expose, it **MUST** send a
+`subagent_spawned` update on the immediate parent session before sending any
+updates for the child session:
+


Yeah this seems important. We may want to handle some things on the SDK side to better tolerate queueing messages for sessions we don't know about in case someone doesn't abide by this, but this does seem also easy enough (before the first event for the new session, emit the first subagent notification)

Added exactly that: SDKs MAY buffer updates for unknown session IDs until the announcing update arrives, and Agents MUST NOT rely on such tolerance. Also added to the implementation plan.

benbrandt · 2026-09-01T17:32:14Z

+The child inherits the parent's effective working directory, additional
+directories, MCP servers, and Client capabilities. The Agent may apply stricter
+runtime or tool restrictions to the child, but it **MUST NOT** grant access that
+was not available to the parent. A future RFD may add explicit per-child
+execution-context fields if Clients need to display or negotiate them.


Hmm I don't know if we want to do this? The reason I say this is I see codex spawning lots of subagents in /tmp directories to do work, and may not pass along mcp or client capabilities.

We likely need a way to express these though

Reworked (182be75): the child's execution context — cwd, MCP servers, tools — is now explicitly Agent-chosen and may differ from the parent's (scratch dirs like the Codex /tmp case). Kept only the enforceable part: child activity flows through the same connection, subject to the same Client capabilities and permission checks, and a child must not be used to bypass parent-session restrictions. The future-RFD pointer for explicit per-child context fields stays — agreed we'll likely want a way to express these; an optional workingDirectory on subagent_update would be an easy follow-up if you want it now.

benbrandt · 2026-09-01T17:33:15Z

+  "params": {
+    "sessionId": "sess_parent",
+    "update": {
+      "sessionUpdate": "subagent_state_update",


Again, I wonder if we want a more generic subagent_update notification that captures all updates of that subagent (see v2 patterns that we can backport to v1 here)

Done — folded both notifications into the single upsert-style subagent_update (ee65f9c), mirrored into v2 (a06ecf2).

benbrandt · 2026-09-01T17:35:00Z

+descendants in a local `disconnected` state: the task outcome is unknown. The
+Client **MUST NOT** present such a child as `failed` or `cancelled`, **MUST
+NOT** continue presenting it as running, and **MUST NOT** wait indefinitely for
+a terminal update.


Hmm this seems odd to me... Because the client could continue to receive updates from that session, which would tell it whether it is still running or not?

The constraint driving this: v1 ties session/update to the active prompt turn, so once session/prompt returns there's no defined channel through which the child's real outcome could still arrive — “keep waiting” becomes a spinner that can never resolve (this rule came from AIR's implementation feedback earlier in this PR). A late terminal update on a still-live connection is already allowed to supersede the local state. I added this rationale to the section. In v2 this trigger disappears entirely: prompt resolves at acceptance and updates keep flowing, so connection loss remains the only cause (covered in the new v2 section).

Address review feedback from #1992: - Merge subagent_spawned and subagent_state_update into one upsert-style subagent_update following the v2 entity pattern; add explicit running state - Make name, task, and capabilities optional; only subagentSessionId required - Drop the Agent-side capability: the Client capability alone gates the updates - Drop the per-child close capability; session/close is not valid for child IDs - Stop implying children inherit the parent's execution context - Allow SDKs to buffer updates for unannounced child sessions - Explain why the local disconnected state cannot wait for late updates - Add FAQ entries for naming, capability, and disconnected-state choices - Define v2 support: capability-free, v2 patch semantics, open state enum Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

…gent_update Replace SubagentSpawnedUpdate and SubagentStateUpdate with a single SubagentUpdate where only subagentSessionId is required and omitted or null fields mean unchanged. Add a running state to SubagentState, drop the per-child close capability, and remove the agent-side subagents session capability. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Mirror the v1 subagent types into v2 with v2 conventions: no capability (unknown updates flow into OtherSessionUpdate), MaybeUndefined patch semantics, and an open SubagentState enum that preserves unknown values. Register subagent_update in the known-discriminator guards. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Ololoshechkin · 2026-09-15T23:28:50Z

Thanks for the thorough review, Ben! Pushed a rework addressing all threads (182be75, ee65f9c, a06ecf2):

subagent_spawned + subagent_state_update are now a single upsert-style subagent_update following the v2 entity pattern (only subagentSessionId required; explicit running state)
Agent-side capability and per-child close are gone
Execution context is no longer implied to be inherited
SDKs may buffer updates for unannounced children
The v2 schema now carries the same type: capability-free, v2 patch semantics (null clears), open state enum — plus a new “Subagents in ACP v2” section in the RFD

On splitting RFD and protocol changes: happy to do that — I'd keep this PR as the RFD and move the schema/Rust changes into a follow-up PR once you're happy with the shape. Say the word and I'll split it.

@nikita-ashihmin heads-up: the wire shape changed (single subagent_update, optional fields, no per-child close), so the adapter branches will need a small migration. Your three earlier points survived the rework: SDK preservation is still an explicit rollout prerequisite, the local disconnected rule and the pending-request race handling are unchanged (now with added rationale), and task remains the canonical field — but note it is now optional, so fallback code shouldn't assume it is always present.

Separate reusable child sessions from individual tool-call operations. Add non-owning session references, object cancellation capabilities, and work-state reporting for both protocol versions. Define ownership, routing, best-effort replay, and provider cost semantics in the RFD and draft guides. Regenerate unstable schemas and add serialization and compatibility tests.

Preserve main's RFD status categories and retain subagents in Draft. Regenerate schema artifacts from the merged Rust definitions to include both main's capabilities and the subagent session model.

The v1 client only uses Usage in the subagent work-state payload. Require both unstable_subagents and unstable_end_turn_token_usage so usage-only feature combinations do not fail CI with warnings denied. Validated all 95 depth-two feature configurations with CARGO_BUILD_WARNINGS=deny.

Replace tool-call session references with message upserts and chunks, with optional participant metadata and mirrored v2 child state snapshots. Align new v1 patches with tri-state semantics and refine subagent recovery and documentation.

Ololoshechkin requested a review from a team as a code owner August 20, 2026 00:39

Ololoshechkin force-pushed the vbr/subagents-rfd branch from 1509932 to 2fc02e6 Compare August 25, 2026 10:20

Ololoshechkin added 4 commits August 31, 2026 16:23

Add subagents RFD draft

ccf4d55

Add to schema.unstable.json and to Rust client

223d917

Fixup

b978a27

fixes after review

4315189

Ololoshechkin force-pushed the vbr/subagents-rfd branch from 0c06d25 to 4315189 Compare August 31, 2026 14:23

benbrandt reviewed Sep 1, 2026

View reviewed changes

Ololoshechkin and others added 3 commits September 16, 2026 01:26

Ololoshechkin requested a review from benbrandt September 16, 2026 23:38

mrmans0n mentioned this pull request Sep 21, 2026

Native subagent sessions: opt into clientCapabilities.subagents and render child transcripts mrmans0n/alas#1367

Closed

6 tasks

This was referenced Sep 23, 2026

Adopt ACP's dedicated subagent channel once agent-client-protocol#1992 ships pilgrimagesoftware/Knot#421

Open

An agent's subagents are invisible: the processes section lists OS processes only pilgrimagesoftware/Knot#417

Merged

benbrandt changed the title ~~Add subagents RFD~~ feat(unstable): Intial schema and RFD for subagents Sep 25, 2026

chore: merge main into subagents RFD

a9d2206

Preserve main's RFD status categories and retain subagents in Draft. Regenerate schema artifacts from the merged Rust definitions to include both main's capabilities and the subagent session model.

benbrandt changed the title ~~feat(unstable): Intial schema and RFD for subagents~~ feat(unstable): Intial RFD and schema for subagents Sep 25, 2026

benbrandt added 2 commits September 25, 2026 13:54

Conversation

Ololoshechkin commented Aug 20, 2026

Uh oh!

nikita-ashihmin commented Aug 26, 2026

Uh oh!

Ololoshechkin commented Aug 31, 2026

Uh oh!

benbrandt commented Sep 1, 2026

Uh oh!

benbrandt left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Ololoshechkin commented Sep 15, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants