Part seven of the Handmade Claude Code campaign: the agent moves into the editor. The Agent Client Protocol is how editors — Zed, Neovim, JetBrains, anything that speaks it — drive a coding agent: they start it, open sessions, send prompts, watch the answer stream in, see every tool call, answer its permission questions, cancel it, and lend it their own unsaved files and MCP servers. This part makes yours a citizen of that world — the same loop, one more front end.

This session continues the agent you built in parts one to six, in the same repository. The protocol client is yours to write, like the MCP client was: JSON-RPC 2.0 over stdio, one object per line, in both directions.

Starting

<command> --acp

reads JSON-RPC from stdin and writes it to stdout — nothing else goes to stdout — until stdin closes. --yes applies here too. The working directory comes from the session, not from -C.

The methods

Client → agent, requests:

• initialize {protocolVersion: 1, clientCapabilities: {fs: {readTextFile, writeTextFile}}, clientInfo} → {protocolVersion: 1, agentCapabilities: {...}, agentInfo, authMethods: []}.
• session/new {cwd, mcpServers: [{name, command, args, env: [{name, value}]}]} → {sessionId}. cwd is the working directory of that session — instructions, tools and paths resolve against it, exactly as -C did. The mcpServers are started for the session like .mcp.json entries.
• session/prompt {sessionId, prompt: [{type: "text", text}]} → runs a turn; the response {stopReason} comes only when the turn is over: end_turn, or cancelled after a session/cancel.

Client → agent, notification: session/cancel {sessionId} — stop the turn: kill a running tool, make no further model call, answer the pending prompt with stopReason: "cancelled".

Agent → client, notifications session/update {sessionId, update}, where update.sessionUpdate is:

• agent_message_chunk {content: {type: "text", text}} — the answer, as it streams (every text_delta, or the final text when the model did not stream), before the prompt response.
• tool_call {toolCallId, title, kind, status: "pending" | "in_progress", rawInput} — when a tool starts; for bash the title carries the command and kind is execute.
• tool_call_update {toolCallId, status: "completed" | "failed", content: [{type: "content", content: {type: "text", text}}], rawOutput} — when it ends, with its output.

Agent → client, requests:

• session/request_permission {sessionId, toolCall: {toolCallId, title, kind, rawInput}, options: [{optionId: "allow", name, kind: "allow_once"}, {optionId: "reject", name, kind: "reject_once"}]} — for a call the rules do not permit, instead of the TUI's question. The reply {outcome: {outcome: "selected", optionId}} decides; {outcome: {outcome: "cancelled"}} denies.
• fs/read_text_file {sessionId, path, line?, limit?} → {content} and fs/write_text_file {sessionId, path, content} → null — only when the client declared the capability: then the read and write tools go through the editor (which has the unsaved buffers) instead of the disk. Paths are absolute.

Ids: the client picks ids for its requests and the agent for its own; a reply carries the id of the request it answers. The checks drive the protocol from a shell script, so line order in the output is what they read: a chunk is streamed when it is written before the response.

The judges

The quality panel — architecture, performance, code quality, test quality, technical governance and DX review — sits on the rungs where its subject is decided, one verdict per judge per rung, on top of the rung's own points. There is no closing review: what you build is judged as you build it, and a rung you never reach is a verdict you never get.

The ladder

• Set up and carry parts one to six forward (10)
• Initialize (20)
• A session has a working directory (20)
• The answer streams as chunks (30)
• Tool calls are reported (30)
• Permission is asked (40)
• Cancel (30)
• The editor's files (20)
• The client's MCP servers (20)