1409 parent_tool_use_id: string | null;1409 parent_tool_use_id: string | null;
1410 error?: SDKAssistantMessageError;1410 error?: SDKAssistantMessageError;
1411 aborted?: true;1411 aborted?: true;
1412 agent_id?: string;
1412 timestamp?: string;1413 timestamp?: string;
1413 context_usage?: SDKContextUsage;1414 context_usage?: SDKContextUsage;
1414 user_message_uuid?: string;1415 user_message_uuid?: string;
1428 1429
1429`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.1430`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.
1430 1431
1432`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.
1433
1434Match 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.
1435
1431Claude 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).1436Claude 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).
1432 1437
1433`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.1438`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.
1443 type: "user";1448 type: "user";
1444 uuid?: UUID;1449 uuid?: UUID;
1445 session_id?: string;1450 session_id?: string;
1451 agent_id?: string;
1446 message: MessageParam; // From Anthropic SDK1452 message: MessageParam; // From Anthropic SDK
1447 pasted_content?: MessageParam["content"][];1453 pasted_content?: MessageParam["content"][];
1448 parent_tool_use_id: string | null;1454 parent_tool_use_id: string | null;
1482};1488};
1483```1489```
1484 1490
1491A 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.
1492
1485On 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:1493On 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:
1486 1494
1487* 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.1495* 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.
1820 1828
1821### `SDKPartialAssistantMessage`1829### `SDKPartialAssistantMessage`
1822 1830
1823Streaming 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.1831Streaming partial message (only when `includePartialMessages` is true).
1832
1833The `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.
1824 1834
1825```typescript theme={null}1835```typescript theme={null}
1826type SDKPartialAssistantMessage = {1836type SDKPartialAssistantMessage = {
5263 task_type?: string;5273 task_type?: string;
5264 is_backgrounded?: boolean;5274 is_backgrounded?: boolean;
5265 spawn_depth?: number;5275 spawn_depth?: number;
5276 parent_task_id?: string;
5266 ambient?: boolean;5277 ambient?: boolean;
5267 uuid: UUID;5278 uuid: UUID;
5268 session_id: string;5279 session_id: string;
5280 5291
5281A [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`.5292A [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`.
5282 5293
5294`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:
5295
5296* The main thread launched the task
5297* Claude Code no longer tracks the parent task
5298* A [teammate](/docs/en/agent-teams) or an agent inside a workflow launched the task
5299
5300The parent can be a foreground task or one that already ended, so treat an ID you don't recognize as no parent.
5301
5283### `SDKTaskProgressMessage`5302### `SDKTaskProgressMessage`
5284 5303
5285Emitted periodically while a subagent or background task is running.5304Emitted periodically while a subagent or background task is running.
5330 5349
5331### `SDKBackgroundTasksChangedMessage`5350### `SDKBackgroundTasksChangedMessage`
5332 5351
5333Emitted 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.5352Emitted 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.
5334 5353
5335The `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.5354The `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.
5336 5355
5337Ordering relative to those per-task events is unspecified, so don't correlate the two streams.5356When a task ends, its [`task_updated`](#sdktaskupdatedmessage) and [`task_notification`](#sdktasknotificationmessage) arrive before the `background_tasks_changed` that drops it from the list. Ordering relative to the per-task events is otherwise unspecified.
5338 5357
5339Nothing 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.5358Nothing 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.
5340 5359
5351 task_type: string;5370 task_type: string;
5352 subagent_type?: string;5371 subagent_type?: string;
5353 description: string;5372 description: string;
5373 parent_task_id?: string;
5354 ambient?: boolean;5374 ambient?: boolean;
5355 }[];5375 }[];
5356 uuid: UUID;5376 uuid: UUID;
