Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.295, published 4 hours before upstream edited the page. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Upstream edited this page at 8 Oct 2026 22:59 UTC, give or take a minute or two: the time comes from Anthropic’s own sitemap rather than from a commit. This site recorded the change at 8 Oct 2026 23:07 UTC.
Upstream edited
Recorded here
Lines+23added
Lines−3removed
From line
1,405
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits90to this page, all time
The whole hunk
from line 1405, old and new numbered
/
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 1405
14051405 parent_tool_use_id: string | null;
14061406 error?: SDKAssistantMessageError;
14071407 aborted?: true;
1408 agent_id?: string;
14081409 timestamp?: string;
14091410 context_usage?: SDKContextUsage;
14101411 user_message_uuid?: string;
from line 1425
14241425
14251426`aborted` is `true` when an interrupt or abort truncated the assistant message before the stream completed: the message has no `stop_reason` and the content may end mid-word. The field is absent on normally completed messages. It requires Agent SDK v0.3.214 or later.
14261427
1428`agent_id` identifies the subagent that produced the message and is absent on main-thread messages. The value equals the `task_id` on that subagent's [`task_started`](#sdktaskstartedmessage) and other task events, and is unchanged when the subagent is [resumed](/docs/en/agent-sdk/subagents#resume-subagents). The field requires Agent SDK v0.3.292 or later.
1429
1430Match a subagent's messages to its task events on `agent_id` rather than pairing a message's `parent_tool_use_id` with a task event's `tool_use_id`. When a tool call resumes the subagent, the task events carry that call's `tool_use_id`, while the messages keep the `parent_tool_use_id` of the tool call that first started the subagent, so the two no longer match.
1431
14271432Claude Code sets `user_message_uuid` and `user_message_uuids` on the turn's first assistant message, under the conditions in [`user_message_uuid`](#user_message_uuid). When Claude Code re-runs a turn that a restart interrupted, the re-run's assistant messages that carry those fields also carry [`resume_reason`](#resume_reason).
14281433
14291434`timestamp` is the ISO 8601 time when the message's content finished generating on the process that produced it. The value comes from that machine's clock, so use it for display only and don't order messages by it. One API turn can produce several assistant messages that share a `message.id`, each with its own `timestamp`. When the field is absent, fall back to the time you received the message.
from line 1444
14391444 type: "user";
14401445 uuid?: UUID;
14411446 session_id?: string;
1447 agent_id?: string;
14421448 message: MessageParam; // From Anthropic SDK
14431449 pasted_content?: MessageParam["content"][];
14441450 parent_tool_use_id: string | null;
from line 1484
14781484};
14791485```
14801486
1487A user message that a subagent produces, such as the `tool_result` for one of its own tool calls, carries `agent_id`. See [`SDKAssistantMessage`](#sdkassistantmessage), which defines the field and its version requirement.
1488
14811489On a message that carries a `tool_result` block, `tool_use_result` is the tool's structured output object rather than the text sent to the model. Its shape depends on the tool named by the matching `tool_use` block, so the field is typed `unknown`; the built-in shapes are listed under [Tool Output Types](#tool-output-types). These results need handling beyond their listed shape:
14821490
14831491* The `Agent` tool: `tool_use_result` is [`AgentOutput`](#agent-2). Render from it rather than parsing the `tool_result` text. A `completed` result's `content` holds the subagent's report, or, for a subagent whose report goes through a `SubagentHandback` tool call, a short note about that hand-back in place of the report. In [auto mode](/docs/en/permission-modes#eliminate-prompts-with-auto-mode) on Claude Code v2.1.271 or later, every subagent that produces a `completed` result reports that way unless it is a [fork](/docs/en/sub-agents#fork-the-current-conversation), and Claude receives the report as a separate message from the subagent.
from line 1824
18161824
18171825### `SDKPartialAssistantMessage`
18181826
1819Streaming partial message (only when `includePartialMessages` is true). The `parent_tool_use_id` field is always `null`: stream events are emitted for the main session only. For subagent attribution, use complete messages, which carry `parent_tool_use_id`, or enable [`forwardSubagentText`](#options) to receive subagent text and thinking as complete messages.
1827Streaming partial message (only when `includePartialMessages` is true).
18201828
1829The `parent_tool_use_id` field is always `null`: stream events are emitted for the main session only. For subagent attribution, use complete messages, which carry [`agent_id`](#sdkassistantmessage) and `parent_tool_use_id`, or enable [`forwardSubagentText`](#options) to receive subagent text and thinking as complete messages.
1830
18211831```typescript theme={null}
18221832type SDKPartialAssistantMessage = {
18231833 type: "stream_event";
from line 5269
52595269 task_type?: string;
52605270 is_backgrounded?: boolean;
52615271 spawn_depth?: number;
5272 parent_task_id?: string;
52625273 ambient?: boolean;
52635274 uuid: UUID;
52645275 session_id: string;
from line 5287
52765287
52775288A [resumed subagent](/docs/en/agent-sdk/subagents#resume-subagents) always reports `is_backgrounded: true`, because Claude Code runs every resumed subagent in the background. When a foreground task moves to the background later, Claude Code reports the new `is_backgrounded` value in a [`task_updated`](#sdktaskupdatedmessage) message rather than sending a second `task_started`.
52785289
5290`parent_task_id` holds the `task_id` of the subagent that launched this task. Use it to group each task under the subagent that started it. Claude Code sets it on subagent, Bash, and [Monitor](#monitor) tasks. The field requires Agent SDK v0.3.292 or later. It is absent when:
5291
5292* The main thread launched the task
5293* Claude Code no longer tracks the parent task
5294* A [teammate](/docs/en/agent-teams) or an agent inside a workflow launched the task
5295
5296The parent can be a foreground task or one that already ended, so treat an ID you don't recognize as no parent.
5297
52795298### `SDKTaskProgressMessage`
52805299
52815300Emitted periodically while a subagent or background task is running.
from line 5345
53265345
53275346### `SDKBackgroundTasksChangedMessage`
53285347
5329Emitted whenever the set of live background tasks changes: a task starts, completes, is killed, a foreground agent is backgrounded, or a task's `description` or `ambient` field changes.
5348Emitted whenever the set of live background tasks changes: a task starts, completes, or is killed; a foreground agent is backgrounded; or a task's `description`, `ambient`, or `parent_task_id` field changes. For the `parent_task_id` field on each entry, see [`SDKTaskStartedMessage`](#sdktaskstartedmessage), which defines it and its version requirement.
53305349
5331The `tasks` array is the full live set. Replace any cached set with each payload instead of pairing `task_started` and `task_notification` events, so the next membership change corrects any event you missed.
5332
5333Ordering relative to those per-task events is unspecified, so don't correlate the two streams.
5334
5335Nothing is emitted at startup. Reset to an empty set whenever the session's CLI process starts or restarts and let the next membership change repopulate it.
5336
5337When you send a repeated `initialize` control request to a running session, such as with [`reinitialize()`](#query-object) after a transport gap, Claude Code follows the response with a snapshot of the current live set, even when it is empty. A reconnecting host therefore learns what is running without waiting for the next membership change. Before Agent SDK v0.3.239, Claude Code sent no snapshot after a repeated `initialize`.
5338
5339Requires Claude Code v2.1.203 or later.
5340
5341```typescript theme={null}
5342type SDKBackgroundTasksChangedMessage = {
5343 type: "system";
5344 subtype: "background_tasks_changed";
5345 tasks: {
5346 task_id: string;
5347 task_type: string;
5348 subagent_type?: string;
5349 description: string;
5350 ambient?: boolean;
5351 }[];
5352 uuid: UUID;
5353 session_id: string;
5354};
5355```
5356
5357`subagent_type` names the subagent type on entries whose [`task_type`](#sdktaskstartedmessage) is `"local_agent"`, such as `general-purpose` or a custom subagent's name. The field requires Agent SDK v0.3.293 or later.
5358
5359### `SDKThinkingTokensMessage`
5360
5361Emitted while Claude is producing a thinking block, including a redacted one. `estimated_tokens` is a running estimate of the thinking tokens generated so far in the current block, and `estimated_tokens_delta` is the increment carried by this frame. Use these estimates for progress display.
5362
5363When the model or provider reports a breakdown, the final count for the top-level agent loop is the result message's [`usag
5350The `tasks` array is the full live set. Replace any cached set with each payload instead of pairing `task_started` and `task_n
No line in this hunk matches that.