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.
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 currently defines no standard Client capability fields. Agent-owned terminal display is baseline behavior, not a Client execution capability.

​

Authentication

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

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

​

The new prompt lifecycle

​

v1: the response is the turn

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

​

v2: the response is an acknowledgment

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

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

​

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",
  "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. 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).

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

​

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, 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

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

​

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