State of the art of the Agent Client Protocol (ACP), and whether it can serve as heartbeat's sensor and actuator.
Researched 2026-09-18 in session 4f0a68f9-1435-4150-bb9e-84567dc7db02 (harness-exploration-status). Heartbeat itself: Heartbeat.
JSON-RPC 2.0 over stdio; the client (editor or supervisor) spawns and owns the agent subprocess. Protocol v1, by Zed; spec at agentclientprotocol.com.
| Aspect | Detail |
|---|---|
| Lifecycle | initialize (capability negotiation) → session/new {cwd, mcpServers} → session/prompt per turn. The response carries stopReason (end_turn | max_tokens | max_turn_requests | refusal | cancelled). session/load replays history; session/resume/close/delete are newer and capability-gated. |
| Event stream | session/update notifications during a turn: tool_call (toolCallId, kind: read|edit|delete|move|search|execute|think|fetch|switch_mode|other, status: pending|in_progress|completed|failed, rawInput, rawOutput, locations, diff content), tool_call_update, agent_thought_chunk (thinking first-class), plan (TodoWrite-like, full replacement), available_commands_update, current_mode_update, usage_update (tokens, cost). |
| Control surface | Client-side authority. session/request_permission: the agent asks, the client picks an option (allow_once/always, reject_once/always). session/cancel: the agent MUST end the turn cancelled; subprocess kill is the deterministic backstop. With fs and terminal capabilities advertised, file writes and shell commands route physically through the client. |
| Adoption | ~50 agents; JetBrains, Google, GitHub; the ACP Registry (Jan 2026, Zed + JetBrains). Anthropic has NOT adopted it natively: Claude Code participates via agentclientprotocol/claude-agent-acp, built on the Agent SDK. |
Measured against a supervision engine's needs.
| Need | ACP |
|---|---|
| Pre-execution veto | Only when the agent volunteers a permission request (mode-dependent); tool_call notifications are fire-and-forget. |
| Input rewriting | None on the wire: option selection only, no updatedInput equivalent. |
| Mid-turn redirect | Undefined; portably, cancel plus a new prompt. |
| Subagents, hook events, skill invocations, compaction | Not in core; only via adapter-specific _meta extensions. |
| Claude hook events | The claude-agent-acp adapter consumes them internally, never forwarding them. Skill invocations map to kind: "other". |
A hybrid: heartbeat's internal event model is a superset with two frontends. ACP validates the heartbeat shape (external supervisor process, typed event stream, client-side permission authority) but falls short as the Claude Code sensor and actuator.
| Frontend | For | How |
|---|---|---|
| Native | Claude Code | Hooks, transcript JSONL and telemetry: a strictly better sensor and actuator (guaranteed PreToolUse veto, input rewriting, hook identity, lossless transcript). |
| ACP | Other agents: Gemini CLI, Goose, Codex-over-ACP | Advertise fs + terminal, decide every permission request, cancel plus kill for hard stops. Per-capability fidelity flags tell the Z3 layer which preconditions are enforceable and which only observable, per agent. |
The spec moves fast (usage_update, session/resume and elicitation are all post-v1). Pin adapter versions like peek versions.