ACP-aligned protocol vs Claude SDK harness

spawn(process.execPath, [claude-agent-acp entry],
  { cwd, env: { …process.env, ELECTRON_RUN_AS_NODE: "1" } })

{ "jsonrpc": "2.0", "id": 1, "method": "initialize",
  "params": {
    "protocolVersion": 1,
    "clientInfo": { "name": "superset-host", "version": "1" },
    "clientCapabilities": {
      "fs": { "readTextFile": false, "writeTextFile": false },
      "terminal": false,
      "elicitation": { "form": {} }  // re-enables AskUserQuestion
    } } }

⤷ elicitation.form is the load-bearing line: without it the adapter disallows Claude Code's built-in AskUserQuestion tool — see phase ⑥.

{ "id": 1, "result": {
    "protocolVersion": 1,
    "agentCapabilities": { … } } }

{ "jsonrpc": "2.0", "id": 2, "method": "session/new",
  "params": {
    "cwd": "/Users/kirill/.superset/worktrees/…",
    "mcpServers": []
  } }

{ "id": 2, "result": {
    "sessionId": "sess_9f3k…",   // adapter-internal
    "modes": {
      "currentModeId": "bypassPermissions",
      "availableModes": [
        { "id": "default", … }, { "id": "acceptEdits", … }, …
      ] } } }

{ "jsonrpc": "2.0", "id": 3, "method": "session/set_mode",
  "params": { "sessionId": "sess_9f3k…", "modeId": "default" } }

{ "jsonrpc": "2.0", "id": 10, "method": "session/prompt",
  "params": {
    "sessionId": "sess_9f3k…",
    "prompt": [ { "type": "text",
        "text": "Implement exponential retry for webhook delivery." } ]
} }

{ "seq": 2, "sessionId": "7d1e4a02-…", "ts": 1752107660001,
  "frame": {
    "kind": "update",
    "update": {
      "sessionUpdate": "user_message_chunk",
      "content": { "type": "text",
        "text": "Implement exponential retry for webhook delivery." }
    } } }

⤷ fold: appendChunk → new user MessageItem { id: "user:2" }.

{ "seq": 4, "sessionId": "7d1e4a02-…", "ts": 1752107663210,
  "frame": { "kind": "update", "update": {
    "sessionUpdate": "agent_message_chunk",
    "content": { "type": "text",
      "text": "I'll inspect the delivery path and existing tests." }
} } }

⤷ fold appendChunk: last item is an agent message → blocks[last].text += chunk — merged in place, no new item. agent_thought_chunk is identical, folds to role "thought". The SDK's consolidated assistant message never crosses: the adapter diffs it against the already-streamed blocks (acp-agent.js:658) and forwards only an un-streamed tail.

{ "kind": "update", "update": {
    "sessionUpdate": "tool_call",
    "toolCallId": "toolu_01XyZaBcDe",
    "title": "Write src/retry.ts",
    "kind": "edit",
    "status": "pending",
    "rawInput": { "file_path": "src/retry.ts", "content": "…" }
} }

⤷ fold upsertToolCall → new ToolCallItem. Later tool_call_update frames are patches: present fields replace, absent keep — merged only at fold time, each patch its own row.

{ "jsonrpc": "2.0", "id": 7,
  "method": "session/request_permission",
  "params": {
    "sessionId": "sess_9f3k…",
    "toolCall": { "toolCallId": "toolu_01XyZaBcDe",
      "title": "Write src/retry.ts", "kind": "edit", "status": "pending" },
    "options": [
      { "optionId": "allow",  "name": "Allow",  "kind": "allow_once" },
      { "optionId": "reject", "name": "Reject", "kind": "reject_once" }
    ] } }

⤷ host parks the response promise in pendingResolvers keyed by the JSON-RPC id ("7") and pushes onto state.pendingPermissions.

{ "jsonrpc": "2.0", "id": 7,
  "result": { "outcome": { "outcome": "selected", "optionId": "allow" } } }

⤷ turn-cancel or adapter death settles unanswered asks as { "outcome": "cancelled" } via the request's AbortSignal — nothing leaks.

{ "jsonrpc": "2.0", "id": 41, "method": "elicitation/create",
  "params": {
    "mode": "form",
    "sessionId": "sess_9f3k…",
    "toolCallId": "toolu_question_01",
    "message": "Which failures should retry?",
    "requestedSchema": {
      "type": "object",
      "properties": {
        "question_0": {
          "type": "string",
          "oneOf": [
            { "const": "429 + 5xx" },
            { "const": "Also network failures" }
          ] },
        "question_0_custom": { "type": "string" }
      } } } }

⤷ extractElicitationQuestions() keeps only question_<n> fields (*_custom ignored — mobile is tap-only); non-form modes → cancel; no recognizable questions → decline.

{ "kind": "permission_requested",
  "pending": {
    "requestId": "q-3f7c9d2e-…",          // randomUUID, host-minted
    "toolCall": { "toolCallId": "toolu_question_01",
      "title": "Which failures should retry?",
      "kind": "other", "status": "pending" },
    "options": [
      { "optionId": "option-0", "name": "429 + 5xx",
        "kind": "allow_once" },
      { "optionId": "option-1", "name": "Also network failures",
        "kind": "allow_once" },
      { "optionId": "skip", "name": "Skip", "kind": "reject_once" }
    ],
    "requestedAt": 1752107668210 } }
// + { "kind": "state", "state": { "status": "awaiting_permission", … } }

