Tool Calls

Tool calls represent actions that language models request Agents to perform during a session. When an LLM determines it needs to interact with external systems—like reading files, running code, or fetching data—it generates tool calls that the Agent executes on its behalf. Agents report tool calls through session/update notifications, allowing Clients to display real-time progress and results to users. Tool call updates may arrive while the Agent reports idle. They do not change the state. While Agents handle the actual execution, they may use Client-mediated interactions like permission requests to provide a richer, more integrated experience.

Reporting

When the language model requests a tool invocation, the Agent SHOULD report it to the Client with a tool_call_update:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "title": "Reading configuration file",
      "name": "read_file",
      "kind": "read",
      "status": "pending"
    }
  }
}

toolCallId

ToolCallId

required

A unique identifier for this tool call within the session

title

string

A human-readable title describing what the tool is doing. Agents SHOULD include the title the first time they report a toolCallId.

name

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.

kind

ToolKind

The category of tool being invoked.

Show kinds

read - Reading files or data - edit - Modifying files or content - delete - Removing files or data - move - Moving or renaming files - search - Searching for information - execute - Running commands or code - think - Internal reasoning or planning - fetch - Retrieving external data
other - Other tool types (default)

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.

status

ToolCallStatus

The current execution status (defaults to pending)

content

ToolCallContent[]

Content produced by the tool call

locations

ToolCallLocation[]

File locations affected by this tool call

rawInput

object

The raw input parameters sent to the tool

rawOutput

object

The raw output returned by the tool

The 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, explicitly clear or unset the value when null, and replace the previous value when concrete values are sent. For a new toolCallId, omitted fields use Client defaults. 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. 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.

Updating

As tools execute, Agents send updates to report progress and results.

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_update",
      "toolCallId": "call_001",
      "status": "in_progress",
      "content": [
        {
          "type": "content",
          "content": {
            "type": "text",
            "text": "Found 3 configuration files..."
          }
        }
      ]
    }
  }
}

All fields except 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 with tool_call_content_chunk:

{
  "jsonrpc": "2.0",
  "method": "session/update",
  "params": {
    "sessionId": "sess_abc123def456",
    "update": {
      "sessionUpdate": "tool_call_content_chunk",
      "toolCallId": "call_001",
      "content": {
        "type": "content",
        "content": {
          "type": "text",
          "text": "Found 3 configuration files..."
        }
      }
    }
  }
}

toolCallId

ToolCallId

required

The ID of the tool call this content belongs to

content

ToolCallContent

required

A single content item produced by the tool call

Clients apply 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.

Requesting Permission

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:

{
  "jsonrpc": "2.0",
  "id": 5,
  "method": "session/request_permission",
  "params": {
    "sessionId": "sess_abc123def456",
    "title": "Approve file edit?",
    "description": "Allow the agent to edit src/main.rs?",
    "subject": {
      "type": "tool_call",
      "toolCall": {
        "toolCallId": "call_001"
      }
    },
    "options": [
      {
        "optionId": "allow-once",
        "name": "Allow once",
        "kind": "allow_once"
      },
      {
        "optionId": "reject-once",
        "name": "Reject",
        "kind": "reject_once"
      }
    ]
  }
}

sessionId

SessionId

required

The session ID for this request

title

string

required

Title shown with the permission prompt. This text is separate from any toolCall update and does not replace the tool-call title.

description

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.

subject

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.

options

PermissionOption[]

required

Available permission options for the user to choose from

For a proposed command, the subject can describe the command directly:

{
  "title": "Run the test suite?",
  "subject": {
    "type": "command",
    "command": "cargo test",
    "cwd": "/home/user/project",
    "toolCallId": "call_001",
    "terminalId": "term_001"
  },
  "options": [
    {
      "optionId": "allow-once",
      "name": "Allow once",
      "kind": "allow_once"
    }
  ]
}

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

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "selected",
      "optionId": "allow-once"
    }
  }
}

Clients MAY automatically allow or reject permission requests according to the user settings. If the current active work gets cancelled, the Client MUST respond with the "cancelled" outcome:

{
  "jsonrpc": "2.0",
  "id": 5,
  "result": {
    "outcome": {
      "outcome": "cancelled"
    }
  }
}

outcome

RequestPermissionOutcome

required

The user’s decision. Known outcomes are cancelled when the active work was cancelled, and selected with an optionId for the selected permission option. 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:

optionId

string

required

Unique identifier for this option

name

string

required

Human-readable label to display to the user

kind

PermissionOptionKind

required

A hint to help Clients choose appropriate icons and UI treatment for each option.

allow_once - Allow this operation only this time
allow_always - Allow this operation and remember the choice
reject_once - Reject this operation only this time
reject_always - Reject this operation and remember the choice

