session/update notifications, which Clients use to show progress and results to users.
Tool call updates may arrive while the Agent reports idle. They do not change the state.
Agents may ask the user for approval before running a tool call. See
Requesting Permission.
Reporting
When the language model requests a tool invocation, the Agent SHOULD report it to the Client with atool_call_update:
ToolCallId
required
A unique identifier for this tool call within the session
string
A human-readable title describing what the tool is doing. Agents SHOULD
include the title the first time they report a
toolCallId.string
The programmatic name of the invoked tool, such as
read_file. This
identifies which tool is being used. title describes this invocation for
users, while kind provides a coarse presentation category. Agents SHOULD
include the name the first time they report a toolCallId when it is
available and SHOULD NOT change it later except to correct metadata. Names
are opaque, informational metadata and do not advertise a capability or grant
authorization.ToolKind
The category of tool being invoked.Tool kinds help Clients choose appropriate icons and optimize how they display tool execution progress.Custom or future tool kinds can be used when Clients can fall back to generic tool display behavior. Custom tool kinds MUST begin with
_. Unknown non-underscore tool kinds are reserved for future ACP variants. Clients display a tool kind they don’t recognize as other.ToolCallStatus
The current execution status (defaults to
pending)ToolCallContent[]
Content produced by the tool call
ToolCallLocation[]
File locations affected by this tool call
unknown
The raw input sent to the tool. It may be any JSON value, including an object,
array, scalar, or
null.unknown
The raw output returned by the tool. It may be any JSON value, including an
object, array, scalar, or
null.tool_call_update notification is an upsert keyed by toolCallId. For
existing tool calls, fields other than _meta leave the previous value
unchanged when omitted, reset the field to its default when null, and
replace the previous value when concrete values are sent. A new toolCallId
starts with every field at its default: status is pending, kind is
other, content and locations are empty, and title, name, rawInput,
and rawOutput are unset. Clients can show a generic title when title is
unset. content and locations are
replaced as whole arrays. Send [] or null to clear them. For _meta, omit
the field to leave it unchanged or set it to null to clear it. An object
patches the stored metadata by top-level key: a key set to null is removed,
any other value replaces that key whole, and keys the object omits are
unchanged. See Metadata Patches.
Use tool_call_content_chunk when a tool produces content incrementally and the
Client should append each item instead of replacing the whole content
collection. Display-only terminal bytes use terminal_output_chunk instead.
rawInput and rawOutput follow the same patch rule, even though null is
also a valid arbitrary JSON value: omission leaves the stored value unchanged,
null clears it, and any non-null JSON value replaces it. Consequently this
patch representation cannot distinguish storing a literal JSON null from
clearing the field.
The Agent MAY also report a tool call that the model did not request, for background work that has no other tool call.
Updating
As tools execute, Agents send updates to report progress and results.toolCallId are optional in updates. Only the fields being changed need to be included.
Streaming content
As tools execute, Agents MAY stream individual content items withtool_call_content_chunk:
ToolCallId
required
The ID of the tool call this content belongs to
ToolCallContent
required
A single content item produced by the tool call
tool_call_update and tool_call_content_chunk notifications in
the order they are received for each toolCallId. A
tool_call_content_chunk appends its content item to the current tool-call
content. A later tool_call_update with content replaces all content
currently stored for that tool call, including content accumulated from earlier
chunks. Later chunks append to that replacement content. A tool_call_update
with content: [] or content: null clears the tool-call content. A
tool_call_content_chunk’s _meta, when present, is chunk-scoped. A chunk for
a toolCallId the Client hasn’t seen creates the tool call with its
defaults, then appends to its content.
An Agent can stream a tool’s text output the way it streams message text, by
sending each piece as a text content item in its own
tool_call_content_chunk. Clients can present adjacent text items as one
continuous text.
Requesting permission
Permission requests do not by themselves change the session’s foreground state. While foreground work is blocked on a permission response, the Agent SHOULD reportrequires_action. Once reported, it MUST report running when foreground progress resumes, or idle if the work ends without resuming. Requests for independent background activity may arrive while the session remains idle. See Waiting for User Action for concurrent requests and late answers.
The Agent MAY request permission from the user before proceeding with an operation, such as executing a tool call, by calling the session/request_permission method:
SessionId
required
The session ID for this request
string
required
Title shown with the permission prompt. This text is separate from any
toolCall update and does not replace the tool-call title.string
Optional explanation shown with the permission prompt. This text is separate
from any
toolCall update and does not replace tool-call content. Omitted or
null means no separate permission description was provided.RequestPermissionSubject
Optional structured context about the operation requiring permission. For tool
calls, use
type: "tool_call" with a toolCall update containing details
about the operation. Omitted or null means no structured subject was
provided. Custom or future subject types may appear. Clients that do not
understand a subject SHOULD preserve it when proxying and use the common
prompt fields or decline according to policy with the cancelled outcome.subject, by toolCallId or terminalId. The Agent MUST list that work before sending the request. session/cancel does not cover listed work, so these requests stay open. See Cancellation.
Clients apply a tool_call subject’s toolCall to their stored tool call
exactly like a tool_call_update notification, in the order it was
received relative to session/update notifications and before showing the
prompt. A first-seen toolCallId creates the tool call.
PermissionOption[]
required
Available permission options for the user to choose
from. Must contain at least one option.
type: "command", command and cwd are required, and cwd MUST be
an absolute path. toolCallId, terminalId, and _meta are optional and
nullable. Omission and null are equivalent and mean the value was not
provided. The IDs only associate the permission with displayed state and may be
unavailable before execution starts. Selecting an allow option authorizes the
Agent to execute the command. It does not ask the Client to execute anything.
The Client responds with the user’s decision:
$/cancel_request, for example after session/cancel, is answered with the "cancelled" outcome:
cancelled when the user dismisses the prompt or the Client declines it by policy, including when no reject_* option is offered. After a cancelled outcome, the Agent MUST NOT proceed with the operation.
RequestPermissionOutcome
required
The user’s decision. Known outcomes are
cancelled when the active work was
cancelled, the user dismissed the
prompt, or the Client declined it, and selected with an optionId for the
selected permission option. If optionId doesn’t match an offered option, the
Agent MUST treat the request as not approved. Custom or future outcomes
may appear. Agents that do not understand the outcome MUST NOT treat it as
approval.Permission options
Each permission option provided to the Client contains:string
required
Identifier for this option. MUST be unique within the request.
string
required
Human-readable label to display to the user
PermissionOptionKind
required
A hint to help Clients choose appropriate icons and UI treatment for each option.
allow_once- Allow this operation only this timeallow_always- Allow this operation and remember the choicereject_once- Reject this operation only this timereject_always- Reject this operation and remember the choice
_. Unknown non-underscore kinds are reserved for future ACP variants. Clients that do not understand a kind should preserve the value and use a generic permission option treatment.allow_always or
reject_always option, the Agent stores the decision, decides its scope (for
example a tool, a command, or a directory) and how long it lasts, and applies
it by not asking again. Clients SHOULD NOT infer the scope from kind. The
option name describes it.
Security
- Clients SHOULD describe the operation from
subject, presenttitleas Agent-authored text, and show commands and paths in full. - Agents SHOULD NOT give an option a
namethat contradicts itskind, and SHOULD act on a selected option according to its knownkind. - Automatic approval SHOULD NOT rely only on
title,description, or optionname. Unless the user’s policy allows all requests, it SHOULD NOT allow a request with an absent or unknown subject. - Agents SHOULD perform only the operation the approved request described, and SHOULD request again if the command or resolved target changes.
- Agents SHOULD state the scope of a remembered decision (
allow_always,reject_always) in the optionnameand SHOULD NOT apply it beyond that scope. - Agents SHOULD NOT switch to a configuration that reduces user oversight without user action.
Status
Tool calls progress through different statuses during their lifecycle:The tool call hasn’t started running yet, for example because its input is
streaming, it is awaiting approval, or it is scheduled to run later
The tool call is currently running
The tool call has started, is not running now, and will not continue until
something resumes it
The tool call completed successfully
The tool call failed with an error
The tool call was cancelled before it completed
_. Unknown non-underscore statuses are reserved for future ACP variants. Clients treat a tool call with an unrecognized status as still in progress.
Clients SHOULD show in_progress as active, pending as waiting or scheduled, and paused as paused. Statuses never go back to pending: a scheduled wakeup goes from pending to completed when it fires, and the work it triggers is new foreground work. in_progress and paused may alternate any number of times. How work is paused and resumed is up to the Agent.
completed, failed, and cancelled are final. If work goes on after its tool call is final, the Agent reports it on a new tool call. When foreground work ends, whether it finished, was cancelled, or failed, the Agent SHOULD give each of that work’s unfinished tool calls a final status. Tool calls in the session’s background list are not part of that work. If a tool call’s permission request is rejected or answered with cancelled, the Agent reports the tool call as cancelled or failed rather than leaving it pending.
Cancelling tool calls
A tool call can advertise that the Client may cancel it on its own, without cancelling the rest of the session’s work.tool_call_update carries an optional capabilities field:
capabilities is a nullable patch: omitted leaves it unchanged, null clears it, and an object replaces the whole previous value. Within it, an omitted or null cancel means unsupported, and {} advertises support. A pending or paused tool call may advertise it too, for example to delete a scheduled job. The Agent SHOULD stop advertising cancel once the tool call reaches a final status.
The Client cancels the tool call with a tool_call/cancel request:
- The Client MUST NOT send it unless the tool call currently advertises
capabilities.cancel. - The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the work has stopped. The Agent confirms that with a
tool_call_updateto a final status, normallycancelled, and may sendcompletedorfailedif the work finished first. - The Agent responds with
-32602if the tool call is unknown, already final, or not cancellable. - Cancelling a tool call does not change the foreground state by itself. This works for foreground tool calls too, so a user can stop one long-running step without cancelling the rest of the work.
Content
Tool calls can produce different types of content: Tool call contenttype values can also be custom or future variants. Implementations SHOULD preserve unknown content payloads when storing, replaying, proxying, or forwarding tool calls, and otherwise render a generic content item or ignore the item if no safe display is available.
Regular content
Standard content blocks like text, images, or resources:Display-only terminals
A terminal content item references an Agent-owned terminal by ID:terminalId is required. Optional nullable
_meta is scoped to this content item. Omission and null both mean that no
item metadata was provided. terminalId is unique within the session, remains
stable for the terminal’s lifetime, and MUST NOT be reused for a different
terminal. It is independent of toolCallId, even when an Agent uses the same
string for both. The reference and the terminal’s session updates may arrive in
either order, so Clients retain state for a first-seen terminalId.
Agents create and update stored terminal state with terminal_update:
terminal_update is an upsert keyed by required terminalId. Other fields are
patches: omission leaves the previous value unchanged, null clears it, and a
concrete value replaces it. On a first-seen ID, omitted fields start unknown or
empty.
commanddescribes the command being run. Agents SHOULD provide it on the first update when applicable.cwdis the command’s working directory and MUST be absolute when supplied.sizeis the terminal size the command runs with, in character cells, with requiredcolsandrows. It is optional. When present, Clients can render output at this size so that column layouts, progress bars, and cursor-positioned output display as the program wrote them. Without it, Clients choose a size.outputis an authoritative replacement snapshot. Its requireddatais RFC 4648 base64-encoded bytes with JSON SchemacontentEncoding: "base64". A concrete snapshot is the complete byte sequence the Agent wants the Client to retain for the terminal at that point. It replaces all previously stored bytes. Clients MUST NOT merge or splice bytes from the previous snapshot into it. Optional nullableoutput._metais scoped to that snapshot. Omission andnullboth mean no snapshot metadata was provided.- A concrete
exitStatusmarks the terminal as exited. Its optional nullableexitCodeandsignalreport known exit information. Its optional nullable_metais scoped to that exit information. For all three fields, omission andnullboth mean the value was not provided. Conventional POSIX signal names includeSIGTERM,SIGKILL, andSIGINT. Other platforms may use platform-specific names. Terminal exit and tool call status are independent. - The top-level
_metais terminal-scoped and follows the same patch semantics, except that an object patches the stored metadata by top-level key. See Metadata Patches.
"exitStatus": { "signal": "SIGTERM" }.
For live output, Agents send terminal_output_chunk:
terminalId and data are required. Each data value is an independently RFC
4648 base64-encoded byte chunk with JSON Schema contentEncoding: "base64". Clients
decode each chunk separately and append the decoded bytes in received order for
that terminalId. They MUST NOT concatenate encoded strings before
decoding. Chunk boundaries may split UTF-8 code points or terminal escape
sequences, so decoders retain parser state across chunks. Optional nullable
_meta is chunk-scoped. Omission and null both mean no chunk metadata was
provided. A chunk for a terminalId the Client hasn’t seen creates the terminal
with unknown fields and empty output, then appends to it.
Clients SHOULD ignore a chunk, or the output snapshot of a terminal_update,
whose data isn’t valid base64, keeping the bytes they already have. The other
fields of that terminal_update still apply. Agents SHOULD send all output before a
concrete exitStatus, but Clients still append output that arrives after it.
Clients MAY bound how much output they keep, for example by dropping the
oldest bytes. A later output snapshot replaces whatever they kept.
Terminal output is Agent content. Clients SHOULD render it so that it cannot write the clipboard, send input or query responses, or open links without user action, and sanitizers SHOULD keep state across chunks.
Cancelling terminals
A terminal may keep running after its tool call returns control to the model, as background work. The tool call that started it keeps referencing the terminal, so the Client can show its output in place. Terminals are display-only except for one opt-in control:terminal_update carries an optional capabilities field with the same shape and patch rules as on tool calls.
cancel once the terminal reports exitStatus. The Client stops the process with a terminal/cancel request with the sessionId and terminalId:
- The Client MUST NOT send it unless the terminal currently advertises
capabilities.cancel. - The Agent responds with an empty result once it has accepted the cancellation. The response does not mean the process has stopped. The Agent confirms that with a
terminal_updatethat setsexitStatus. - The Agent responds with
-32602if the terminal is unknown, has already exited, or is not cancellable. - Cancelling stops the process but does not release the terminal: its output remains available for display and replay. It does not change the foreground state or the status of any tool call that references the terminal.
Diffs
File modifications shown as diffs. A diff always includes structured file changes and can optionally include renderable patch text.changes is authoritative for affected absolute paths and operations. patch,
when present, provides renderable text for some or all of those changes and MUST
be consistent with changes: it describes only those paths and operations. Agents
SHOULD provide patch whenever feasible. Clients MUST handle diffs where
patch is omitted or null, and SHOULD follow changes when patch
disagrees with it.
A diff describes each file’s change from its state before the change. Each path value appears in at most one entry of changes. A move or copy’s oldPath may also appear as another entry’s path, for example a file copied and then edited, or a file moved and replaced by a new one. A move or copy that also edits the
file is a single move or copy entry, with the edits in patch.
DiffChange[]
required
Structured file changes described by this diff.
DiffPatch
Optional renderable patch text. Agents SHOULD provide this whenever
feasible. Omitted or
null means no patch text was provided.string
required
Patch format.
git_patch, the only ACP-defined value, is one or more diff --git sections in Git’s --patch (-p) text format. Unlike Git, which
writes paths relative to the repository root, every path MUST be absolute,
including in rename from, rename to, copy from, and copy to lines, and
MUST NOT have a prefix such as Git’s default a/ and b/. Otherwise paths
follow Git: /dev/null names the missing side of an added or deleted file in
the --- and +++ lines, and paths with unusual characters are quoted as Git
quotes them. Each path, once unquoted, is the same native absolute path string as the matching changes entry, for example C:\repo\src\a.rs on Windows.
Surrounding commit metadata and email envelopes MUST NOT be included.
Custom formats MUST begin with _. Clients treat a patch with a format they don’t recognize as if patch were omitted, and render from changes.Git can produce most of this. With $ROOT set to the repository root,
git diff --src-prefix="$ROOT/" --dst-prefix="$ROOT/" writes absolute
diff --git, ---, and +++ lines. Git never prefixes rename from,
rename to, copy from, or copy to paths, so those still need the
repository root prepended, with Git’s quoting applied to the full path. On Windows, Git still writes / after the root (C:\repo/src/a.rs), so Agents convert those paths to native separators before quoting.Many diff parsers strip one leading path component by default to remove Git’s
a/ and b/ prefixes. Don’t strip anything from an absolute path, which has no
such prefix. A Client can still strip a leading a/ or b/ from a relative
path to tolerate Agents that send Git’s default output, as long as changes
decides which file a patch belongs to. Take paths from changes, or from the
---, +++, rename, and copy lines, rather than by splitting the diff --git
header, which is ambiguous when paths contain spaces.string
required
Renderable patch text in the format named by
patch.format.string
required
File operation:
add, delete, modify, move, or copy. Custom
operations MUST begin with _. Clients show an operation they don’t
recognize generically, using path and oldPath when present.string
required
The absolute path after the operation. For deletes, this is the deleted path.
string
The absolute path before the operation. Required for
move and copy.string
Optional file kind after the operation (for
delete, of the deleted file):
text, binary, directory, or symlink. Custom file types MUST begin
with _, and Clients treat a file type they don’t recognize as unknown.string
Optional MIME type of the file contents after the operation (for
delete, of
the deleted file).patch when there is no useful text patch, such as a same-path binary
update or symlink target change:
changes, not from patch headers.
Following the Agent
Tool calls can report the file locations they’re working with. Clients can use this to follow along, showing which files the Agent is reading or modifying as it works.string
required
The absolute file path being accessed or modified
integer | null
Optional 1-based line number within the file, represented as an unsigned
32-bit integer.
0 is invalid. Omission and null are equivalent and mean no
specific line was provided.