Skip to content

feat(subagent-tool-call): report coherent agent and command updates#284

Open
duclvz wants to merge 1 commit into
agentclientprotocol:mainfrom
duclvz:feat/subagent-tool-call
Open

feat(subagent-tool-call): report coherent agent and command updates#284
duclvz wants to merge 1 commit into
agentclientprotocol:mainfrom
duclvz:feat/subagent-tool-call

Conversation

@duclvz

@duclvz duclvz commented Jul 11, 2026

Copy link
Copy Markdown

Summary

Improve how Codex app-server command execution and sub-agent activity are represented through ACP.

This change:

  • Represents each sub-agent run as one coherent parent-visible ACP tool call.
  • Folds wait, sendInput, and closeAgent control actions into updates on that activity.
  • Creates a new activity when a completed child agent is resumed.
  • Completes the activity from the child thread’s final message and turn result.
  • Adds _meta.codex.toolName: "Agent" for deterministic client classification.
  • Uses portable ACP content for internal command output unless the client explicitly advertises the legacy terminal-output extension.
  • Applies the same behavior to live events, session history, and response-item fallback recovery.

Motivation

The previous mapping exposed Codex orchestration details too literally.

A delegated agent could appear as a foreground command followed by separate wait tool calls, even though those waits were control-plane operations for the same unit of work. This made ACP clients display several unrelated tool cards instead of one sub-agent activity.

Internal command executions also used ACP terminal content with a Codex item ID that was never created through ACP terminal/create. That behavior was not portable to clients without codex-acp-specific terminal handling.

The new mapping presents semantic work to the client while retaining the underlying Codex action details in structured output.

Sub-agent lifecycle

Codex event ACP representation
Sub-agent started or spawned New Agent tool call
wait Update the active run
sendInput Update the active run
closeAgent Update the active run
Resume after a terminal state New run ID correlated to the same child thread
Child final message and turn completion Complete the active run
Spawn or resume failure Failed Agent tool call
Tools executed by the child Remain isolated on the child thread

Every synthesized sub-agent event includes:

{
  "_meta": {
    "codex": {
      "toolName": "Agent",
      "subAgent": {
        "agentThreadId": "<child-thread-id>",
        "runId": "<activity-tool-call-id>"
      }
    }
  }
}

Present each sub-agent run as one activity and expose internal command output through portable ACP content.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant