Home Docs Claude Code CLI 9 Sep 2026

One change · claude-code

Agent SDK reference - TypeScript changedagent-sdk/typescript

Nearest release: v2.1.267, published under an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.

Recorded here 9 Sep 2026 19:10 UTC

Lines+23added

Lines−17removed

From line 430 where the diff opens

First seen 14 Aug 2026 this site's first read of the page

Recorded edits115to this page, all time

The whole hunk

from line 430, old and new numbered

lines

This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.

from line 430

430430| `extraArgs` | `Record<string, string \| null>` | `{}` | Additional arguments |

433| `forwardSubagentText` | `boolean` | `false` | Forward subagent text and thinking blocks as assistant and user messages with `parent_tool_use_id` set, so consumers can render a nested transcript. By default only `tool_use` and `tool_result` blocks from subagents are emitted. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared |

433| `forwardSubagentText` | `boolean` | `false` | Forward subagent text and thinking blocks as assistant and user messages with `parent_tool_use_id` set, so consumers can render a nested transcript. Without this option, Claude Code emits subagent `tool_use` and `tool_result` blocks but not text or thinking. Messages from subagents at every nesting depth are forwarded on Claude Code v2.1.219 and later; before v2.1.219, only messages from depth-1 subagents appeared |

434434| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Hook callbacks for events |

435435| `includeHookEvents` | `boolean` | `false` | Include hook lifecycle events in the message stream as [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage). Lifecycle events for `SessionStart` and `Setup` hooks are always included and don't need this option. Some hook events, such as `Notification`, `SessionEnd`, `PreCompact`, and `PostCompact`, never produce an `SDKHookStartedMessage`, even with this option. For those events, Claude Code still emits an `SDKHookProgressMessage` while a command hook that runs for more than a second produces output, and emits an `SDKHookResponseMessage` only when a hook [that runs in the background](/docs/en/hooks#run-hooks-in-the-background) finishes |

from line 1317

13171317* `api_error_status`: the HTTP status code of the API error that terminated the conversation. Absent or `null` when the turn ended without an API error.

13181318* `ttft_ms`: time to first token in milliseconds, measured when the first complete assistant message arrives. Present on the success arm only.

13191319* `ttft_stream_ms`: time in milliseconds until the first `message_start` stream event, when the response stream opens. Lower than `ttft_ms`; the gap between the two is time spent streaming the first message. Present on the success arm only.

