140 min read

Documentation Index

Fetch the complete documentation index at: https://agentclientprotocol.com/llms.txt Use this file to discover all available pages before exploring further.

Schema

Schema definitions for the Agent Client Protocol

<Note> This schema file is generated in this repository at schema/v2/schema.json. GitHub releases for this schema are not published yet.

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.

Authenticates the client using the specified authentication method.

Agents MUST support this method when their initialize response advertised at least one valid authentication method. 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 new_session without receiving an auth_required 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 advertised at least one valid authentication method. Clients MUST NOT call this method when authMethods was omitted or empty.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“methodId” type={AuthMethodId} required> The ID of the authentication method to use. Must be one of the methods advertised in the initialize response.

LoginAuthResponse

Response to the auth/login method.

Type: Object

Properties:

See protocol docs: Extensibility

auth/logout

Logs out of the current authenticated state.

Agents MUST support this method when their initialize response advertised at least one valid authentication method. 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 advertised at least one valid authentication method. Clients MUST NOT call this method when authMethods was omitted or empty.

Type: Object

Properties:

See protocol docs: Extensibility

LogoutAuthResponse

Response to the auth/logout method.

Type: Object

Properties:

See protocol docs: Extensibility

initialize

Establishes the connection with a client and negotiates protocol capabilities.

This method is called once at the beginning of the connection to:

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

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:

See protocol docs: Extensibility

<ResponseField name=“capabilities” type={ClientCapabilities}> Capabilities supported by the client.

Default: {}

<ResponseField name=“info” type={Implementation} required> Information about the implementation sending this initialize request.

<ResponseField name=“protocolVersion” type={ProtocolVersion} required> The latest protocol version supported by the client.

InitializeResponse

Response to the initialize method.

Contains the negotiated protocol version and agent capabilities.

See protocol docs: Initialization

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“authMethods” type={AuthMethod[]}> Authentication methods supported by the agent.

Optional. Omitted or empty means the agent does not advertise the authentication method surface. Supplying one or more valid methods means the agent MUST support both auth/login and auth/logout.

<ResponseField name=“capabilities” type={AgentCapabilities}> Capabilities supported by the agent.

Default: {}

<ResponseField name=“info” type={Implementation} required> Information about the implementation sending this initialize response.

<ResponseField name=“protocolVersion” type={ProtocolVersion} required> The protocol version the client specified if supported by the agent, or the latest protocol version supported by the agent.

The client should disconnect, if it doesn’t support this version.

session/cancel

Cancels ongoing operations for a session.

This is a notification sent by the client to cancel active work in a session.

Upon receiving this notification, the Agent SHOULD:

Stop all language model requests as soon as possible
Abort all tool call invocations in progress
Send any pending session/update notifications
Report an idle state_update with StopReason::Cancelled after cancellation succeeds

See protocol docs: Cancellation

CancelSessionNotification

Notification to cancel ongoing operations for a session.

See protocol docs: Cancellation

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to cancel operations for.

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) and then free up any resources associated with the session.

CloseSessionRequest

Request parameters for closing an active session.

The agent must cancel any ongoing work related to the session (treat it as if session/cancel was called) and then free up any resources associated with the session.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to close.

CloseSessionResponse

Response from closing a session.

Type: Object

Properties:

See protocol docs: Extensibility

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:

See protocol docs: Extensibility

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to delete.

DeleteSessionResponse

Response from deleting a session.

Type: Object

Properties:

See protocol docs: Extensibility

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:

See protocol docs: Extensibility

<ResponseField name=“cursor” type={<>SessionListCursor | null</>}> Opaque cursor token from a previous response’s nextCursor field for cursor-based pagination

<ResponseField name=“cwd” type={<>AbsolutePath | null</>}> Filter sessions by working directory. Must be an absolute path.

ListSessionsResponse

Response from listing sessions.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“nextCursor” type={<>SessionListCursor | null</>}> Opaque cursor token. If present, pass this in the next request’s cursor parameter to fetch the next page. If absent, there are no more results.

<ResponseField name=“sessions” type={SessionInfo[]} required> Array of session information objects.

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

See protocol docs: Extensibility

<ResponseField name=“additionalDirectories” type={AbsolutePath[]}> Additional workspace roots for this session. Each path must be absolute.

These expand the session’s workspace scope without changing cwd, which remains the base for relative paths. When omitted or empty, no additional roots are activated for the new session.

<ResponseField name=“cwd” type={AbsolutePath} required> The working directory for this session. Must be an absolute path.

<ResponseField name=“mcpServers” type={McpServer[]}> List of MCP (Model Context Protocol) servers the agent should connect to.

NewSessionResponse

Response from creating a new session.

See protocol docs: Creating a Session

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“configOptions” type={SessionConfigOption[]}> Initial session configuration options.

<ResponseField name=“sessionId” type={SessionId} required> Unique identifier for the created session.

Used in all subsequent requests for this conversation.

session/prompt

Processes a user prompt within a session.

This request accepts the prompt:

Receives user messages with optional context (files, images, etc.)
Returns once the prompt is accepted

After acceptance, the Agent reports the accepted user message, processing state, output, tool calls, and completion through session/update notifications.

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:

See protocol docs: Extensibility

<ResponseField name=“prompt” type={ContentBlock[]} required> The blocks of content that compose the user’s message.

As a baseline, the Agent MUST support ContentBlock::Text and ContentBlock::ResourceLink, while other variants are optionally enabled via PromptCapabilities.

The Client MUST adapt its interface according to PromptCapabilities.

The client MAY include referenced pieces of context as either ContentBlock::Resource or ContentBlock::ResourceLink.

When available, ContentBlock::Resource is preferred as it avoids extra round-trips and allows the message to include pieces of context from sources the agent may not have access to.

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to send this user message to

PromptResponse

Response acknowledging that a user prompt was accepted.

This response does not indicate that the agent has finished processing. Processing and completion are reported through state_update session updates.

See protocol docs: Prompt Accepted

Type: Object

Properties:

See protocol docs: Extensibility

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 conversation history before responding.

ResumeSessionRequest

Request parameters for resuming an existing session.

Resumes an existing session and optionally replays prior conversation history according to replayFrom.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“additionalDirectories” type={AbsolutePath[]}> Additional workspace roots to activate for this session. Each path must be absolute.

When omitted or empty, no additional roots are activated. When non-empty, this is the complete resulting additional-root list for the resumed session. It may differ from any previously used or reported list as long as the request cwd matches the session’s cwd.

<ResponseField name=“cwd” type={AbsolutePath} required> The working directory for this session. Must be an absolute path.

<ResponseField name=“mcpServers” type={McpServer[]}> List of MCP servers to connect to for this session.

<ResponseField name=“replayFrom” type={<>ReplayFrom | null</>}> Inclusive cursor describing where conversation replay should begin.

Optional. Omitted or null both mean the Agent should resume without replaying previous conversation history. Replay cursors are inclusive: replay includes the position identified by the cursor. Supplying \{ "type": "start" \} means the Agent should replay the whole conversation before responding.

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to resume.

ResumeSessionResponse

Response from resuming an existing session.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“configOptions” type={SessionConfigOption[]}> Initial session configuration options.

session/set_config_option

Sets the current value for a session configuration option.

SetSessionConfigOptionRequest

Request parameters for setting a session configuration option.

Type: Union

Shared properties:

See protocol docs: Extensibility

<ResponseField name=“configId” type={SessionConfigId} required> The ID of the configuration option to set.

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session to set the configuration option for.

Variants:

A `SessionConfigValueId` string value (`type: "id"`). The discriminator value. Must be `"id"`.

<ResponseField name="value" type={<a href="#sessionconfigvalueid">SessionConfigValueId</a>} required>
  The value ID.
</ResponseField>

A boolean value (`type: "boolean"`). The discriminator value. Must be `"boolean"`.

<ResponseField name="value" type={"boolean"} required>
  The boolean value.
</ResponseField>

Custom or future session configuration option value payload.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Custom or future session configuration option value type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

<ResponseField name="value" type={"object"} required>
  Raw value payload for the custom or future value type.
</ResponseField>

SetSessionConfigOptionResponse

Response to session/set_config_option method.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“configOptions” type={SessionConfigOption[]} required> The full set of configuration options and their current values.

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.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“elicitationId” type={ElicitationId} required> The ID of the elicitation that completed.

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.

Type: Union

Shared properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“message” type={“string”} required> A human-readable message describing what input is needed.

Variants:

Form-based elicitation where the client renders a form from the provided schema. The discriminator value. Must be `"form"`.

<ResponseField name="requestedSchema" type={<a href="#elicitationschema">ElicitationSchema</a>} required>
  A JSON Schema describing the form fields to present to the user.
</ResponseField>

URL-based elicitation where the client directs the user to a URL. ElicitationId} required> The unique identifier for this elicitation.

<ResponseField name="mode" type={"string"} required>
  The discriminator value. Must be `"url"`.
</ResponseField>

<ResponseField name="url" type={"string"} required>
  The URL to direct the user to.

  * Format: `uri`
</ResponseField>

Custom or future elicitation mode.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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.

Custom or future elicitation mode.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

CreateElicitationResponse

Response from the client to an elicitation request.

Type: Union

Shared properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

Variants:

The user accepted and provided content. The discriminator value. Must be `"accept"`.

<ResponseField name="content" type={"object | null"}>
  The user-provided content, if any, as an object matching the requested schema.
</ResponseField>

The user declined the elicitation. The discriminator value. Must be `"decline"`. The elicitation was cancelled. The discriminator value. Must be `"cancel"`. Custom or future elicitation action.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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.

Custom or future elicitation action.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

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.

If the client cancels active session work via session/cancel, it MUST respond to this request with RequestPermissionOutcome::Cancelled.

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:

