Schema

Agent

Defines the interface that all ACP-compliant agents must implement. Agents are programs that use generative AI to autonomously modify code. They handle requests from clients and execute tasks using language models and tools.

auth/login

Authenticates the client using the specified authentication method. Agents MUST support this method when their initialize response included a non-empty authMethods list. Clients MUST call this method only with a method whose type defines a protocol-driven login flow, and MUST NOT call it when authMethods was omitted or empty. Called when the agent requires authentication before allowing session creation. The client provides the authentication method ID that was advertised during initialization. After successful authentication, the client can proceed to create sessions with session/new without receiving an auth_required (-32000) error. See protocol docs: Initialization

LoginAuthRequest

Request parameters for the auth/login method. Specifies which authentication method to use. Agents MUST support this method when their initialize response included a non-empty authMethods list. Clients MUST NOT call this method when authMethods was omitted or empty. Type: Object Properties:

LoginAuthResponse

Response to the auth/login method. Type: Object Properties:

auth/logout

Logs out of the current authenticated state. Agents MUST support this method when their initialize response included a non-empty authMethods list. Clients MUST NOT call this method when authMethods was omitted or empty. After a successful logout, authentication-gated requests require the client to complete an advertised authentication flow again. There is no guarantee about the behavior of already running sessions.

LogoutAuthRequest

Request parameters for the auth/logout method. Terminates the current authenticated session. Agents MUST support this method when their initialize response included a non-empty authMethods list. Clients MUST NOT call this method when authMethods was omitted or empty. Type: Object Properties:

LogoutAuthResponse

Response to the auth/logout method. Type: Object Properties:

initialize

Establishes the connection with a client and negotiates protocol capabilities. This method is called at the beginning of the connection, before any other request, to:

• Negotiate the protocol version to use
• Exchange capability information between client and agent
• Determine available authentication methods

The Client may repeat it before its first other request. The latest successful initialize is authoritative. The agent should respond with its supported protocol version and capabilities. See protocol docs: Initialization

InitializeRequest

Request parameters for the initialize method. Sent by the client to establish connection and negotiate capabilities. See protocol docs: Initialization Type: Object Properties:

InitializeResponse

Response to the initialize method. Contains the negotiated protocol version and agent capabilities. See protocol docs: Initialization Type: Object Properties:

session/cancel

Cancels a session’s foreground work and its prompts not yet inserted. Work in the latest background list is not covered and keeps running. The Agent MAY stop background activity it does not list. Upon receiving this notification, the Agent SHOULD stop all language model requests and all tool call invocations of the cancelled foreground work as soon as possible. The Agent MUST stop waiting for pending session/request_permission requests of the cancelled work and treat them as not approved. It SHOULD cancel each of them with $/cancel_request. After all ongoing operations have been successfully aborted and pending updates have been sent, the Agent MUST send an idle state_update session update with the cancelled stop reason if cancellation ended active foreground work. No additional completion update is required if no foreground work was active. After cancellation completes, the Agent SHOULD ignore late answers rather than use them to resume the cancelled work. Agents MUST catch errors caused by aborting cancelled work and report the cancelled stop reason, not error. The Agent MAY send content or tool call updates after receiving session/cancel, but MUST send them before the idle state_update that reports cancellation. See protocol docs: Cancellation

CancelSessionNotification

Notification to cancel a session’s foreground work and its prompts not yet inserted. See protocol docs: Cancellation Type: Object Properties:

session/close

Closes an active session and frees up any resources associated with it. The Agent MUST cancel any ongoing work as if session/cancel was called, stop the session’s background work, and then free the resources associated with the session.

CloseSessionRequest

Request parameters for closing an active session. The Agent MUST cancel any ongoing work related to the session as if session/cancel was called, then free the resources associated with the session. Unlike session/cancel, closing also stops the session’s background work. After the close response, the Agent sends no other messages for the session on that connection. Closing a session that does not exist or is not active SHOULD succeed, and Clients SHOULD treat a -32002 response as a successful close. When closing cancels active foreground work, the Agent MUST send the final updates for that work and the idle state_update with stopReason: "cancelled" before responding successfully to session/close. Closing an idle session does not itself require another idle update. Closing also cancels pending session/prompt requests whose messages have not been inserted, including held prompts. If closing prevents a prompt’s user message from being inserted, the Agent MUST answer that request with -32800 (Request Cancelled). If the message has already been inserted, the Agent MUST respond successfully with its messageId. Prompt responses need not precede the close response. Type: Object Properties:

CloseSessionResponse

Response from closing a session. Type: Object Properties:

session/delete

Deletes an existing session from session/list. This method is only available if the agent advertises the session.delete capability.

DeleteSessionRequest

Request parameters for deleting an existing session from session/list. Only available if the Agent supports the session.delete capability. Type: Object Properties:

DeleteSessionResponse

Response from deleting a session. Type: Object Properties:

session/list

Lists existing sessions known to the agent. The agent should return metadata about sessions with optional filtering and pagination support.

ListSessionsRequest

Request parameters for listing existing sessions. Type: Object Properties:

ListSessionsResponse

Response from listing sessions. Type: Object Properties:

session/new

Creates a new conversation session with the agent. Sessions represent independent conversation contexts with their own history and state. The agent should:

• Create a new session context
• Connect to any specified MCP servers
• Return a unique session ID for future requests

May return an auth_required (-32000) error if the agent requires authentication. See protocol docs: Session Setup

NewSessionRequest

Request parameters for creating a new session. See protocol docs: Creating a Session Type: Object Properties:

NewSessionResponse

Response from creating a new session. New sessions default to idle until a state update reports otherwise. Updates may arrive before or after this response. Clients MUST NOT overwrite an already-reported state when the response arrives. See protocol docs: Creating a Session Type: Object Properties:

session/prompt

Processes a user prompt within a session. Acceptance means adding a logical user message with an ID and a position relative to other messages in the ACP conversation, not receipt or queueing. The Agent MUST return the inserted message’s ID without waiting for processing to finish. The Agent reports the user message with the same ID through session/update. This notification may arrive before or after the response, but neither may precede insertion. Processing state, output, tool calls, and completion are also reported through session updates. An error response means the user message was not inserted. Once it is inserted, the Agent MUST NOT answer with an error, even if the work fails before the response is sent. It ends that work with the error stop reason. A rejected submission produces no user-message updates. Foreground state follows its normal lifecycle independently of the request outcome: running may precede insertion, and rejection alone does not imply idle. See protocol docs: Prompt Lifecycle

PromptRequest

Request parameters for sending a user prompt to the agent. Contains the user’s message and any additional context. See protocol docs: User Message Type: Object Properties:

PromptResponse

Response acknowledging that a user prompt was inserted into the ACP conversation. This response does not indicate that the prompt was merely received or held, nor that the agent has finished processing it. Processing and completion are reported through state_update session updates. Insertion is the logical addition of a user message with a message ID and a position relative to other messages in the ACP conversation. See protocol docs: Prompt Accepted Type: Object Properties:

session/resume

Resumes an existing session. The agent should resume the session context, allowing the conversation to continue. If replayFrom is set, the agent should replay retained conversation history before responding.

ResumeSessionRequest

Request parameters for resuming an existing session. Resumes an existing session and optionally replays retained conversation history according to replayFrom. Type: Object Properties:

ResumeSessionResponse

Response from resuming an existing session. The agent MUST send a current state_update after any requested history replay and before this response, even without replay. The update reports foreground state after resuming. The response alone does not imply idle. See protocol docs: Current-State Synchronization Type: Object Properties:

session/set_config_option

Sets the current value for a session configuration option.

SetSessionConfigOptionRequest

Request parameters for setting a session configuration option. Agents MUST support this method for any session where they advertise config options. Agents MUST reject an unknown configId or invalid value with -32602 and leave the configuration unchanged. See protocol docs: Session Config Options Type: Union Shared properties: Variants:

SetSessionConfigOptionResponse

Response to session/set_config_option method. Type: Object Properties:

terminal/cancel

Stops one terminal’s process without cancelling the rest of the session’s work. This method is only available while the terminal advertises capabilities.cancel. The response means the Agent accepted the cancellation. A terminal_update with exitStatus confirms it.

CancelTerminalRequest

Request parameters for cancelling one terminal. Clients MUST NOT send it unless the terminal currently advertises capabilities.cancel. The Agent responds once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms it with a terminal_update that sets exitStatus. Cancelling stops the process but does not release the terminal, and does not change the status of a tool call that references it. The Agent responds with -32602 if the terminal is unknown, has already exited, or is not cancellable. Cancelling a terminal does not change the foreground state by itself. See protocol docs: Cancelling Terminals Type: Object Properties:

CancelTerminalResponse

Response from cancelling a terminal. Type: Object Properties:

tool_call/cancel

Cancels one tool call without cancelling the rest of the session’s work. This method is only available while the tool call advertises capabilities.cancel. The response means the Agent accepted the cancellation. A final tool_call_update confirms it.

CancelToolCallRequest

Request parameters for cancelling one tool call. Clients MUST NOT send it unless the tool call currently advertises capabilities.cancel. The Agent responds once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms it with a tool_call_update to a final status: normally cancelled, or completed or failed if the work finished first. The Agent responds with -32602 if the tool call is unknown, already final, or not cancellable. Cancelling a tool call does not change the foreground state by itself. See protocol docs: Cancelling Tool Calls Type: Object Properties:

CancelToolCallResponse

Response from cancelling a tool call. Type: Object Properties:

Client

Defines the interface that ACP-compliant clients must implement. Clients are typically code editors (IDEs, text editors) that provide the interface between users and AI agents. They manage the environment, handle user interactions, and control access to resources.

elicitation/complete

Notification that a URL-based elicitation has completed. See protocol docs: Elicitation

CompleteElicitationNotification

Notification sent by the agent when a URL-based elicitation is complete. This notification is not a foreground state update. Type: Object Properties:

elicitation/create

Requests structured user input via a form or URL. See protocol docs: Elicitation

CreateElicitationRequest

Request from the agent to elicit structured user input. The agent sends this to the client to request information from the user, either via a form or by directing them to a URL. Elicitations are tied to a session (optionally a tool call) or a request. A session-scoped request follows the aggregate foreground-state contract: agents SHOULD report requires_action when the whole foreground workflow is blocked on user action. Once reported, they MUST report running when progress resumes, or idle if work ends without resuming. Independent background requests and request-scoped elicitations do not themselves change session state. Accepting a URL does not mean the external interaction completed. Agents SHOULD cancel pending elicitations no longer needed by cancelled work. The request’s scope alone does not establish that dependency. See protocol docs: Elicitation Type: Union Shared properties: Variants:

CreateElicitationResponse

Response from the client to an elicitation request. Type: Union Shared properties: Variants:

session/request_permission

Requests permission from the user for an operation. Called by the agent when it needs user authorization before executing a potentially sensitive operation. The client should present the options to the user and return their decision. After session/cancel, the agent stops waiting for requests of the cancelled foreground work and SHOULD cancel them with $/cancel_request. The client answers a cancelled request with the cancelled outcome. See protocol docs: Requesting Permission

RequestPermissionRequest

Request for user permission to proceed with an operation. Sent when the agent needs authorization before performing a sensitive operation. See protocol docs: Requesting Permission Type: Object Properties:

RequestPermissionResponse

Response to a permission request. Type: Object Properties:

session/update

Handles session update notifications from the agent. This is a notification endpoint (no response expected) that receives updates about session activity, including message updates, message chunks, tool calls, and execution plans. Note: Clients SHOULD continue accepting tool call updates even after sending a session/cancel notification, as the agent may send final updates before reporting an idle state_update with the cancelled stop reason. See protocol docs: Agent Reports Output

UpdateSessionNotification

Notification containing a session update from the agent. Agents can send session updates at any point while the session exists. See protocol docs: Agent Reports Output Type: Object Properties:

Protocol Level

Defines the interface that ACP-compliant agents and clients must both implement. Notifications whose methods start with ‘$/' are messages which are protocol implementation dependent and might not be implementable in all clients or agents. For example if the implementation uses a single threaded synchronous programming language then there is little it can do to react to a `$/cancel_request` notification. If an agent or client receives notifications starting with ’$/’ it is free to ignore the notification.

$/cancel_request

Cancels an ongoing request. This is a notification sent by the side that sent a request to cancel that request. Upon receiving this notification, the receiver:

1. MAY cancel the corresponding request activity and all nested activities
2. MAY send any pending notifications.
3. MUST still send a response for the original request. If the request already finished or is not cancelled, that is its normal response. If it is cancelled, it is either the method’s defined cancellation result (for example an inserted session/prompt, or a cancelled permission outcome) or an error with code -32800 (Request Cancelled).

Receivers MUST ignore this notification for an unknown or already-answered request ID, and MUST NOT send a second response for it. See protocol docs: Cancellation

CancelRequestNotification

Notification to cancel an ongoing request. See protocol docs: Cancellation Type: Object Properties:

AbsolutePath

An absolute filesystem path used by the protocol. Uses the native syntax of the machine the Agent runs on, such as /home/user/project, C:\Users\user\project, or \\server\share\project. It is not a URI. Type: string

AgentAuthCapabilities

Authentication-related extension capabilities supported by the agent. This object does not advertise support for auth/login or auth/logout. Those methods are advertised by a non-empty authMethods list in the initialize response. Type: Object Properties:

AgentCapabilities

Capabilities supported by the agent. Advertised during initialization to inform the client about available features and content types. See protocol docs: Agent Capabilities Type: Object Properties:

AgentMessage

An agent message upsert. Only messageId is required. content has patch semantics: an omitted field leaves existing message content unchanged, null clears the value, and a concrete array replaces the previous value. For a new messageId, omitted content starts empty. content is replaced as a whole array. Send [] or null to clear it. Message updates and chunks are applied in the order they are received. When an agent_message update includes content, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties:

AgentThought

An agent thought or reasoning message upsert. Only messageId is required. content has patch semantics: an omitted field leaves existing thought content unchanged, null clears the value, and a concrete array replaces the previous value. For a new messageId, omitted content starts empty. content is replaced as a whole array. Send [] or null to clear it. Message updates and chunks are applied in the order they are received. When an agent_thought update includes content, that array replaces any content previously accumulated for the thought, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties:

Annotations

Optional annotations for the client. The client can use annotations to inform how objects are used or displayed Type: Object Properties:

AudioContent

Audio provided to or from an LLM. Type: Object Properties:

AuthMethod

Describes an available authentication method. The type field acts as the discriminator in the serialized JSON form. Type: Union

AuthMethodAgent

Agent handles authentication itself through auth/login. The type discriminator value is agent. Type: Object Properties:

AuthMethodId

Typed identifier used for auth method values on the wire. Type: string

AuthMethodTerminal

Terminal-based authentication method. The client runs the configured agent program as a separate interactive process for the user to authenticate via a TUI. Agents MUST advertise this method only when the client enabled its terminal authentication capability. A zero exit status signals success. Any other termination signals failure. The client MUST NOT pass this method to auth/login. Type: Object Properties:

AvailableCommand

A command the agent advertises to the client. The type field acts as the discriminator in the serialized JSON form. Type: Union

AvailableCommandInput

The input specification for a command. Type: Union

AvailableCommandsUpdate

Available commands are ready or have changed Type: Object Properties:

BackgroundSubagent

A listed subagent session associated with this session through subagent_update. Type: Object Properties:

BackgroundTerminal

A listed terminal running in the background. Type: Object Properties:

BackgroundToolCall

A listed tool call whose work continues in the background. Type: Object Properties:

BackgroundWork