⤷ options = enum labels + Skip; card title = the question. Mobile renders and resolves this exactly like the Write ask in ⑤.

{ "jsonrpc": "2.0", "id": 10,
  "result": { "stopReason": "end_turn" } }

// subagent assistant message (parent_tool_use_id !== null):
// "It is never streamed live and its text/thinking is internal
//  to the tool call — keep dropping it so subagent prose
//  doesn't leak into the top-level feed."
content = message.message.content.filter(
  (item) => item.type !== "text" && item.type !== "thinking");

⤷ only the tool_use blocks survive the filter and continue to the next hop.

{ "kind": "update", "update": {
    "sessionUpdate": "tool_call",
    "toolCallId": "toolu_02Grep",
    "title": "grep \"retry\" src/delivery",
    "kind": "search", "status": "pending",
    "rawInput": { "pattern": "retry", "path": "src/delivery" },
    "_meta": { "claudeCode": {
        "toolName": "Grep",
        "parentToolUseId": "toolu_01TaskAa" } }   // ← the whole tree
} }

⤷ _meta is ACP's sanctioned extension point, but nothing about this key is standard: a generic ACP client renders this call flat, as a sibling of the Task it belongs to.

// no tool_call frame is ever emitted for these:
shouldEmitToolCall = toolName !== "TodoWrite"
                     && !isTaskTool(toolName)   // TaskCreate/Update/List/Get
// at tool_result, mutate an in-adapter Map instead:
applyTaskCreate(state, input, output)  // keeps subject, status,
applyTaskUpdate(state, input)          // activeForm, description
// TaskList / TaskGet: invisible — reads never cross

{ "kind": "update", "update": {
    "sessionUpdate": "plan",
    "entries": [
      { "content": "Add retry queue",
        "status": "in_progress", "priority": "medium" },
      { "content": "Wire dead-letter alerts",
        "status": "pending",     "priority": "medium" }
    ] } }

⤷ entries carry content + status only; priority is hardcoded "medium". Dropped on the adapter floor: taskId · description · activeForm · blocks/blockedBy · owner · metadata. TodoWrite takes the same door (tools.js:553) and loses its activeForm too. Fold: PlanItem is replaced wholesale per frame — no diffing possible without ids.

{ "jsonrpc": "2.0", "id": 19, "method": "session/request_permission",
  "params": {
    "sessionId": "sess_9f3k…",
    "toolCall": {
      "toolCallId": "toolu_01ExitPlan",
      "title": "Ready to code?",
      "kind": "switch_mode",
      "content": [ { "type": "content", "content": {
          "type": "text", "text": "## Plan\n1. Add retry queue…" } } ],
      "rawInput": { "plan": "## Plan\n1. Add retry queue…" }
    },
    "options": [
      { "optionId": "auto",        "name": "Yes, and use \"auto\" mode",       "kind": "allow_always" },
      { "optionId": "acceptEdits", "name": "Yes, and auto-accept edits",      "kind": "allow_always" },
      { "optionId": "default",     "name": "Yes, and manually approve edits", "kind": "allow_once"    },
      { "optionId": "plan",        "name": "No, keep planning",               "kind": "reject_once"   }
    ] } }

⤷ crosses to devices via the exact phase-⑤ machinery: permission_requested row + state snapshot; mobile renders option buttons it already knows how to render. A bypassPermissions option is prepended only when the adapter allows bypass.

{ "kind": "update", "update": {
    "sessionUpdate": "tool_call",
    "toolCallId": "toolu_01Bash",
    "title": "bun test --watch=false",
    "kind": "execute", "status": "pending",
    "content": [ { "type": "content", "content": {
        "type": "text", "text": "Run the test suite" } } ],
    "rawInput": { "command": "bun test --watch=false",
      "description": "Run the test suite",
      "run_in_background": true },
    "_meta": { "claudeCode": { "toolName": "Bash" } } } }

// long-running: heartbeat patches, NOT output
{ "sessionUpdate": "tool_call_update",
  "toolCallId": "toolu_01Bash", "status": "in_progress",
  "_meta": { "claudeCode": { "toolResponse":
      { "elapsedTimeSeconds": 45 } } } }

// completion — stdout lands once, in one piece
{ "sessionUpdate": "tool_call_update",
  "toolCallId": "toolu_01Bash", "status": "completed",
  "content": [ /* full output as text */ ], "rawOutput": { … } }

⤷ a client that advertises _meta["terminal_output"] = true unlocks the adapter's own lifecycle (_meta.terminal_info / terminal_output / terminal_exit on these same frames) — still adapter-owned, still not ACP's terminal/* methods.

{ "kind": "update", "update": {
    "sessionUpdate": "tool_call",
    "toolCallId": "toolu_01Wf",
    "title": "Workflow",            // default: title = tool name
    "kind": "other", "status": "pending",
    "rawInput": { "script": "export const meta = …", "args": { … } },
    "_meta": { "claudeCode": { "toolName": "Workflow" } } } }
// …then a single "completed" patch carrying the
// WorkflowOutput as rawOutput. That's the whole story:
// task_started / task_summary system frames → no case in the
// adapter's system-subtype switch → dropped. Sub-run activity
// crosses only as whatever agent() spawns emit (phase ⑩ rules).

// known-but-ignored types get an explicit `break`:
//   tool_use_summary · auth_status · prompt_suggestion ·
//   conversation_reset · control_request_progress
// anything else — active_goal included — hits:
default: unreachable(message)   // logged, dropped, never emitted