codex-acp reports Codex subagents as ACP child sessions through one of two contracts. A connection gets one contract, never both.
- The standard contract follows the ACP subagent sessions specification:
subagent_update,session_message, andsessiontool call content. - The AIR legacy contract is the older private contract for JetBrains AIR clients:
subagent_spawnedandsubagent_state_update.
Without either contract, a subagent stays an ordinary tool call on the root session. See Fallback.
- A v1 Client opts in with
clientCapabilities.subagents: {}. Without it, the adapter sends none of the updates below. - A v2 Client needs no capability. Subagent updates are part of the v2 session model.
- There is no Agent-side capability. The
initializeresponse to a standard Client does not containagentCapabilities.sessionCapabilities.subagents.
- The adapter sends
subagent_updateon the immediate parent before any update, permission request, or elicitation that bears the child's session ID. Ancestors are announced before descendants. - A child keeps one session ID across assignments, idle periods, and replay.
titlecomes from the Codex agent path or thread name.descriptionis the role that Codex assigned to the child (agentRole). It is omitted when Codex reports no role. It never holds the task prompt.capabilities.cancelis advertised only while the child's current turn can be interrupted.session/cancelwith the child's ID interrupts that work. On v2 it skips listed background work; a child terminal with its owncapabilities.cancelcan be stopped withterminal/cancelwithout interrupting the child turn. Other client-initiated requests for a child session are rejected.statereportsrunning,requires_action,idlewith astopReason, orunknownwhen observability is lost. A v2 Client also gets the samestate_updateon the child session. There is no terminal child state.cwdis reported as described in Directories.
The task a session gives a child is reported as session_message, not as a user message and not in description.
- Incoming view. A
userMessageitem in the child's Codex thread is reported on the child session, before the child's response.messageIdis the Codex item ID.recipientSessionIdis the child. - Outgoing view. A completed
spawnAgent,sendInput,sendMessage, orfollowupTaskcollaboration call with a prompt is reported on the sender's session.messageIdis<item id>:to:<receiver thread id>. A failed or interrupted call reports no message. - Linking. The two views are linked with
senderMessageIdandrecipientMessageIdwhen the same text was observed for the same recipient on both sides and identifies one waiting view. Repeated identical text with several waiting views is left unlinked. Whichever view is observed second carries the reference, and a metadata-onlysession_messageadds the reference to the first. - The incoming view names
senderSessionIdonly when it is linked. Codex does not record the sender on the child's item, so an unlinked incoming view names only its recipient. Subagents recorded only assubAgentActivityitems have no prompt on the parent side, so their tasks have no outgoing view and no sender. - Neither view is derived from the other. A view is reported only when its Codex item was observed.
- Message IDs are the same live and on replay.
- The
spawnAgentcall is not shown. The announcement and the task message report the delegation. - Other collaboration calls (
wait,sendInput,closeAgent, and so on) stay visible on the sender's session. Theircontentholds one{ "type": "session", "sessionId": ... }entry for each receiver that is already announced.rawInputstill holds the Codex thread IDs.
session/load, and v2 session/resume with replayFrom, replay each recorded child conversation once, before the response. Replay reports the same announcements, session messages, and session references as the live path. The latest recorded turn outcome is historical state on the parent's subagent_update, not a live state_update for the child. Replay grants no cancel capability.
On v2, the root and each announced child get exactly one replay_complete, including children with no retained content. A parent's marker separates historical child associations from current child state and capabilities reported on that parent. Live updates, state snapshots, and requests follow the boundary for their session. Root activation and child controls still wait for the successful resume response. A resume without replayFrom sends no replay boundary. V1 session/load uses the response as the freshness boundary.
V2 replay omits historical child configuration. Only a restored child's current configuration is reported. V1 load keeps recorded child configuration in history.
A missing or incomplete child transcript adds one advisory on the root session. On v1 this is a thought. On v2 it is a live notice after replay_complete, not retained history.
Directory information is part of subagent_update on the immediate parent, on both ACP versions.
A verified loaded-child read reports its absolute cwd, including a worktree directory. Known child settings changes update that value. Announcements do not reset directory fields while readback is pending. Omission preserves a retained override. null would explicitly restore inheritance from the immediate parent, not report an unknown directory. Readback does not block child output, and a superseded read cannot replace newer settings.
The adapter verifies the child's ID, parent, and loaded state before accepting readback. It does not report relative paths or infer directories from provider IDs. Codex does not expose an authoritative ACP additional-directory list for children, so the adapter omits that field. It does not copy parent roots or treat writable sandbox paths as workspace roots. [] would mean explicitly no additional directories, not unknown directories.
This contract applies only to a Client that declares _meta.jetbrains.air. It does not use subagent_update, session_message, or session tool call content. See AIR extensions.
- AIR opts in with
nativeSubagentSessionsin_meta.jetbrains.air.capabilities, or on v1 withclientCapabilities.subagents: {}. - The adapter answers an AIR Client with
agentCapabilities.sessionCapabilities.subagents: {}on v1 and listsnativeSubagentSessionsin its own_meta.jetbrains.air.capabilities.
- The adapter sends
subagent_spawnedbefore any child output. Itstaskfield holds the prompt. - It uses the child session ID for later messages, thoughts, plans, tools, permissions, and elicitations.
- It sends one
subagent_state_updateon the immediate parent, withcompleted,failed,cancelled, ordisconnected. - The adapter advertises an empty child capability object. It does not support targeted child cancel or close operations.
- On v2 both updates are sent as
_subagent_update.
session/load reconstructs the child tree from Codex history. It reports an orphan as disconnected when the history does not prove an outcome. Live timeout, shutdown, and notFound fallbacks use failed.
Without either contract, the subagent lifecycle stays an ordinary ACP tool call. Child permission and elicitation requests stay on the root session.