Custom or future permission option kinds can be used as UI hints. Custom kinds MUST begin with _. 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.

Status

Tool calls progress through different statuses during their lifecycle:

pending

The tool call hasn’t started running yet because the input is either streaming or awaiting approval

in_progress

The tool call is currently running

completed

The tool call completed successfully

failed

The tool call failed with an error

cancelled

The tool call was cancelled before it completed

Custom or future status values can be used when Clients can display a generic progress state. Custom status values MUST begin with _; unknown non-underscore statuses are reserved for future ACP variants.

Content

Tool calls can produce different types of content: Tool call content type 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:

{
  "type": "content",
  "content": {
    "type": "text",
    "text": "Analysis complete. Found 3 issues."
  }
}

Display-only Terminals

A terminal content item references an Agent-owned terminal by ID:

{
  "type": "terminal",
  "terminalId": "term_001"
}

The item is only a display anchor. 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:

{
  "sessionUpdate": "terminal_update",
  "terminalId": "term_001",
  "command": "cargo test",
  "cwd": "/home/user/project",
  "output": {
    "data": "cnVubmluZyB0ZXN0cw0K"
  },
  "exitStatus": {
    "exitCode": 0,
    "signal": null
  }
}

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.

command describes the command being run. Agents SHOULD provide it on the first update when applicable.
cwd is the command’s working directory and MUST be absolute when supplied.
output is an authoritative replacement snapshot. Its required data is RFC 4648 base64-encoded bytes with JSON Schema contentEncoding: "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 nullable output._meta is scoped to that snapshot; omission and null both mean no snapshot metadata was provided.
A concrete exitStatus marks the terminal as exited. Its optional nullable exitCode and signal report known exit information. Its optional nullable _meta is scoped to that exit information. For all three fields, omission and null both mean the value was not provided. Conventional POSIX signal names include SIGTERM, SIGKILL, and SIGINT; other platforms may use platform-specific names. Terminal exit and tool call status are independent.
The top-level _meta is terminal-scoped and follows the same patch semantics.

For example, a process terminated by a POSIX termination signal can report "exitStatus": { "signal": "SIGTERM" }. For live output, Agents send terminal_output_chunk:

{
  "sessionUpdate": "terminal_output_chunk",
  "terminalId": "term_001",
  "data": "cGFzc2VkDQo="
}

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.

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. Agents SHOULD provide patch whenever feasible. Clients MUST handle diffs where patch is omitted or null.

{
  "type": "diff",
  "changes": [
    {
      "operation": "modify",
      "path": "/home/user/project/src/config.json",
      "fileType": "text",
      "mimeType": "application/json"
    }
  ],
  "patch": {
    "format": "git_patch",
    "text": "diff --git /home/user/project/src/config.json /home/user/project/src/config.json\n--- /home/user/project/src/config.json\n+++ /home/user/project/src/config.json\n@@ -1,3 +1,3 @@\n {\n-  \"debug\": false\n+  \"debug\": true\n }\n"
  }
}

changes

DiffChange[]

required

Structured file changes described by this diff.

patch

DiffPatch

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

patch.format

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. Paths MUST be absolute. Surrounding commit metadata and email envelopes MUST NOT be included.

patch.text

string

required

Renderable patch text in the format named by patch.format.

changes[].operation

string

required

File operation: add, delete, modify, move, or copy.

changes[].path

string

required

The absolute path after the operation. For deletes, this is the deleted path.

changes[].oldPath

string

The absolute path before the operation. Required for move and copy.

changes[].fileType

string

Optional file kind: text, binary, directory, or symlink.

changes[].mimeType

string

Optional MIME type for the file contents.

Omit patch when there is no useful text patch, such as a same-path binary update or symlink target change:

{
  "type": "diff",
  "changes": [
    {
      "operation": "modify",
      "path": "/home/user/project/assets/logo.png",
      "fileType": "binary",
      "mimeType": "image/png"
    }
  ]
}

Following the Agent

Tool calls can report file locations they’re working with, enabling Clients to implement “follow-along” features that track which files the Agent is accessing or modifying in real-time.

{
  "path": "/home/user/project/src/main.py",
  "line": 42
}

path

string

required

The absolute file path being accessed or modified

line

number

Optional line number within the file

Get Started

Protocol

Libraries

Reporting

Updating

Streaming Content

Requesting Permission

Permission Options

Status

Content

Regular Content

Display-only Terminals

Diffs

Following the Agent

​Reporting

​Updating

​Streaming Content

​Requesting Permission

​Permission Options

​Status

​Content

​Regular Content

​Display-only Terminals

​Diffs

​Following the Agent

Reporting

Updating

Streaming Content

Requesting Permission

Permission Options

Status

Content

Regular Content

Display-only Terminals

Diffs

Following the Agent