> ## Documentation Index
> Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating from v1
> A complete guide to ACP v2 for implementers familiar with v1: breaking changes, new features, and step-by-step migration
ACP v2 is a consolidation release. It redesigns the prompt lifecycle and allows for more flexible session state patterns, unifies streaming and non-streaming updates, makes the schema forward-compatible by default, and removes protocol surface that the ecosystem had already moved away from.
Migrating does not mean dropping v1. v1-only Agents and Clients will remain common for some time, so implementers should support both versions side by side: negotiate the version per connection, keep your v1 support working, and add v2 behind feature flags until it stabilizes. See [Supporting v1 and v2 side by side](#supporting-v1-and-v2-side-by-side) for how to structure this.
If you only remember five things, remember these:
1. **The `session/prompt` response no longer ends the turn.** It acknowledges acceptance. Foreground progress and completion arrive as `state_update` notifications, and the stop reason moved there too.
2. **Updates are upserts.** Messages, tool calls, and plans are patched by ID with uniform semantics: omitted field = unchanged, `null` = cleared, value = replaced, chunks append.
3. **The Client file system, terminal execution, and session modes APIs are gone.** Agent-owned terminal output is a separate display-only v2 surface; use client-provided MCP servers when the Agent needs Client-side tools.
4. **Capabilities were reorganized.** One `capabilities` + required `info` field on both sides, session-scoped groups nested under `session`, object support markers instead of booleans, and a required baseline of session methods.
5. **Everything is extensible now.** Enums and tagged unions accept unknown values. `_`-prefixed values are yours, the rest are reserved for future ACP versions.
## Scope: stable v2 and draft surfaces
This guide describes the stable v2 baseline (`schema/v2/schema.json`). The v2 protocol surface as a whole is still labeled draft, so gate **v2 support behind explicit version negotiation and feature flags until it stabilizes.**
The unstable schema (`schema/v2/schema.unstable.json`) layers opt-in draft features on top of that baseline. Negotiating `protocolVersion: 2` does **not** imply any of them. Gate each behind its own capability or feature flag the same as v1.
## Version negotiation
The mechanism is unchanged: the Client sends the latest protocol version it supports in `initialize`, and the Agent responds with the same version if supported, or its own latest version otherwise. To use v2, send `"protocolVersion": 2`. An Agent that only supports v1 will answer with `"protocolVersion": 1`, and the Client decides whether to continue with v1 or disconnect.
Treat v2 support as additive. Keep serving `protocolVersion: 1` peers when you add v2: an Agent that drops v1 cuts itself off from existing Clients, and a Client that drops v1 loses access to existing Agents. Each side selects its v1 or v2 surface per connection based on the negotiated version.
Nothing about v2 changes the underlying JSON-RPC framing, so a single connection always speaks exactly one negotiated version after `initialize`.
## At a glance
### Method changes
| v1 method | v2 |
| --------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `initialize` | Unchanged name. Params and result restructured |
| `authenticate` | Renamed to `auth/login` |
| `logout` (gated by `agentCapabilities.auth.logout`) | Renamed to `auth/logout`. Required when `authMethods` is non-empty; no logout capability marker |
| `session/new` | `mcpServers` now optional. Response no longer includes `modes` |
| `session/load` | **Removed**. Use `session/resume` with `"replayFrom": { "type": "start" }` |
| `session/resume` | Gains optional `replayFrom`. Required (no capability marker) |
| `session/list` | Required. No capability |
| `session/close` | Required. No capability |
| `session/delete` | Unchanged. Still optional via `session.delete` capability |
| `session/prompt` | Unchanged shape. **Response semantics redesigned** (see [Prompt lifecycle](#the-new-prompt-lifecycle)) |
| `session/cancel` | Unchanged name. Completion now reported via `state_update` instead of the prompt response |
| `session/set_mode` | **Removed**. Use `session/set_config_option` |
| `session/set_config_option` | Unchanged |
| `session/request_permission` | Unchanged name. Params restructured (required `title`, optional `subject`) |
| `session/update` | Unchanged name. Update variants changed (see below) |
| `fs/read_text_file`, `fs/write_text_file` | **Removed** |
| `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` | **Removed** |
| `$/cancel_request` | Unchanged |
### `session/update` variant changes
| v1 `sessionUpdate` | v2 |
| --------------------------- | ------------------------------------------------------------------------------------------- |
| `user_message_chunk` | Kept. `messageId` now required |
| `agent_message_chunk` | Kept. `messageId` now required |
| `agent_thought_chunk` | Kept. `messageId` now required |
| - | **New:** `user_message`, `agent_message`, `agent_thought` whole-message upserts |
| - | **New:** foreground `state_update` (`running`, `idle`, `requires_action`) with stop reasons |
| `tool_call` | **Removed**. The first `tool_call_update` for a `toolCallId` creates the tool call |
| `tool_call_update` | Kept. Now an explicit upsert with omit/`null`/value patch semantics |
| - | **New:** `tool_call_content_chunk` for streaming individual content items |
| - | **New:** `terminal_update` for Agent-owned display terminal state and replay |
| - | **New:** `terminal_output_chunk` for appending display terminal bytes |
| `plan` | Replaced by `plan_update` with a `planId` and a `type` discriminator |
| `current_mode_update` | **Removed**. Modes are config options. Use `config_option_update` |
| `available_commands_update` | Kept. Command `input` now carries a required `type` discriminator |
| `config_option_update` | Unchanged |
| `session_info_update` | Unchanged |
| `usage_update` | Unchanged |
## Initialization
### Role-agnostic `info` and `capabilities`
v1 used role-specific field names: the Client sent `clientCapabilities` and optional `clientInfo`, and the Agent returned `agentCapabilities` and optional `agentInfo`. v2 uses the same two field names in both directions (`capabilities` and `info`), and `info` is now **required** on both sides.
```json v1 request theme={null}
{
"jsonrpc": "2.0",
"id": 0,
"method": "initialize",
"params": {
"protocolVersion": 1,
"clientCapabilities": {
"fs": { "readTextFile": true, "writeTextFile": true },
"terminal": true
},
"clientInfo": { "name": "my-client", "version": "1.0.0" }
}
}
```
```json v2 request theme={null}
{
"jsonrpc": "2.0",
"id": 0,
"method": "initialize",
"params": {
"protocolVersion": 2,
"info": {
"name": "my-client",
"title": "My Client",
"version": "1.0.0"
},
"capabilities": {}
}
}
```
```json v1 response theme={null}
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"protocolVersion": 1,
"agentCapabilities": {
"loadSession": true,
"promptCapabilities": { "image": true, "embeddedContext": true },
"mcpCapabilities": { "http": true, "sse": false },
"sessionCapabilities": {
"list": {},
"resume": {},
"close": {}
}
},
"authMethods": [],
"agentInfo": { "name": "my-agent", "version": "0.3.0" }
}
}
```
```json v2 response theme={null}
{
"jsonrpc": "2.0",
"id": 0,
"result": {
"protocolVersion": 2,
"info": {
"name": "my-agent",
"title": "My Agent",
"version": "0.3.0"
},
"capabilities": {
"session": {
"prompt": {
"image": {},
"embeddedContext": {}
},
"mcp": {
"stdio": {},
"http": {}
},
"delete": {},
"additionalDirectories": {}
}
},
"authMethods": []
}
}
```
Both responses above have an empty `authMethods` array. In v2, omitting `authMethods` has the same availability meaning: the Agent does not advertise the authentication surface, and Clients **MUST NOT** call `auth/login` or `auth/logout`.
### Support markers are objects, not booleans
In v1, capability support was a mix of booleans (`"image": true`) and objects (`"list": {}`). In v2, every support marker is an object: supplying `{}` (or an object with fields) means supported, and omitting the key or supplying `null` means unsupported.
This means checks like `promptCapabilities.image === true` become presence checks: `capabilities.session.prompt.image != null`. The object shape leaves room for each capability to grow fields or extend with `_meta` without another breaking change.
### Capability reorganization
* All session-scoped capability groups now live under `capabilities.session`. What was `agentCapabilities.promptCapabilities` is now `capabilities.session.prompt`, and `agentCapabilities.mcpCapabilities` is now `capabilities.session.mcp`.
* `capabilities.session` itself is **optional**, so agents that don't do session-based prompting (for example, agents that only serve specialized extension surfaces) can omit it entirely. Currently there isn't protocol support for this, but several experiments are in flight and we are making sure non-session components can be expressed via capabilities.
* `loadSession` is gone along with `session/load` (see [Session setup](#session-setup-and-lifecycle)).
* The individual `list`, `resume`, and `close` markers are gone: advertising `capabilities.session` at all now **requires** supporting the baseline methods `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Optional extras such as `session.delete`, `session.additionalDirectories`, `session.prompt`, and `session.mcp` keep their own markers.
* The v1 Client capabilities `fs` and `terminal` are removed entirely (see [Client file system and terminal execution](#client-file-system-and-terminal-execution-removed)). Stable v2 currently defines no standard Client capability fields. Agent-owned terminal display is baseline behavior, not a Client execution capability.
## Authentication
The auth methods are grouped under an `auth/` prefix:
* `authenticate` → `auth/login`. The params are unchanged (`methodId` selecting one of the advertised auth methods). The descriptor's identifier field is renamed from `id` to `methodId` to match, and its `type` discriminator is now required.
* `logout` → `auth/logout`. In v1, logout support was opt-in via a capability marker. In v2, returning one or more valid entries in `authMethods` advertises the authentication surface, and the Agent **MUST** implement both `auth/login` and `auth/logout`. If `authMethods` is omitted or empty, Clients **MUST NOT** call either method. There is no logout support marker; `capabilities.auth` remains orthogonal and advertises only authentication-related extensions.
```json theme={null}
{
"jsonrpc": "2.0",
"id": 1,
"method": "auth/login",
"params": { "methodId": "agent-login" }
}
```
### Auth methods
Each entry in `authMethods` now uses `methodId` instead of `id`, and carries a required `type` discriminator so future auth flows can be introduced without breaking existing implementations:
```json theme={null}
{
"methodId": "agent-login",
"type": "agent",
"name": "Agent login",
"description": "Sign in using the agent's login flow"
}
```
Including this entry in an initialize response requires the Agent to support both `auth/login` and `auth/logout`.
Stable v2 defines `type: "agent"`. Custom types **MUST** begin with `_`. Unknown values without a leading `_` are reserved for future ACP versions.
## The new prompt lifecycle
This is the most significant semantic change in v2. Read this section even if you skim the rest. In short, everything that v1 expressed through the pending `session/prompt` request moved into `session/update` notifications:
| Foreground signal | v1 | v2 |
| ----------------------- | ---------------------------------------------- | ---------------------------------------------------- |
| Prompt accepted | Implicit | `session/prompt` response (`{}`) |
| User message in history | Implicit (the request itself) | `user_message` update with agent-owned `messageId` |
| Foreground work running | `session/prompt` still pending | `state_update` with `state: "running"` |
| Foreground work waiting | Implicit (pending permission request) | `state_update` with `state: "requires_action"` |
| Foreground work ended | `session/prompt` response with `stopReason` | `state_update` with `state: "idle"` and `stopReason` |
| Cancellation confirmed | Prompt response with `stopReason: "cancelled"` | Idle `state_update` with `stopReason: "cancelled"` |
### v1: the response is the turn
In v1, `session/prompt` stayed pending for the entire turn. The Agent streamed `session/update` notifications while working, and the eventual response carried the `stopReason` that ended the turn:
```json theme={null}
{ "jsonrpc": "2.0", "id": 2, "result": { "stopReason": "end_turn" } }
```
This entangled prompt acceptance with turn completion, which made replay, multi-client sessions, background work, and queued messages awkward to express.
### v2: the response is an acknowledgment
In v2, the Agent **MUST** respond to `session/prompt` as soon as it has *accepted* the prompt, with an empty result:
```json theme={null}
{ "jsonrpc": "2.0", "id": 2, "result": {} }
```
Everything else happens through `session/update` notifications:
1. **User message acknowledgment.** After accepting the prompt, the Agent **MUST** report where the user message was inserted into session history, either as a `user_message` update with a full `content` array or as streamed `user_message_chunk` updates. This update is the source of truth for the agent-owned `messageId`:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123",
"update": {
"sessionUpdate": "user_message",
"messageId": "msg_user_8f7a1",
"content": [{ "type": "text", "text": "Can you analyze this code?" }]
}
}
}
```
2. **Running state.** When foreground work starts or resumes, the Agent **MUST** send a `state_update` with `"state": "running"`.
3. **Output.** Messages, thoughts, plans, and tool calls stream as before (with the changes described in the following sections).
4. **Completion.** When the Agent is ready to process a new prompt, it **MUST** report `idle`. When the transition ends foreground work, it **MUST** include the stop reason:
```json theme={null}
{
"jsonrpc": "2.0",
"method": "session/update",
"params": {
"sessionId": "sess_abc123",
"update": {
"sessionUpdate": "state_update",
"state": "idle",
"stopReason": "end_turn"
}
}
}
```
### Session states
`state_update` is new in v2 and reports foreground work using one of three stable states (extensible like all v2 enums):
* `running`: Foreground work is in progress.
* `idle`: The Agent is ready to process a new prompt. Carries a `stopReason` when the transition ends foreground work.
* `requires_action`: Foreground work is blocked on user action. Agents **SHOULD** send this while waiting on a permission response, and another `running` update when work resumes.
Background activity can continue and emit other `session/update` notifications while the Agent reports `idle`. Those notifications do not change the state.
The stop reasons themselves are unchanged from v1 (`end_turn`, `max_tokens`, `max_turn_requests`, `refusal`, `cancelled`). They just moved from the `session/prompt` response to the idle `state_update` and describe why foreground work stopped.
### Cancellation
`session/cancel` is unchanged as a notification, but confirmation moved with the rest of the lifecycle: instead of responding to `session/prompt` with `"stopReason": "cancelled"`, the Agent **MUST** finish sending any pending updates and then send an idle `state_update` with the `cancelled` stop reason. Clients still respond to all pending `session/request_permission` requests with the `cancelled` outcome and **SHOULD** accept tool-call updates that arrive after sending `session/cancel`.
### Why this matters beyond bookkeeping
Because foreground progress is now expressed entirely in notifications, the same message flow works for history replay on `session/resume`, multiple clients observing one session, and future agent-initiated or queued work.
## Messages and message IDs
### Message IDs are required
Every message chunk and message update in v2 **MUST** carry a `messageId`. In v1, `messageId` was optional on chunks. Message IDs are opaque strings generated by the Agent: the Agent owns session history, so it is the single source of message identity. All chunks of one message share one `messageId`. A changed `messageId` starts a new message.
### Whole-message upserts
Alongside the chunk updates, v2 adds `user_message`, `agent_message`, and `agent_thought` updates that carry a full `content` **array** (chunks carry a single content block). These are upserts keyed by `messageId`, with three-state patch semantics:
* **Omitted** `content` leaves existing content unchanged (useful for updating `_meta` or other fields without resending content).
* `content: null` **or** `content: []` clears the message content.
* A **concrete array** replaces all content currently stored for that message, including content accumulated from earlier chunks.
Chunks always **append** to whatever content is current. For example: `agent_message` with `content: [A]`, then `agent_message_chunk` with `B` renders as `[A, B]`. A later `agent_message` with `content: [C]` resets the message to `[C]`, and subsequent chunks append to that.
Use chunks for streaming. Use whole-message updates for replay, correction, or output that is already complete.
## Tool calls
### One upsert notification
v1 had `tool_call` (create) and `tool_call_update` (modify). In practice the split bought nothing, so v2 keeps only `tool_call_update`. The first update with an unseen `toolCallId` creates the tool call. Subsequent updates patch it. Only `toolCallId` is required, but the Agent **SHOULD** include `title` on the first report:
```json theme={null}
{
"sessionUpdate": "tool_call_update",
"toolCallId": "call_001",
"title": "Reading configuration file",
"kind": "read",
"status": "pending"
}
```
The patch semantics are the same three-state model as messages: omitted fields stay unchanged, `null` explicitly clears a field, and concrete values replace. Array fields such as `content` and `locations` are replaced wholesale when present. The field set (`title`, `kind`, `status`, `content`, `locations`, `rawInput`, `rawOutput`) and `kind` values are unchanged from v1. The `status` enum adds `cancelled`, and both enums are now extensible.
### Streaming tool-call content
v2 adds `tool_call_content_chunk`, which **appends** a single `ToolCallContent` item to a tool call instead of resending the whole array:
```json theme={null}
{
"sessionUpdate": "tool_call_content_chunk",
"toolCallId": "call_001",
"content": {
"type": "content",
"content": { "type": "text", "text": "Checked syntax..." }
}
}
```
Chunks and updates compose exactly like message chunks and updates: a `tool_call_update` that includes `content` replaces the accumulated content. Later chunks append to it.
### Agent-owned terminal display
v2 retains a `terminal` `ToolCallContent` shape, but changes its ownership and meaning. It is now only a reference to a display terminal owned by the Agent:
```json theme={null}
{
"type": "terminal",
"terminalId": "term_001"
}
```
The reference contains no mutable state. The Agent reports that separately with a `terminal_update` upsert keyed by `terminalId`:
```json theme={null}
{
"sessionUpdate": "terminal_update",
"terminalId": "term_001",
"command": "cargo test",
"cwd": "/workspace/project",
"output": {
"data": "cnVubmluZyAxMjMgdGVzdHMNCg=="
},
"exitStatus": {
"exitCode": 0,
"signal": null
}
}
```
Only `terminalId` is required. `command`, `cwd`, `output`, `exitStatus`, and `_meta` are patch fields: omission leaves the stored value unchanged, `null` clears it, and a concrete value replaces it. On a first-seen terminal, omitted fields start unknown or empty. Every supplied `cwd` must be absolute.
`output` is an authoritative replacement snapshot for replay, correction, or resynchronization. Its required `data` field is RFC 4648 base64-encoded bytes and is the complete byte sequence the Agent wants the Client to retain for the terminal at that point. A concrete snapshot replaces all previously stored bytes; Clients must not merge or splice bytes from the previous snapshot into it. Optional nullable `output._meta` is snapshot-scoped; omission and `null` both mean no snapshot metadata was provided.
A concrete `exitStatus` marks the terminal as exited. Its optional nullable `exitCode` and `signal` fields use omission or `null` when unavailable. Optional nullable `exitStatus._meta` is scoped to that exit information and likewise treats omission and `null` as equivalent. Conventional POSIX signal names include `SIGTERM`, `SIGKILL`, and `SIGINT`; other platforms may use platform-specific names. For example: `"exitStatus": { "signal": "SIGTERM" }`.
For efficient live output, the Agent sends append updates:
```json theme={null}
{
"sessionUpdate": "terminal_output_chunk",
"terminalId": "term_001",
"data": "cGFzc2VkDQo="
}
```
Each chunk's `data` is independently base64-encoded. Decode each chunk separately, then append the resulting bytes in received order for that terminal; do not concatenate encoded strings before decoding. Chunk boundaries may split UTF-8 code points and ANSI escape sequences, so text and terminal parsers retain state between chunks. A later `terminal_update.output` snapshot replaces all bytes accumulated so far, and subsequent chunks append to that replacement.
A Client may use an isolated terminal emulator, but it only needs to provide a safe sanitized transcript fallback. The surface is display-only: it has no input, resize, interrupt, kill, wait, release, or execution semantics.
## Diff content
The v1 diff shape (a single `path` with `oldText`/`newText`) could not distinguish a deleted file from an emptied one, had no way to express renames, copies, or binary changes, and forced clients to compute renderable diffs themselves. v2 replaces it with structured changes plus optional renderable patch text:
```json theme={null}
{
"type": "diff",
"changes": [
{
"operation": "modify",
"path": "/home/user/project/src/config.json",
"fileType": "text",
"mimeType": "application/json"
}
],
"patch": {
"format": "git_patch",
"text": "diff --git /home/user/project/src/config.json /home/user/project/src/config.json\n--- /home/user/project/src/config.json\n+++ /home/user/project/src/config.json\n@@ -1,3 +1,3 @@\n {\n- \"debug\": false\n+ \"debug\": true\n }\n"
}
}
```
* `changes` (required) is the authoritative list of file-level operations. `add`, `delete`, and `modify` carry a `path`. `move` and `copy` carry `oldPath` and `path`. Each change may carry an optional `fileType` (`text`, `binary`, `directory`, `symlink`) and `mimeType`. Clients can build file trees and summaries from `changes` without parsing any patch text.
* `patch` (optional) carries renderable text for some or all changes and **MUST** be consistent with `changes`. Stable v2 defines `git_patch` as one or more `diff --git` sections in Git's `--patch` (`-p`) text format. Paths **MUST** be absolute. Surrounding commit metadata and email envelopes **MUST NOT** be included. Agents **SHOULD** provide `patch` whenever feasible. Clients **MUST** handle diffs where `patch` is omitted or `null` (binary changes, symlink retargets, and similar cases have no useful text rendering).
A deleted file is now simply:
```json theme={null}
{
"type": "diff",
"changes": [
{
"operation": "delete",
"path": "/home/user/project/old_file.txt",
"fileType": "text"
}
]
}
```
There is no mechanical mapping from v2 diffs back to `oldText`/`newText`. When migrating a v1 client, render `patch.text` according to `patch.format`, using `changes` for headers, file trees, and non-text cases.
## Permission requests
`session/request_permission` no longer takes a bare `toolCall`. The prompt copy and the subject of the request are now separate concerns:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 5,
"method": "session/request_permission",
"params": {
"sessionId": "sess_abc123",
"title": "Run this script?",
"description": "The agent wants to execute scripts/setup.sh in your project.",
"subject": {
"type": "tool_call",
"toolCall": {
"toolCallId": "call_001",
"title": "Execute setup script",
"kind": "execute",
"status": "pending"
}
},
"options": [
{ "optionId": "allow", "name": "Allow once", "kind": "allow_once" },
{ "optionId": "deny", "name": "Deny", "kind": "reject_once" }
]
}
}
```
* `title` is **required**: human-readable text for the permission prompt itself. It does not update any tool call's displayed title.
* `description` is optional supporting copy.
* `subject` is an optional tagged union describing *what* needs permission. Stable v2 defines `type: "tool_call"`, whose `toolCall` payload is the same `ToolCallUpdate` upsert shape used in session updates, and `type: "command"`, which describes an Agent-executed command. Requests may omit `subject` entirely for approvals without structured context, and unknown subject types should be preserved when proxying and either rendered generically or declined by policy.
In v1, agents routinely stuffed permission prompt text into the tool call's `title`, mutating displayed tool state as a side effect. In v2, put prompt copy in `title`/`description` and let `subject.toolCall` carry only genuine tool-call state.
A command permission subject is self-contained rather than a patch:
```json theme={null}
{
"type": "command",
"command": "cargo test",
"cwd": "/workspace/project",
"toolCallId": "call_001",
"terminalId": "term_001"
}
```
`command` and `cwd` are required, and `cwd` must be absolute. `toolCallId`, `terminalId`, and `_meta` are optional and nullable; omission and `null` are equivalent and mean the value was not provided. The IDs only associate the permission with displayed state and may be absent when permission is requested before execution. Approval authorizes the Agent to execute the command; it never asks the Client to execute it.
`options` and the response shape are unchanged: options carry `optionId`, `name`, and `kind` (`allow_once`, `allow_always`, `reject_once`, `reject_always`), and the response outcome is `{ "outcome": "selected", "optionId": ... }` or `{ "outcome": "cancelled" }`. Both unions are extensible in v2, with one safety rule: an Agent that receives an outcome it does not understand **MUST NOT** treat it as approval.
While a permission request is pending, the Agent **SHOULD** report `state_update` with `requires_action`, and `running` again once resolved.
## Plans
The v1 `plan` update was a flat entries list with no identity and no room to grow. v2 replaces it with `plan_update`, whose payload is a tagged union keyed by a required `planId`:
```json v1 theme={null}
{
"sessionUpdate": "plan",
"entries": [
{
"content": "Check for syntax errors",
"priority": "high",
"status": "pending"
}
]
}
```
```json v2 theme={null}
{
"sessionUpdate": "plan_update",
"plan": {
"type": "items",
"planId": "plan-1",
"entries": [
{
"content": "Check for syntax errors",
"priority": "high",
"status": "pending"
}
]
}
}
```
Stable v2 defines the `items` plan type. The entry shape (`content`, `priority`, `status`, all required) is unchanged from v1. Entry priorities and statuses are now extensible enums, and `status` adds `cancelled`. Each `plan_update` for a given `planId` replaces that plan's entries, and the `planId` allows multiple plans per session and future plan content types (such as markdown or file-backed plans, which remain unstable) without another breaking change.
## Session setup and lifecycle
### `session/load` is gone. `session/resume` does both
v1 had two ways to reattach to a session: `session/load` (replays full history, gated by `loadSession`) and `session/resume` (no replay, gated by `sessionCapabilities.resume`). v2 keeps only `session/resume` with an optional `replayFrom` cursor:
```json theme={null}
{
"jsonrpc": "2.0",
"id": 3,
"method": "session/resume",
"params": {
"sessionId": "sess_abc123",
"cwd": "/home/user/project",
"replayFrom": { "type": "start" }
}
}
```
* Omit `replayFrom` (or send `null`) for v1 `resume` behavior: reattach without replay.
* `"replayFrom": { "type": "start" }` for v1 `load` behavior: the Agent replays the entire conversation as `session/update` notifications (using the same message, tool-call, and plan updates as live traffic) before responding.
The cursor is a tagged union so future versions can add replay-from-a-point variants without new methods.
### Consistent lifecycle requests
`session/new` and `session/resume` take the same shape of environment parameters: a required `cwd` (absolute path), plus optional `additionalDirectories` and `mcpServers`. Note that `mcpServers` was required (even if empty) on `session/new` in v1 and is now optional. Omitting it and sending `[]` are equivalent. Both responses carry the session's `configOptions`. Neither carries `modes` anymore.
`additionalDirectories` still requires the `session.additionalDirectories` capability and absolute paths, and each `session/resume` must send the full intended additional-root list. Omitting the field or sending `[]` activates no additional roots rather than restoring previous ones.
### Baseline methods
As covered under [Initialization](#capability-reorganization), advertising `capabilities.session` commits the Agent to `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`. Clients can rely on listing, resuming, and closing sessions without probing individual capability markers. `session/delete` remains optional behind `session.delete`.
## Session modes become config options
The dedicated modes API is removed: the `modes` field on session responses, `session/set_mode`, the `current_mode_update` notification, and all `SessionMode*` types. Mode-like state (and model selection, thinking level, and similar knobs) is expressed through session config options, which already existed in v1:
```json theme={null}
{
"configId": "mode",
"name": "Session Mode",
"category": "mode",
"type": "select",
"currentValue": "ask",
"options": [
{ "value": "ask", "name": "Ask" },
{ "value": "code", "name": "Code" }
]
}
```
* The option's identifier field is renamed from `id` to `configId`, matching the parameter name used by `session/set_config_option`.
* The stable `category` values are `mode`, `model`, `model_config`, and `thought_level`. Clients can use them for UX affordances (placement, shortcuts) and must tolerate unknown categories.
* Clients change values with `session/set_config_option` (`sessionId`, `configId`, `value`), and the response returns the full updated `configOptions` array, since one change can affect other options. Agent-initiated changes arrive as `config_option_update` session updates, which replace the v1 `current_mode_update`.
## Client file system and terminal execution removed
v2 removes the entire v1 Client-provided execution surface:
* `clientCapabilities.fs` and the `fs/read_text_file` / `fs/write_text_file` methods
* `clientCapabilities.terminal` and the `terminal/create`, `terminal/output`, `terminal/release`, `terminal/wait_for_exit`, `terminal/kill` methods
In practice this surface was inconsistently implemented outside of a few IDEs, and agents already needed their own file and execution handling for clients that didn't offer it. Clients that want to expose file access, unsaved editor state, or command execution to agents should do so by providing an **MCP server** to the session (via `mcpServers` on `session/new` / `session/resume`), which puts those tools on the same footing as every other tool the Agent uses. Agent-side, drop the capability checks and the dual execution paths. Report file changes through [diff content](#diff-content); when byte-faithful command display matters, report output through the new Agent-owned terminal stream.
The v2 `terminal` content reference does not restore this Client execution surface. It only anchors display state supplied by the Agent.
## MCP server configuration
MCP transport configuration is aligned with the current MCP transport model:
* Every server config **MUST** carry a `type` discriminator. In v1, stdio configs had no `type` field. In v2 they are `"type": "stdio"`. Unknown transport types can then be carried as extension variants instead of failing to parse.
* The deprecated HTTP+SSE transport (`"type": "sse"`) is **removed**.
* Support is advertised per transport under `capabilities.session.mcp`: `stdio` is now an explicit capability (`session.mcp.stdio`), so agents that cannot launch subprocesses can opt out, and `session.mcp.http` covers remote servers.
* Empty arrays are no longer required: `args` and `env` on stdio configs and `headers` on HTTP configs are optional in v2 (v1 required `args` and `env` even when empty).
```json theme={null}
{
"mcpServers": [
{
"type": "stdio",
"name": "filesystem",
"command": "/usr/local/bin/mcp-fs",
"args": ["--root", "/home/user/project"]
},
{
"type": "http",
"name": "linear",
"url": "https://mcp.linear.app/mcp"
}
]
}
```
## Content blocks
The five content block types are unchanged: `text`, `image`, `audio`, `resource_link`, and `resource`. v2 realigns their fields with the latest MCP specification. Notably, `resource_link` gains an optional `icons` array (each icon has a required `src` URI plus optional `mimeType`, `sizes`, and `theme` of `light`/`dark`), and the `type` discriminator is extensible like every other v2 enum, so unknown block types no longer break deserialization for receivers that have a fallback.
If you maintain a validator or generated models, v2 also tightens schema-level details that v1 left loose: base64 payloads (image/audio and terminal `data`, resource `blob`) are marked with `contentEncoding: "base64"`, URI fields are marked `format: "uri"`, and `annotations.priority` is bounded to the inclusive range 0–1.
## Slash commands
The advertisement model (`available_commands_update` carrying commands with `name` and `description`) is unchanged, but a command's optional `input` specification is now a tagged union. The v1 untagged unstructured input gains an explicit `type: "text"` discriminator so richer input types can be added later:
```json v1 theme={null}
{
"name": "search",
"description": "Search the codebase",
"input": { "hint": "query to search for" }
}
```
```json v2 theme={null}
{
"name": "search",
"description": "Search the codebase",
"input": { "type": "text", "hint": "query to search for" }
}
```
As with other extensible unions, unknown input types should be preserved when proxying. A client that can't render one can fall back to plain text input or hide the command's input hint.
## Consistent ID naming
v2 applies one naming rule across the schema: a field that identifies a protocol entity or references one is named after its domain (`sessionId`, `messageId`, `toolCallId`, `planId`, `optionId`), never a generic `id`. The concrete renames from v1:
| Where | v1 | v2 |
| --------------------------- | ------- | ---------- |
| Auth method descriptor | `id` | `methodId` |
| Session config option | `id` | `configId` |
| Session config select group | `group` | `groupId` |
New entities introduced in v2 follow the same rule (`messageId` on messages, `planId` on plans).
A few schema definition names also changed without any wire-format change, which matters only to schema-codegen consumers: the `session/update` and `session/cancel` payload types are now `UpdateSessionNotification` and `CancelSessionNotification`, and the auth request/response types follow the new method names (`LoginAuthRequest`/`LoginAuthResponse`, `LogoutAuthRequest`/`LogoutAuthResponse`).
## Extensibility and forward compatibility
v2 makes the whole schema forward-compatible by convention:
* **Open enums and tagged unions.** Every enum-like string accepts unknown values. Values beginning with `_` are reserved for implementation-specific extensions (e.g. `_mycompany_widget`). Unknown values *without* a leading `_` are reserved for future ACP versions. Receivers **SHOULD** preserve unknown values when storing, replaying, proxying, or forwarding, and either render them generically or fall back safely. Do not mint non-underscore custom values.
* **`_meta` everywhere.** As in v1, `_meta` objects carry implementation metadata. In v2's upsert-style updates, top-level `_meta` follows the same patch semantics as other fields: omitted means unchanged, `null` clears. Metadata nested in a snapshot, exit-status object, content item, command permission subject, or chunk is scoped to that object; omission and `null` are equivalent.
* **Custom methods** still use the `_` prefix, unchanged from v1.
## Transports
stdio remains the primary transport and is unchanged except that v2 explicitly follows **JSON-RPC 2.0 batch** behavior: a newline-delimited message may be a single request, notification, response, or a batch array. Receivers may process batch entries concurrently, must not reply to notifications, and return per-entry `-32600` errors for invalid entries. Don't batch lifecycle-sensitive messages (`initialize`, `auth/login`, `session/new`, `session/resume`, `session/prompt`). They change which later messages are valid.
A standard remote transport (streamable HTTP with SSE streams, plus WebSocket) is being specified in its own RFD and is not part of the core v2 protocol surface. See the [transport RFD](/rfds/streamable-http-websocket-transport) for its current state.
## Migration checklist: Agents
1. **Initialization.** Read `params.capabilities` / `params.info`. Return `capabilities` and a required `info`. Restructure your capability object: nest prompt and MCP capabilities under `session`, convert boolean markers to `{}` objects, drop `loadSession` and the `list`/`resume`/`close` markers.
2. **Implement the baseline.** If you advertise `session`, implement `session/new`, `session/list`, `session/resume`, `session/close`, `session/prompt`, `session/cancel`, and `session/update`.
3. **Auth.** Rename `authenticate` → `auth/login`. If you return one or more valid `authMethods`, implement both `auth/login` and `auth/logout`; if you omit the field or return an empty array, Clients **MUST NOT** call either method. Do not add a logout support marker: `capabilities.auth` is only for authentication-related extensions. Add `type` and `methodId` to your auth method descriptors.
4. **Prompt lifecycle.** Respond to `session/prompt` immediately with `{}` on acceptance. Emit a `user_message` acknowledgment with an agent-generated `messageId`, a `running` state update when foreground work starts, and an idle `state_update` carrying the stop reason when it ends, including `cancelled` after `session/cancel`. Background updates may continue while idle.
5. **Message IDs.** Generate and attach a `messageId` to every message chunk and update.
6. **Tool calls.** Stop sending `tool_call`. Send `tool_call_update` for creation and patches. Use `tool_call_content_chunk` to stream content. Respect omit/`null`/value patch semantics.
7. **Terminal output.** Add `terminal` content references for Agent-owned display terminals. Send `terminal_update` for command, absolute cwd, snapshots, and exit state; send independently base64-encoded `terminal_output_chunk` values for live bytes. Do not expect Client control methods or capability negotiation.
8. **Diffs.** Replace `oldText`/`newText` with `changes` (+ `fileType`/`mimeType` where known) and provide `patch` in `git_patch` format whenever feasible.
9. **Permissions.** Put prompt copy in required `title` (+ optional `description`). Use the `tool_call` subject for tool-call state and the `command` subject for a command, required absolute cwd, and optional tool-call/terminal associations.
10. **Plans.** Send `plan_update` with `{ "type": "items", "planId": ..., "entries": [...] }`.
11. **Modes.** Drop `session/set_mode`, `modes`, and `current_mode_update`. Expose the same state as config options with `category: "mode"` and emit `config_option_update`.
12. **Replay.** Handle `replayFrom` on `session/resume`. Replay history as ordinary `session/update` notifications when asked, including terminal replacement snapshots rather than requiring every historical output chunk. Remove `session/load`.
13. **Client surface.** Remove all `fs/*` and `terminal/*` calls. The new terminal content is Agent-owned display state, not a Client resource.
14. **MCP config.** Require and emit `type` discriminators. Drop SSE. Advertise `session.mcp.stdio` / `session.mcp.http` as appropriate.
15. **Slash commands.** Add the `type: "text"` discriminator to command `input` specifications.
16. **Parsing.** Make enum handling open: preserve unknown variants where a safe fallback exists, and accept batch arrays on stdio.
## Migration checklist: Clients
1. **Initialization.** Send `protocolVersion: 2`, required `info`, and `capabilities` (drop `fs`/`terminal`). Read the Agent's capabilities from `result.capabilities` with presence checks instead of boolean checks.
2. **Rely on the baseline.** When `capabilities.session` is present, use list/resume/close/prompt/cancel without probing markers. Keep checking `session.delete` and other optional extras.
3. **Prompt lifecycle.** Don't treat the `session/prompt` response as turn completion. Drive UI from `state_update` (`running` / `idle` / `requires_action`), take the stop reason from the idle update, and render the user's message from the `user_message` acknowledgment (which carries its canonical `messageId`). Keep accepting background updates while idle.
4. **Messages.** Track messages by required `messageId`. Implement upsert semantics: whole-message updates replace content (or clear it with `null`/`[]`), chunks append.
5. **Tool calls.** Create tool calls on first-seen `toolCallId` in `tool_call_update`. Apply omit/`null`/value patches. Append `tool_call_content_chunk` items. Replace accumulated content when an update carries `content`.
6. **Terminal output.** Maintain Agent-owned terminal state by `terminalId`. Apply update patch and snapshot-replacement semantics; independently decode and append chunk bytes. Render them in an isolated terminal emulator or sanitized transcript, with no input or process controls.
7. **Diffs.** Render `patch.text` when present. Drive file trees and summaries from `changes`. Handle patch-less diffs (binary, symlink, directory).
8. **Permissions.** Render `title`/`description`. Apply `tool_call` subjects like ordinary tool-call updates; render `command` subjects from their command, required absolute cwd, and optional associations. Show a generic prompt for absent or unknown subjects.
9. **Plans.** Handle `plan_update` keyed by `planId`. Each update replaces that plan's entries.
10. **Modes.** Drop `session/set_mode` and `current_mode_update` handling. Drive mode/model UI from `configOptions` (using `category`) via `session/set_config_option` and `config_option_update`.
11. **Resume.** Replace `session/load` with `session/resume` + `replayFrom: { "type": "start" }`, and plain reconnects with `session/resume` without `replayFrom`.
12. **Client surface.** Remove `fs/*` and `terminal/*` implementations for v2 connections. Expose Client-side tools through MCP servers passed in `mcpServers`; do not treat display terminals as Client resources.
13. **Cancellation.** After `session/cancel`, keep accepting updates and wait for the idle `state_update` with `stopReason: "cancelled"` as confirmation.
14. **Parsing.** Preserve unknown enum variants, tolerate unknown `sessionUpdate` types, read command `input` as a tagged union, and accept batch arrays on stdio.
## Migration checklist: SDKs
1. **Separate the versions.** Keep v1 and v2 schemas, generated models, and test fixtures fully separate, and gate unstable-v2 surfaces independently of `protocolVersion: 2`.
2. **Three-state fields.** Model omitted vs `null` vs concrete values distinctly wherever v2 defines patch semantics. A plain nullable/optional type erases a distinction the protocol depends on.
3. **Strict where it counts.** Reject malformed payloads for *known* discriminator values instead of demoting them to the unknown-variant fallback. The fallback exists only for genuinely unknown values.
4. **Preserve what you don't understand.** Round-trip `_`-prefixed extension values, unknown future variants, and `_meta` when storing, replaying, proxying, or forwarding.
5. **Fixtures.** Cover the full prompt lifecycle, resume replay, cancellation, permission flow, message replacement and clearing, tool-call content chunks, terminal snapshot replacement, split and invalid UTF-8 bytes, exit state, command subjects, structured diffs, and JSON-RPC batches.
## Supporting v1 and v2 side by side
Supporting both versions is the recommended path, not an edge case: v1 peers will remain in the wild well after v2 stabilizes, and dropping v1 support means losing them. Version negotiation gives you one protocol version per connection, so the cleanest approach is to keep two thin protocol surfaces behind shared application logic and select one after `initialize`.