One piece of work running independently of the session’s foreground work. Items reference entities the Client already tracks. The Agent MUST announce each item before the first snapshot that lists it, and MUST report a terminal’s exitStatus or a tool call’s final status before the snapshot that removes it. Each piece of work is listed once: process-backed work is listed as its terminal, not also as its tool call. See protocol docs: Background Work Type: Union

BlobResourceContents

Binary resource contents. Type: Object Properties:

BooleanPropertySchema

Schema for boolean properties in an elicitation form. Type: Object Properties:

CancelledPermissionOutcome

The request was not approved and no option was selected. Type: Object Properties:

ClientAuthCapabilities

Authentication capabilities supported by the client. Advertised during initialization to inform the agent which authentication method types the client can handle. This governs opt-in types that require additional client-side support. Type: Object Properties:

ClientCapabilities

Capabilities supported by the client. Advertised during initialization to inform the agent about available features and methods. See protocol docs: Client Capabilities Type: Object Properties:

Command

A slash command the user can invoke by including it in a prompt. The type discriminator value is command. Type: Object Properties:

CommandPermissionSubject

Permission request details for a command. Type: Object Properties:

CompactionId

Unique identifier for a context compaction within a session. Type: string

CompactionStatus

Lifecycle state of a context compaction. Type: Union

CompactionSummaryChunk

A content block appended to a compaction’s summary. A first-seen ID creates an in-progress compaction. Chunks append in receive order. Type: Object Properties:

CompactionUpdate

A context compaction upsert. The first notification fixes the compaction’s timeline position. Later updates with the same ID patch that entity in place. summary, error, and _meta have patch semantics: omission leaves the stored value unchanged, null clears it, and a concrete value replaces it. summary: [] also clears the summary. A concrete _meta object patches the stored metadata by top-level key instead of replacing it. Type: Object Properties:

ConfigOptionUpdate

Session configuration options have been updated. Type: Object Properties:

Content

Standard content block (text, images, resources). Type: Object Properties:

ContentBlock

Content blocks represent displayable information in the Agent Client Protocol. Content blocks appear in:

• User prompts sent via session/prompt
• Language model output reported through session/update notifications as message updates or streamed chunks
• Progress updates and results from tool calls

This structure is compatible with the Model Context Protocol (MCP), so agents can forward content from MCP tool outputs without transformation. See protocol docs: Content Type: Union

ContentChunk

A streamed item of message content. Type: Object Properties:

Cost

Cost information for a session. Type: Object Properties:

Diff

File changes produced by a tool call. changes is authoritative for affected absolute paths and operations. patch optionally carries renderable text for some or all of those changes and MUST be consistent with changes. Agents SHOULD provide patch whenever feasible. Clients MUST handle diffs where patch is omitted or null. See protocol docs: Content Type: Object Properties:

DiffChange

One file-level change described by a Diff. Structured change metadata lets clients identify affected files and operations without parsing the text patch. Type: Union Shared properties: Variants:

DiffFileType

Kind of file content represented by a diff change. Type: Union

DiffPatch

Renderable patch text and its format. Type: Object Properties:

DiffPatchFormat

Text patch format used by DiffPatch. Type: Union

DiffPathChange

Operation metadata for add, delete, and modify changes. Type: Object Properties:

DiffPathPairChange

Operation metadata for move and copy changes. Type: Object Properties:

ElicitationAcceptAction

The user accepted the elicitation and provided content. Type: Object Properties:

ElicitationCapabilities

Elicitation capabilities supported by the client. Type: Object Properties:

ElicitationContentValue

Allowed wire representations for ElicitationContentValue. Type: Union

ElicitationFormCapabilities

Form-based elicitation capabilities. Supplying \{\} means the client supports form-based elicitation. Type: Object Properties:

ElicitationFormMode

Form-based elicitation mode where the client renders a form from the provided schema. Type: Union Shared properties: Variants:

ElicitationId

Unique identifier for an elicitation. Type: string

ElicitationPropertySchema

Property schema for elicitation form fields. Each variant corresponds to a JSON Schema "type" value. Single-select enums use type: "string" with enum or oneOf set. Multi-select enums use type: "array". Type: Union

ElicitationRequestScope

Request-scoped elicitation, tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). Type: Object Properties:

ElicitationSchema

Type-safe elicitation schema for requesting structured user input. This represents a JSON Schema object with primitive-typed properties, as required by the elicitation specification. Type: Object Properties:

ElicitationSchemaType

Type discriminator for elicitation schemas. Type: Union

ElicitationSessionScope

Session-scoped elicitation, optionally tied to a specific tool call. When toolCallId is set, the elicitation is tied to a specific tool call. This is useful when an agent receives an elicitation from an MCP server during a tool call and needs to redirect it to the user. Type: Object Properties:

ElicitationUrlCapabilities

URL-based elicitation capabilities. Supplying \{\} means the client supports URL-based elicitation. Type: Object Properties:

ElicitationUrlMode

URL-based elicitation mode where the client directs the user to a URL. Type: Union Shared properties: Variants:

EmbeddedResource

The contents of a resource, embedded into a prompt or tool call result. Type: Object Properties:

EmbeddedResourceResource

Resource content that can be embedded in a message. Type: Union

EnumOption

A titled enum option with a const value, human-readable title, and optional description. Type: Object Properties:

EnvVariable

An environment variable to set when launching a process. Type: Object Properties:

