Migrating from v1

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, including failures after acceptance.
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

​

Version negotiation

​

At a glance

​

Method changes

​

session/update variant changes

​

Initialization

​

Role-agnostic info and capabilities

{
  "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" }
  }
}

{
  "jsonrpc": "2.0",
  "id": 0,
  "method": "initialize",
  "params": {
    "protocolVersion": 2,
    "info": {
      "name": "my-client",
      "title": "My Client",
      "version": "1.0.0"
    },
    "capabilities": {}
  }
}

{
  "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" }
  }
}

{
  "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": []
  }
}

​

Support markers are objects, not booleans

​

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).
• 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). Stable v2 defines Client auth and elicitation capability groups. Agent-owned terminal display is baseline behavior, not a Client execution capability.

​

Complete v1 → v2 capability mapping

​

Agent capability fields

​

Client capability fields

​

Authentication

• authenticate → auth/login. The params are unchanged (methodId selecting an advertised method whose type defines a protocol-driven login flow). 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.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "auth/login",
  "params": { "methodId": "agent-login" }
}

​

Auth methods

{
  "methodId": "agent-login",
  "type": "agent",
  "name": "Agent login",
  "description": "Sign in using the agent's login flow"
}

​

Terminal auth methods

• env is an array of { "name", "value" } entries with unique names, instead of an object that maps names to values.
• The Client advertises terminal auth support with the support marker capabilities.auth.terminal: {} instead of clientCapabilities.auth.terminal: true (see Support markers).

{
  "id": "terminal-login",
  "name": "Log in from the terminal",
  "type": "terminal",
  "args": ["--login"],
  "env": { "ACP_INTERACTIVE_LOGIN": "1" }
}

{
  "methodId": "terminal-login",
  "name": "Log in from the terminal",
  "type": "terminal",
  "args": ["--login"],
  "env": [{ "name": "ACP_INTERACTIVE_LOGIN", "value": "1" }]
}

​

The new prompt lifecycle

​

v1: the response is the turn

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

​

v2: the response acknowledges insertion

{ "jsonrpc": "2.0", "id": 2, "result": { "messageId": "msg_user_8f7a1" } }