See protocol docs: Extensibility

<ResponseField name=“description” type={“string | null”}> Optional human-readable explanation of why permission is needed.

This text is specific to the permission prompt and does not update any subject’s displayed content. Omitted or null both mean no separate permission description was provided.

<ResponseField name=“options” type={PermissionOption[]} required> Available permission options for the user to choose from. Must contain at least one option.

<ResponseField name=“sessionId” type={SessionId} required> The session ID for this request.

<ResponseField name=“subject” type={<>RequestPermissionSubject | null</>}> Optional structured context about the operation requiring permission.

Omitted or null both mean no structured subject was provided.

<ResponseField name=“title” type={“string”} required> Human-readable title for the permission prompt.

This title is specific to the permission prompt and does not update any subject’s displayed title.

RequestPermissionResponse

Response to a permission request.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“outcome” type={RequestPermissionOutcome} required> The user’s decision on the permission request.

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:

See protocol docs: Extensibility

<ResponseField name=“sessionId” type={SessionId} required> The ID of the session this update pertains to.

<ResponseField name=“update” type={SessionUpdate} required> The actual update content.

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:

MAY cancel the corresponding request activity and all nested activities
MAY send any pending notifications.
MUST send one of these responses for the original request:

Valid response with appropriate data (partial results or cancellation marker)
Error response with code -32800 (Cancelled)

See protocol docs: Cancellation

CancelRequestNotification

Notification to cancel an ongoing request.

See protocol docs: Cancellation

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“requestId” type={RequestId} required> The ID of the request to cancel.

AbsolutePath

An absolute filesystem path used by the protocol.

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:

See protocol docs: Extensibility

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:

See protocol docs: Extensibility

<ResponseField name=“auth” type={<>AgentAuthCapabilities | null</>}> Authentication-related extension capabilities supported by the agent.

Optional. Omitted or null both mean the agent does not advertise any authentication-related extensions. This field does not advertise support for auth/login or auth/logout; those methods are advertised by a non-empty authMethods list in the initialize response.

<ResponseField name=“session” type={<>SessionCapabilities | null</>}> Session capabilities supported by the agent.