Error

JSON-RPC error object. Represents an error that occurred during method execution, following the JSON-RPC 2.0 error object specification with optional additional data. See protocol docs: JSON-RPC Error Object Type: Object Properties:

ErrorCode

Predefined error codes for common JSON-RPC and ACP-specific errors. Standard errors use the JSON-RPC 2.0 codes. ACP-specific errors use the JSON-RPC server-error range (-32000 to -32099), and request cancellation uses -32800 from the range LSP reserves (-32899 to -32800). Type: Union

ErrorData

Schema for Error::data: the shapes ACP defines, or any other value. Type: Union

ErrorStopReason

Details of a failure that ended active work. Type: Object Properties:

ExtNotification

Allows either side to send an arbitrary notification that is not part of the ACP spec. Extension notifications provide a way to send one-way messages for custom functionality while maintaining protocol compatibility. See protocol docs: Extensibility

ExtRequest

Allows for sending an arbitrary request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: Extensibility

ExtResponse

Allows for sending an arbitrary response to an extension request that is not part of the ACP spec. Extension methods provide a way to add custom functionality while maintaining protocol compatibility. See protocol docs: Extensibility

HttpHeader

An HTTP header to set when making requests to the MCP server. Type: Object Properties:

Icon

An optionally-sized icon that can be displayed in a user interface. Type: Object Properties:

IconTheme

Theme an icon is designed for. Type: Union

IdleStateUpdate

No foreground work is active. Background activity may continue. Agents SHOULD include a stopReason when the idle transition ends foreground work. An idle update that does not end foreground work need not include one. Receivers treat an omitted, null, or malformed stopReason as the agent not reporting one. Repeated or resume snapshots may carry the last stop reason for context. They MUST NOT be counted as new completions, cancellations, or additional usage. Type: Union Shared properties: Variants:

ImageContent

An image provided to or from an LLM. Type: Object Properties:

Implementation

Metadata about the implementation of the client or agent. Describes the name and version of an ACP implementation, with an optional title for UI representation. Type: Object Properties:

IntegerPropertySchema

Schema for integer properties in an elicitation form. Type: Object Properties:

McpCapabilities

MCP capabilities supported by the agent for session lifecycle requests. Type: Object Properties:

McpHttpCapabilities

Capabilities for HTTP MCP server transports. Supplying \{\} means the agent supports HTTP MCP server transports. Type: Object Properties:

McpServer

Configuration for connecting to an MCP (Model Context Protocol) server. MCP servers provide tools and context that the agent can use when processing prompts. See protocol docs: MCP Servers Type: Union

McpServerHttp

HTTP transport configuration for MCP. Type: Object Properties:

McpServerStdio

Stdio transport configuration for MCP. Type: Object Properties:

McpStdioCapabilities

Capabilities for stdio MCP server transports. Supplying \{\} means the agent supports stdio MCP server transports. Type: Object Properties:

MediaType

An Internet media type identifying the format of protocol content. Type: string

MessageId

Identifier for a message, unique among messages of the same type within a session. Each message type, such as user messages, agent messages, and agent thoughts, has its own ID space: messages of different types may share an ID and remain distinct messages. Type: string

MultiSelectItems

Items for a multi-select (array) property schema. Type: Union

MultiSelectPropertySchema

Schema for multi-select (array) properties in an elicitation form. Type: Object Properties:

Notice

Fire-and-forget information for the user. Notices are live events rather than session history. Agents must not rely on a notice being received, displayed, or seen by the user. No Client capability is required, and unsupported Clients may ignore notices. See protocol docs: Session Notices Type: Object Properties:

NoticeSeverity

Severity hint for a session notice. Type: Union

NumberPropertySchema

Schema for number (floating-point) properties in an elicitation form. Type: Object Properties:

PermissionOption

An option presented to the user when requesting permission. Type: Object Properties:

PermissionOptionId

Unique identifier for a permission option. Type: string

PermissionOptionKind

The type of permission option being presented to the user. Helps clients choose appropriate icons and UI treatment. Type: Union

PlanEntry

A single entry in the execution plan. Represents a task or goal that the assistant intends to accomplish as part of fulfilling the user’s request. See protocol docs: Plan Entries Type: Object Properties:

PlanEntryPriority

Priority levels for plan entries. Used to indicate the relative importance or urgency of different tasks in the execution plan. See protocol docs: Plan Entries Type: Union

PlanEntryStatus

Status of a plan entry in the execution flow. Tracks the lifecycle of each task from planning through completion. See protocol docs: Plan Entries Type: Union

PlanId

Unique identifier for a plan within a session. Type: string

PlanItems

A plan represented as structured entries. Type: Object Properties:

PlanUpdate

A content update for a plan identified by ID. Type: Object Properties:

PlanUpdateContent

Updated content for a plan. Type: Union

PromptAudioCapabilities

Capabilities for audio content in prompt requests. Supplying \{\} means the agent supports audio content in prompts. Type: Object Properties:

PromptCapabilities

Prompt capabilities supported by the agent in session/prompt requests. Baseline agent functionality requires support for text and resource_link content blocks in prompt requests. Other variants must be explicitly opted in to. Capabilities for different types of content in prompt requests. Indicates which content types beyond the baseline (text and resource links) the agent can process. See protocol docs: Session Prompt Capabilities Type: Object Properties:

PromptEmbeddedContextCapabilities

Capabilities for embedded context in prompt requests. Supplying \{\} means the agent supports embedded context in prompts. Type: Object Properties:

PromptImageCapabilities

Capabilities for image content in prompt requests. Supplying \{\} means the agent supports image content in prompts. Type: Object Properties:

ProtocolVersion

Protocol version identifier. This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities. Type: integer (uint16)

ReplayComplete

Marks the end of the history replay requested by session/resume. The Agent sends this once on a session for each session/resume request with a replayFrom cursor, after the last replayed update for that session and before the response. It sends it for an empty history too. Every update for the session between the request and this update is replayed history. Every update after it is not. The Agent does not send it when replayFrom is omitted or null, or when it cannot finish the replay. A resume that ends without it delivered a truncated replay. See protocol docs: Replay Complete Type: Object Properties:

ReplayFrom

Inclusive cursor describing where replayed session history should begin. Replay includes the position identified by the cursor. Type: Union

ReplayFromStart

Inclusive replay cursor requesting replay from the start of retained conversation history. Type: Object Properties:

RequestId

A JSON-RPC request ID: a string or an integer. Unlike base JSON-RPC, it MUST NOT be null. The receiver MUST reply with the same value in the response. Each side chooses IDs for its own requests, so the same ID can be in use in both directions. A sender MUST NOT reuse an ID while a request with it is still awaiting a response. Type: Union

RequestPermissionOutcome

The outcome of a permission request. Type: Union

RequestPermissionSubject

The operation requiring permission. Type: Union

RequiresActionStateUpdate

The foreground workflow as a whole is blocked on user action. Agents SHOULD report this state when foreground work cannot progress without user action. Pending permissions or elicitations alone do not imply this state if other foreground work can progress, or if the requests belong only to independent background activity. Once reported, agents MUST report running when progress resumes, or idle if the work ends without resuming. Responding to one request does not itself imply running. Type: Object Properties:

ResourceLink

A link to a resource that the receiver may be able to read, included in a prompt or tool call result. Type: Object Properties:

Role

The sender or recipient of messages and data in a conversation. Type: Union

RunningStateUpdate

Foreground work is in progress. Type: Object Properties:

SelectedPermissionOutcome

The user selected one of the provided options. Type: Object Properties:

SessionAdditionalDirectoriesCapabilities

Capabilities for additional session directories support. Supplying \{\} means the agent supports the additionalDirectories field on supported session lifecycle requests. Agents may return SessionInfo.additionalDirectories in session/list to report the complete ordered additional-root list associated with a listed session. Type: Object Properties:

SessionCancelCapabilities

Capability to cancel work in a subagent session without ending that session. Supplying \{\} advertises support. An omitted or null cancel does not. Type: Object Properties:

SessionCapabilities

Session capabilities supported by the agent. Supplying \{\} means the agent supports the baseline session methods: session/new, session/list, session/resume, session/close, session/prompt, session/cancel, and session/update. Agents that support sessions MAY support additional session methods, prompt content types, and MCP transports by specifying additional capabilities. See protocol docs: Session Capabilities Type: Object Properties:

SessionConfigBoolean

A boolean on/off toggle session configuration option payload. Type: Object Properties:

SessionConfigGroupId

Unique identifier for a session configuration option value group. Type: string

SessionConfigId

Unique identifier for a session configuration option. Type: string

SessionConfigOption

A session configuration option selector and its current state. Type: Union Shared properties: Variants:

SessionConfigOptionCategory

Semantic category for a session configuration option. This is intended to help Clients distinguish broadly common selectors (e.g. model selector vs session mode selector vs thought/reasoning level) for UX purposes (keyboard shortcuts, icons, placement). It MUST NOT be required for correctness. Clients MUST handle missing or unknown categories gracefully. Category names beginning with _ are free for custom use, like other ACP extension methods. Category names that do not begin with _ are reserved for the ACP spec. Type: Union

SessionConfigSelect

A single-value selector (dropdown) session configuration option payload. Type: Object Properties:

SessionConfigSelectGroup

A group of possible values for a session configuration option. Type: Object Properties:

SessionConfigSelectOption

A possible value for a session configuration option. Type: Object Properties:

SessionConfigSelectOptions

Possible values for a session configuration option. Type: Union

SessionConfigValueId

Unique identifier for a session configuration option value. Type: string

SessionDeleteCapabilities

Capabilities for the session/delete method. Supplying \{\} means the agent supports deleting sessions from session/list. Type: Object Properties:

SessionId

A unique identifier for a conversation session between a client and agent. Each session has its own context, conversation history, and state, so one agent can run several independent sessions. See protocol docs: Session ID Type: string

SessionInfo

Information about a session returned by session/list Type: Object Properties:

SessionInfoUpdate

Update to session metadata. All fields are optional to support partial updates. Agents send this notification to update session information like title or custom metadata. Clients can use it to keep session titles and state current. Omitted fields leave the existing session info unchanged. null clears the corresponding value. A concrete _meta object patches the stored metadata by top-level key. Type: Object Properties:

SessionListCursor

An opaque cursor used to paginate session/list results. Type: string

SessionMessage

An upsert for an inter-session message. Type: Object Properties:

SessionMessageChunk

