feat(unstable): Intial RFD and schema for subagents

[Ololoshechkin]

Add subagents RFD

[nikita-ashihmin]

Implementation feedback from AIR and the reference adapter branches:

• feat: expose native subagents and async tasks claude-agent-acp#1017
• feat: add native ACP subagent sessions codex-acp#419

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:

1. 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?

2. 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]

@nikita-ashihmin please check again :)

[benbrandt]

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!

[Ololoshechkin]

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.

[agourakis82]

Real-world confirmation this works end to end, from an independent (non-JetBrains) client, in case it's useful signal for moving this RFD along.

We're building a multi-agent client that juggles several ACP agent sessions at once (Claude, Codex, Kimi, each over SSH/stdio) and wanted exactly this: a standard way to see an agent's own subagent/Task dispatch instead of flattened tool_calls with vendor-specific _meta (e.g. claudeCode.parentToolUseId).

Found clientCapabilities.subagents has no effect yet against claude-agent-acp@0.84.0 — the published SDK schema doesn't carry unstable_subagents, so it gets silently dropped (same root cause as agentclientprotocol/claude-agent-acp#1195). Declaring the AIR back-channel instead:

{ "clientCapabilities": { "_meta": { "jetbrains": { "air": { "version": 1, "capabilities": ["nativeSubagentSessions"] } } } } }

does work today and produces exactly the shape this RFD describes — tested dispatching two parallel Task subagents against a real claude-agent-acp process:

{"sessionUpdate": "subagent_spawned", "subagentSessionId": "...", "name": "Contar até 3", "task": "...", "capabilities": {}}
{"sessionUpdate": "subagent_state_update", "subagentSessionId": "...", "state": "completed"}

So the design works in practice; what's missing for a non-AIR client is just the canonical field reaching a published SDK build. Not asking for anything specific here beyond leaving this as a data point — happy to help test once unstable_subagents is exposed, or to open a focused issue if that's more useful than a PR comment.

[benbrandt]

This is in progress and the adapters need to be updated