1320* `user_message_uuid`: the `uuid` of the message you sent that started this turn. See [`user_message_uuid`](#user_message_uuid) for which results carry it.

1320* `user_message_uuid`: the `uuid` of the message you sent that this turn answered. See [`user_message_uuid`](#user_message_uuid) for which results carry it.

13211321* `user_message_uuids`: the `uuid`s of every message you sent that Claude Code answered in this turn. See [`user_message_uuids`](#user_message_uuids).

1322* `request_sent_wall_ms`: epoch milliseconds at which Claude Code dispatched the API request, for joins against server-side timestamps. Present on the success arm only, together with `user_message_uuid`, when `is_error` is false.

1322* `request_sent_wall_ms`: epoch milliseconds at which Claude Code dispatched the API request, for joins against server-side timestamps. Present only together with [`user_message_uuid`](#user_message_uuid), on a success result with `is_error` false whose turn sent an API request.

13231323* `first_content_frame_ms`: time in milliseconds until the first `content_block_start` or `content_block_delta` stream event, counting thinking blocks as content. Present on the success arm only, when `is_error` is false. Requires Agent SDK v0.3.260 or later.

13241324* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: timings for uploading the turn's first stream event. Claude Code records them only in sessions it streams to claude.ai, such as [cloud sessions](/docs/en/claude-code-on-the-web), and the results `query()` yields don't carry them. Requires Agent SDK v0.3.260 or later.

13251325* `usage`: main agent loop only. Excludes subagent and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer `modelUsage` for token/cost accounting.

from line 1355

13551355

13561356#### `user_message_uuid`

13571357

1358The `uuid` of the [`SDKUserMessage`](#sdkusermessage) that started the turn, echoed so you can match Claude Code's reply to the message you sent. Claude Code echoes it only if you set `uuid` on that message. The field is optional on `SDKUserMessage`, and a string prompt passed to `query()` carries none.

1358The `uuid` of the [`SDKUserMessage`](#sdkusermessage) the turn is answering, echoed so you can match Claude Code's reply to the message you sent. Claude Code echoes a `uuid` only if you set one on the message. The field is optional on `SDKUserMessage`, and a string prompt passed to `query()` carries none.

13591359

1360When you send several messages close together, Claude Code can merge them into one turn. The field then carries only the last message's `uuid`. To match the reply to any of the merged messages, use [`user_message_uuids`](#user_message_uuids).

1360Which of your messages a turn answers depends on how the turn started:

13611361

1362When you set `uuid`, Claude Code echoes it on three kinds of frame:

1362* **A regular message you sent**, meaning one without `isSynthetic: true`: the turn answers that message for its whole run. When you send several messages close together, Claude Code can merge them into one turn, and the field then carries only the last message's `uuid`. To match the reply to any of the merged messages, use [`user_message_uuids`](#user_message_uuids).

1363* **A message you sent with `isSynthetic: true`**: the turn answers that message at first. If Claude Code picks up a regular message of yours between tool calls, the turn answers the picked-up message from then on. Echoing a synthetic message's `uuid` requires Agent SDK v0.3.265 or later; earlier versions echo nothing on synthetic turns.

1364* **A prompt Claude Code generated itself**, such as the turn that continues interrupted work after a session restarts: the turn answers no message of yours at first and its frames carry no echo. If Claude Code picks up a regular message of yours between tool calls, the turn answers that message from then on. The pickup echo requires Agent SDK v0.3.265 or later; earlier versions echo nothing on these turns.

13631365

1364* **The result**: on the success arm with `is_error` false, together with `request_sent_wall_ms`, which requires Agent SDK v0.3.216 or later. Claude Code also echoes it on an error result that answers a message you sent, which requires Agent SDK v0.3.246 or later.

1365* **The turn's first reply**: the first [assistant message](#sdkassistantmessage), or with `includePartialMessages` the first [stream event](#sdkpartialassistantmessage) whose `event.type` isn't `ping`, so you can bind the reply before the result arrives. When a turn streams nothing, Claude Code sets it on the first assistant message instead. One reply frame per turn carries it. Requires Agent SDK v0.3.246 or later.

1366Claude Code echoes the answered message's `uuid` on three kinds of frame:

1367

1368* **The result**: every result of a turn that answered a message you sent. Every such result carries it on Agent SDK v0.3.265 or later. Before v0.3.265, the success result of a turn that a regular message started lacked it when the turn sent no API request or ended with a deferred tool call. Before v0.3.246, error results lacked it too, and before v0.3.216 every result did.

1369* **The turn's first reply**: the first [assistant message](#sdkassistantmessage), or with `includePartialMessages` the first [stream event](#sdkpartialassistantmessage) whose `event.type` isn't `ping`, so you can bind the reply before the result arrives. When a turn streams nothing, Claude Code sets it on the first assistant message instead. The first-reply echo requires Agent SDK v0.3.246 or later. When the message the turn is answering changes mid-turn, the first reply after the change carries the field too, on Agent SDK v0.3.265 or later; earlier versions set it on one reply frame per turn.

13661370* **Every [`thinking_tokens`](#sdkthinkingtokensmessage) frame of the turn**: so you can attribute thinking progress to the message you sent without waiting for the turn's first reply. Requires Agent SDK v0.3.260 or later.

13671371

13681372Claude Code omits the field in these cases:

13691373

1370* Later assistant messages and stream events of the same turn

1374* Reply frames other than those first replies

13711375* Subagent frames

1372* Synthetic turns, such as scheduled ones

1376* Turns that answer no message with a `uuid`: the turn answered a message you sent without one, or Claude Code started the turn itself and picked up no regular message that has one

13731377* Results that answer no message you sent, such as the zeroed result after a crashed worker process

13741378

13751379#### `user_message_uuids`

from line 1380

13761380

13771381The `uuid`s of every message you sent that Claude Code answered in this turn. When you send several messages close together, Claude Code can merge them into one turn, and `user_message_uuid` then names only the last of them. To match the reply to any of the merged messages, look for that message's `uuid` anywhere in this list. Requires Agent SDK v0.3.259 or later.

13781382

1379Claude Code sets the list together with `user_message_uuid` on the turn's first reply and on the result. For the full set of frames that carry `user_message_uuid`, and the version each requires, see [`user_message_uuid`](#user_message_uuid). The list always contains `user_message_uuid` and holds at most 64 entries. A message you send while the turn is running that Claude Code picks up between tool calls appears only in the result's list.

1383Claude Code sets the list together with `user_message_uuid` on each reply frame that carries that field and on the result. For the full set of frames that carry `user_message_uuid`, and the version each requires, see [`user_message_uuid`](#user_message_uuid). The list always contains `user_message_uuid` and holds at most 64 entries.

13801384

1385When Claude Code picks up a regular message you sent while a turn was running, it adds that message's `uuid` to the result's list.

1386

13811387When a first reply or result carries `user_message_uuid` without the list, it came from an earlier Claude Code version, so fall back to the single field.

13821388

13831389#### `queued_turn_count`

from line 1454

14481454 uuid: UUID;

14491455 session_id: string;

14501456 ttft_ms?: number; // Time to first token in ms, present only on message_start events

1451 user_message_uuid?: string; // Present on at most one stream event per turn

1457 user_message_uuid?: string;

14521458 user_message_uuids?: string[];

14531459};

14541460```

14551461

1456Claude Code sets `user_message_uuid` and `user_message_uuids` on one stream event per turn, under the conditions in [`user_message_uuid`](#user_message_uuid).

1462Claude Code sets `user_message_uuid` and `user_message_uuids` on the turn's first non-ping stream event, and again when the message the turn is answering changes, under the conditions in [`user_message_uuid`](#user_message_uuid).

14571463

14581464### `SDKCompactBoundaryMessage`

14591465

from line 2561

25552561};

25562562```

25572563

2558Executes Bash commands with optional timeout and background execution. The working directory persists between commands; shell state such as exported environment variables doesn't.

2564Executes Bash commands with optional timeout and background execution. The working directory persists between commands, including commands run in later turns of a multi-turn session; shell state such as exported environment variables doesn't. For the limits on which directory changes carry over, see [What persists between commands](/docs/en/tools-reference#what-persists-between-commands).

25592565

25602566### Monitor

25612567

from line 3462

34563462 totalLines: number;

34573463 /** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). */

34583464 truncatedByTokenCap?: boolean;

3459 };

3460 }

3461 | {

3462 type: "image";

3463 file: {

3464 base64: string;

3465 type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";

3466 originalSize: number;

3467 dimensions?: {

3468 originalWidth?: number;

3469 originalHeight?: number;

3470 displayWidth?: number;

3471 displayHeight?: number;

3472 };

3473 };

3474 }

3475 | {

3476 type: "notebook";

3477 file: {

3478 filePath: string;

3479 cells: unknown[];

3480 };

3481 }

3482 | {

3483 type: "pdf";

3484 file: {

3485 filePath: string;

3486 base64: string;

3487 originalSize: number;

3488 };

3489 }

3490 | {

3491 type: "parts";

3492 file: {

3493 filePath: string;

3494 originalSize: number;

3495 count: number;

3496 outputDir: string;

3497 };

3498 /** Document page number of the first extracted page; labels the page images in the tool_result content. */

3499 firstPage?: number;

3500 /** In-process only: the page-image bytes are delivered as image blocks in the tool_result content and aren't retained on the emitted tool_use_result, so this key is absent there. */

3501 pages?: {

3502 base64: string;

3503 mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";

3504 error?: string;

3505 }[];

3506 }

3507 | {

3508 type: "file_unchanged";

3509 file: {

3510 filePath: string;

3511 };

3512 /** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result. */

3513 source?: "seeded";

3514 };

3515```

3516

3517Returns file contents in a format appropriate to the file type. Discriminated on the `type` field.

3518

3519### Write

3520

3521**Tool name:** `Write`

3522

3523```typescript theme={null}

3524type FileWriteOutput =

3465

This page’s history 115 edits

23 Oct 2026 +2 −0
21 Oct 2026 +152 −152
21 Oct 2026 +21 −0
21 Oct 2026 +2 −0
20 Oct 2026 +27 −2
20 Oct 2026 +70 −72

The page’s own history →

Where it came from

The captureclaude-code
Upstream pagecode.claude.com

Around it

Every changethe ledger
That day9 Sep 2026