1. User message update. The Agent MUST report the inserted message’s content and placement, either as a user_message update with a full content array or as streamed user_message_chunk updates. These use the same agent-owned messageId as the response. The response and updates describe the same insertion, but updates may arrive before or after the response:
   {
     "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. Active state. When foreground work starts, the Agent MUST report running, or requires_action if it starts blocked on user action. After reporting requires_action, it MUST report running when foreground progress resumes. Active state reporting may precede insertion, for example while a foreground hook runs. It is not acknowledgment of insertion.
3. Output. Messages, thoughts, plans, and tool calls stream as before (with the changes described in the following sections).
4. Completion. When foreground work ends, the Agent MUST report idle and SHOULD include the stop reason:
   {
     "jsonrpc": "2.0",
     "method": "session/update",
     "params": {
       "sessionId": "sess_abc123",
       "update": {
         "sessionUpdate": "state_update",
         "state": "idle",
         "stopReason": "end_turn"
       }
     }
   }
   

​

Session states

• running: Foreground work is in progress.
• idle: No foreground work is active. Background activity may continue. Agents SHOULD include a stopReason when the transition ends foreground work.
• requires_action: Foreground work as a whole is blocked on user action. Agents SHOULD send this when blocked, including on elicitations. Once reported, they MUST send running when foreground progress resumes, or idle if the work ends without resuming.

​

Cancellation

​

Why this matters beyond bookkeeping

​

Messages and message IDs

​

Message IDs are required

​

Whole-message upserts

• 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.

​

Tool calls

​

One upsert notification

{
  "sessionUpdate": "tool_call_update",
  "toolCallId": "call_001",
  "name": "read_file",
  "title": "Reading configuration file",
  "kind": "read",
  "status": "pending"
}

​

Streaming tool-call content

{
  "sessionUpdate": "tool_call_content_chunk",
  "toolCallId": "call_001",
  "content": {
    "type": "content",
    "content": { "type": "text", "text": "Checked syntax..." }
  }
}

​

Agent-owned terminal display

{
  "type": "terminal",
  "terminalId": "term_001"
}

{
  "sessionUpdate": "terminal_update",
  "terminalId": "term_001",
  "command": "cargo test",
  "cwd": "/workspace/project",
  "output": {
    "data": "cnVubmluZyAxMjMgdGVzdHMNCg=="
  },
  "exitStatus": {
    "exitCode": 0,
    "signal": null
  }
}

{
  "sessionUpdate": "terminal_output_chunk",
  "terminalId": "term_001",
  "data": "cGFzc2VkDQo="
}

​

Diff content

{
  "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. Unlike Git’s repository-relative paths, every path MUST be absolute, including in rename from, rename to, copy from, and copy to lines, with no prefix such as Git’s default a/ and b/. Otherwise paths follow Git, including /dev/null for the missing side of an added or deleted file and Git’s quoting of unusual paths. See Diffs for producing this with git diff. 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).

{
  "type": "diff",
  "changes": [
    {
      "operation": "delete",
      "path": "/home/user/project/old_file.txt",
      "fileType": "text"
    }
  ]
}

​

Edits known only as a snippet

• Read the file before the tool runs, and compute changes and patch from its contents.
• Send no diff until the change is done. Until then, locations can still point the Client at the file.

​

Permission requests

{
  "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.

{
  "type": "command",
  "command": "cargo test",
  "cwd": "/workspace/project",
  "toolCallId": "call_001",
  "terminalId": "term_001"
}

​

Plans

{
  "sessionUpdate": "plan",
  "entries": [
    {
      "content": "Check for syntax errors",
      "priority": "high",
      "status": "pending"
    }
  ]
}

{
  "sessionUpdate": "plan_update",
  "plan": {
    "type": "items",
    "planId": "plan-1",
    "entries": [
      {
        "content": "Check for syntax errors",
        "priority": "high",
        "status": "pending"
      }
    ]
  }
}

​

Session setup and lifecycle

​

session/load is gone. session/resume does both

{
  "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.

​

Consistent lifecycle requests

​

Baseline methods

​

Session modes become config options

{
  "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, type, value). The required type discriminator is "id" with a string option ID or "boolean" with a boolean value. 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

• 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

​

MCP server configuration

• 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).

{
  "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

​

Slash commands

{
  "name": "search",
  "description": "Search the codebase",
  "input": { "hint": "query to search for" }
}

{
  "name": "search",
  "description": "Search the codebase",
  "input": { "type": "text", "hint": "query to search for" }
}

​

Consistent ID naming

​

Extensibility and forward compatibility

• 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 is a patch: omitted means unchanged, null clears it, and an object patches stored metadata by top-level key, where a key set to null is removed and any other value replaces that key whole (see Metadata Patches). 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

​

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 for method types that define protocol-driven 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, and send terminal method env as { "name", "value" } entries.
4. Prompt lifecycle. Respond to an accepted session/prompt with { "messageId": "…" }, carrying the agent-generated ID of the inserted user message. Emit a user_message acknowledgment with the same 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. Report a failure after insertion as an idle state_update with stopReason: "error" and the JSON-RPC error in error, never as an error response to the prompt. 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, including key-level _meta patches.
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. If a tool’s input describes an edit only as a snippet, read the file somewhere the tool waits on, before it can run, or send no diff until the change is done (see Edits known only as a snippet).
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. When the Client may already hold an entity’s _meta, remove stale keys explicitly, since an _meta object no longer replaces them. 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. Optionally advertise initial commands in setup responses via availableCommands, and use complete-replacement available_commands_update notifications for later changes.
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, and advertise terminal auth as auth.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). Treat stopReason: "error" as a failed outcome and read its details from the idle update’s error. An error response to session/prompt means the message was not inserted. 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, and patch top-level _meta by key. 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, and 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. Read initial availableCommands from setup responses and replace the list on each available_commands_update, including [] to clear it.

​

Migration checklist: SDKs

1. Separate the versions. Keep v1 and v2 schemas, generated models, and test fixtures fully separate. Exposing unstable-v2 types does not advertise support; enforce each feature’s documented negotiation requirements 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. Apply the top-level _meta of upserts as a key-level patch rather than a replacement.
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.
6. Stop reasons. Model the idle update’s stop reason as a union tagged by stopReason and flattened into the update, so a stop reason can carry fields of its own, such as the error stop reason’s error. Keep unknown stop reasons with their fields, and treat a missing, null, or non-string stopReason as no stop reason rather than rejecting the update.

​

Supporting v1 and v2 side by side

​

Negotiate once, then use the selected surface

• The Client MUST request the latest version it supports.
• An Agent implementing v2 MUST select the highest supported version at or below the requested version. If none exists, it MUST return -32022 with requested and supported data instead of a higher-version success response.
• Both peers MUST use the selected version’s specification for subsequent traffic. A Client that cannot support the returned version SHOULD close the connection and inform the user.

​

Agent routing in the SDKs

import * as v2 from "@agentclientprotocol/sdk/experimental/v2";

// v1Agent and v2Agent implement their respective protocol surfaces.
v2.agentProtocolRouter().withV1(v1Agent).withV2(v2Agent).connect(stream);

use agent_client_protocol::Agent;

let agent = Agent
    .protocol_router()
    .with_v1(v1_agent)
    .with_v2(v2_agent);

​

Version mismatch is an initialization failure

​

Share application logic, not wire shapes

• Prompt completion: v1 keeps session/prompt pending until the turn ends. v2 acknowledges insertion and reports foreground completion through an idle state_update.
• Conversation updates: v1 streams chunks, while v2 also supports identified entities, replacements, clearing, and replay. A v1 projection must not assume it can represent every v2 update.
• Client tools: v1 may use Client file system and terminal methods. v2 uses MCP servers for Client-side tools. Agent-owned display terminals are not a replacement execution API.

​

Validate the dual-stack endpoint

1. Check that each Client reaches the matching implementation and receives that version’s capabilities.
2. Check fallback from a v2 Client to a v1-only Agent, including whether the Client continues with v1 or disconnects.
3. Send a higher requested version with compatible initialization parameters and check that the Agent selects its latest supported version.
4. Run prompt completion and cancellation through both surfaces, and assert each version’s completion signal, not just successful initialization.
5. Check that disabling draft v2 support leaves the v1 endpoint working.
6. Send a v1 request without Client identity to a v2-only endpoint. Check for -32022 with requested: 1 and supported: [2], and check that no v2 session work starts.