Tool Calls

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

The tool call failed with an error

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"
  }
}

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
}

Last updated Oct 08, 2026