Optional. Omitted or null both mean the agent does not support the session/* method surface. Supplying \{\} means the agent supports the baseline session methods: session/new, session/prompt, session/cancel, and session/update.

AgentMessage

An agent message upsert.

Only AgentMessage::message_id 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 fields use client defaults. 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:

<ResponseField name=“_meta” type={“object | null”}> 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. Omitted means no metadata update; null is an explicit clear signal.

See protocol docs: Extensibility

<ResponseField name=“content” type={<>ContentBlock[] | null</>}> Complete replacement content for this message.

<ResponseField name=“messageId” type={MessageId} required> A unique identifier for the message.

AgentThought

An agent thought or reasoning message upsert.

Only AgentThought::message_id 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 fields use client defaults. 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:

See protocol docs: Extensibility

<ResponseField name=“content” type={<>ContentBlock[] | null</>}> Complete replacement content for this thought message.

<ResponseField name=“messageId” type={MessageId} required> A unique identifier for the thought message.

Annotations

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

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“audience” type={<>Role[] | null</>}> Intended recipients for this content, such as the user or assistant.

<ResponseField name=“lastModified” type={“string | null”}> Timestamp indicating when the underlying resource was last modified.

Must be an RFC 3339 formatted string (e.g., “2025-01-12T15:00:58Z”).

Format: date-time

<ResponseField name=“priority” type={“number | null”}> Relative importance of this content when clients choose what to surface.

Constraint	Value
Minimum	`0`
Maximum	`1`

AudioContent

Audio provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“annotations” type={<>Annotations | null</>}> Optional annotations that help clients decide how to display or route this content.

<ResponseField name=“data” type={“string”} required> Base64-encoded media payload.

Content encoding: base64

<ResponseField name=“mimeType” type={MediaType} required> MIME type describing the encoded media payload.

AuthCapabilities

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:

See protocol docs: Extensibility

<ResponseField name=“terminal” type={<>TerminalAuthCapabilities | null</>}> Whether the client supports terminal authentication methods.

Optional. Omitted or null both mean the client does not advertise support. The client should supply \{\} only when it can reproduce the configured agent invocation in an interactive terminal. Supplying \{\} means the agent may include terminal entries in its authentication methods.

AuthMethod

Describes an available authentication method.

The type field acts as the discriminator in the serialized JSON form.

Type: Union

Client runs the configured agent program as a separate interactive process, without passing this method to `auth/login`. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>}>
  Additional arguments to append to the configured agent invocation for terminal auth.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Optional description providing more details about this authentication method.
</ResponseField>

<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>}>
  Additional environment variables to set on the configured agent invocation for terminal auth.
  Names MUST be unique. These values override same-named variables in the
  base launch configuration.
</ResponseField>

<ResponseField name="methodId" type={<a href="#authmethodid">AuthMethodId</a>} required>
  Unique identifier for this authentication method.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name of the authentication method.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"terminal"`.
</ResponseField>

Agent handles authentication itself through `auth/login`.

The type discriminator value is agent.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Optional description providing more details about this authentication method.
</ResponseField>

<ResponseField name="methodId" type={<a href="#authmethodid">AuthMethodId</a>} required>
  Unique identifier for this authentication method.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name of the authentication method.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"agent"`.
</ResponseField>

Custom or future authentication method.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Clients that do not understand this method type should preserve the raw payload when storing, replaying, proxying, or forwarding initialization data, and otherwise ignore the method or display it generically.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Optional description providing more details about this authentication method.
</ResponseField>

<ResponseField name="methodId" type={<a href="#authmethodid">AuthMethodId</a>} required>
  Unique identifier for this authentication method.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name of the authentication method.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  Custom or future authentication method type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

AuthMethodAgent

Agent handles authentication itself through auth/login.

The type discriminator value is agent.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“description” type={“string | null”}> Optional description providing more details about this authentication method.

<ResponseField name=“methodId” type={AuthMethodId} required> Unique identifier for this authentication method.

<ResponseField name=“name” type={“string”} required> Human-readable name of the authentication method.

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:

See protocol docs: Extensibility

<ResponseField name=“args” type={<>“string”[]</>}> Additional arguments to append to the configured agent invocation for terminal auth.

<ResponseField name=“description” type={“string | null”}> Optional description providing more details about this authentication method.

<ResponseField name=“env” type={EnvVariable[]}> Additional environment variables to set on the configured agent invocation for terminal auth. Names MUST be unique. These values override same-named variables in the base launch configuration.

<ResponseField name=“methodId” type={AuthMethodId} required> Unique identifier for this authentication method.

<ResponseField name=“name” type={“string”} required> Human-readable name of the authentication method.

AvailableCommand

Information about a command.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“description” type={“string”} required> Human-readable description of what the command does.

<ResponseField name=“input” type={<>AvailableCommandInput | null</>}> Input for the command if required

<ResponseField name=“name” type={“string”} required> Command name (e.g., create_plan, research_codebase).

AvailableCommandInput

The input specification for a command.

Type: Union

All text that was typed after the command name is provided as input. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="hint" type={"string"} required>
  A hint to display when the input hasn't been provided yet
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"text"`.
</ResponseField>

Custom or future command input specification.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Clients that do not understand this input type should preserve the raw payload when storing, replaying, proxying, or forwarding command metadata, and otherwise ignore the input specification or display the command without structured input.

Custom or future command input type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

AvailableCommandsUpdate

Available commands are ready or have changed

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“availableCommands” type={AvailableCommand[]} required> Commands the agent can execute.

BlobResourceContents

Binary resource contents.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“blob” type={“string”} required> Base64-encoded bytes for a binary resource payload.

Content encoding: base64

<ResponseField name=“mimeType” type={<>MediaType | null</>}> MIME type describing the encoded media payload.

<ResponseField name=“uri” type={“string”} required> URI associated with this resource or media payload.

Format: uri

BooleanPropertySchema

Schema for boolean properties in an elicitation form.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“default” type={“boolean | null”}> Default value.

Optional. Omitted and null are equivalent and mean no default value is provided.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“title” type={“string | null”}> Optional title for the property.

Optional. Omitted and null are equivalent and mean no title is provided.

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:

See protocol docs: Extensibility

<ResponseField name=“auth” type={<>AuthCapabilities | null</>}> Authentication capabilities supported by the client. Determines which authentication method types the agent may include in its InitializeResponse.

Optional. Omitted or null both mean the client does not advertise any authentication-method extensions.

<ResponseField name=“elicitation” type={<>ElicitationCapabilities | null</>}> Elicitation capabilities supported by the client. Determines which elicitation modes the agent may use.

Optional. Omitted or null both mean the client does not advertise elicitation support.

CommandPermissionSubject

Permission request details for a command.

Type: Object

Properties:

<ResponseField name=“_meta” type={“object | null”}> 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. Omitted and null are equivalent and mean no subject metadata was provided.

See protocol docs: Extensibility

<ResponseField name=“command” type={“string”} required> The command that would be run if permission is granted.

<ResponseField name=“cwd” type={AbsolutePath} required> The absolute working directory for the command.

<ResponseField name=“terminalId” type={<>TerminalId | null</>}> The associated terminal, when already known. Omitted and null are equivalent.

<ResponseField name=“toolCallId” type={<>ToolCallId | null</>}> The associated tool call, when known. Omitted and null are equivalent.

ConfigOptionUpdate

Session configuration options have been updated.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“configOptions” type={SessionConfigOption[]} required> The full set of configuration options and their current values.

Content

Standard content block (text, images, resources).

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“content” type={ContentBlock} required> The actual content block.

ContentBlock

Content blocks represent displayable information in the Agent Client Protocol.

They provide a structured way to handle various types of user-facing content—whether it’s text from language models, images for analysis, or embedded resources for context.

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), enabling agents to seamlessly forward content from MCP tool outputs without transformation.

See protocol docs: Content

Type: Union

Text content. May be plain text or formatted with Markdown.

All agents MUST support text content blocks in prompts. Clients SHOULD render this text as Markdown.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="annotations" type={<><span><a href="#annotations">Annotations</a></span><span> | null</span></>}>
  Optional annotations that help clients decide how to display or route this content.
</ResponseField>

<ResponseField name="text" type={"string"} required>
  Text payload carried by this content block.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"text"`.
</ResponseField>

Images for visual context or analysis.

Requires the image prompt capability when included in prompts.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="annotations" type={<><span><a href="#annotations">Annotations</a></span><span> | null</span></>}>
  Optional annotations that help clients decide how to display or route this content.
</ResponseField>

<ResponseField name="data" type={"string"} required>
  Base64-encoded media payload.

  * Content encoding: `base64`
</ResponseField>

<ResponseField name="mimeType" type={<a href="#mediatype">MediaType</a>} required>
  MIME type describing the encoded media payload.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"image"`.
</ResponseField>

<ResponseField name="uri" type={"string | null"}>
  URI associated with this resource or media payload.

  * Format: `uri`
</ResponseField>

Audio data for transcription or analysis.

Requires the audio prompt capability when included in prompts.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="annotations" type={<><span><a href="#annotations">Annotations</a></span><span> | null</span></>}>
  Optional annotations that help clients decide how to display or route this content.
</ResponseField>

<ResponseField name="data" type={"string"} required>
  Base64-encoded media payload.

  * Content encoding: `base64`
</ResponseField>

<ResponseField name="mimeType" type={<a href="#mediatype">MediaType</a>} required>
  MIME type describing the encoded media payload.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"audio"`.
</ResponseField>

References to resources that the agent can access.

All agents MUST support resource links in prompts.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="annotations" type={<><span><a href="#annotations">Annotations</a></span><span> | null</span></>}>
  Optional annotations that help clients decide how to display or route this content.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Optional human-readable details shown with this protocol object.
</ResponseField>

<ResponseField name="icons" type={<><span><a href="#icon">Icon[]</a></span><span> | null</span></>}>
  Optional set of sized icons that the client can display in a user interface.
</ResponseField>

<ResponseField name="mimeType" type={<><span><a href="#mediatype">MediaType</a></span><span> | null</span></>}>
  MIME type describing the encoded media payload.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name shown for this protocol object.
</ResponseField>

<ResponseField name="size" type={"integer | null"}>
  Optional size of the linked resource in bytes, if known.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional display title for end-user UI.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"resource_link"`.
</ResponseField>

<ResponseField name="uri" type={"string"} required>
  URI associated with this resource or media payload.

  * Format: `uri`
</ResponseField>

Complete resource contents embedded directly in the message.

Preferred for including context as it avoids extra round-trips.

Requires the embeddedContext prompt capability when included in prompts.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="annotations" type={<><span><a href="#annotations">Annotations</a></span><span> | null</span></>}>
  Optional annotations that help clients decide how to display or route this content.
</ResponseField>

<ResponseField name="resource" type={<a href="#embeddedresourceresource">EmbeddedResourceResource</a>} required>
  Embedded resource payload, either text or binary data.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"resource"`.
</ResponseField>

Custom or future content block.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this content block type should preserve the raw payload when storing, replaying, proxying, or forwarding content, and otherwise ignore it or display it generically.

Custom or future content block type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

ContentChunk

A streamed item of message content.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“content” type={ContentBlock} required> A single item of content

<ResponseField name=“messageId” type={MessageId} required> A unique identifier for the message this chunk belongs to.

All chunks belonging to the same message share the same messageId. A change in messageId indicates a new message has started.

Cost

Cost information for a session.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“amount” type={“number”} required> Total cumulative cost for session.

<ResponseField name=“currency” type={“string”} required> ISO 4217 currency code (e.g., “USD”, “EUR”).

Pattern: "^[A-Z]{3}$"

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:

See protocol docs: Extensibility

<ResponseField name=“changes” type={DiffChange[]} required> Structured file changes described by this diff.

Clients can use this field without parsing patch text to determine affected paths.

<ResponseField name=“patch” type={<>DiffPatch | null</>}> Renderable patch text for some or all of the structured changes.

Agents SHOULD provide patch text whenever feasible. Omitted or null means no renderable patch text was provided.

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:

See protocol docs: Extensibility

<ResponseField name=“fileType” type={<>DiffFileType | null</>}> File content kind.

Omitted or null means the content kind is unknown.

<ResponseField name=“mimeType” type={<>MediaType | null</>}> MIME type of the file contents.

Omitted or null means the MIME type is unknown.

Variants:

A file was added. The discriminator value. Must be `"add"`.

<ResponseField name="path" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path for the operation.
</ResponseField>

A file was deleted. The discriminator value. Must be `"delete"`.

<ResponseField name="path" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path for the operation.
</ResponseField>

A file was modified in place. The discriminator value. Must be `"modify"`.

<ResponseField name="path" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path for the operation.
</ResponseField>

A file was moved or renamed. AbsolutePath} required> Absolute path before the operation.

<ResponseField name="operation" type={"string"} required>
  The discriminator value. Must be `"move"`.
</ResponseField>

<ResponseField name="path" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path after the operation.
</ResponseField>

A file was copied. AbsolutePath} required> Absolute path before the operation.

<ResponseField name="operation" type={"string"} required>
  The discriminator value. Must be `"copy"`.
</ResponseField>

<ResponseField name="path" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path after the operation.
</ResponseField>

Custom or future file operation.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Custom or future file operation.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

DiffFileType

Kind of file content represented by a diff change.

Type: Union

Text content. Binary or otherwise non-text content. Directory entry. Symbolic link. Custom or future file type.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

DiffPatch

Renderable patch text and its format.

Type: Object

Properties:

<ResponseField name=“format” type={DiffPatchFormat} required> Patch format. The only ACP-defined value is git_patch.

<ResponseField name=“text” type={“string”} required> Patch text in the format named by format.

DiffPatchFormat

Text patch format used by DiffPatch.

Type: Union

One or more `diff --git` sections in Git's `--patch` (`-p`) text format.

Paths MUST be absolute. Surrounding commit metadata and email envelopes MUST NOT be included.

Custom or future patch format.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

DiffPathChange

Operation metadata for add, delete, and modify changes.

Type: Object

Properties:

<ResponseField name=“path” type={AbsolutePath} required> Absolute path for the operation.

DiffPathPairChange

Operation metadata for move and copy changes.

Type: Object

Properties:

<ResponseField name=“oldPath” type={AbsolutePath} required> Absolute path before the operation.

<ResponseField name=“path” type={AbsolutePath} required> Absolute path after the operation.

ElicitationAcceptAction

The user accepted the elicitation and provided content.

Type: Object

Properties:

<ResponseField name=“content” type={“object | null”}> The user-provided content, if any, as an object matching the requested schema.

ElicitationCapabilities

Elicitation capabilities supported by the client.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“form” type={<>ElicitationFormCapabilities | null</>}> Whether the client supports form-based elicitation.

Optional. Omitted and null are equivalent and mean form support is not advertised. Supplying \{\} explicitly advertises form support.

<ResponseField name=“url” type={<>ElicitationUrlCapabilities | null</>}> Whether the client supports URL-based elicitation.

Optional. Omitted or null both mean the client does not advertise support. Supplying \{\} means the client supports URL-based elicitation.

ElicitationContentValue

Allowed wire representations for ElicitationContentValue.

Type: Union

String value accepted in elicitation response content. Integer value accepted in elicitation response content. Number value accepted in elicitation response content. Boolean value accepted in elicitation response content. String array value accepted in elicitation response content.

ElicitationFormCapabilities

Form-based elicitation capabilities.

Supplying \{\} means the client supports form-based elicitation.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

ElicitationFormMode

Form-based elicitation mode where the client renders a form from the provided schema.

Type: Union

Shared properties:

<ResponseField name=“requestedSchema” type={ElicitationSchema} required> A JSON Schema describing the form fields to present to the user.

Variants:

Tied to a session, optionally to a specific tool call within that session. SessionId} required> The session this elicitation is tied to.

<ResponseField name="toolCallId" type={<><span><a href="#toolcallid">ToolCallId</a></span><span> | null</span></>}>
  Optional tool call within the session.

  Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the
  session without a specific tool call.
</ResponseField>

Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). RequestId} required> The request this elicitation is tied to.

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 the String variant with enum or oneOf set. Multi-select enums use the Array variant.

Type: Union

String property (or single-select enum when `enum`/`oneOf` is set). 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="default" type={"string | null"}>
  Default value.

  Optional. Omitted and `null` are equivalent and mean no default value is provided.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Human-readable description.

  Optional. Omitted and `null` are equivalent and mean no description is provided.
</ResponseField>

<ResponseField name="enum" type={<><span><><span>"string"</span><span>[]</span></></span><span> | null</span></>}>
  Enum values for untitled single-select enums.
  Must contain at least one value when present.
  Optional. Omitted and `null` are equivalent and mean no untitled single-select choices are
  declared by `enum`.
</ResponseField>

<ResponseField name="format" type={<><span><a href="#stringformat">StringFormat</a></span><span> | null</span></>}>
  String format.

  Optional. Omitted and `null` are equivalent and mean there is no format constraint.
</ResponseField>

<ResponseField name="maxLength" type={"integer | null"}>
  Maximum string length.

  Optional. Omitted and `null` are equivalent and mean there is no maximum length constraint.

  * Minimum: `0`
</ResponseField>

<ResponseField name="minLength" type={"integer | null"}>
  Minimum string length.

  Optional. Omitted and `null` are equivalent and mean there is no minimum length constraint.

  * Minimum: `0`
</ResponseField>

<ResponseField name="oneOf" type={<><span><a href="#enumoption">EnumOption[]</a></span><span> | null</span></>}>
  Titled enum options for titled single-select enums.
  Must contain at least one option when present.
  Optional. Omitted and `null` are equivalent and mean no titled single-select choices are
  declared by `oneOf`.
</ResponseField>

<ResponseField name="pattern" type={"string | null"}>
  Pattern the string must match.

  Optional. Omitted and `null` are equivalent and mean there is no pattern constraint.

  * Format: `regex`
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional title for the property.

  Optional. Omitted and `null` are equivalent and mean no title is provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"string"`.
</ResponseField>

Number (floating-point) property. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="default" type={"number | null"}>
  Default value.

  Optional. Omitted and `null` are equivalent and mean no default value is provided.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Human-readable description.

  Optional. Omitted and `null` are equivalent and mean no description is provided.
</ResponseField>

<ResponseField name="maximum" type={"number | null"}>
  Maximum value (inclusive).

  Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.
</ResponseField>

<ResponseField name="minimum" type={"number | null"}>
  Minimum value (inclusive).

  Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional title for the property.

  Optional. Omitted and `null` are equivalent and mean no title is provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"number"`.
</ResponseField>

Integer property. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="default" type={"integer | null"}>
  Default value.

  Optional. Omitted and `null` are equivalent and mean no default value is provided.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Human-readable description.

  Optional. Omitted and `null` are equivalent and mean no description is provided.
</ResponseField>

<ResponseField name="maximum" type={"integer | null"}>
  Maximum value (inclusive).

  Optional. Omitted and `null` are equivalent and mean there is no inclusive upper bound.
</ResponseField>

<ResponseField name="minimum" type={"integer | null"}>
  Minimum value (inclusive).

  Optional. Omitted and `null` are equivalent and mean there is no inclusive lower bound.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional title for the property.

  Optional. Omitted and `null` are equivalent and mean no title is provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"integer"`.
</ResponseField>

Boolean property. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="default" type={"boolean | null"}>
  Default value.

  Optional. Omitted and `null` are equivalent and mean no default value is provided.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Human-readable description.

  Optional. Omitted and `null` are equivalent and mean no description is provided.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional title for the property.

  Optional. Omitted and `null` are equivalent and mean no title is provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"boolean"`.
</ResponseField>

Multi-select array property. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="default" type={<><span><><span>"string"</span><span>[]</span></></span><span> | null</span></>}>
  Default selected values.

  Optional. Omitted and `null` are equivalent and mean no default selections are provided.
</ResponseField>

<ResponseField name="description" type={"string | null"}>
  Human-readable description.

  Optional. Omitted and `null` are equivalent and mean no description is provided.
</ResponseField>

<ResponseField name="items" type={<a href="#multiselectitems">MultiSelectItems</a>} required>
  The items definition describing allowed values.
</ResponseField>

<ResponseField name="maxItems" type={"integer | null"}>
  Maximum number of items to select.

  Optional. Omitted and `null` are equivalent and mean there is no maximum selection count.

  * Minimum: `0`
</ResponseField>

<ResponseField name="minItems" type={"integer | null"}>
  Minimum number of items to select.

  Optional. Omitted and `null` are equivalent and mean there is no minimum selection count.

  * Minimum: `0`
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Optional title for the property.

  Optional. Omitted and `null` are equivalent and mean no title is provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"array"`.
</ResponseField>

Custom or future elicitation property schema.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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.

Custom or future elicitation property schema type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

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:

<ResponseField name=“requestId” type={RequestId} required> The request this elicitation is tied to.

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:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“description” type={“string | null”}> Optional description of what this schema represents.

Optional. Omitted and null are equivalent and mean no schema description is provided.

<ResponseField name=“properties” type={“object”}> Property definitions (must be primitive types).

Default: {}

<ResponseField name=“required” type={<><>“string”[]</> | null</>}> List of required property names.

Optional. Omitted and null are equivalent and mean no property names are required.

<ResponseField name=“title” type={“string | null”}> Optional title for the schema.

Optional. Omitted and null are equivalent and mean no title is provided.

<ResponseField name=“type” type={ElicitationSchemaType}> Type discriminator. Always "object".

Default: "object"

ElicitationSchemaType

Type discriminator for elicitation schemas.

Type: Union

Object schema type.

ElicitationSessionScope

Session-scoped elicitation, optionally tied to a specific tool call.

When tool_call_id 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:

<ResponseField name=“sessionId” type={SessionId} required> The session this elicitation is tied to.

<ResponseField name=“toolCallId” type={<>ToolCallId | null</>}> Optional tool call within the session.

Optional. Omitted and null are equivalent and mean the elicitation is scoped to the session without a specific tool call.

ElicitationUrlCapabilities

URL-based elicitation capabilities.

Supplying \{\} means the client supports URL-based elicitation.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

ElicitationUrlMode

URL-based elicitation mode where the client directs the user to a URL.

Type: Union

Shared properties:

<ResponseField name=“elicitationId” type={ElicitationId} required> The unique identifier for this elicitation.

<ResponseField name=“url” type={“string”} required> The URL to direct the user to.

Format: uri

Variants:

Tied to a session, optionally to a specific tool call within that session. SessionId} required> The session this elicitation is tied to.

<ResponseField name="toolCallId" type={<><span><a href="#toolcallid">ToolCallId</a></span><span> | null</span></>}>
  Optional tool call within the session.

  Optional. Omitted and `null` are equivalent and mean the elicitation is scoped to the
  session without a specific tool call.
</ResponseField>

Tied to a specific JSON-RPC request outside of a session (e.g., during auth/configuration phases before any session is started). RequestId} required> The request this elicitation is tied to.

EmbeddedResource

The contents of a resource, embedded into a prompt or tool call result.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“annotations” type={<>Annotations | null</>}> Optional annotations that help clients decide how to display or route this content.

<ResponseField name=“resource” type={EmbeddedResourceResource} required> Embedded resource payload, either text or binary data.

EmbeddedResourceResource

Resource content that can be embedded in a message.

Type: Union

Text resource contents embedded directly in the message. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="mimeType" type={<><span><a href="#mediatype">MediaType</a></span><span> | null</span></>}>
  MIME type describing the encoded media payload.
</ResponseField>

<ResponseField name="text" type={"string"} required>
  Text payload carried by this content block.
</ResponseField>

<ResponseField name="uri" type={"string"} required>
  URI associated with this resource or media payload.

  * Format: `uri`
</ResponseField>

Binary resource contents embedded directly in the message. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="blob" type={"string"} required>
  Base64-encoded bytes for a binary resource payload.

  * Content encoding: `base64`
</ResponseField>

<ResponseField name="mimeType" type={<><span><a href="#mediatype">MediaType</a></span><span> | null</span></>}>
  MIME type describing the encoded media payload.
</ResponseField>

<ResponseField name="uri" type={"string"} required>
  URI associated with this resource or media payload.

  * Format: `uri`
</ResponseField>

EnumOption

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

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“const” type={“string”} required> The constant value for this option.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“title” type={“string”} required> Human-readable title for this option.

EnvVariable

An environment variable to set when launching a process.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“name” type={“string”} required> The name of the environment variable.

<ResponseField name=“value” type={“string”} required> The value to set for the environment variable.

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:

<ResponseField name=“code” type={ErrorCode} required> A number indicating the error type that occurred. This must be an integer as defined in the JSON-RPC specification.

<ResponseField name=“data” type={“object”}> Optional primitive or structured value that contains additional information about the error. This may include debugging information or context-specific details.

<ResponseField name=“message” type={“string”} required> A string providing a short description of the error. The message should be limited to a concise single sentence.

ErrorCode

Predefined error codes for common JSON-RPC and ACP-specific errors.

These codes follow the JSON-RPC 2.0 specification for standard errors and use the reserved range (-32000 to -32099) for protocol-specific errors.

Type: Union

**Parse error**: Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text. **Invalid request**: The JSON sent is not a valid Request object. **Method not found**: The method does not exist or is not available. **Invalid params**: Invalid method parameter(s). **Internal error**: Internal JSON-RPC error. Reserved for implementation-defined server errors. **Request cancelled**: Execution of the method was aborted either due to a cancellation request from the caller or because of resource constraints or shutdown. **Authentication required**: Authentication is required before this operation can be performed. **Resource not found**: A given resource, such as a file, was not found. Other undefined error code.

ExtNotification

Allows the Agent 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 ExtRequest 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:

See protocol docs: Extensibility

<ResponseField name=“name” type={“string”} required> The name of the HTTP header.

<ResponseField name=“value” type={“string”} required> The value to set for the HTTP header.

Icon

An optionally-sized icon that can be displayed in a user interface.

Type: Object

Properties:

<ResponseField name=“mimeType” type={<>MediaType | null</>}> Optional MIME type override if the source MIME type is missing or generic.

<ResponseField name=“sizes” type={<><>“string”[]</> | null</>}> Optional array of strings that specify sizes at which the icon can be used. Each string should be in WxH format (e.g., "48x48", "96x96") or "any" for scalable formats like SVG.

If not provided, the client should assume that the icon can be used at any size.

<ResponseField name=“src” type={“string”} required> A standard URI pointing to an icon resource.

Format: uri

<ResponseField name=“theme” type={<>IconTheme | null</>}> Optional theme this icon is designed for.

IconTheme

Theme an icon is designed for.

Type: Union

Icon designed for light backgrounds. Icon designed for dark backgrounds. Custom or future icon theme.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

IdleStateUpdate

The agent is ready to process a new prompt.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“stopReason” type={<>StopReason | null</>}> Indicates why foreground work stopped.

Optional. Omitted or null both mean the agent is not reporting a stop reason. Agents SHOULD include this when the idle transition ends foreground work.

ImageContent

An image provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“annotations” type={<>Annotations | null</>}> Optional annotations that help clients decide how to display or route this content.

<ResponseField name=“data” type={“string”} required> Base64-encoded media payload.

Content encoding: base64

<ResponseField name=“mimeType” type={MediaType} required> MIME type describing the encoded media payload.

<ResponseField name=“uri” type={“string | null”}> URI associated with this resource or media payload.

Format: uri

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:

See protocol docs: Extensibility

<ResponseField name=“name” type={“string”} required> Intended for programmatic or logical use, but can be used as a display name fallback if title isn’t present.

<ResponseField name=“title” type={“string | null”}> Intended for UI and end-user contexts — optimized to be human-readable and easily understood.

If not provided, the name should be used for display.

<ResponseField name=“version” type={“string”} required> Version of the implementation. Can be displayed to the user or used for debugging or metrics purposes. (e.g. “1.0.0”).

IntegerPropertySchema

Schema for integer properties in an elicitation form.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“default” type={“integer | null”}> Default value.

Optional. Omitted and null are equivalent and mean no default value is provided.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“maximum” type={“integer | null”}> Maximum value (inclusive).

Optional. Omitted and null are equivalent and mean there is no inclusive upper bound.

<ResponseField name=“minimum” type={“integer | null”}> Minimum value (inclusive).

Optional. Omitted and null are equivalent and mean there is no inclusive lower bound.

<ResponseField name=“title” type={“string | null”}> Optional title for the property.

Optional. Omitted and null are equivalent and mean no title is provided.

McpCapabilities

MCP capabilities supported by the agent for session lifecycle requests.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“http” type={<>McpHttpCapabilities | null</>}> Agent supports McpServer::Http.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports HTTP MCP server transports.

<ResponseField name=“stdio” type={<>McpStdioCapabilities | null</>}> Agent supports McpServer::Stdio.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports stdio MCP server transports.

McpHttpCapabilities

Capabilities for HTTP MCP server transports.

Supplying \{\} means the agent supports HTTP MCP server transports.

Type: Object

Properties:

See protocol docs: Extensibility

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

HTTP transport configuration

Only available when the Agent capabilities include session.mcp.http.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="headers" type={<a href="#httpheader">HttpHeader[]</a>}>
  HTTP headers to set when making requests to the MCP server.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name identifying this MCP server.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"http"`.
</ResponseField>

<ResponseField name="url" type={"string"} required>
  URL to the MCP server.

  * Format: `uri`
</ResponseField>

Stdio transport configuration

Only available when the Agent capabilities include session.mcp.stdio.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="args" type={<><span>"string"</span><span>[]</span></>}>
  Command-line arguments to pass to the MCP server.
</ResponseField>

<ResponseField name="command" type={<a href="#absolutepath">AbsolutePath</a>} required>
  Absolute path to the MCP server executable.
</ResponseField>

<ResponseField name="env" type={<a href="#envvariable">EnvVariable[]</a>}>
  Environment variables to set when launching the MCP server.
</ResponseField>

<ResponseField name="name" type={"string"} required>
  Human-readable name identifying this MCP server.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"stdio"`.
</ResponseField>

Custom or future MCP server transport configuration.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this transport should preserve the raw payload when storing, replaying, proxying, or forwarding session setup data, and otherwise ignore it or reject the server configuration.

Custom or future MCP server transport type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

McpServerHttp

HTTP transport configuration for MCP.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“headers” type={HttpHeader[]}> HTTP headers to set when making requests to the MCP server.

<ResponseField name=“name” type={“string”} required> Human-readable name identifying this MCP server.

<ResponseField name=“url” type={“string”} required> URL to the MCP server.

Format: uri

McpServerStdio

Stdio transport configuration for MCP.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“args” type={<>“string”[]</>}> Command-line arguments to pass to the MCP server.

<ResponseField name=“command” type={AbsolutePath} required> Absolute path to the MCP server executable.

<ResponseField name=“env” type={EnvVariable[]}> Environment variables to set when launching the MCP server.

<ResponseField name=“name” type={“string”} required> Human-readable name identifying this MCP server.

McpStdioCapabilities

Capabilities for stdio MCP server transports.

Supplying \{\} means the agent supports stdio MCP server transports.

Type: Object

Properties:

See protocol docs: Extensibility

MediaType

An Internet media type identifying the format of protocol content.

Type: string

MessageId

Unique identifier for a message within a session.

Type: string

MultiSelectItems

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

Type: Union

Multi-select string items with plain string values. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="enum" type={<><span>"string"</span><span>[]</span></>} required>
  Allowed enum values. Must contain at least one value.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"string"`.
</ResponseField>

Custom or future typed multi-select items. Custom or future multi-select item type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

Titled multi-select items with human-readable labels. 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.

  Optional. Omitted and `null` are equivalent and mean no metadata.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="anyOf" type={<a href="#enumoption">EnumOption[]</a>} required>
  Titled enum options. Must contain at least one option.
</ResponseField>

MultiSelectPropertySchema

Schema for multi-select (array) properties in an elicitation form.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“default” type={<><>“string”[]</> | null</>}> Default selected values.

Optional. Omitted and null are equivalent and mean no default selections are provided.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“items” type={MultiSelectItems} required> The items definition describing allowed values.

<ResponseField name=“maxItems” type={“integer | null”}> Maximum number of items to select.

Optional. Omitted and null are equivalent and mean there is no maximum selection count.

Minimum: 0

<ResponseField name=“minItems” type={“integer | null”}> Minimum number of items to select.

Optional. Omitted and null are equivalent and mean there is no minimum selection count.

Minimum: 0

<ResponseField name=“title” type={“string | null”}> Optional title for the property.

Optional. Omitted and null are equivalent and mean no title is provided.

NumberPropertySchema

Schema for number (floating-point) properties in an elicitation form.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“default” type={“number | null”}> Default value.

Optional. Omitted and null are equivalent and mean no default value is provided.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“maximum” type={“number | null”}> Maximum value (inclusive).

Optional. Omitted and null are equivalent and mean there is no inclusive upper bound.

<ResponseField name=“minimum” type={“number | null”}> Minimum value (inclusive).

Optional. Omitted and null are equivalent and mean there is no inclusive lower bound.

<ResponseField name=“title” type={“string | null”}> Optional title for the property.

Optional. Omitted and null are equivalent and mean no title is provided.

PermissionOption

An option presented to the user when requesting permission.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“kind” type={PermissionOptionKind} required> Hint about the nature of this permission option.

<ResponseField name=“name” type={“string”} required> Human-readable label to display to the user.

<ResponseField name=“optionId” type={PermissionOptionId} required> Unique identifier for this permission option.

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

Allow this operation only this time. Allow this operation and remember the choice. Reject this operation only this time. Reject this operation and remember the choice. Custom or future permission option kind.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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:

See protocol docs: Extensibility

<ResponseField name=“content” type={“string”} required> Human-readable description of what this task aims to accomplish.

<ResponseField name=“priority” type={PlanEntryPriority} required> The relative importance of this task. Used to indicate which tasks are most critical to the overall goal.

<ResponseField name=“status” type={PlanEntryStatus} required> Current execution status of this task.

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

High priority task - critical to the overall goal. Medium priority task - important but not critical. Low priority task - nice to have but not essential. Custom or future plan entry priority.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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

The task has not started yet. The task is currently being worked on. The task has been successfully completed. The task was cancelled before it completed. Custom or future plan entry status.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

PlanId

Unique identifier for a plan within a session.

Type: string

PlanItems

A plan represented as structured entries.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“entries” type={PlanEntry[]} required> The list of tasks to be accomplished.

When updating an item-based plan, the agent must send a complete list of all entries with their current status. The client replaces that plan with each update.

<ResponseField name=“planId” type={PlanId} required> The plan ID to update.

PlanUpdate

A content update for a plan identified by ID.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“plan” type={PlanUpdateContent} required> The updated plan content.

PlanUpdateContent

Updated content for a plan.

Type: Union

Structured plan entries. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="entries" type={<a href="#planentry">PlanEntry[]</a>} required>
  The list of tasks to be accomplished.

  When updating an item-based plan, the agent must send a complete list of all entries
  with their current status. The client replaces that plan with each update.
</ResponseField>

<ResponseField name="planId" type={<a href="#planid">PlanId</a>} required>
  The plan ID to update.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"items"`.
</ResponseField>

Custom or future plan update content.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding plans, and otherwise ignore it or display it generically.

PlanId} required> The plan ID to update.

<ResponseField name="type" type={"string"} required>
  Custom or future plan update content type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

PromptAudioCapabilities

Capabilities for audio content in prompt requests.

Supplying \{\} means the agent supports audio content in prompts.

Type: Object

Properties:

See protocol docs: Extensibility

PromptCapabilities

Prompt capabilities supported by the agent in session/prompt requests.

Baseline agent functionality requires support for ContentBlock::Text and ContentBlock::ResourceLink 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: Prompt Capabilities

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“audio” type={<>PromptAudioCapabilities | null</>}> Agent supports ContentBlock::Audio.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports audio content in prompts.

<ResponseField name=“embeddedContext” type={<>PromptEmbeddedContextCapabilities | null</>}> Agent supports embedded context in session/prompt requests.

When enabled, the Client is allowed to include ContentBlock::Resource in prompt requests for pieces of context that are referenced in the message.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports embedded context in prompts.

<ResponseField name=“image” type={<>PromptImageCapabilities | null</>}> Agent supports ContentBlock::Image.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports image content in prompts.

PromptEmbeddedContextCapabilities

Capabilities for embedded context in prompt requests.

Supplying \{\} means the agent supports embedded context in prompts.

Type: Object

Properties:

See protocol docs: Extensibility

PromptImageCapabilities

Capabilities for image content in prompt requests.

Supplying \{\} means the agent supports image content in prompts.

Type: Object

Properties:

See protocol docs: Extensibility

ProtocolVersion

Protocol version identifier.

This version is only bumped for breaking changes. Non-breaking changes should be introduced via capabilities.

Type: integer (uint16)

Constraint	Value
Minimum	`0`
Maximum	`65535`

ReplayFrom

Inclusive cursor describing where replayed session history should begin.

Replay includes the position identified by the cursor.

Type: Union

Replay the whole conversation from its first replayable entry. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"start"`.
</ResponseField>

Custom or future replay cursor.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this cursor should preserve the raw payload when storing, replaying, proxying, or forwarding requests, and otherwise reject the request rather than guessing where to replay from.

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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="type" type={"string"} required>
  Custom or future replay cursor type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

ReplayFromStart

Inclusive replay cursor requesting replay from the start of the conversation.

Type: Object

Properties:

See protocol docs: Extensibility

RequestId

JSON RPC Request Id

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. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]

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.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

Type: Union

The JSON-RPC `null` request id. A numeric JSON-RPC request id. A string JSON-RPC request id.

RequestPermissionOutcome

The outcome of a permission request.

Type: Union

Active session work was cancelled before the user responded.

When a client sends a session/cancel notification to cancel active session work, it MUST respond to all pending session/request_permission requests with this Cancelled outcome.

See protocol docs: Cancellation

The discriminator value. Must be `"cancelled"`. The user selected one of the provided options. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="optionId" type={<a href="#permissionoptionid">PermissionOptionId</a>} required>
  The ID of the option the user selected.
</ResponseField>

<ResponseField name="outcome" type={"string"} required>
  The discriminator value. Must be `"selected"`.
</ResponseField>

Custom or future permission outcome.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Agents that do not understand this outcome MUST NOT treat it as approval. They should preserve the raw payload when storing, replaying, proxying, or forwarding permission responses, and otherwise fail or decline the permission request according to policy.

Custom or future permission outcome.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

RequestPermissionSubject

The operation requiring permission.

Type: Union

Permission is requested before executing a tool call. ToolCallUpdate} required> Details about the tool call requiring permission.

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"tool_call"`.
</ResponseField>

Permission is requested before running a command. 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. Omitted and `null` are equivalent and mean no subject metadata was provided.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="command" type={"string"} required>
  The command that would be run if permission is granted.
</ResponseField>

<ResponseField name="cwd" type={<a href="#absolutepath">AbsolutePath</a>} required>
  The absolute working directory for the command.
</ResponseField>

<ResponseField name="terminalId" type={<><span><a href="#terminalid">TerminalId</a></span><span> | null</span></>}>
  The associated terminal, when already known. Omitted and `null` are equivalent.
</ResponseField>

<ResponseField name="toolCallId" type={<><span><a href="#toolcallid">ToolCallId</a></span><span> | null</span></>}>
  The associated tool call, when known. Omitted and `null` are equivalent.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"command"`.
</ResponseField>

Custom or future permission subject.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Clients that do not understand this subject type should preserve the raw payload when storing, replaying, proxying, or forwarding permission requests, and otherwise display a generic permission prompt or decline it according to policy.

Custom or future permission subject type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

RequiresActionStateUpdate

Foreground work is blocked on user action.

Type: Object

Properties:

See protocol docs: Extensibility

ResourceLink

A resource that the server is capable of reading, included in a prompt or tool call result.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“annotations” type={<>Annotations | null</>}> Optional annotations that help clients decide how to display or route this content.

<ResponseField name=“description” type={“string | null”}> Optional human-readable details shown with this protocol object.

<ResponseField name=“icons” type={<>Icon[] | null</>}> Optional set of sized icons that the client can display in a user interface.

<ResponseField name=“mimeType” type={<>MediaType | null</>}> MIME type describing the encoded media payload.

<ResponseField name=“name” type={“string”} required> Human-readable name shown for this protocol object.

<ResponseField name=“size” type={“integer | null”}> Optional size of the linked resource in bytes, if known.

<ResponseField name=“title” type={“string | null”}> Optional display title for end-user UI.

<ResponseField name=“uri” type={“string”} required> URI associated with this resource or media payload.

Format: uri

Role

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

Type: Union

The assistant side of a conversation. The user side of a conversation. Custom or future role.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

RunningStateUpdate

Foreground work is in progress.

Type: Object

Properties:

See protocol docs: Extensibility

SelectedPermissionOutcome

The user selected one of the provided options.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“optionId” type={PermissionOptionId} required> The ID of the option the user selected.

SessionAdditionalDirectoriesCapabilities

Capabilities for additional session directories support.

Supplying \{\} means the agent supports the additionalDirectories field on supported session lifecycle requests. Agents that also support session/list may return SessionInfo.additionalDirectories to report the complete ordered additional-root list associated with a listed session.

Type: Object

Properties:

See protocol docs: Extensibility

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:

See protocol docs: Extensibility

<ResponseField name=“additionalDirectories” type={<>SessionAdditionalDirectoriesCapabilities | null</>}> Whether the agent supports additionalDirectories on supported session lifecycle requests.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports additionalDirectories on supported session lifecycle requests.

Agents may return SessionInfo.additionalDirectories to report the complete ordered additional-root list associated with a listed session.

<ResponseField name=“delete” type={<>SessionDeleteCapabilities | null</>}> Whether the agent supports session/delete.

Optional. Omitted or null both mean the agent does not advertise support. Supplying \{\} means the agent supports deleting sessions from session/list.

<ResponseField name=“mcp” type={<>McpCapabilities | null</>}> MCP capabilities supported by the agent for session lifecycle requests.

Optional. Omitted or null both mean the agent does not advertise MCP server transport support for sessions.

<ResponseField name=“prompt” type={<>PromptCapabilities | null</>}> Prompt capabilities supported by the agent in session/prompt requests.

Optional. Omitted or null both mean the agent does not advertise any prompt extensions beyond the baseline text and resource-link content required by session/prompt.

SessionConfigBoolean

A boolean on/off toggle session configuration option payload.

Type: Object

Properties:

<ResponseField name=“currentValue” type={“boolean”} required> The current value of the boolean option.

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:

See protocol docs: Extensibility

<ResponseField name=“category” type={<>SessionConfigOptionCategory | null</>}> Optional semantic category for this option (UX only).

<ResponseField name=“configId” type={SessionConfigId} required> Unique identifier for the configuration option.

<ResponseField name=“description” type={“string | null”}> Optional description for the Client to display to the user.

<ResponseField name=“name” type={“string”} required> Human-readable label for the option.

Variants:

Single-value selector (dropdown). SessionConfigValueId} required> The currently selected value.

<ResponseField name="options" type={<a href="#sessionconfigselectoptions">SessionConfigSelectOptions</a>} required>
  The set of selectable options.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"select"`.
</ResponseField>

Boolean on/off toggle. The current value of the boolean option.

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"boolean"`.
</ResponseField>

Custom or future session configuration option payload.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Clients that do not understand this option type should preserve the raw payload when storing, replaying, proxying, or forwarding configuration data, and otherwise ignore the option or display it generically.

Custom or future session configuration option type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

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

Session mode selector. Model selector. Model-related configuration parameter. Thought/reasoning level selector. Custom or future category.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

SessionConfigSelect

A single-value selector (dropdown) session configuration option payload.

Type: Object

Properties:

<ResponseField name=“currentValue” type={SessionConfigValueId} required> The currently selected value.

<ResponseField name=“options” type={SessionConfigSelectOptions} required> The set of selectable options.

SessionConfigSelectGroup

A group of possible values for a session configuration option.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“groupId” type={SessionConfigGroupId} required> Unique identifier for this group.

<ResponseField name=“name” type={“string”} required> Human-readable label for this group.

<ResponseField name=“options” type={SessionConfigSelectOption[]} required> The set of option values in this group.

SessionConfigSelectOption

A possible value for a session configuration option.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“description” type={“string | null”}> Optional description for this option value.

<ResponseField name=“name” type={“string”} required> Human-readable label for this option value.

<ResponseField name=“value” type={SessionConfigValueId} required> Unique identifier for this option value.

SessionConfigSelectOptions

Possible values for a session configuration option.

Type: Union

A flat list of options with no grouping. A list of options grouped under headers.

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:

See protocol docs: Extensibility

SessionId

A unique identifier for a conversation session between a client and agent.

Sessions maintain their own context, conversation history, and state, allowing multiple independent interactions with the same agent.

See protocol docs: Session ID

Type: string

SessionInfo

Information about a session returned by session/list

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“additionalDirectories” type={AbsolutePath[]}> Additional workspace roots reported for this session. Each path must be absolute.

When present, this is the complete ordered additional-root list reported by the Agent. Omitted and empty values are equivalent: the response reports no additional roots.

<ResponseField name=“cwd” type={AbsolutePath} required> The working directory for this session. Must be an absolute path.

<ResponseField name=“sessionId” type={SessionId} required> Unique identifier for the session

<ResponseField name=“title” type={“string | null”}> Human-readable title for the session

<ResponseField name=“updatedAt” type={“string | null”}> RFC 3339 timestamp of last activity.

Format: date-time

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. This allows clients to display dynamic session names and track session state changes.

Omitted fields leave the existing session info unchanged. null clears the corresponding value.

Type: Object

Properties:

<ResponseField name=“_meta” type={“object | null”}> The _meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted means no metadata update; null is an explicit clear signal. Implementations MUST NOT make assumptions about values at these keys.

See protocol docs: Extensibility

<ResponseField name=“title” type={“string | null”}> Human-readable title for the session. Set to null to clear.

<ResponseField name=“updatedAt” type={“string | null”}> RFC 3339 timestamp of last activity. Set to null to clear.

Format: date-time

SessionListCursor

An opaque cursor used to paginate session/list results.

Type: string

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

A chunk of the user's message being streamed. 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. This field is chunk-scoped.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
  A single item of content
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the message this chunk belongs to.

  All chunks belonging to the same message share the same `messageId`.
  A change in `messageId` indicates a new message has started.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"user_message_chunk"`.
</ResponseField>

A user message has been created or updated.

Agents can send this when they accept or replay a user message. When a client receives another user_message update with the same messageId, fields in the new update patch the previous fields for that message.

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. Omitted means no metadata update; `null` is an explicit clear signal.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<><span><a href="#contentblock">ContentBlock[]</a></span><span> | null</span></>}>
  Complete replacement content for this message.
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the message.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"user_message"`.
</ResponseField>

A chunk of the agent's response being streamed. 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. This field is chunk-scoped.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
  A single item of content
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the message this chunk belongs to.

  All chunks belonging to the same message share the same `messageId`.
  A change in `messageId` indicates a new message has started.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"agent_message_chunk"`.
</ResponseField>

An agent message has been created or updated.

Agents can send this in addition to streamed chunks. When a client receives another agent_message update with the same messageId, fields in the new update patch the previous fields for that message.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<><span><a href="#contentblock">ContentBlock[]</a></span><span> | null</span></>}>
  Complete replacement content for this message.
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the message.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"agent_message"`.
</ResponseField>

A chunk of the agent's internal reasoning being streamed. 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. This field is chunk-scoped.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
  A single item of content
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the message this chunk belongs to.

  All chunks belonging to the same message share the same `messageId`.
  A change in `messageId` indicates a new message has started.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"agent_thought_chunk"`.
</ResponseField>

An agent thought or reasoning message has been created or updated.

Agents can send this in addition to streamed chunks. When a client receives another agent_thought update with the same messageId, fields in the new update patch the previous fields for that message.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<><span><a href="#contentblock">ContentBlock[]</a></span><span> | null</span></>}>
  Complete replacement content for this thought message.
</ResponseField>

<ResponseField name="messageId" type={<a href="#messageid">MessageId</a>} required>
  A unique identifier for the thought message.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"agent_thought"`.
</ResponseField>

The state of the agent's foreground work has changed. The discriminator value. Must be `"state_update"`. A chunk of tool-call content being streamed. 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. This field is chunk-scoped.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<a href="#toolcallcontent">ToolCallContent</a>} required>
  A single item of content produced by the tool call.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"tool_call_content_chunk"`.
</ResponseField>

<ResponseField name="toolCallId" type={<a href="#toolcallid">ToolCallId</a>} required>
  The ID of the tool call this content belongs to.
</ResponseField>

A tool call has been created or updated. The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted means no metadata update; `null` is an explicit clear signal. Implementations MUST NOT make assumptions about values at these keys.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<><span><a href="#toolcallcontent">ToolCallContent[]</a></span><span> | null</span></>}>
  Content produced by the tool call.
</ResponseField>

<ResponseField name="kind" type={<><span><a href="#toolkind">ToolKind</a></span><span> | null</span></>}>
  The category of tool being invoked.
  Helps clients choose appropriate icons and UI treatment.
</ResponseField>

<ResponseField name="locations" type={<><span><a href="#toolcalllocation">ToolCallLocation[]</a></span><span> | null</span></>}>
  File locations affected by this tool call.
  Enables "follow-along" features in clients.
</ResponseField>

<ResponseField name="rawInput" type={"object"}>
  Raw input parameters sent to the tool.
</ResponseField>

<ResponseField name="rawOutput" type={"object"}>
  Raw output returned by the tool.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"tool_call_update"`.
</ResponseField>

<ResponseField name="status" type={<><span><a href="#toolcallstatus">ToolCallStatus</a></span><span> | null</span></>}>
  Current execution status of the tool call.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Human-readable title describing what the tool is doing.
</ResponseField>

<ResponseField name="toolCallId" type={<a href="#toolcallid">ToolCallId</a>} required>
  Unique identifier for this tool call within the session.
</ResponseField>

An agent-owned terminal has been created or updated. The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted means no metadata update; `null` is an explicit clear signal. Implementations MUST NOT make assumptions about values at these keys.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="command" type={"string | null"}>
  The command being run.
</ResponseField>

<ResponseField name="cwd" type={<><span><a href="#absolutepath">AbsolutePath</a></span><span> | null</span></>}>
  The absolute working directory of the command.
</ResponseField>

<ResponseField name="exitStatus" type={<><span><a href="#terminalexitstatus">TerminalExitStatus</a></span><span> | null</span></>}>
  Exit information. A concrete object marks the terminal as exited.
</ResponseField>

<ResponseField name="output" type={<><span><a href="#terminaloutput">TerminalOutput</a></span><span> | null</span></>}>
  An authoritative replacement snapshot of terminal output bytes.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"terminal_update"`.
</ResponseField>

<ResponseField name="terminalId" type={<a href="#terminalid">TerminalId</a>} required>
  Unique identifier for this terminal within the session.
</ResponseField>

A chunk of bytes appended to an agent-owned terminal's output. 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. This field is chunk-scoped. Omitted and `null` are equivalent and mean no chunk metadata was provided.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="data" type={"string"} required>
  Independently base64-encoded terminal output bytes.

  * Content encoding: `base64`
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"terminal_output_chunk"`.
</ResponseField>

<ResponseField name="terminalId" type={<a href="#terminalid">TerminalId</a>} required>
  The terminal receiving these bytes.
</ResponseField>

A content update for a plan identified by ID. See protocol docs: [Agent Plan](https://agentclientprotocol.com/protocol/v2/agent-plan) 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="plan" type={<a href="#planupdatecontent">PlanUpdateContent</a>} required>
  The updated plan content.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"plan_update"`.
</ResponseField>

Available commands are ready or have changed 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="availableCommands" type={<a href="#availablecommand">AvailableCommand[]</a>} required>
  Commands the agent can execute.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"available_commands_update"`.
</ResponseField>

Session configuration options have been updated. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="configOptions" type={<a href="#sessionconfigoption">SessionConfigOption[]</a>} required>
  The full set of configuration options and their current values.
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"config_option_update"`.
</ResponseField>

Session metadata has been updated (title, timestamps, custom metadata) The \_meta property is reserved by ACP to allow clients and agents to attach additional metadata to their interactions. Omitted means no metadata update; `null` is an explicit clear signal. Implementations MUST NOT make assumptions about values at these keys.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"session_info_update"`.
</ResponseField>

<ResponseField name="title" type={"string | null"}>
  Human-readable title for the session. Set to null to clear.
</ResponseField>

<ResponseField name="updatedAt" type={"string | null"}>
  RFC 3339 timestamp of last activity. Set to null to clear.

  * Format: `date-time`
</ResponseField>

Context window and cost update for the session. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="cost" type={<><span><a href="#cost">Cost</a></span><span> | null</span></>}>
  Cumulative session cost (optional).
</ResponseField>

<ResponseField name="sessionUpdate" type={"string"} required>
  The discriminator value. Must be `"usage_update"`.
</ResponseField>

<ResponseField name="size" type={"uint64"} required>
  Total context window size in tokens.

  * Minimum: `0`
</ResponseField>

<ResponseField name="used" type={"uint64"} required>
  Tokens currently in context.

  * Minimum: `0`
</ResponseField>

Custom or future session update.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this update type should preserve the raw payload when storing, replaying, proxying, or forwarding session history, and otherwise ignore it or display it generically.

Custom or future session update type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

StateUpdate

The state of the agent’s foreground work has changed.

Background activity can continue and emit other session/update notifications while idle. Those notifications do not change this state.

Type: Union

Foreground work is in progress. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="state" type={"string"} required>
  The discriminator value. Must be `"running"`.
</ResponseField>

The agent is ready to process a new prompt. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="state" type={"string"} required>
  The discriminator value. Must be `"idle"`.
</ResponseField>

<ResponseField name="stopReason" type={<><span><a href="#stopreason">StopReason</a></span><span> | null</span></>}>
  Indicates why foreground work stopped.

  Optional. Omitted or `null` both mean the agent is not reporting a stop reason.
  Agents SHOULD include this when the idle transition ends foreground work.
</ResponseField>

Foreground work is blocked on user action. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="state" type={"string"} required>
  The discriminator value. Must be `"requires_action"`.
</ResponseField>

Custom or future session state.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Custom or future session state.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

StopReason

Reasons why an agent stops active session work.

See protocol docs: Stop Reasons

Type: Union

The active work ended successfully. The active work ended because the agent reached the maximum number of tokens. The active work ended because the agent reached the maximum number of allowed agent requests before returning idle. The active work ended because the agent refused to continue. The user prompt and everything that comes after it won't be included in the next prompt, so this should be reflected in the UI. Active session work was cancelled by the client via `session/cancel`.

Agents should report this stop reason on an idle state_update session update when cancellation succeeds, even if cancellation causes exceptions in underlying operations.

Custom or future stop reason.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

StringFormat

String format types for string properties in elicitation schemas.

Type: Union

Email address format. URI format. Date format (YYYY-MM-DD). Date-time format (RFC 3339). Custom or future string format.

Unknown formats are preserved. Implementations that do not understand a format should treat it as an annotation rather than rejecting the schema.

StringMultiSelectItems

String item schema for multi-select enum properties.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“enum” type={<>“string”[]</>} required> Allowed enum values. Must contain at least one value.

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:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“default” type={“string | null”}> Default value.

Optional. Omitted and null are equivalent and mean no default value is provided.

<ResponseField name=“description” type={“string | null”}> Human-readable description.

Optional. Omitted and null are equivalent and mean no description is provided.

<ResponseField name=“enum” type={<><>“string”[]</> | null</>}> Enum values for untitled single-select enums. Must contain at least one value when present. Optional. Omitted and null are equivalent and mean no untitled single-select choices are declared by enum.

<ResponseField name=“format” type={<>StringFormat | null</>}> String format.

Optional. Omitted and null are equivalent and mean there is no format constraint.

<ResponseField name=“maxLength” type={“integer | null”}> Maximum string length.

Optional. Omitted and null are equivalent and mean there is no maximum length constraint.

Minimum: 0

<ResponseField name=“minLength” type={“integer | null”}> Minimum string length.

Optional. Omitted and null are equivalent and mean there is no minimum length constraint.

Minimum: 0

<ResponseField name=“oneOf” type={<>EnumOption[] | null</>}> Titled enum options for titled single-select enums. Must contain at least one option when present. Optional. Omitted and null are equivalent and mean no titled single-select choices are declared by oneOf.

<ResponseField name=“pattern” type={“string | null”}> Pattern the string must match.

Optional. Omitted and null are equivalent and mean there is no pattern constraint.

Format: regex

<ResponseField name=“title” type={“string | null”}> Optional title for the property.

Optional. Omitted and null are equivalent and mean no title is provided.

Terminal

A display-only reference to an agent-owned terminal.

Terminal state and output are delivered separately through TerminalUpdate and TerminalOutputChunk.

Type: Object

Properties:

<ResponseField name=“_meta” type={“object | null”}> 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. This metadata is scoped to the content reference. Omitted and null are equivalent and mean no item metadata was provided.

See protocol docs: Extensibility

<ResponseField name=“terminalId” type={TerminalId} required> The ID of the terminal to display.

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:

See protocol docs: Extensibility

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:

<ResponseField name=“_meta” type={“object | null”}> 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. This metadata is scoped to the exit information. Omitted and null are equivalent and mean no exit metadata was provided.

See protocol docs: Extensibility

<ResponseField name=“exitCode” type={“integer | null”}> Process exit code, when known. Omitted and null are equivalent.

Minimum: 0

<ResponseField name=“signal” type={“string | null”}> Signal that terminated the process, when known.

Agents should use the conventional platform signal name. POSIX examples include SIGTERM, SIGKILL, and SIGINT. Other platforms may use a platform-specific name. Omitted and null are equivalent.

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:

<ResponseField name=“_meta” type={“object | null”}> 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. This metadata is scoped to the replacement snapshot. Omitted and null are equivalent and mean no snapshot metadata was provided.

See protocol docs: Extensibility

<ResponseField name=“data” type={“string”} required> Base64-encoded replacement terminal output bytes.

Content encoding: base64

TerminalOutputChunk

A chunk of bytes appended to an agent-owned terminal’s output.

Type: Object

Properties:

<ResponseField name=“_meta” type={“object | null”}> 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. This field is chunk-scoped. Omitted and null are equivalent and mean no chunk metadata was provided.

See protocol docs: Extensibility

<ResponseField name=“data” type={“string”} required> Independently base64-encoded terminal output bytes.

Content encoding: base64

<ResponseField name=“terminalId” type={TerminalId} required> The terminal receiving these bytes.

TerminalUpdate

An upsert for the stored state of an agent-owned terminal.

Only TerminalUpdate::terminal_id is required. Other fields have patch semantics: omitted fields leave the stored value unchanged, null clears it, and concrete values replace it. When the terminal ID is new, omitted fields start unknown.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“command” type={“string | null”}> The command being run.

<ResponseField name=“cwd” type={<>AbsolutePath | null</>}> The absolute working directory of the command.

<ResponseField name=“exitStatus” type={<>TerminalExitStatus | null</>}> Exit information. A concrete object marks the terminal as exited.

<ResponseField name=“output” type={<>TerminalOutput | null</>}> An authoritative replacement snapshot of terminal output bytes.

<ResponseField name=“terminalId” type={TerminalId} required> Unique identifier for this terminal within the session.

TextCommandInput

All text that was typed after the command name is provided as input.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“hint” type={“string”} required> A hint to display when the input hasn’t been provided yet

TextContent

Text provided to or from an LLM.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“annotations” type={<>Annotations | null</>}> Optional annotations that help clients decide how to display or route this content.

<ResponseField name=“text” type={“string”} required> Text payload carried by this content block.

TextResourceContents

Text-based resource contents.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“mimeType” type={<>MediaType | null</>}> MIME type describing the encoded media payload.

<ResponseField name=“text” type={“string”} required> Text payload carried by this content block.

<ResponseField name=“uri” type={“string”} required> URI associated with this resource or media payload.

Format: uri

TitledMultiSelectItems

Items definition for titled multi-select enum properties.

Type: Object

Properties:

Optional. Omitted and null are equivalent and mean no metadata.

See protocol docs: Extensibility

<ResponseField name=“anyOf” type={EnumOption[]} required> Titled enum options. Must contain at least one option.

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

Standard content block (text, images, resources). 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="content" type={<a href="#contentblock">ContentBlock</a>} required>
  The actual content block.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"content"`.
</ResponseField>

File modification shown as a diff. 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.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="changes" type={<a href="#diffchange">DiffChange[]</a>} required>
  Structured file changes described by this diff.

  Clients can use this field without parsing patch text to determine affected paths.
</ResponseField>

<ResponseField name="patch" type={<><span><a href="#diffpatch">DiffPatch</a></span><span> | null</span></>}>
  Renderable patch text for some or all of the structured changes.

  Agents SHOULD provide patch text whenever feasible. Omitted or `null`
  means no renderable patch text was provided.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"diff"`.
</ResponseField>

A display-only reference to an agent-owned terminal. 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. This metadata is scoped to the content reference. Omitted and `null` are equivalent and mean no item metadata was provided.

  See protocol docs: [Extensibility](https://agentclientprotocol.com/protocol/v2/extensibility)
</ResponseField>

<ResponseField name="terminalId" type={<a href="#terminalid">TerminalId</a>} required>
  The ID of the terminal to display.
</ResponseField>

<ResponseField name="type" type={"string"} required>
  The discriminator value. Must be `"terminal"`.
</ResponseField>

Custom or future tool call content.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

Receivers that do not understand this content type should preserve the raw payload when storing, replaying, proxying, or forwarding tool call output, and otherwise ignore it or display it generically.

Custom or future tool call content type.

  Values beginning with `_` are reserved for implementation-specific
  extensions. Unknown values that do not begin with `_` are reserved for
  future ACP variants.
</ResponseField>

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 use ToolCallUpdate::content when they need to replace the whole content collection instead.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“content” type={ToolCallContent} required> A single item of content produced by the tool call.

<ResponseField name=“toolCallId” type={ToolCallId} required> The ID of the tool call this content belongs to.

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:

See protocol docs: Extensibility

<ResponseField name=“line” type={“integer | null”}> Optional line number within the file.

Minimum: 0

<ResponseField name=“path” type={AbsolutePath} required> The absolute file path being accessed or modified.

ToolCallPermissionSubject

Permission request details for a tool call.

Type: Object

Properties:

<ResponseField name=“toolCall” type={ToolCallUpdate} required> Details about the tool call requiring permission.

ToolCallStatus

Execution status of a tool call.

Tool calls progress through different statuses during their lifecycle.

See protocol docs: Status

Type: Union

The tool call hasn't started running yet because the input is either streaming or we're awaiting approval. The tool call is currently running. The tool call completed successfully. The tool call failed with an error. The tool call was cancelled before it completed. Custom or future tool call status.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

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 ToolCallUpdate::tool_call_id 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. When a client receives a tool call ID it has not seen before, omitted fields use client defaults.

See protocol docs: Tool Calls

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“content” type={<>ToolCallContent[] | null</>}> Content produced by the tool call.

<ResponseField name=“kind” type={<>ToolKind | null</>}> The category of tool being invoked. Helps clients choose appropriate icons and UI treatment.

<ResponseField name=“locations” type={<>ToolCallLocation[] | null</>}> File locations affected by this tool call. Enables “follow-along” features in clients.

<ResponseField name=“rawInput” type={“object”}> Raw input parameters sent to the tool.

<ResponseField name=“rawOutput” type={“object”}> Raw output returned by the tool.

<ResponseField name=“status” type={<>ToolCallStatus | null</>}> Current execution status of the tool call.

<ResponseField name=“title” type={“string | null”}> Human-readable title describing what the tool is doing.

<ResponseField name=“toolCallId” type={ToolCallId} required> Unique identifier for this tool call within the session.

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: Creating

Type: Union

Reading files or data. Modifying files or content. Removing files or data. Moving or renaming files. Searching for information. Running commands or code. Internal reasoning or planning. Retrieving external data. Switching the current session mode. Other tool types (default). Custom or future tool kind.

Values beginning with _ are reserved for implementation-specific extensions. Unknown values that do not begin with _ are reserved for future ACP variants.

UsageUpdate

Context window and cost update for a session.

Type: Object

Properties:

See protocol docs: Extensibility

<ResponseField name=“cost” type={<>Cost | null</>}> Cumulative session cost (optional).

<ResponseField name=“size” type={“uint64”} required> Total context window size in tokens.

Minimum: 0

<ResponseField name=“used” type={“uint64”} required> Tokens currently in context.

Minimum: 0

UserMessage

A user message upsert.

Only UserMessage::message_id 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 fields use client defaults. 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:

See protocol docs: Extensibility

<ResponseField name=“content” type={<>ContentBlock[] | null</>}> Complete replacement content for this message.

<ResponseField name=“messageId” type={MessageId} required> A unique identifier for the message.

Last updated Oct 08, 2026