Derived ACP v1 testing requirements, revision acp-v1-2797d331-r2. Pinned agentclientprotocol/agent-client-protocol commit 2797d33125c14e5bcfc815952930130c43e5bc4c; stable schema sha256 3c17bd6385d90cf672d8a661fddc359d73422cf8b8ce6865213d25cfd4c0eca7. This file is generated from spec/manifest/ by scripts/import-spec.py; do not edit it by hand. It is not an official replacement specification.
Requirements: 240 — MAY: 34, MUST: 120, MUST NOT: 30, SHOULD: 52, SHOULD NOT: 4
| # | ID | Keyword | Role | Responsibility | Kind | Requirement | Source |
|---|---|---|---|---|---|---|---|
| 1 | ACP-V1-OVERVIEW-ABSOLUTE-PATHS |
MUST | both | sdk | imported | All file paths in the protocol MUST be absolute. | docs/protocol/v1/overview.mdx L214 |
| 2 | ACP-V1-INIT-CLIENT-INITIALIZE-FIRST |
MUST | client | sdk | imported | Before a Session can be created, Clients MUST initialize the connection by calling the initialize method with: - The latest protocol version supported - The capabilities supported | docs/protocol/v1/initialization.mdx L24-L27 |
| 3 | ACP-V1-INIT-IMPLEMENTATION-INFO |
SHOULD | both | shared | imported | Both Clients and Agents SHOULD provide information about their implementation in the clientInfo and agentInfo fields respectively. | docs/protocol/v1/initialization.mdx L271 |
| 4 | ACP-V1-INIT-AGENT-RESPONSE |
MUST | agent | sdk | imported | The Agent MUST respond with the chosen protocol version and the capabilities it supports. | docs/protocol/v1/initialization.mdx L54 |
| 5 | ACP-V1-INIT-VERSION-AGREEMENT |
MUST | both | sdk | imported | Clients and Agents MUST agree on a protocol version and act according to its specification. | docs/protocol/v1/initialization.mdx L88 |
| 6 | ACP-V1-INIT-REQUEST-LATEST-VERSION |
MUST | client | sdk | imported | The initialize request MUST include the latest protocol version the Client supports. | docs/protocol/v1/initialization.mdx L94 |
| 7 | ACP-V1-INIT-AGENT-SAME-VERSION |
MUST | agent | sdk | imported | If the Agent supports the requested version, it MUST respond with the same version. | docs/protocol/v1/initialization.mdx L96 |
| 8 | ACP-V1-INIT-AGENT-LATEST-VERSION |
MUST | agent | sdk | imported | Otherwise, the Agent MUST respond with the latest version it supports. (Applies when: Applies when the Agent does not support the protocol version requested in initialize.) |
docs/protocol/v1/initialization.mdx L96 |
| 9 | ACP-V1-INIT-CLIENT-UNSUPPORTED-VERSION |
SHOULD | client | shared | imported | If the Client does not support the version specified by the Agent in the initialize response, the Client SHOULD close the connection and inform the user about it. (Applies when: Applies when the Agent's initialize response carries a protocol version the Client does not support.) |
docs/protocol/v1/initialization.mdx L98 |
| 10 | ACP-V1-INIT-CAPABILITIES-OPTIONAL |
MAY | both | sdk | imported | All capabilities included in the initialize request are OPTIONAL. | docs/protocol/v1/initialization.mdx L104 |
| 11 | ACP-V1-INIT-SUPPORT-ALL-COMBINATIONS |
SHOULD | both | sdk | imported | Clients and Agents SHOULD support all possible combinations of their peer's capabilities. | docs/protocol/v1/initialization.mdx L104 |
| 12 | ACP-V1-INIT-OMITTED-UNSUPPORTED |
MUST | both | sdk | imported | Therefore, Clients and Agents MUST treat all capabilities omitted in the initialize request as UNSUPPORTED. | docs/protocol/v1/initialization.mdx L106 |
| 13 | ACP-V1-INIT-CLIENT-SPECIFY-CAPABILITIES |
SHOULD | client | shared | imported | The Client SHOULD specify whether it supports the following capabilities: | docs/protocol/v1/initialization.mdx L116 |
| 14 | ACP-V1-INIT-AGENT-SPECIFY-CAPABILITIES |
SHOULD | agent | shared | imported | The Agent SHOULD specify whether it supports the following capabilities: | docs/protocol/v1/initialization.mdx L186 |
| 15 | ACP-V1-INIT-PROMPT-BASELINE |
MUST | agent | sdk | imported | As a baseline, all Agents MUST support ContentBlock::Text and ContentBlock::ResourceLink in session/prompt requests. | docs/protocol/v1/initialization.mdx L204 |
| 16 | ACP-V1-INIT-PROMPT-RICHER-MAY |
MAY | agent | sdk | imported | Optionally, they MAY support richer types of content by specifying the following capabilities: | docs/protocol/v1/initialization.mdx L206 |
| 17 | ACP-V1-INIT-SESSION-BASELINE |
MUST | agent | sdk | imported | As a baseline, all Agents MUST support session/new, session/prompt, session/cancel, and session/update. | docs/protocol/v1/initialization.mdx L245 |
| 18 | ACP-V1-INIT-SESSION-OPTIONAL-MAY |
MAY | agent | sdk | imported | Optionally, they MAY support other session methods and notifications by specifying additional capabilities. | docs/protocol/v1/initialization.mdx L247 |
| 19 | ACP-V1-AUTH-CLIENT-NO-LOGOUT-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If agentCapabilities.auth.logout is omitted or null, the Agent does not support logout and Clients MUST NOT call it. Supplying {} means the Agent supports the method. | docs/protocol/v1/authentication.mdx L74-L76 |
| 20 | ACP-V1-AUTH-CLIENT-NO-TERMINAL-METHOD-ID |
MUST NOT | client | sdk | imported | The ID of an advertised authentication method whose type defines the authenticate flow. Clients MUST NOT pass a terminal method. | docs/protocol/v1/authentication.mdx L151-L154 |
| 21 | ACP-V1-AUTH-AGENT-TERMINAL-LOGIN-ARGS |
SHOULD | agent | application | imported | Agents SHOULD provide arguments that enter a login-only flow and exit when it completes. (Applies when: Applies only to an Agent that advertises a terminal authentication method; the arguments are the Agent program's, so the SDK is the subject only insofar as it models and transmits the method descriptor.) |
docs/protocol/v1/authentication.mdx L183-L184 |
| 22 | ACP-V1-AUTH-CLIENT-AFTER-LOGOUT |
SHOULD | client | application | imported | Clients SHOULD be prepared for active session operations to fail with authentication-related errors after logout and should prompt the user to authenticate again when appropriate. (Applies when: The user prompt is the embedding application's; the SDK is the subject insofar as it surfaces auth_required errors on active sessions after logout rather than hiding them.) |
docs/protocol/v1/authentication.mdx L224-L226 |
| 23 | ACP-V1-SETUP-INIT-BEFORE-SESSION |
MUST | client | sdk | imported | Before creating a session, Clients MUST first complete the initialization phase to establish protocol compatibility and capabilities. | docs/protocol/v1/session-setup.mdx L8 |
| 24 | ACP-V1-SETUP-NEW-SESSION-ID |
MUST | agent | sdk | imported | The Agent MUST respond with a unique Session ID that identifies this conversation: | docs/protocol/v1/session-setup.mdx L71 |
| 25 | ACP-V1-SETUP-CLIENT-CHECK-LOADSESSION |
MUST | client | sdk | imported | Before attempting to load a session, Clients MUST verify that the Agent supports this capability by checking the loadSession field in the initialize response: | docs/protocol/v1/session-setup.mdx L89 |
| 26 | ACP-V1-SETUP-CLIENT-NO-LOAD-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If loadSession is false or not present, the Agent does not support loading sessions and Clients MUST NOT attempt to call session/load. | docs/protocol/v1/session-setup.mdx L104 |
| 27 | ACP-V1-SETUP-LOAD-REQUEST-CONTENTS |
MUST | client | sdk | imported | To load an existing session, Clients MUST call the session/load method with: - The Session ID to resume - MCP servers to connect to - The working directory (Applies when: Applies when the Client loads a session (the Agent advertised loadSession).) |
docs/protocol/v1/session-setup.mdx L108-L112 |
| 28 | ACP-V1-SETUP-LOAD-REPLAY |
MUST | agent | shared | imported | The Agent MUST replay the entire conversation to the Client in the form of session/update notifications (like session/prompt). (Applies when: Applies when the Agent advertises loadSession; the conversation history is the application's, so the SDK is assessed on whether it lets the application replay through session/update before the session/load response.) |
docs/protocol/v1/session-setup.mdx L134 |
| 29 | ACP-V1-SETUP-LOAD-RESPOND-AFTER-REPLAY |
MUST | agent | shared | imported | When all the conversation entries have been streamed to the Client, the Agent MUST respond to the original session/load request. (Applies when: Applies when the Agent advertises loadSession.) |
docs/protocol/v1/session-setup.mdx L178 |
| 30 | ACP-V1-SETUP-CLIENT-CHECK-RESUME |
MUST | client | sdk | imported | Before attempting to resume a session, Clients MUST verify that the Agent supports this capability by checking for the sessionCapabilities.resume field in the initialize response: | docs/protocol/v1/session-setup.mdx L196 |
| 31 | ACP-V1-SETUP-CLIENT-NO-RESUME-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If sessionCapabilities.resume is not present, the Agent does not support resuming sessions and Clients MUST NOT attempt to call session/resume. | docs/protocol/v1/session-setup.mdx L213 |
| 32 | ACP-V1-SETUP-RESUME-REQUEST-CONTENTS |
MUST | client | sdk | imported | To resume an existing session without replaying prior messages, Clients MUST call the session/resume method with: - The Session ID to resume - MCP servers to connect to - The working directory (Applies when: Applies when the Client resumes a session (the Agent advertised sessionCapabilities.resume).) |
docs/protocol/v1/session-setup.mdx L217-L221 |
| 33 | ACP-V1-SETUP-RESUME-NO-REPLAY |
MUST NOT | agent | shared | imported | Unlike session/load, the Agent MUST NOT replay the conversation history via session/update notifications before responding. Instead, it restores the session context, reconnects to the requested MCP servers, and returns once the session is ready to continue. (Applies when: Applies when the Agent advertises sessionCapabilities.resume.) |
docs/protocol/v1/session-setup.mdx L243 |
| 34 | ACP-V1-SETUP-RESUME-RESPONSE-STATE-MAY |
MAY | agent | sdk | imported | The response MAY also include initial mode, model, or session configuration state when those features are supported by the Agent. (Applies when: Applies when the Agent advertises sessionCapabilities.resume.) |
docs/protocol/v1/session-setup.mdx L253 |
| 35 | ACP-V1-SETUP-CLIENT-CHECK-CLOSE |
MUST | client | sdk | imported | Before attempting to close a session, Clients MUST verify that the Agent supports this capability by checking the sessionCapabilities.close field in the initialize response: | docs/protocol/v1/session-setup.mdx L261 |
| 36 | ACP-V1-SETUP-CLIENT-NO-CLOSE-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If sessionCapabilities.close is not present, the Agent does not support closing sessions and Clients MUST NOT attempt to call session/close. | docs/protocol/v1/session-setup.mdx L278 |
| 37 | ACP-V1-SETUP-CLOSE-REQUEST |
MUST | client | sdk | imported | To close an active session, Clients MUST call the session/close method with the session ID: (Applies when: Applies when the Client closes a session (the Agent advertised sessionCapabilities.close).) |
docs/protocol/v1/session-setup.mdx L282 |
| 38 | ACP-V1-SETUP-CLOSE-CANCELS-AND-FREES |
MUST | agent | shared | imported | The Agent MUST cancel any ongoing work for that session as if session/cancel had been called, then free the resources associated with the session. (Applies when: Applies when the Agent advertises sessionCapabilities.close.) |
docs/protocol/v1/session-setup.mdx L299 |
| 39 | ACP-V1-SETUP-CLOSE-MAY-ERROR |
MAY | agent | sdk | imported | Agents MAY return an error if the session does not exist or is not currently active. (Applies when: Applies when the Agent advertises sessionCapabilities.close.) |
docs/protocol/v1/session-setup.mdx L311 |
| 40 | ACP-V1-SETUP-ADDITIONAL-DIRS-ABSOLUTE |
MUST | client | sdk | imported | each additionalDirectories entry MUST be an absolute path (Applies when: Applies when additionalDirectories is sent (the Agent advertised sessionCapabilities.additionalDirectories).) |
docs/protocol/v1/session-setup.mdx L340 |
| 41 | ACP-V1-SETUP-CLIENT-ADDITIONAL-DIRS-ONLY-WITH-CAPABILITY |
MUST | client | sdk | imported | Clients MUST only send additionalDirectories when the Agent advertises sessionCapabilities.additionalDirectories. | docs/protocol/v1/session-setup.mdx L344 |
| 42 | ACP-V1-SETUP-CWD-ABSOLUTE |
MUST | client | sdk | imported | MUST be an absolute path | docs/protocol/v1/session-setup.mdx L362 |
| 43 | ACP-V1-SETUP-CWD-USED-REGARDLESS-OF-SPAWN |
MUST | agent | shared | imported | MUST be used for the session regardless of where the Agent subprocess was spawned | docs/protocol/v1/session-setup.mdx L363 |
| 44 | ACP-V1-SETUP-CWD-RELATIVE-BASE |
MUST | agent | shared | imported | MUST remain the base for relative-path resolution | docs/protocol/v1/session-setup.mdx L364 |
| 45 | ACP-V1-SETUP-CWD-IN-ROOT-SET |
MUST | agent | shared | imported | MUST be part of the session's effective root set | docs/protocol/v1/session-setup.mdx L365 |
| 46 | ACP-V1-SETUP-ROOT-SET-BOUNDARY |
SHOULD | agent | application | imported | This root set SHOULD serve as a boundary for tool operations on the file system. (Applies when: Tool operations are the Agent application's; the SDK is the subject only insofar as it exposes the effective root set to the application.) | docs/protocol/v1/session-setup.mdx L367 |
| 47 | ACP-V1-SETUP-CLIENT-MCP-SERVERS-MAY |
MAY | client | sdk | imported | When creating a session, Clients MAY include connection details for MCP servers that the Agent should connect to. | docs/protocol/v1/session-setup.mdx L371 |
| 48 | ACP-V1-SETUP-AGENT-MCP-STDIO |
MUST | agent | shared | imported | All Agents MUST support the stdio transport, while HTTP and SSE transports are optional capabilities that can be checked during initialization. (Applies when: Connecting to MCP servers is the Agent application's; the SDK is assessed on accepting and exposing stdio MCP server configurations unconditionally.) | docs/protocol/v1/session-setup.mdx L373 |
| 49 | ACP-V1-SETUP-AGENT-MCP-HTTP-SHOULD |
SHOULD | agent | application | imported | While they are not required to by the spec, new Agents SHOULD support the HTTP transport to ensure compatibility with modern MCP servers. (Applies when: MCP connectivity is the Agent application's; the SDK is the subject only insofar as it models the HTTP MCP server configuration and the mcpCapabilities.http capability.) |
docs/protocol/v1/session-setup.mdx L375 |
| 50 | ACP-V1-SETUP-CLIENT-CHECK-MCP-TRANSPORT |
MUST | client | sdk | imported | Before using HTTP or SSE transports, Clients MUST verify the Agent's capabilities during initialization: | docs/protocol/v1/session-setup.mdx L522 |
| 51 | ACP-V1-SETUP-AGENT-CONNECT-ALL-MCP |
SHOULD | agent | application | imported | Agents SHOULD connect to all MCP servers specified by the Client. (Applies when: MCP connectivity is the Agent application's; the SDK is the subject only insofar as it delivers every configured server to the application.) | docs/protocol/v1/session-setup.mdx L543 |
| 52 | ACP-V1-SETUP-CLIENT-OWN-MCP-MAY |
MAY | client | application | imported | Clients MAY use this ability to provide tools directly to the underlying language model by including their own MCP server. (Applies when: A permission for Client applications; the SDK is the subject only insofar as it does not prevent including a Client-owned MCP server.) | docs/protocol/v1/session-setup.mdx L545 |
| 53 | ACP-V1-LIST-INIT-FIRST |
MUST | client | sdk | imported | Before listing sessions, Clients MUST first complete the initialization phase to verify the Agent supports this capability. | docs/protocol/v1/session-list.mdx L10 |
| 54 | ACP-V1-LIST-CLIENT-CHECK-CAPABILITY |
MUST | client | sdk | imported | Before attempting to list sessions, Clients MUST verify that the Agent supports this capability by checking the sessionCapabilities.list field in the initialize response: | docs/protocol/v1/session-list.mdx L37 |
| 55 | ACP-V1-LIST-CLIENT-NO-LIST-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If sessionCapabilities.list is not present, the Agent does not support listing sessions and Clients MUST NOT attempt to call session/list. | docs/protocol/v1/session-list.mdx L54 |
| 56 | ACP-V1-LIST-AGENT-RESPONSE |
MUST | agent | sdk | imported | The Agent MUST respond with a list of sessions and optional pagination metadata: (Applies when: Applies when the Agent advertises sessionCapabilities.list.) |
docs/protocol/v1/session-list.mdx L94 |
| 57 | ACP-V1-LIST-ADDITIONAL-DIRS-MAY |
MAY | agent | sdk | imported | If the Agent advertises sessionCapabilities.additionalDirectories, it MAY include this field to report the complete ordered additional-root list associated with the listed session. Omitted and empty values are equivalent: this SessionInfo response reports no additional roots. (Applies when: Applies when the Agent advertises sessionCapabilities.list and sessionCapabilities.additionalDirectories.) |
docs/protocol/v1/session-list.mdx L139-L143 |
| 58 | ACP-V1-LIST-CLIENT-NO-MERGE-ADDITIONAL-DIRS |
MUST NOT | client | sdk | imported | Clients MUST NOT merge this field with prior values or infer additional roots from agent-specific state. | docs/protocol/v1/session-list.mdx L144-L145 |
| 59 | ACP-V1-LIST-EMPTY-ARRAY |
MUST | agent | shared | imported | When no sessions match the criteria, the Agent MUST return an empty sessions array. (Applies when: Applies when the Agent advertises sessionCapabilities.list.) |
docs/protocol/v1/session-list.mdx L166 |
| 60 | ACP-V1-LIST-CLIENT-MISSING-CURSOR-IS-END |
MUST | client | sdk | imported | Clients MUST treat a missing nextCursor as the end of results | docs/protocol/v1/session-list.mdx L172 |
| 61 | ACP-V1-LIST-CLIENT-OPAQUE-CURSOR |
MUST | client | sdk | imported | Clients MUST treat cursors as opaque tokens — do not parse, modify, or persist them | docs/protocol/v1/session-list.mdx L173 |
| 62 | ACP-V1-LIST-AGENT-INVALID-CURSOR-ERROR |
SHOULD | agent | shared | imported | Agents SHOULD return an error if the cursor is invalid (Applies when: Applies when the Agent advertises sessionCapabilities.list; cursor validity is the application's to judge, so the SDK is assessed on letting the handler fail the request with an error.) |
docs/protocol/v1/session-list.mdx L174 |
| 63 | ACP-V1-LIST-AGENT-PAGE-SIZE |
SHOULD | agent | application | imported | Agents SHOULD enforce reasonable page sizes internally (Applies when: Applies when the Agent advertises sessionCapabilities.list; page sizing is the application's.) |
docs/protocol/v1/session-list.mdx L175 |
| 64 | ACP-V1-DELETE-INIT-FIRST |
MUST | client | sdk | imported | Before deleting sessions, Clients MUST first complete the initialization phase and verify the Agent supports this capability. | docs/protocol/v1/session-delete.mdx L8 |
| 65 | ACP-V1-DELETE-CLIENT-CHECK-CAPABILITY |
MUST | client | sdk | imported | Before attempting to delete a session, Clients MUST verify that the Agent supports this capability by checking the sessionCapabilities.delete field in the initialize response: | docs/protocol/v1/session-delete.mdx L35 |
| 66 | ACP-V1-DELETE-CLIENT-NO-DELETE-WITHOUT-CAPABILITY |
MUST NOT | client | sdk | imported | If sessionCapabilities.delete is omitted or null, the Agent does not support deleting sessions and Clients MUST NOT attempt to call session/delete. Supplying {} means the Agent supports the method. | docs/protocol/v1/session-delete.mdx L52 |
| 67 | ACP-V1-DELETE-IDEMPOTENT |
SHOULD | agent | application | imported | Deleting an already-deleted session, or a session that never existed, SHOULD succeed silently. (Applies when: Applies when the Agent advertises sessionCapabilities.delete; the outcome is decided by the application's delete handler.) |
docs/protocol/v1/session-delete.mdx L86 |
| 68 | ACP-V1-PROMPT-INIT-AND-SETUP-FIRST |
MUST | client | sdk | imported | Before sending prompts, Clients MUST first complete the initialization phase and session setup. | docs/protocol/v1/prompt-turn.mdx L8 |
| 69 | ACP-V1-PROMPT-CLIENT-RESTRICT-CONTENT |
MUST | client | sdk | imported | Clients MUST restrict types of content according to the Prompt Capabilities established during initialization. | docs/protocol/v1/prompt-turn.mdx L114 |
| 70 | ACP-V1-PROMPT-MESSAGE-ID-MAY |
MAY | agent | sdk | imported | The Agent MAY include an opaque, unique messageId on message chunks. Chunks with the same messageId belong to the same message; a changed messageId indicates a new message. | docs/protocol/v1/prompt-turn.mdx L191 |
| 71 | ACP-V1-PROMPT-USAGE-UPDATE-MAY |
MAY | agent | sdk | imported | The Agent MAY also report current session context and cumulative cost state with a usage_update: | docs/protocol/v1/prompt-turn.mdx L214 |
| 72 | ACP-V1-PROMPT-RESPOND-WITH-STOP-REASON |
MUST | agent | sdk | imported | If there are no pending tool calls, the turn ends and the Agent MUST respond to the original session/prompt request with a StopReason: | docs/protocol/v1/prompt-turn.mdx L239 |
| 73 | ACP-V1-PROMPT-AGENT-MAY-STOP |
MAY | agent | sdk | imported | Agents MAY stop the turn at any point by returning the corresponding StopReason. | docs/protocol/v1/prompt-turn.mdx L251 |
| 74 | ACP-V1-PROMPT-PERMISSION-MAY |
MAY | agent | sdk | imported | Before proceeding with execution, the Agent MAY request permission from the Client via the session/request_permission method. | docs/protocol/v1/prompt-turn.mdx L255 |
| 75 | ACP-V1-PROMPT-TOOL-IN-PROGRESS |
SHOULD | agent | shared | imported | Once permission is granted (if required), the Agent SHOULD invoke the tool and report a status update marking the tool as in_progress: (Applies when: Tool invocation is the application's; the SDK is assessed on letting the application report the in_progress status update.) |
docs/protocol/v1/prompt-turn.mdx L257 |
| 76 | ACP-V1-PROMPT-TOOL-UPDATES-MAY |
MAY | agent | sdk | imported | As the tool runs, the Agent MAY send additional updates, providing real-time feedback about tool execution progress. | docs/protocol/v1/prompt-turn.mdx L274 |
| 77 | ACP-V1-PROMPT-TOOLS-MAY-USE-CLIENT-CAPABILITIES |
MAY | agent | sdk | imported | While tools execute on the Agent, they MAY leverage Client capabilities such as the file system (fs) methods to access resources within the Client's environment. | docs/protocol/v1/prompt-turn.mdx L276 |
| 78 | ACP-V1-PROMPT-CLIENT-CANCEL-MAY |
MAY | client | sdk | imported | Clients MAY cancel an ongoing prompt turn at any time by sending a session/cancel notification: | docs/protocol/v1/prompt-turn.mdx L336 |
| 79 | ACP-V1-PROMPT-CLIENT-MARK-CANCELLED |
SHOULD | client | shared | imported | The Client SHOULD preemptively mark all non-finished tool calls pertaining to the current turn as cancelled as soon as it sends the session/cancel notification. (Applies when: Tool-call display state is the application's; the SDK is assessed on giving the application the hook to do this when session/cancel is sent.) |
docs/protocol/v1/prompt-turn.mdx L348 |
| 80 | ACP-V1-PROMPT-CLIENT-RESPOND-PENDING-PERMISSIONS |
MUST | client | sdk | imported | The Client MUST respond to all pending session/request_permission requests with the cancelled outcome. | docs/protocol/v1/prompt-turn.mdx L350 |
| 81 | ACP-V1-PROMPT-AGENT-STOP-ON-CANCEL |
SHOULD | agent | shared | imported | When the Agent receives this notification, it SHOULD stop all language model requests and all tool call invocations as soon as possible. (Applies when: Model and tool execution are the application's; the SDK is assessed on delivering cancellation to the running prompt promptly.) | docs/protocol/v1/prompt-turn.mdx L352 |
| 82 | ACP-V1-PROMPT-AGENT-CANCELLED-STOP-REASON |
MUST | agent | sdk | imported | After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent MUST respond to the original session/prompt request with the cancelled stop reason. | docs/protocol/v1/prompt-turn.mdx L354 |
| 83 | ACP-V1-PROMPT-AGENT-CATCH-ABORT-ERRORS |
MUST | agent | sdk | imported | Agents MUST catch these errors and return the semantically meaningful cancelled stop reason, so that Clients can reliably confirm the cancellation. | docs/protocol/v1/prompt-turn.mdx L361 |
| 84 | ACP-V1-PROMPT-UPDATES-AFTER-CANCEL-MAY |
MAY | agent | sdk | imported | The Agent MAY send session/update notifications with content or tool call updates after receiving the session/cancel notification, | docs/protocol/v1/prompt-turn.mdx L365 |
| 85 | ACP-V1-PROMPT-UPDATES-BEFORE-RESPONSE |
MUST | agent | sdk | imported | but it MUST ensure that it does so before responding to the session/prompt request. | docs/protocol/v1/prompt-turn.mdx L365 |
| 86 | ACP-V1-PROMPT-CLIENT-ACCEPT-LATE-UPDATES |
SHOULD | client | sdk | imported | The Client SHOULD still accept tool call updates received after sending session/cancel. | docs/protocol/v1/prompt-turn.mdx L367 |
| 87 | ACP-V1-CONTENT-TEXT-SUPPORT |
MUST | agent | sdk | imported | All Agents MUST support text content blocks when included in prompts. | docs/protocol/v1/content.mdx L31 |
| 88 | ACP-V1-TOOLS-REPORT-TOOL-CALL |
SHOULD | agent | shared | imported | When the language model requests a tool invocation, the Agent SHOULD report it to the Client: (Applies when: The model loop is the application's; the SDK is assessed on providing the tool_call session update for the application to report.) |
docs/protocol/v1/tool-calls.mdx L14 |
| 89 | ACP-V1-TOOLS-NAME-IN-FIRST-REPORT |
SHOULD | agent | shared | imported | Agents SHOULD include it in the first report when available | docs/protocol/v1/tool-calls.mdx L39-L40 |
| 90 | ACP-V1-TOOLS-NAME-STABLE |
SHOULD NOT | agent | shared | imported | SHOULD NOT change it later except to correct metadata. Names are opaque, informational metadata: they do not advertise a capability or grant authorization. | docs/protocol/v1/tool-calls.mdx L40-L43 |
| 91 | ACP-V1-TOOLS-PERMISSION-MAY |
MAY | agent | sdk | imported | The Agent MAY request permission from the user before executing a tool call by calling the session/request_permission method: | docs/protocol/v1/tool-calls.mdx L135 |
| 92 | ACP-V1-TOOLS-CLIENT-AUTO-PERMISSION-MAY |
MAY | client | application | imported | Clients MAY automatically allow or reject permission requests according to the user settings. (Applies when: A permission for Client applications; the SDK is the subject only insofar as it lets the permission handler answer without user interaction.) | docs/protocol/v1/tool-calls.mdx L191 |
| 93 | ACP-V1-ELIC-CLIENT-IDENTIFY-AGENT |
MUST | client | application | imported | Clients MUST clearly identify the Agent requesting information, respect user privacy, and provide clear decline and cancel controls. (Applies when: User-interface conduct is the Client application's; the SDK is the subject only insofar as it exposes the request, the decline and the cancel actions to the application.) | docs/protocol/v1/elicitation.mdx L17-L18 |
| 94 | ACP-V1-ELIC-CLIENT-FORM-REVIEW |
MUST | client | application | imported | For form mode, Clients MUST let users review and modify responses before sending them. (Applies when: Applies when the Client advertises form-mode elicitation; the form UI is the application's.) | docs/protocol/v1/elicitation.mdx L18-L19 |
| 95 | ACP-V1-ELIC-CLIENT-URL-CONSENT |
MUST | client | application | imported | For URL mode, Clients MUST display the target host and obtain consent before navigating to it. (Applies when: Applies when the Client advertises URL-mode elicitation; the consent UI is the application's.) | docs/protocol/v1/elicitation.mdx L19-L21 |
| 96 | ACP-V1-ELIC-CLIENT-PRESENT-MESSAGE |
SHOULD | client | application | imported | Clients SHOULD present the request's message so users understand what is requested and why. (Applies when: Applies when the Client advertises elicitation; presentation is the application's, the SDK is assessed on exposing message.) |
docs/protocol/v1/elicitation.mdx L21-L22 |
| 97 | ACP-V1-ELIC-AGENT-NO-UNADVERTISED-MODE |
MUST NOT | agent | sdk | imported | Agents MUST NOT request a mode the Client has not advertised. | docs/protocol/v1/elicitation.mdx L54 |
| 98 | ACP-V1-ELIC-AGENT-FALLBACK |
SHOULD | agent | application | imported | Agents SHOULD provide a graceful fallback when the required mode is unavailable. (Applies when: The fallback is the Agent application's; the SDK is the subject only insofar as it reports which modes the Client advertised.) | docs/protocol/v1/elicitation.mdx L54-L55 |
| 99 | ACP-V1-ELIC-AGENT-BIND-CONNECTION |
MUST | agent | shared | imported | Agents MUST bind each elicitation and related state to the receiving Client connection and, when authentication exists, the verified user identity. A sessionId alone or an unverified Client-provided identity is not sufficient. (Applies when: Applies when the Agent uses elicitation.) | docs/protocol/v1/elicitation.mdx L69-L71 |
| 100 | ACP-V1-ELIC-CLIENT-VALIDATE |
SHOULD | client | shared | imported | Clients SHOULD validate submitted values before responding, (Applies when: Applies when the Client advertises form-mode elicitation.) | docs/protocol/v1/elicitation.mdx L99 |
| 101 | ACP-V1-ELIC-AGENT-REVALIDATE |
SHOULD | agent | shared | imported | and Agents SHOULD validate them again. (Applies when: Applies when the Agent uses form-mode elicitation.) | docs/protocol/v1/elicitation.mdx L99-L100 |
| 102 | ACP-V1-ELIC-CLIENT-DEFAULTS |
SHOULD | client | application | imported | Clients that support schema defaults SHOULD pre-populate form fields with their declared default values. (Applies when: Applies only to Clients that support schema defaults; form rendering is the application's.) | docs/protocol/v1/elicitation.mdx L102-L103 |
| 103 | ACP-V1-ELIC-FORM-NO-SECRETS |
MUST NOT | agent | application | imported | Form mode MUST NOT be used to request secrets or credentials that grant access or authorize transactions, such as passwords, API keys, access or refresh tokens, private keys, recovery codes, or payment credentials. (Applies when: What is requested is the Agent application's choice; the SDK is the subject only if it itself composes elicitation requests.) | docs/protocol/v1/elicitation.mdx L105-L108 |
| 104 | ACP-V1-ELIC-AGENT-URL-FOR-SENSITIVE |
MUST | agent | application | imported | Agents MUST use URL mode for sensitive interactions. (Applies when: What is requested is the Agent application's choice; the SDK is the subject only if it itself composes elicitation requests.) | docs/protocol/v1/elicitation.mdx L109-L110 |
| 105 | ACP-V1-ELIC-AGENT-NO-FORM-FALLBACK |
MUST NOT | agent | application | imported | If the Client does not support URL mode, the Agent MUST NOT fall back to form mode; it must use another safe flow or fail the operation. (Applies when: Applies when the Client has not advertised URL mode; the choice is the Agent application's.) | docs/protocol/v1/elicitation.mdx L110-L111 |
| 106 | ACP-V1-ELIC-AGENT-NO-CREDENTIALS-OVER-ACP |
MUST NOT | agent | application | imported | Agents MUST NOT send credentials or tokens obtained through URL mode back over ACP or place them in Client or model context. (Applies when: Applies when the Agent uses URL-mode elicitation; the handling of obtained credentials is the application's.) | docs/protocol/v1/elicitation.mdx L134-L135 |
| 107 | ACP-V1-ELIC-ACCEPT-CONTENT-SCHEMA |
SHOULD | client | shared | imported | For an accepted form elicitation, content SHOULD conform to the requested schema. (Applies when: Applies when the Client accepts a form-mode elicitation.) | docs/protocol/v1/elicitation.mdx L147-L148 |
| 108 | ACP-V1-ELIC-AGENT-NO-ASSUME-SUCCESS |
MUST NOT | agent | application | imported | Agents MUST NOT assume an elicitation succeeds. (Applies when: Applies when the Agent uses elicitation; the SDK is assessed on surfacing every action (accept, decline, cancel) and failures to the application.) |
docs/protocol/v1/elicitation.mdx L151 |
| 109 | ACP-V1-ELIC-AGENT-HANDLE-OUTCOMES |
MUST | agent | application | imported | They MUST handle decline, cancel, and failures by safely falling back, retrying, or failing the originating operation as appropriate. (Applies when: Applies when the Agent uses elicitation; the handling is the application's.) | docs/protocol/v1/elicitation.mdx L151-L153 |
| 110 | ACP-V1-ELIC-AGENT-UNIQUE-ELICITATION-ID |
MUST | agent | application | imported | The Agent MUST keep each elicitationId unique among outstanding URL elicitations on that Agent-Client connection, (Applies when: Applies when the Agent application uses URL-mode elicitation. The application chooses the elicitationId and alone knows when a URL elicitation stops being outstanding (completion is optional), so the SDK is the subject only insofar as it sends the id unchanged.) | docs/protocol/v1/elicitation.mdx L158-L160 |
| 111 | ACP-V1-ELIC-CLIENT-OPAQUE-ELICITATION-ID |
MUST | client | sdk | imported | and the Client MUST treat it as opaque. | docs/protocol/v1/elicitation.mdx L160 |
| 112 | ACP-V1-ELIC-AGENT-COMPLETE-MAY |
MAY | agent | sdk | imported | The Agent MAY send elicitation/complete after the external interaction finishes. | docs/protocol/v1/elicitation.mdx L160-L161 |
| 113 | ACP-V1-ELIC-AGENT-COMPLETE-SAME-CLIENT |
MUST | agent | sdk | imported | It MUST send that notification only to the same Client that received the original request and include the original elicitationId. (Applies when: Applies when the Agent sends elicitation/complete.) |
docs/protocol/v1/elicitation.mdx L161-L163 |
| 114 | ACP-V1-ELIC-CLIENT-IGNORE-UNKNOWN-COMPLETE |
MUST | client | sdk | imported | Clients MUST ignore unknown or already-completed IDs. | docs/protocol/v1/elicitation.mdx L163-L164 |
| 115 | ACP-V1-ELIC-URL-NO-CREDENTIALS |
MUST NOT | agent | application | imported | Agents MUST NOT put credentials, personal data, or pre-authenticated access in the URL (Applies when: Applies when the Agent uses URL-mode elicitation; the URL is composed by the application.) | docs/protocol/v1/elicitation.mdx L177-L178 |
| 116 | ACP-V1-ELIC-URL-HTTPS |
SHOULD | agent | application | imported | and SHOULD use HTTPS outside development. (Applies when: Applies when the Agent uses URL-mode elicitation; the URL is composed by the application.) | docs/protocol/v1/elicitation.mdx L178 |
| 117 | ACP-V1-ELIC-FORM-NO-CLICKABLE-URLS |
SHOULD NOT | agent | application | imported | Agents SHOULD NOT include URLs intended to be clickable in any field of a form-mode request. (Applies when: Applies when the Agent uses form-mode elicitation; the request content is the application's.) | docs/protocol/v1/elicitation.mdx L179-L180 |
| 118 | ACP-V1-ELIC-CLIENT-NO-PREFETCH |
MUST NOT | client | application | imported | Clients MUST NOT prefetch the URL or open it without explicit user consent. (Applies when: Applies when the Client advertises URL-mode elicitation; navigation is the application's.) | docs/protocol/v1/elicitation.mdx L181-L182 |
| 119 | ACP-V1-ELIC-CLIENT-SHOW-FULL-URL |
MUST | client | application | imported | They MUST show the full URL before asking for consent. (Applies when: Applies when the Client advertises URL-mode elicitation; the consent UI is the application's.) | docs/protocol/v1/elicitation.mdx L182 |
| 120 | ACP-V1-ELIC-CLIENT-SECURE-CONTEXT |
MUST | client | application | imported | Clients MUST open the URL in a secure context that prevents the Client or Agent's language model from inspecting the page or user input. (Applies when: Applies when the Client advertises URL-mode elicitation; navigation is the application's.) | docs/protocol/v1/elicitation.mdx L183-L184 |
| 121 | ACP-V1-ELIC-CLIENT-HIGHLIGHT-DOMAIN |
SHOULD | client | application | imported | Clients SHOULD highlight the domain and warn about suspicious or ambiguous URLs, including Punycode domains. (Applies when: Applies when the Client advertises URL-mode elicitation; the UI is the application's.) | docs/protocol/v1/elicitation.mdx L185-L186 |
| 122 | ACP-V1-ELIC-CLIENT-NO-CLICKABLE-FIELDS |
SHOULD NOT | client | application | imported | Clients SHOULD NOT render a URL as clickable in any elicitation field except the url field of a URL-mode request, subject to the restrictions above. (Applies when: Applies when the Client advertises elicitation; rendering is the application's.) | docs/protocol/v1/elicitation.mdx L187-L189 |
| 123 | ACP-V1-ELIC-AGENT-VERIFY-SAME-USER |
MUST | agent | application | imported | The Agent MUST verify that the authenticated user who started the elicitation is the same user who completes the external interaction. (Applies when: Applies when the Agent uses URL-mode elicitation; the external interaction is the application's.) | docs/protocol/v1/elicitation.mdx L190-L191 |
| 124 | ACP-V1-FS-AGENT-CHECK-CAPABILITY |
MUST | agent | sdk | imported | Before attempting to use filesystem methods, Agents MUST verify that the Client supports these capabilities by checking the Client Capabilities field in the Client's initialize request: | docs/protocol/v1/file-system.mdx L10 |
| 125 | ACP-V1-FS-AGENT-NO-CALL-WITHOUT-CAPABILITY |
MUST NOT | agent | sdk | imported | If readTextFile or writeTextFile is false or not present, the Agent MUST NOT attempt to call the corresponding filesystem method. | docs/protocol/v1/file-system.mdx L29 |
| 126 | ACP-V1-FS-CLIENT-CREATE-FILE |
MUST | client | shared | imported | Absolute path to the file to write. The Client MUST create the file if it doesn't exist. (Applies when: Applies when the Client advertises fs.writeTextFile; the file write is performed by the application's handler unless the SDK supplies one.) |
docs/protocol/v1/file-system.mdx L98-L101 |
| 127 | ACP-V1-CANCEL-REQUEST-MAY-CANCEL-ACTIVITY |
MAY | both | sdk | imported | When a $/cancel_request notification is received by a supporting implementation, the implementation: - MAY cancel the corresponding request activity and all nested activities related to that request (Applies when: Applies to an implementation that supports $/cancel_request; support is optional (cancellation.mdx:14).) |
docs/protocol/v1/cancellation.mdx L16-L18 |
| 128 | ACP-V1-CANCEL-REQUEST-MAY-FINISH-NOTIFICATIONS |
MAY | both | sdk | imported | MAY finish sending any pending notifications before responding (Applies when: Applies to an implementation that supports $/cancel_request.) |
docs/protocol/v1/cancellation.mdx L19 |
| 129 | ACP-V1-CANCEL-REQUEST-MUST-RESPOND |
MUST | both | sdk | imported | MUST send one of these responses for the original request: - A valid response with appropriate data (such as partial results or cancellation marker) - An error response with code -32800 (Request Cancelled) (Applies when: Applies to an implementation that supports $/cancel_request.) |
docs/protocol/v1/cancellation.mdx L20-L22 |
| 130 | ACP-V1-CANCEL-CALLER-MAY-WAIT |
MAY | both | sdk | imported | The calling side MAY implement graceful cancellation processing by waiting for the response from the remote side. | docs/protocol/v1/cancellation.mdx L24 |
| 131 | ACP-V1-CANCEL-INTERNAL-SHOULD |
SHOULD | both | shared | imported | When internal cancellation occurs, the executing party SHOULD: - Send the same -32800 (Cancelled) error response as if $/cancel_request was received - Ensure consistent behavior regardless of cancellation source (Applies when: Applies when the executing party cancels a request internally (for example on timeout or shutdown).) | docs/protocol/v1/cancellation.mdx L35-L38 |
| 132 | ACP-V1-TERM-AGENT-CHECK-CAPABILITY |
MUST | agent | sdk | imported | Before attempting to use terminal methods, Agents MUST verify that the Client supports this capability by checking the Client Capabilities field in the Client's initialize request: | docs/protocol/v1/terminals.mdx L10 |
| 133 | ACP-V1-TERM-AGENT-NO-CALL-WITHOUT-CAPABILITY |
MUST NOT | agent | sdk | imported | If terminal is false or not present, the Agent MUST NOT attempt to call any terminal methods. | docs/protocol/v1/terminals.mdx L26 |
| 134 | ACP-V1-TERM-CLIENT-TRUNCATE-AT-CHARACTER-BOUNDARY |
MUST | client | shared | imported | The Client MUST ensure truncation happens at a character boundary to maintain valid string output, even if this means the retained output is slightly less than the specified limit. (Applies when: Applies when the Client advertises terminal and a terminal/create request carries outputByteLimit; the terminal is run by the application's handler unless the SDK supplies one.) |
docs/protocol/v1/terminals.mdx L86-L88 |
| 135 | ACP-V1-TERM-AGENT-RELEASE |
MUST | agent | shared | imported | The Agent MUST release the terminal using terminal/release when it's no longer needed. (Applies when: Applies when the Agent uses terminal methods; the release call is issued by the application's tool code unless the SDK manages terminal lifetimes.) | docs/protocol/v1/terminals.mdx L109-L110 |
| 136 | ACP-V1-TERM-CLIENT-DISPLAY-AFTER-RELEASE |
SHOULD | client | application | imported | If the terminal was added to a tool call, the client SHOULD continue to display its output after release. (Applies when: Display is the Client application's; the SDK is the subject only insofar as releasing a terminal does not destroy output the application still references.) | docs/protocol/v1/terminals.mdx L282 |
| 137 | ACP-V1-PLAN-REPORT |
SHOULD | agent | shared | imported | When the language model creates an execution plan, the Agent SHOULD report it to the Client: (Applies when: Planning is the application's; the SDK is assessed on providing the plan session update.) |
docs/protocol/v1/agent-plan.mdx L12 |
| 138 | ACP-V1-PLAN-REPORT-UPDATES |
SHOULD | agent | shared | imported | As the Agent progresses through the plan, it SHOULD report updates by sending more session/update notifications with the same structure. (Applies when: Applies when the Agent reports plans.) | docs/protocol/v1/agent-plan.mdx L77 |
| 139 | ACP-V1-PLAN-COMPLETE-LIST |
MUST | agent | shared | imported | The Agent MUST send a complete list of all plan entries in each update and their current status. (Applies when: Applies when the Agent reports plans.) | docs/protocol/v1/agent-plan.mdx L79 |
| 140 | ACP-V1-PLAN-CLIENT-REPLACE |
MUST | client | shared | imported | The Client MUST replace the current plan completely. (Applies when: Applies when the Client receives plan updates; plan state is the application's unless the SDK keeps it.) |
docs/protocol/v1/agent-plan.mdx L79 |
| 141 | ACP-V1-PLAN-DYNAMIC-MAY |
MAY | agent | sdk | imported | The Agent MAY add, remove, or modify plan entries as it discovers new requirements or completes tasks, allowing it to adapt based on what it learns. | docs/protocol/v1/agent-plan.mdx L83 |
| 142 | ACP-V1-MODES-INITIAL-STATE-MAY |
MAY | agent | sdk | imported | During Session Setup the Agent MAY return a list of modes it can operate in and the currently active mode: | docs/protocol/v1/session-modes.mdx L17 |
| 143 | ACP-V1-CONFIG-CLIENT-PREFER-CONFIG-OPTIONS |
SHOULD | client | application | imported | If an Agent provides configOptions, Clients SHOULD use them instead of the modes field. (Applies when: Applies when the Agent provides configOptions; which selector the UI uses is the application's.) |
docs/protocol/v1/session-config-options.mdx L9-L12 |
| 144 | ACP-V1-CONFIG-INITIAL-STATE-MAY |
MAY | agent | sdk | imported | During Session Setup the Agent MAY return a list of configuration options and their current values: | docs/protocol/v1/session-config-options.mdx L17 |
| 145 | ACP-V1-CONFIG-CLIENT-RESPECT-ORDER |
SHOULD | client | application | imported | The order of this array represents the Agent's preferred priority. Clients SHOULD respect this ordering when displaying options. (Applies when: Display order is the application's; the SDK is assessed on preserving array order.) | docs/protocol/v1/session-config-options.mdx L70-L74 |
| 146 | ACP-V1-CONFIG-BOOLEAN-ONLY-AFTER-CAPABILITY-MAY |
MAY | agent | sdk | imported | Agents MAY include boolean config options only after the Client advertises support during initialization: | docs/protocol/v1/session-config-options.mdx L156-L157 |
| 147 | ACP-V1-CONFIG-NO-BOOLEAN-WITHOUT-CAPABILITY |
MUST NOT | agent | sdk | imported | Agents MUST NOT include type: "boolean" options in configOptions payloads unless the Client advertised support. | docs/protocol/v1/session-config-options.mdx L187-L188 |
| 148 | ACP-V1-CONFIG-CATEGORY-MAY |
MAY | agent | sdk | imported | Each config option MAY include a category field. | docs/protocol/v1/session-config-options.mdx L193 |
| 149 | ACP-V1-CONFIG-CATEGORY-NOT-REQUIRED-FOR-CORRECTNESS |
MUST NOT | both | sdk | imported | Categories are for UX purposes only and MUST NOT be required for correctness. | docs/protocol/v1/session-config-options.mdx L196-L197 |
| 150 | ACP-V1-CONFIG-CLIENT-UNKNOWN-CATEGORY |
MUST | client | sdk | imported | Clients MUST handle missing or unknown categories gracefully. | docs/protocol/v1/session-config-options.mdx L197 |
| 151 | ACP-V1-CONFIG-CLIENT-RENDER-MODEL-CONFIG-NEAR-MODEL |
SHOULD | client | application | imported | Clients SHOULD render model_config options near the model selector, such as in the same popover or panel. (Applies when: Rendering is the Client application's; the SDK is the subject only insofar as it exposes category.) |
docs/protocol/v1/session-config-options.mdx L209 |
| 152 | ACP-V1-CONFIG-CLIENT-TIE-ORDER |
SHOULD | client | application | imported | When multiple options share the same category, Clients SHOULD use the array ordering to resolve ties, preferring earlier options in the list for prominent placement or keyboard shortcuts. (Applies when: Placement is the Client application's; the SDK is assessed on preserving array order.) | docs/protocol/v1/session-config-options.mdx L211 |
| 153 | ACP-V1-CONFIG-AGENT-PRIORITY-ORDER |
SHOULD | agent | application | imported | The order of the configOptions array is significant. Agents SHOULD place higher-priority options first in the list. (Applies when: Option priority is the Agent application's; the SDK is assessed on preserving array order.) | docs/protocol/v1/session-config-options.mdx L215 |
| 154 | ACP-V1-CONFIG-CLIENT-ORDERING |
SHOULD | client | application | imported | Clients SHOULD: - Display options in the order provided by the Agent - Use ordering to resolve ties when multiple options share the same category - If displaying a limited number of options, prefer those at the beginning of the list (Applies when: Display is the Client application's; the SDK is assessed on preserving array order.) | docs/protocol/v1/session-config-options.mdx L217-L221 |
| 155 | ACP-V1-CONFIG-AGENT-DEFAULTS |
MUST | agent | shared | imported | Agents MUST always provide a default value for every configuration option. (Applies when: Applies when the Agent provides configOptions; currentValue is required by the schema, so the SDK is assessed on requiring it.) |
docs/protocol/v1/session-config-options.mdx L225 |
| 156 | ACP-V1-CONFIG-CLIENT-IGNORE-UNKNOWN-TYPE |
SHOULD | client | sdk | imported | If a Client receives an option with an unrecognized type, it SHOULD ignore that option. | docs/protocol/v1/session-config-options.mdx L231 |
| 157 | ACP-V1-CONFIG-SET-RESPONSE-COMPLETE |
MUST | agent | shared | imported | The Agent MUST respond with the complete list of all configuration options and their current values: (Applies when: Applies when the Agent handles session/set_config_option.) |
docs/protocol/v1/session-config-options.mdx L284 |
| 158 | ACP-V1-CONFIG-AGENT-SEND-BOTH-DURING-TRANSITION |
SHOULD | agent | application | imported | However, during the transition period, Agents that provide mode-like configuration SHOULD send both: - configOptions with a category: "mode" option for Clients that support config options - modes for Clients that only support the older API (Applies when: Applies to Agents that provide mode-like configuration; what to send is the application's choice, the SDK is assessed on allowing both fields.) | docs/protocol/v1/session-config-options.mdx L359-L362 |
| 159 | ACP-V1-CONFIG-CLIENT-USE-CONFIG-EXCLUSIVELY |
SHOULD | client | application | imported | Clients that support config options SHOULD use configOptions exclusively and ignore modes (Applies when: Applies when both fields are present; the choice is the Client application's.) | docs/protocol/v1/session-config-options.mdx L366 |
| 160 | ACP-V1-CONFIG-CLIENT-FALLBACK-TO-MODES |
SHOULD | client | application | imported | Clients that don't support config options SHOULD fall back to modes (Applies when: Applies to Clients without config-option support when both fields are present; the choice is the application's.) | docs/protocol/v1/session-config-options.mdx L367 |
| 161 | ACP-V1-CONFIG-AGENT-KEEP-IN-SYNC |
SHOULD | agent | application | imported | Agents SHOULD keep both in sync to ensure consistent behavior regardless of which field the Client uses (Applies when: Applies when the Agent sends both configOptions and modes; the values are the application's.) |
docs/protocol/v1/session-config-options.mdx L368 |
| 162 | ACP-V1-COMMANDS-ADVERTISE-MAY |
MAY | agent | sdk | imported | After creating a session, the Agent MAY send a list of available commands via the available_commands_update session notification: | docs/protocol/v1/slash-commands.mdx L10 |
| 163 | ACP-V1-EXT-META-TRACE-KEYS-RESERVED |
SHOULD | both | shared | imported | The following root-level keys in _meta SHOULD be reserved for W3C trace context to guarantee interop with existing MCP implementations and OpenTelemetry tooling: - traceparent - tracestate - baggage (Applies when: Applies to any implementation that writes _meta; the SDK is assessed on not using these keys for anything else.) |
docs/protocol/v1/extensibility.mdx L37-L41 |
| 164 | ACP-V1-EXT-NO-ROOT-CUSTOM-FIELDS |
MUST NOT | both | sdk | imported | Implementations MUST NOT add any custom fields at the root of a type that's part of the specification. All possible names are reserved for future protocol versions. | docs/protocol/v1/extensibility.mdx L43 |
| 165 | ACP-V1-EXT-CUSTOM-REQUESTS-MAY |
MAY | both | sdk | imported | In addition to the requests specified by the protocol, implementations MAY expose and call custom JSON-RPC requests as long as their name starts with an underscore (_). | docs/protocol/v1/extensibility.mdx L56 |
| 166 | ACP-V1-EXT-RESPOND-TO-CUSTOM-REQUEST |
MUST | both | sdk | imported | Upon receiving a custom request, implementations MUST respond accordingly with the provided id: | docs/protocol/v1/extensibility.mdx L69 |
| 167 | ACP-V1-EXT-ADVERTISE-CUSTOM-CAPABILITIES |
SHOULD | both | application | imported | To avoid such cases, extensions SHOULD advertise their custom capabilities so that callers can check their availability first and adapt their behavior or interface accordingly. (Applies when: Applies to implementations that define extension methods; what to advertise is the application's, the SDK is assessed on allowing _meta in capability objects.) |
docs/protocol/v1/extensibility.mdx L97 |
| 168 | ACP-V1-EXT-IGNORE-UNKNOWN-NOTIFICATIONS |
SHOULD | both | sdk | imported | Unlike with custom requests, implementations SHOULD ignore unrecognized notifications. | docs/protocol/v1/extensibility.mdx L113 |
| 169 | ACP-V1-EXT-META-FOR-CUSTOM-CAPABILITIES |
SHOULD | both | shared | imported | Implementations SHOULD use the _meta field in capability objects to advertise support for extensions and their methods: (Applies when: Applies to implementations that support extensions; the SDK is assessed on carrying _meta in capability objects.) |
docs/protocol/v1/extensibility.mdx L117 |
| 170 | ACP-V1-TRANSPORT-UTF8 |
MUST | both | sdk | imported | JSON-RPC messages MUST be UTF-8 encoded. | docs/protocol/v1/transports.mdx L6 |
| 171 | ACP-V1-TRANSPORT-STDIO-SHOULD |
SHOULD | both | sdk | imported | Agents and clients SHOULD support stdio whenever possible. | docs/protocol/v1/transports.mdx L13 |
| 172 | ACP-V1-TRANSPORT-STDIO-NEWLINE-DELIMITED |
MUST NOT | both | sdk | imported | Messages are delimited by newlines (\n), and MUST NOT contain embedded newlines. (Applies when: Applies to the stdio transport.) | docs/protocol/v1/transports.mdx L24 |
| 173 | ACP-V1-TRANSPORT-AGENT-STDERR-MAY |
MAY | agent | sdk | imported | The agent MAY write UTF-8 strings to its standard error (stderr) for logging purposes. (Applies when: Applies to the stdio transport.) | docs/protocol/v1/transports.mdx L25 |
| 174 | ACP-V1-TRANSPORT-CLIENT-STDERR-MAY |
MAY | client | sdk | imported | Clients MAY capture, forward, or ignore this logging. (Applies when: Applies to the stdio transport.) | docs/protocol/v1/transports.mdx L25 |
| 175 | ACP-V1-TRANSPORT-AGENT-STDOUT-ONLY-ACP |
MUST NOT | agent | sdk | imported | The agent MUST NOT write anything to its stdout that is not a valid ACP message. (Applies when: Applies to the stdio transport.) | docs/protocol/v1/transports.mdx L26 |
| 176 | ACP-V1-TRANSPORT-CLIENT-STDIN-ONLY-ACP |
MUST NOT | client | sdk | imported | The client MUST NOT write anything to the agent's stdin that is not a valid ACP message. (Applies when: Applies to the stdio transport.) | docs/protocol/v1/transports.mdx L27 |
| 177 | ACP-V1-TRANSPORT-CUSTOM-MAY |
MAY | both | sdk | imported | Agents and clients MAY implement additional custom transport mechanisms to suit their specific needs. | docs/protocol/v1/transports.mdx L50 |
| 178 | ACP-V1-TRANSPORT-CUSTOM-PRESERVE-FORMAT-AND-LIFECYCLE |
MUST | both | sdk | imported | Implementers who choose to support custom transports MUST ensure they preserve the JSON-RPC message format and lifecycle requirements defined by ACP. (Applies when: Applies to every custom transport the implementation offers; for the Java SDK that is its HTTP and WebSocket transports, which the stable page does not define and which are assessed here only as custom transports.) | docs/protocol/v1/transports.mdx L52 |
| 179 | ACP-V1-TRANSPORT-CUSTOM-DOCUMENT |
SHOULD | both | shared | imported | Custom transports SHOULD document their specific connection establishment and message exchange patterns to aid interoperability. (Applies when: Applies to every custom transport the implementation offers.) | docs/protocol/v1/transports.mdx L52 |
| 180 | ACP-V1-CONTENT-CLIENT-RENDER-MARKDOWN |
SHOULD | client | application | imported | Clients SHOULD render this text as Markdown. (Applies when: Rendering is the Client application's; the SDK is the subject only insofar as it preserves the text unchanged.) | schema/v1/schema.json /$defs/ContentBlock/oneOf/0 |
| 181 | ACP-V1-ELIC-CLIENT-UNKNOWN-MODE-NOT-RENDERED-AS-KNOWN |
MUST NOT | client | sdk | imported | Clients that do not understand this mode should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known elicitation mode. (Applies when: Applies when the Client receives an elicitation/create request whose mode it does not understand.) |
schema/v1/schema.json /$defs/CreateElicitationRequest/anyOf/2 |
| 182 | ACP-V1-ELIC-CLIENT-UNKNOWN-PROPERTY-SCHEMA-NOT-RENDERED-AS-KNOWN |
MUST NOT | client | sdk | imported | Clients that do not understand this property schema type should preserve the raw schema when storing, replaying, proxying, or forwarding elicitation requests. They MUST NOT render it as a known input control. (Applies when: Applies when the Client receives a form-mode elicitation with a property schema type it does not understand.) | schema/v1/schema.json /$defs/ElicitationPropertySchema/anyOf/5 |
| 183 | ACP-V1-AUTH-AGENT-TERMINAL-METHOD-ONLY-WITH-CAPABILITY |
MUST | agent | sdk | imported | Agents MUST advertise this method only when the client enabled its terminal authentication capability. (Applies when: Applies when the Agent offers a terminal authentication method.) |
schema/v1/schema.json /$defs/AuthMethodTerminal |
| 184 | ACP-V1-EXT-META-NO-ASSUMPTIONS |
MUST NOT | both | sdk | imported | The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Implementations MUST NOT make assumptions about values at these keys. | schema/v1/schema.json /$defs/InitializeRequest/properties/_meta |
| 185 | ACP-V1-PROMPT-CLIENT-CONTEXT-BLOCKS-MAY |
MAY | client | sdk | imported | The client MAY include referenced pieces of context as either [ContentBlock::Resource] or [ContentBlock::ResourceLink]. (Applies when: Embedded resources additionally require the Agent's embeddedContext prompt capability.) |
schema/v1/schema.json /$defs/PromptRequest/properties/prompt |
| 186 | ACP-V1-ELIC-AGENT-UNKNOWN-ACTION-NOT-TREATED-AS-KNOWN |
MUST NOT | agent | sdk | imported | Agents that do not understand this action should preserve the raw payload when storing, replaying, proxying, or forwarding elicitation responses. They MUST NOT treat it as a known elicitation action. (Applies when: Applies when the Agent receives an elicitation/create response whose action it does not understand.) |
schema/v1/schema.json /$defs/CreateElicitationResponse/anyOf/3 |
| 187 | ACP-V1-SCHEMA-INITIALIZE-SHAPE |
MUST | both | sdk | derived | initialize messages MUST conform to the stable schema: the request params is an InitializeRequest object and a successful result is an InitializeResponse object, each carrying every required member with its declared type, including the nested ClientCapabilities and AgentCapabilities objects whose omitted or null members mean 'not advertised'. Derived structure (generated from the pinned schema): /$defs/InitializeRequest: required ['protocolVersion']; declared properties ['protocolVersion', 'clientCapabilities', 'clientInfo', '_meta'] | /$defs/InitializeResponse: required ['protocolVersion']; declared properties ['protocolVersion', 'agentCapabilities', 'authMethods', 'agentInfo', '_meta'] | /$defs/ClientCapabilities: required none; declared properties ['fs', 'terminal', 'session', 'auth', 'elicitation', '_meta'] | /$defs/AgentCapabilities: required none; declared properties ['loadSession', 'promptCapabilities', 'mcpCapabilities', 'sessionCapabilities', 'auth', '_meta'] |
schema/v1/schema.json /$defs/InitializeRequest |
| 188 | ACP-V1-SCHEMA-AUTHENTICATE-SHAPE |
MUST | both | sdk | derived | authenticate messages MUST conform to the stable schema: params is an AuthenticateRequest object and a successful result is an AuthenticateResponse object. Derived structure (generated from the pinned schema): /$defs/AuthenticateRequest: required ['methodId']; declared properties ['methodId', '_meta'] | /$defs/AuthenticateResponse: required none; declared properties ['_meta'] |
schema/v1/schema.json /$defs/AuthenticateRequest |
| 189 | ACP-V1-SCHEMA-LOGOUT-SHAPE |
MUST | both | sdk | derived | logout messages MUST conform to the stable schema: params is a LogoutRequest object and a successful result is a LogoutResponse object. Derived structure (generated from the pinned schema): /$defs/LogoutRequest: required none; declared properties ['_meta'] | /$defs/LogoutResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Agent advertises auth.logout.) |
schema/v1/schema.json /$defs/LogoutRequest |
| 190 | ACP-V1-SCHEMA-NEW-SESSION-SHAPE |
MUST | both | sdk | derived | session/new messages MUST conform to the stable schema: params is a NewSessionRequest object and a successful result is a NewSessionResponse object, including the optional SessionModeState and SessionConfigOption structures. Derived structure (generated from the pinned schema): /$defs/NewSessionRequest: required ['cwd', 'mcpServers']; declared properties ['cwd', 'additionalDirectories', 'mcpServers', '_meta'] | /$defs/NewSessionResponse: required ['sessionId']; declared properties ['sessionId', 'modes', 'configOptions', '_meta'] | /$defs/SessionModeState: required ['currentModeId', 'availableModes']; declared properties ['currentModeId', 'availableModes', '_meta'] | /$defs/SessionConfigOption: required ['id', 'name']; declared properties ['id', 'name', 'description', 'category', '_meta'] |
schema/v1/schema.json /$defs/NewSessionRequest |
| 191 | ACP-V1-SCHEMA-LOAD-SESSION-SHAPE |
MUST | both | sdk | derived | session/load messages MUST conform to the stable schema: params is a LoadSessionRequest object and a successful result is a LoadSessionResponse object. Derived structure (generated from the pinned schema): /$defs/LoadSessionRequest: required ['mcpServers', 'cwd', 'sessionId']; declared properties ['mcpServers', 'cwd', 'additionalDirectories', 'sessionId', '_meta'] | /$defs/LoadSessionResponse: required none; declared properties ['modes', 'configOptions', '_meta'] (Applies when: Applies when the Agent advertises loadSession.) |
schema/v1/schema.json /$defs/LoadSessionRequest |
| 192 | ACP-V1-SCHEMA-RESUME-SESSION-SHAPE |
MUST | both | sdk | derived | session/resume messages MUST conform to the stable schema: params is a ResumeSessionRequest object and a successful result is a ResumeSessionResponse object. Derived structure (generated from the pinned schema): /$defs/ResumeSessionRequest: required ['sessionId', 'cwd']; declared properties ['sessionId', 'cwd', 'additionalDirectories', 'mcpServers', '_meta'] | /$defs/ResumeSessionResponse: required none; declared properties ['modes', 'configOptions', '_meta'] (Applies when: Applies when the Agent advertises sessionCapabilities.resume.) |
schema/v1/schema.json /$defs/ResumeSessionRequest |
| 193 | ACP-V1-SCHEMA-CLOSE-SESSION-SHAPE |
MUST | both | sdk | derived | session/close messages MUST conform to the stable schema: params is a CloseSessionRequest object and a successful result is a CloseSessionResponse object. Derived structure (generated from the pinned schema): /$defs/CloseSessionRequest: required ['sessionId']; declared properties ['sessionId', '_meta'] | /$defs/CloseSessionResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Agent advertises sessionCapabilities.close.) |
schema/v1/schema.json /$defs/CloseSessionRequest |
| 194 | ACP-V1-SCHEMA-LIST-SESSIONS-SHAPE |
MUST | both | sdk | derived | session/list messages MUST conform to the stable schema: params is a ListSessionsRequest object and a successful result is a ListSessionsResponse object whose sessions entries are SessionInfo objects. Derived structure (generated from the pinned schema): /$defs/ListSessionsRequest: required none; declared properties ['cwd', 'cursor', '_meta'] | /$defs/ListSessionsResponse: required ['sessions']; declared properties ['sessions', 'nextCursor', '_meta'] | /$defs/SessionInfo: required ['sessionId', 'cwd']; declared properties ['sessionId', 'cwd', 'additionalDirectories', 'title', 'updatedAt', '_meta'] (Applies when: Applies when the Agent advertises sessionCapabilities.list.) |
schema/v1/schema.json /$defs/ListSessionsRequest |
| 195 | ACP-V1-SCHEMA-DELETE-SESSION-SHAPE |
MUST | both | sdk | derived | session/delete messages MUST conform to the stable schema: params is a DeleteSessionRequest object and a successful result is a DeleteSessionResponse object. Derived structure (generated from the pinned schema): /$defs/DeleteSessionRequest: required ['sessionId']; declared properties ['sessionId', '_meta'] | /$defs/DeleteSessionResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Agent advertises sessionCapabilities.delete.) |
schema/v1/schema.json /$defs/DeleteSessionRequest |
| 196 | ACP-V1-SCHEMA-SET-MODE-SHAPE |
MUST | both | sdk | derived | session/set_mode messages MUST conform to the stable schema: params is a SetSessionModeRequest object and a successful result is a SetSessionModeResponse object. Derived structure (generated from the pinned schema): /$defs/SetSessionModeRequest: required ['sessionId', 'modeId']; declared properties ['sessionId', 'modeId', '_meta'] | /$defs/SetSessionModeResponse: required none; declared properties ['_meta'] |
schema/v1/schema.json /$defs/SetSessionModeRequest |
| 197 | ACP-V1-SCHEMA-SET-CONFIG-OPTION-SHAPE |
MUST | both | sdk | derived | session/set_config_option messages MUST conform to the stable schema: params is a SetSessionConfigOptionRequest object and a successful result is a SetSessionConfigOptionResponse object. Derived structure (generated from the pinned schema): /$defs/SetSessionConfigOptionRequest: required ['sessionId', 'configId']; declared properties ['sessionId', 'configId', '_meta'] | /$defs/SetSessionConfigOptionResponse: required ['configOptions']; declared properties ['configOptions', '_meta'] |
schema/v1/schema.json /$defs/SetSessionConfigOptionRequest |
| 198 | ACP-V1-SCHEMA-PROMPT-SHAPE |
MUST | both | sdk | derived | session/prompt messages MUST conform to the stable schema: params is a PromptRequest object whose prompt is an array of ContentBlock values, and a successful result is a PromptResponse object carrying a StopReason. Derived structure (generated from the pinned schema): /$defs/PromptRequest: required ['sessionId', 'prompt']; declared properties ['sessionId', 'prompt', '_meta'] | /$defs/PromptResponse: required ['stopReason']; declared properties ['stopReason', '_meta'] |
schema/v1/schema.json /$defs/PromptRequest |
| 199 | ACP-V1-SCHEMA-CANCEL-NOTIFICATION-SHAPE |
MUST | both | sdk | derived | session/cancel is a notification whose params MUST be a CancelNotification object. Derived structure (generated from the pinned schema): /$defs/CancelNotification: required ['sessionId']; declared properties ['sessionId', '_meta'] |
schema/v1/schema.json /$defs/CancelNotification |
| 200 | ACP-V1-SCHEMA-CANCEL-REQUEST-NOTIFICATION-SHAPE |
MUST | both | sdk | derived | $/cancel_request is a protocol-level notification whose params MUST be a CancelRequestNotification object carrying the requestId of the request to cancel. Derived structure (generated from the pinned schema): /$defs/CancelRequestNotification: required ['requestId']; declared properties ['requestId', '_meta'] (Applies when: Applies to an implementation that sends or supports $/cancel_request.) |
schema/v1/schema.json /$defs/CancelRequestNotification |
| 201 | ACP-V1-SCHEMA-REQUEST-PERMISSION-SHAPE |
MUST | both | sdk | derived | session/request_permission messages MUST conform to the stable schema: params is a RequestPermissionRequest object with a ToolCallUpdate and PermissionOption entries, and a successful result is a RequestPermissionResponse object whose outcome is a RequestPermissionOutcome variant (cancelled or selected with optionId). Derived structure (generated from the pinned schema): /$defs/RequestPermissionRequest: required ['sessionId', 'toolCall', 'options']; declared properties ['sessionId', 'toolCall', 'options', '_meta'] | /$defs/RequestPermissionResponse: required ['outcome']; declared properties ['outcome', '_meta'] | /$defs/RequestPermissionOutcome: oneOf | /$defs/PermissionOption: required ['optionId', 'name', 'kind']; declared properties ['optionId', 'name', 'kind', '_meta'] |
schema/v1/schema.json /$defs/RequestPermissionRequest |
| 202 | ACP-V1-SCHEMA-SESSION-UPDATE-VARIANTS |
MUST | both | sdk | derived | session/update is a notification whose params MUST be a SessionNotification object; its update MUST be exactly one SessionUpdate variant discriminated by sessionUpdate (user_message_chunk, agent_message_chunk, agent_thought_chunk, tool_call, tool_call_update, plan, available_commands_update, current_mode_update, config_option_update, session_info_update, usage_update), each carrying that variant's required members (for example toolCallId and title on tool_call, entries on plan, used and size on usage_update). Derived structure (generated from the pinned schema): /$defs/SessionNotification: required ['sessionId', 'update']; declared properties ['sessionId', 'update', '_meta'] | /$defs/SessionUpdate: oneOf | /$defs/ToolCall: required ['toolCallId', 'title']; declared properties ['toolCallId', 'title', 'name', 'kind', 'status', 'content', 'locations', 'rawInput', 'rawOutput', '_meta'] | /$defs/ToolCallUpdate: required ['toolCallId']; declared properties ['toolCallId', 'kind', 'status', 'title', 'name', 'content', 'locations', 'rawInput', 'rawOutput', '_meta'] | /$defs/Plan: required ['entries']; declared properties ['entries', '_meta'] | /$defs/UsageUpdate: required ['used', 'size']; declared properties ['used', 'size', 'cost', '_meta'] |
schema/v1/schema.json /$defs/SessionNotification |
| 203 | ACP-V1-SCHEMA-READ-TEXT-FILE-SHAPE |
MUST | both | sdk | derived | fs/read_text_file messages MUST conform to the stable schema: params is a ReadTextFileRequest object and a successful result is a ReadTextFileResponse object. Derived structure (generated from the pinned schema): /$defs/ReadTextFileRequest: required ['sessionId', 'path']; declared properties ['sessionId', 'path', 'line', 'limit', '_meta'] | /$defs/ReadTextFileResponse: required ['content']; declared properties ['content', '_meta'] (Applies when: Applies when the Client advertises fs.readTextFile.) |
schema/v1/schema.json /$defs/ReadTextFileRequest |
| 204 | ACP-V1-SCHEMA-WRITE-TEXT-FILE-SHAPE |
MUST | both | sdk | derived | fs/write_text_file messages MUST conform to the stable schema: params is a WriteTextFileRequest object and a successful result is a WriteTextFileResponse object. Derived structure (generated from the pinned schema): /$defs/WriteTextFileRequest: required ['sessionId', 'path', 'content']; declared properties ['sessionId', 'path', 'content', '_meta'] | /$defs/WriteTextFileResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Client advertises fs.writeTextFile.) |
schema/v1/schema.json /$defs/WriteTextFileRequest |
| 205 | ACP-V1-SCHEMA-TERMINAL-CREATE-SHAPE |
MUST | both | sdk | derived | terminal/create messages MUST conform to the stable schema: params is a CreateTerminalRequest object and a successful result is a CreateTerminalResponse object. Derived structure (generated from the pinned schema): /$defs/CreateTerminalRequest: required ['sessionId', 'command']; declared properties ['sessionId', 'command', 'args', 'env', 'cwd', 'outputByteLimit', '_meta'] | /$defs/CreateTerminalResponse: required ['terminalId']; declared properties ['terminalId', '_meta'] (Applies when: Applies when the Client advertises terminal.) |
schema/v1/schema.json /$defs/CreateTerminalRequest |
| 206 | ACP-V1-SCHEMA-TERMINAL-OUTPUT-SHAPE |
MUST | both | sdk | derived | terminal/output messages MUST conform to the stable schema: params is a TerminalOutputRequest object and a successful result is a TerminalOutputResponse object with an optional TerminalExitStatus. Derived structure (generated from the pinned schema): /$defs/TerminalOutputRequest: required ['sessionId', 'terminalId']; declared properties ['sessionId', 'terminalId', '_meta'] | /$defs/TerminalOutputResponse: required ['output', 'truncated']; declared properties ['output', 'truncated', 'exitStatus', '_meta'] | /$defs/TerminalExitStatus: required none; declared properties ['exitCode', 'signal', '_meta'] (Applies when: Applies when the Client advertises terminal.) |
schema/v1/schema.json /$defs/TerminalOutputRequest |
| 207 | ACP-V1-SCHEMA-TERMINAL-RELEASE-SHAPE |
MUST | both | sdk | derived | terminal/release messages MUST conform to the stable schema: params is a ReleaseTerminalRequest object and a successful result is a ReleaseTerminalResponse object. Derived structure (generated from the pinned schema): /$defs/ReleaseTerminalRequest: required ['sessionId', 'terminalId']; declared properties ['sessionId', 'terminalId', '_meta'] | /$defs/ReleaseTerminalResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Client advertises terminal.) |
schema/v1/schema.json /$defs/ReleaseTerminalRequest |
| 208 | ACP-V1-SCHEMA-TERMINAL-WAIT-FOR-EXIT-SHAPE |
MUST | both | sdk | derived | terminal/wait_for_exit messages MUST conform to the stable schema: params is a WaitForTerminalExitRequest object and a successful result is a WaitForTerminalExitResponse object. Derived structure (generated from the pinned schema): /$defs/WaitForTerminalExitRequest: required ['sessionId', 'terminalId']; declared properties ['sessionId', 'terminalId', '_meta'] | /$defs/WaitForTerminalExitResponse: required none; declared properties ['exitCode', 'signal', '_meta'] (Applies when: Applies when the Client advertises terminal.) |
schema/v1/schema.json /$defs/WaitForTerminalExitRequest |
| 209 | ACP-V1-SCHEMA-TERMINAL-KILL-SHAPE |
MUST | both | sdk | derived | terminal/kill messages MUST conform to the stable schema: params is a KillTerminalRequest object and a successful result is a KillTerminalResponse object. Derived structure (generated from the pinned schema): /$defs/KillTerminalRequest: required ['sessionId', 'terminalId']; declared properties ['sessionId', 'terminalId', '_meta'] | /$defs/KillTerminalResponse: required none; declared properties ['_meta'] (Applies when: Applies when the Client advertises terminal.) |
schema/v1/schema.json /$defs/KillTerminalRequest |
| 210 | ACP-V1-SCHEMA-ELICITATION-CREATE-SHAPE |
MUST | both | sdk | derived | elicitation/create messages MUST conform to the stable schema: params is a CreateElicitationRequest object with an explicit mode (form or url, with their mode-specific members and either sessionId or requestId scope) and a successful result is a CreateElicitationResponse object whose action is accept, decline or cancel. Derived structure (generated from the pinned schema): /$defs/CreateElicitationRequest: required ['message']; declared properties ['message', '_meta'] | /$defs/CreateElicitationResponse: required none; declared properties ['_meta'] | /$defs/ElicitationSchema: required none; declared properties ['type', 'title', 'properties', 'required', 'description', '_meta'] (Applies when: Applies when the Client advertises an elicitation mode.) |
schema/v1/schema.json /$defs/CreateElicitationRequest |
| 211 | ACP-V1-SCHEMA-ELICITATION-COMPLETE-SHAPE |
MUST | both | sdk | derived | elicitation/complete is a notification whose params MUST be a CompleteElicitationNotification object carrying elicitationId. Derived structure (generated from the pinned schema): /$defs/CompleteElicitationNotification: required ['elicitationId']; declared properties ['elicitationId', '_meta'] (Applies when: Applies when the Agent sends elicitation/complete.) |
schema/v1/schema.json /$defs/CompleteElicitationNotification |
| 212 | ACP-V1-SCHEMA-CONTENT-BLOCK-VARIANTS |
MUST | both | sdk | derived | Every ContentBlock MUST be exactly one of the stable variants discriminated by type (text, image, audio, resource, resource_link) with that variant's required members, and every ToolCallContent MUST be exactly one of content, diff or terminal. Derived structure (generated from the pinned schema): /$defs/ContentBlock: oneOf | /$defs/TextContent: required ['text']; declared properties ['annotations', 'text', '_meta'] | /$defs/ImageContent: required ['data', 'mimeType']; declared properties ['annotations', 'data', 'mimeType', 'uri', '_meta'] | /$defs/AudioContent: required ['data', 'mimeType']; declared properties ['annotations', 'data', 'mimeType', '_meta'] | /$defs/EmbeddedResource: required ['resource']; declared properties ['annotations', 'resource', '_meta'] | /$defs/ResourceLink: required ['name', 'uri']; declared properties ['annotations', 'description', 'mimeType', 'name', 'size', 'title', 'uri', '_meta'] | /$defs/ToolCallContent: oneOf | /$defs/Diff: required ['path', 'newText']; declared properties ['path', 'oldText', 'newText', '_meta'] |
schema/v1/schema.json /$defs/ContentBlock |
| 213 | ACP-V1-SCHEMA-STOP-REASON-VALUES |
MUST | both | sdk | derived | A PromptResponse stopReason MUST be one of the stable StopReason values (end_turn, max_tokens, max_turn_requests, refusal, cancelled). Derived structure (generated from the pinned schema): /$defs/StopReason: oneOf |
schema/v1/schema.json /$defs/StopReason |
| 214 | ACP-V1-SCHEMA-ERROR-OBJECT |
MUST | both | sdk | derived | An error response MUST carry an Error object with integer code and string message (and optional data), and the predefined codes MUST keep their stable meanings: -32700 parse error, -32600 invalid request, -32601 method not found, -32602 invalid params, -32603 internal error, -32800 request cancelled, -32000 authentication required, -32002 resource not found. Derived structure (generated from the pinned schema): /$defs/Error: required ['code', 'message']; declared properties ['code', 'message', 'data'] | /$defs/ErrorCode: anyOf |
schema/v1/schema.json /$defs/Error |
| 215 | ACP-V1-SCHEMA-MCP-SERVER-VARIANTS |
MUST | both | sdk | derived | Every McpServer entry MUST be exactly one of the stable variants: stdio (no type, with name, command, args), http (type: "http" with name, url, headers) or sse (type: "sse" with name, url, headers). Derived structure (generated from the pinned schema): /$defs/McpServer: anyOf | /$defs/McpServerStdio: required ['name', 'command', 'args', 'env']; declared properties ['name', 'command', 'args', 'env', '_meta'] | /$defs/McpServerHttp: required ['name', 'url', 'headers']; declared properties ['name', 'url', 'headers', '_meta'] | /$defs/McpServerSse: required ['name', 'url', 'headers']; declared properties ['name', 'url', 'headers', '_meta'] |
schema/v1/schema.json /$defs/McpServer |
| 216 | ACP-V1-SCHEMA-AUTH-METHOD-VARIANTS |
MUST | both | sdk | derived | Every AuthMethod advertised in authMethods MUST be exactly one of the stable variants: agent (no type or type: "agent", with id and name) or terminal (type: "terminal" with id, name and optional args and env). Derived structure (generated from the pinned schema): /$defs/AuthMethod: anyOf | /$defs/AuthMethodAgent: required ['id', 'name']; declared properties ['id', 'name', 'description', '_meta'] | /$defs/AuthMethodTerminal: required ['id', 'name']; declared properties ['id', 'name', 'description', 'args', 'env', '_meta'] |
schema/v1/schema.json /$defs/AuthMethod |
| 217 | ACP-V1-SCHEMA-EXTENSION-METHOD-NAMES |
MUST | both | sdk | derived | Extension requests and notifications MUST use method names beginning with _ and carry arbitrary JSON params; they are the only methods outside the stable method set that an implementation may route. Derived structure (generated from the pinned schema): /$defs/ExtRequest: schema | /$defs/ExtNotification: schema | /$defs/ExtResponse: schema |
schema/v1/schema.json /$defs/ExtRequest |
| 218 | ACP-V1-JSONRPC-VERSION-MEMBER |
MUST | both | sdk | incorporated | A String specifying the version of the JSON-RPC protocol. MUST be exactly "2.0". | jsonrpc/specification.html #request_object |
| 219 | ACP-V1-JSONRPC-RPC-PREFIX-RESERVED |
MUST NOT | both | sdk | incorporated | Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else. | jsonrpc/specification.html #request_object |
| 220 | ACP-V1-JSONRPC-PARAMS-MAY-BE-OMITTED |
MAY | both | sdk | incorporated | A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted. | jsonrpc/specification.html #request_object |
| 221 | ACP-V1-JSONRPC-ID-TYPE |
MUST | both | sdk | incorporated | An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. | jsonrpc/specification.html #request_object |
| 222 | ACP-V1-JSONRPC-ID-NOT-NULL |
SHOULD | both | sdk | incorporated | The value SHOULD normally not be Null [1] | jsonrpc/specification.html #request_object |
| 223 | ACP-V1-JSONRPC-ID-NO-FRACTION |
SHOULD NOT | both | sdk | incorporated | Numbers SHOULD NOT contain fractional parts [2] | jsonrpc/specification.html #request_object |
| 224 | ACP-V1-JSONRPC-RESPONSE-SAME-ID |
MUST | both | sdk | incorporated | The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects. | jsonrpc/specification.html #request_object |
| 225 | ACP-V1-JSONRPC-NO-REPLY-TO-NOTIFICATION |
MUST NOT | both | sdk | incorporated | The Server MUST NOT reply to a Notification, including those that are within a batch request. | jsonrpc/specification.html #notification |
| 226 | ACP-V1-JSONRPC-PARAMS-STRUCTURED |
MUST | both | sdk | incorporated | If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object. | jsonrpc/specification.html #parameter_structures |
| 227 | ACP-V1-JSONRPC-PARAM-NAMES-EXACT |
MUST | both | sdk | incorporated | The names MUST match exactly, including case, to the method's expected parameters. | jsonrpc/specification.html #parameter_structures |
| 228 | ACP-V1-JSONRPC-RESPONSE-REQUIRED |
MUST | both | sdk | incorporated | When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications. | jsonrpc/specification.html #response_object |
| 229 | ACP-V1-JSONRPC-RESULT-ON-SUCCESS |
MUST | both | sdk | incorporated | This member is REQUIRED on success. This member MUST NOT exist if there was an error invoking the method. | jsonrpc/specification.html #response_object |
| 230 | ACP-V1-JSONRPC-ERROR-MEMBER-ON-ERROR |
MUST | both | sdk | incorporated | This member is REQUIRED on error. This member MUST NOT exist if there was no error triggered during invocation. The value for this member MUST be an Object as defined in section 5.1. | jsonrpc/specification.html #response_object |
| 231 | ACP-V1-JSONRPC-RESPONSE-ID-ECHO |
MUST | both | sdk | incorporated | It MUST be the same as the value of the id member in the Request Object. If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null. | jsonrpc/specification.html #response_object |
| 232 | ACP-V1-JSONRPC-RESULT-XOR-ERROR |
MUST | both | sdk | incorporated | Either the result member or error member MUST be included, but both members MUST NOT be included. | jsonrpc/specification.html #response_object |
| 233 | ACP-V1-JSONRPC-ERROR-CODE-INTEGER |
MUST | both | sdk | incorporated | A Number that indicates the error type that occurred. This MUST be an integer. | jsonrpc/specification.html #error_object |
| 234 | ACP-V1-JSONRPC-ERROR-MESSAGE-CONCISE |
SHOULD | both | sdk | incorporated | A String providing a short description of the error. The message SHOULD be limited to a concise single sentence. | jsonrpc/specification.html #error_object |
| 235 | ACP-V1-JSONRPC-ERROR-RESPONSE-CONTAINS-ERROR |
MUST | both | sdk | incorporated | When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members: | jsonrpc/specification.html #error_object |
| 236 | ACP-V1-SETUP-ADDITIONAL-DIRS-FULL-LIST-ON-LOAD |
MUST | client | sdk | prose-imported | on session/load and session/resume, Clients must send the full intended additional-root list again; that list may differ from any previous or reported list as long as the request cwd matches the session's cwd, and omitting the field or providing an empty array does not restore stored roots implicitly (Applies when: Applies when the Client sends additionalDirectories on session/load or session/resume.) |
docs/protocol/v1/session-setup.mdx L342 |
| 237 | ACP-V1-ELIC-CLIENT-UNADVERTISED-MODE-INVALID-PARAMS |
MUST | client | sdk | prose-imported | Requests using a mode the Client has not advertised produce JSON-RPC -32602 (Invalid params). | docs/protocol/v1/elicitation.mdx L166-L167 |
| 238 | ACP-V1-MODES-SET-MODE-ID-LISTED |
MUST | client | shared | prose-imported | The ID of the mode to switch to. Must be one of the modes listed in availableModes (Applies when: Applies when the Client calls session/set_mode.) |
docs/protocol/v1/session-modes.mdx L101-L104 |
| 239 | ACP-V1-CONFIG-SET-VALUE-VALID |
MUST | client | shared | prose-imported | For select options, this must be one of the values listed in the option's options array. For boolean options, this must be a boolean. (Applies when: Applies when the Client calls session/set_config_option.) |
docs/protocol/v1/session-config-options.mdx L262-L266 |
| 240 | ACP-V1-EXT-UNKNOWN-METHOD-NOT-FOUND |
SHOULD | both | sdk | prose-imported | If the receiving end doesn't recognize the custom method name, it should respond with the standard "Method not found" error: | docs/protocol/v1/extensibility.mdx L84 |