A streamed content block of an inter-session message. A chunk carries only content. The message’s participants and references come from session_message upserts, which can arrive before, between, or after its chunks. Type: Object Properties:

SessionNotFoundErrorData

Data for the -32002 (Resource not found) error when a session-scoped request names a session that does not exist or is not active. See protocol docs: Unknown Sessions Type: Object Properties:

SessionReference

A display-only reference to another session that this tool call operates on, such as a subagent it created, delegated to, or is waiting on. The referenced session must already be known to the Client through ordinary session setup or a subagent_update announcement. The reference does not establish ownership, grant any Client-initiated controls, or report that the referenced session received or finished any work. Type: Object Properties:

SessionSystemPromptCapabilities

Capabilities for client-provided system prompts. Supplying \{\} means the agent supports systemPrompt on session lifecycle requests in append mode. Type: Object Properties:

SessionSystemPromptModeCapabilities

System prompt delivery modes the agent supports in addition to append. append has no entry because every agent advertising session.systemPrompt supports it. Type: Object Properties:

SessionSystemPromptOverrideCapabilities

Capabilities for the override system prompt mode. Supplying \{\} means the agent supports replacing its built-in default instructions with the client-provided system prompt. Type: Object Properties:

SessionUpdate

Different types of updates that can be sent while a session exists. These updates report messages, progress, and other session activity. See protocol docs: Agent Reports Output Type: Union

StateUpdate

A snapshot of the session’s aggregate foreground activity. Foreground work is the agent’s active response or workflow in the session, including model processing, tool execution, and waiting for user action needed to continue that work. It can start with a prompt or be agent-initiated, for example to pursue an ongoing goal or follow up on a completed background task. Either way, the agent MUST report running when foreground work starts, or requires_action if it starts blocked on user action, and idle when it ends. The agent SHOULD include a stop reason on that idle update. Agent-initiated work does not require a prompt request or a synthetic user message. running may precede user-message insertion, for example during a foreground hook. It is not acknowledgment of insertion, and rejecting a prompt does not itself end foreground work. Background activity can continue and emit other session/update notifications while idle. Those notifications, including a detached task’s progress or completion, do not by themselves change this state. A permission request only warrants requires_action when foreground work is blocked on user action. The agent SHOULD report requires_action when the foreground workflow as a whole cannot progress without user action, including permissions or elicitations. Once reported, it MUST report running when progress resumes, or idle when work ends without resuming. If other foreground work can progress, the state remains running. Resolving one of several requests does not itself change the state. Agents SHOULD ignore responses for work that has already ended rather than use them to resume it. A new session defaults to idle until a state update reports otherwise. Resume MUST send a current-state snapshot after any replay and before its response. The snapshot reports foreground state after resuming. The response alone does not imply idle. Repeated snapshots are idempotent, not additional work, completions, or usage. A repeated state may carry updated information without another state transition. The agent MUST report idle when no foreground activity remains. Completing an individual activity while other foreground work continues does not require an idle boundary. Local commands use the same lifecycle even without model work. See protocol docs: Session States Type: Union

StringFormat

String format types for string properties in elicitation schemas. Type: Union

StringMultiSelectItems

String item schema for multi-select enum properties. Type: Object Properties:

StringPropertySchema

Schema for string properties in an elicitation form. When enum or oneOf is set, this represents a single-select enum with "type": "string". Type: Object Properties:

SubagentSessionCapabilities

Client-initiated session mutations permitted for a specific subagent session. A mutation requires an explicit per-child capability. Support for the method on ordinary sessions does not grant support on a child. Type: Object Properties:

SubagentUpdate

Notification that the enclosing parent session created and owns a child session. Later updates modify the existing association’s metadata, not its ownership. Sent on the immediate parent session. The first update for an unknown sessionId announces the child and MUST be sent before any live request or notification bearing the child’s session ID, including messages naming it as sender or recipient. Child events are delivered automatically. No separate child load, resume, or subscription is needed. Understanding this update, registering child sessions, and applying their operation restrictions are baseline v2 requirements. No Client capability is required. Only sessionId is required. Other fields have patch semantics: omitted fields leave the stored value unchanged, null clears or unsets the value, and concrete values replace it. A concrete _meta object instead patches the stored metadata by top-level key. For state, null removes the current state report and leaves activity unconfirmed. It does not report idle or cancellation. A child whose capabilities are unset permits no Client-initiated session mutations. cwd and additionalDirectories report where the Agent placed the child. While unset, each inherits the immediate parent’s effective value. The title and description provide the parent’s display metadata for the child. Agents SHOULD mirror known child state changes in the parent’s state using the same StateUpdate snapshot as the ordinary state_update notification on the child session. This reports child state, not a separate parent-owned lifecycle. Consumers should treat duplicate reports idempotently. Completing or cancelling work does not end the association: the parent may message the same child again. Individual messages and their outcomes do not change this association. Type: Object Properties:

SystemPrompt

Client-provided system-level instructions for a session. Clients MUST only send this when the Agent advertises session.systemPrompt. Agents that cannot apply it, for example because of an unadvertised mode or an unsupported content block type, MUST return an error instead of creating or resuming the session. Type: Object Properties:

SystemPromptMode

How the Agent combines a client-provided system prompt with its own instructions. Unknown modes are preserved so they can be stored, proxied, or forwarded. An Agent MUST return an error for a mode it does not support rather than treating it as append or override. Type: Union

