Reference: Agent Client Protocol surface

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107

# Reference: Agent Client Protocol surface

> Neutral description of what `mm -acp` exposes over JSON-RPC 2.0 on stdio, through `github.com/coder/acp-go-sdk` v0.13.5.

## Transport

| Aspect | Value |
|--------|-------|
| Input | stdin, one JSON-RPC message per line. |
| Output | stdout, JSON-RPC messages only. |
| Logs | stderr: banner, warnings, `[acp] …` lines, SDK logger. |
| Lifetime | Until the client closes stdin or the process context is cancelled. |

## `initialize` response

| Field | Value |
|-------|-------|
| `protocolVersion` | `1` |
| `agentCapabilities` | `loadSession: true` when `sessions.enabled` is set, absent (false) otherwise. Everything else absent (false): no image or audio prompts, no HTTP MCP. |
| `agentInfo.name` | `bob` |
| `agentInfo.title` | `Bob (bash-first agent)` |
| `agentInfo.version` | `0.11.0` |
| `authMethods` | `[]` |

## Methods

| Method | Behaviour |
|--------|-----------|
| `initialize` | Logs the client name and protocol version on stderr; returns the values above. |
| `authenticate` | Returns an empty response. |
| `session/new` | Creates a session with a time-sortable id (`20260916-101530-4f2a9c1e`) and the request's `cwd`, a fresh history holding the system prompt, and an empty allow-always set. `mcpServers` are counted in the log and ignored. Once the response is written, sends an `available_commands_update` notification listing the slash commands (see below). With `sessions.enabled`, writes `<cwd>/<sessions.dir>/<id>.json` at once and rewrites it after every turn, `/new` and `/compact`. |
| `session/prompt` | Runs one generation on the session's history, or executes a slash command without consulting the model. Turns are serialised process-wide. |
| `session/cancel` | Cancels the turn in flight for that session. |
| `session/load` | With `sessions.enabled`: reads `<cwd>/<sessions.dir>/<sessionId>.json`, replaces its system prompt by the current one, registers the session (empty allow-always set), sends the replay (below) then an `available_commands_update`, and answers `{}`. Unknown id or unreadable file: `invalid params` carrying the `sessionId` and the error. Without `sessions.enabled`: `method not found`. |
| `session/set_mode`, `session/set_config_option`, `session/list`, `session/resume`, `session/close`, `logout` | `method not found`. |

## `session/load` replay

Sent before the response, one notification per element of the stored history, in order. The system prompt is not sent.

| Stored element | Notification |
|----------------|--------------|
| User message | `user_message_chunk` with its text. |
| Compression summary (user-role message marked by `/compact`) | `agent_message_chunk` with `🗜️ ` followed by the summary. |
| Model text | `agent_message_chunk`. |
| Tool call with its recorded response | `tool_call` with `toolCallId` = the call's ref, `title` and `kind` as the live tool would give (`bash: <command>` execute, `read_file: <path>` read, `write_file`/`edit_file` edit, `read_skill: <name>` read), `status: completed`, `rawInput`, `rawOutput.output` and a `text` content holding the output. |
| Tool call without a recorded response | `tool_call` with `status: failed` and no content. |

No tool runs during a replay. Logged as `[acp] session <id> loaded from <dir>: N message(s) replayed`.

## `session/prompt`

| Aspect | Behaviour |
|--------|-----------|
| Unknown `sessionId` | `invalid params` error carrying the `sessionId`. |
| Prompt content | `text` blocks concatenated; a `resource_link` becomes `\n[attached file: <path without file://>]`; other block types are ignored. Then every `@path` in the text that names an existing file or directory under the session's `cwd` (or an absolute / `~` path) appends `\n[attached file: <absolute path>]` or `\n[attached directory: …]`, once per path, and is logged as `[acp] session <id>: attached <path>`. |
| Slash command | When the flattened text, trimmed, is exactly `/new` or `/compact`, no generation runs; the command answers with one `agent_message_chunk` and `stopReason: end_turn`. |
| `/new` | The session's history is reset to the system prompt alone, the engine's last input-token count is forgotten, the chunk is `🆕 New session: N message(s) forgotten.`. The session id, `cwd` and allow-always grants are kept. With `sessions.enabled`, the conversation so far is saved under a new id first (logged `previous conversation kept as <id>`; nothing saved when it was empty) and the session's own file is rewritten with the fresh history. Logged as `[acp] session <id>: new session, N message(s) forgotten`. |
| `/compact` | The history is compressed with the `context` settings, forced (the threshold is ignored, `keepLastTurns` is honoured). The chunk is `🗜️ compressed N messages → 1 summary + N kept (… tokens, …s)`, or `🗜️ nothing to compact: N message(s), no turn older than the last K` (history unchanged), or `[compact: failed, history kept: <explanation>]` (history unchanged). The token count is forgotten only when the history changed. Waits for a running turn: turns are serialised. Logged as `[acp] session <id>: /compact — <line>`. |
| History | The full history returned by the engine is kept, even after a failure or a cancellation; a question with no answer at all is removed. |
| Success | `stopReason: end_turn`. |
| Cancelled | `stopReason: cancelled`. |
| Failure | `internal error` with `error: <one-line explanation>`. |
| Log line | `[acp] turn done: N command(s) · N file op(s) · N skill(s)` on stderr. |

## `session/update` notifications sent

| Update | When |
|--------|------|
| `available_commands_update` | Once per session, right after the `session/new` response has been written (the editor must know the session id first, or it drops the update). Lists the slash commands `session/prompt` intercepts. Also sent at the end of a `session/load` replay. |
| `agent_message_chunk` (text) | Each streamed chunk of the model's answer, whitespace preserved; also the one-line confirmation of a slash command. |
| `tool_call` status `pending` | Before a tool runs; carries `title`, `kind`, `rawInput`, and `locations` with the absolute path when a file is involved. |
| `tool_call_update` status `in_progress` | Permission granted, tool executing. |
| `tool_call_update` status `completed` or `failed` | Tool finished; `content` is a `diff` for file changes, else a `text` block with the output; `rawOutput.output` always carries the output. |

## Available commands

| `name` | `description` | `input` |
|--------|---------------|---------|
| `new` | `Clear the history and start a new session` | none |
| `compact` | `Compress the history now, keeping the last turns` | none |

Clients display the name with a leading slash and send it back as the text of a `session/prompt`.

## `session/request_permission` requests sent

Sent before `bash`, `read_file`, `write_file` and `edit_file` run; never for `read_skill`.

| Option id | Kind | Effect |
|-----------|------|--------|
| `allow` | `allow_once` | Runs the tool. |
| `allow_always` | `allow_always` | Runs the tool and skips the dialog for that tool name for the rest of the session. |
| `reject` | `reject_once` | Does not run; the model receives `[command rejected by the user]`. |

A transport error or a `cancelled` outcome counts as a rejection.

## Tool kinds

| `mm` kind | ACP `ToolKind` | Tools |
|-----------|----------------|-------|
| `execute` | `execute` | `bash` (and any unknown kind) |
| `read` | `read` | `read_skill`, `read_file` |
| `edit` | `edit` | `write_file`, `edit_file` |

## Tool call identifiers

`call_1`, `call_2`, … numbered per process and never reset.