Terminal

A display-only reference to an agent-owned terminal. Terminal state and output are delivered separately through terminal_update and terminal_output_chunk session updates. Type: Object Properties:

TerminalAuthCapabilities

Capabilities for terminal authentication methods. Supplying \{\} means the client can reproduce the configured agent invocation in an interactive terminal and supports terminal authentication methods. Type: Object Properties:

TerminalCancelCapabilities

Capability to cancel a terminal with terminal/cancel. Supplying \{\} advertises support. An omitted or null cancel does not. Type: Object Properties:

TerminalCapabilities

Client-initiated controls a terminal currently supports. A malformed value falls back to no controls, so the Client never sends a request the Agent did not advertise. See protocol docs: Cancelling Terminals Type: Object Properties:

TerminalExitStatus

Exit information for an agent-owned terminal. The presence of this object marks the terminal as exited, even when neither an exit code nor a signal is known. Type: Object Properties:

TerminalId

Unique identifier for an agent-owned terminal within a session. Type: string

TerminalOutput

An authoritative replacement snapshot of terminal output bytes. Type: Object Properties:

TerminalOutputChunk

A chunk of bytes appended to an agent-owned terminal’s output. Type: Object Properties:

TerminalSize

The size of an agent-owned terminal in character cells. Type: Object Properties:

TerminalUpdate

An upsert for the stored state of an agent-owned terminal. Only terminalId is required. Other fields have patch semantics: omitted fields leave the stored value unchanged, null clears it, and concrete values replace it. A concrete _meta object instead patches the stored metadata by top-level key. When the terminal ID is new, omitted fields start unknown. Type: Object Properties:

TextCommandInput

All text that was typed after the command name is provided as input. Type: Object Properties:

TextContent

Text provided to or from an LLM. Type: Object Properties:

TextResourceContents

Text-based resource contents. Type: Object Properties:

TitledMultiSelectItems

Items definition for titled multi-select enum properties. Type: Object Properties:

ToolCallCancelCapabilities

Capability to cancel a tool call with tool_call/cancel. Supplying \{\} advertises support. An omitted or null cancel does not. Type: Object Properties:

ToolCallCapabilities

Client-initiated controls a tool call currently supports. A malformed value falls back to no controls, so the Client never sends a request the Agent did not advertise. See protocol docs: Cancelling Tool Calls Type: Object Properties:

ToolCallContent

Content produced by a tool call. Tool calls can produce different types of content including standard content blocks (text, images), file diffs, or display-only terminals. See protocol docs: Content Type: Union

ToolCallContentChunk

A streamed item of tool-call content. Tool-call content chunks append one ToolCallContent item to the current content for the matching toolCallId. Agents can send a tool_call_update with content when they need to replace the whole content collection instead. Type: Object Properties:

ToolCallId

Unique identifier for a tool call within a session. Type: string

ToolCallLocation

A file location being accessed or modified by a tool. Enables clients to implement “follow-along” features that track which files the agent is working with in real-time. See protocol docs: Following the Agent Type: Object Properties:

ToolCallPermissionSubject

Permission request details for a tool call. Type: Object Properties:

ToolCallStatus

Execution status of a tool call. Tool calls progress through different statuses during their lifecycle. See protocol docs: Status Type: Union

ToolCallUpdate

Represents an upsert for a tool call that the language model has requested. Tool calls are actions that the agent executes on behalf of the language model, such as reading files, executing code, or fetching data from external sources. Only toolCallId is required. Other fields have patch semantics: omitted fields leave the existing tool call value unchanged, null clears or unsets the value, and concrete values replace the previous value. For collection fields, concrete arrays replace the previous collection, and both null and [] clear the collection. A concrete _meta object instead patches the stored metadata by top-level key. When a client receives a tool call ID it has not seen before, omitted fields start at their protocol defaults. See protocol docs: Tool Calls Type: Object Properties:

ToolKind

Categories of tools that can be invoked. Tool kinds help clients choose appropriate icons and optimize how they display tool execution progress. See protocol docs: Reporting Type: Union

UnknownStateUpdate

The Agent cannot currently determine foreground activity. Report this when activity becomes unobservable, not merely because the session has been quiet. The Client MUST stop presenting the previous state as confirmed current activity, but may retain it as last known. A later state replaces this snapshot normally. This is not a task outcome or session closure. It does not cancel work, resolve pending requests, or revoke capabilities. If a control is no longer available, the Agent updates the capabilities explicitly. Unfinished tool calls and terminals stay as last reported. The Agent does not invent a final status for them, and Clients do not present them as confirmed live activity. Type: Object Properties:

UnsupportedProtocolVersionErrorData

Data for the -32022 (Unsupported protocol version) error. See protocol docs: Version Negotiation Type: Object Properties:

UsageUpdate

Context window and cost update for a session. Type: Object Properties:

UserMessage

A user message upsert. Only messageId is required. content has patch semantics: an omitted field leaves existing message content unchanged, null clears the value, and a concrete array replaces the previous value. For a new messageId, omitted content starts empty. content is replaced as a whole array. Send [] or null to clear it. Message updates and chunks are applied in the order they are received. When a user_message update includes content, that array replaces any content previously accumulated for the message, including content from earlier chunks. Later chunks with the same messageId append to the current content. Type: Object Properties: