Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.296, 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 9 Oct 2026 21:25 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 9 Oct 2026 21:37 UTC.
Upstream edited
Recorded here
Lines+83added
Lines−0removed
From line
1,410
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits93to this page, all time
### `SDKUsageReport`
The whole hunk
from line 1410, 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 1410
14101410 agent_id?: string;
14111411 timestamp?: string;
14121412 context_usage?: SDKContextUsage;
1413 usage_report?: SDKUsageReport;
14131414 user_message_uuid?: string;
14141415 user_message_uuids?: string[];
14151416 resume_reason?: string;
from line 1438
14371438
14381439`context_usage` is a structured copy of the `/context` report, typed as [`SDKContextUsage`](#sdkcontextusage), and requires Agent SDK v0.3.232 or later. When you send `/context` as a prompt, Claude Code delivers the report as an assistant message whose `message.content` holds the markdown table, and attaches `context_usage` to that same message. Claude Code doesn't set the field on any other assistant message, and earlier versions deliver the `/context` table without it, so read the breakdown from the field when it's present and fall back to the markdown text when it isn't.
14391440
1441`usage_report` is a structured copy of the `/usage` report, typed as [`SDKUsageReport`](#sdkusagereport), and requires Agent SDK v0.3.273 or later. When you send `/usage` as a prompt, Claude Code delivers the report as an assistant message whose `message.content` holds the text. It attaches `usage_report` to that same message only when the session meets all of these conditions:
1442
1443* The session authenticates with a claude.ai credential
1444* The credential shows a known plan type or carries the `user:profile` scope
1445* The account isn't on usage-based billing
1446
1447A `claude setup-token` token passed as `CLAUDE_CODE_OAUTH_TOKEN` doesn't qualify by default, because it carries only the `user:inference` scope. Other sessions, such as API-key sessions, deliver the text without the field, and so do earlier versions. Read the report from the field when it's present and fall back to the text when it isn't.
1448
14401449### `SDKUserMessage`
14411450
14421451User input message.
from line 2058
20492058* `buffer`: the compaction reserve
20502059* `deferred`: tool schemas Claude Code holds out of the window and excludes from the usage calculation, listed for awareness
20512060
2061### `SDKUsageReport`
2062
2063Structured form of the `/usage` report, carried as `usage_report` on the [`SDKAssistantMessage`](#sdkassistantmessage) that delivers a `/usage` result. Agent SDK v0.3.273 and later export the type. The type is experimental: its shape may change.
2064
2065```typescript theme={null}
2066type SDKUsageReport = {
2067 session: {
2068 total_cost_usd: number;
2069 total_api_duration_ms: number;
2070 total_duration_ms: number;
2071 total_lines_added: number;
2072 total_lines_removed: number;
2073 model_usage: { [modelName: string]: ModelUsage };
2074 };
2075 rate_limits: {
2076 limits:
2077 | {
2078 kind: string;
2079 group: string;
2080 percent: number;
2081 resets_at: string | null;
2082 scope?: {
2083 model?: { display_name: string } | null;
2084 surface?: { display_name: string } | null;
2085 } | null;
2086 severity: string;
2087 is_active: boolean;
2088 }[]
2089 | null;
2090 extra_usage?: {
2091 is_enabled: boolean;
2092 monthly_limit: number | null;
2093 used_credits: number | null;
2094 utilization: number | null;
2095 currency?: string | null;
2096 } | null;
2097 } | null;
2098};
2099```
2100
2101The top-level fields are `session` and `rate_limits`:
2102
2103* `session`: Claude Code's running cost and usage totals, read from the same ledger as `total_cost_usd` and `modelUsage` on [`SDKResultMessage`](#sdkresultmessage). Each `model_usage` entry is a [`ModelUsage`](#modelusage).
2104* `rate_limits`: the plan's usage rows in `limits` and usage-credits spend in `extra_usage`. It is `null` when Claude Code couldn't get the plan's usage, for example when the session's OAuth token lacks the `user:profile` scope.
2105
2106Claude Code computes `session.total_cost_usd` locally from token counts, so it is an estimate and not what your plan bills. The usage-credits spend the server reports is the separate `extra_usage` block. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for the accuracy caveats.
2107
2108`limits` holds the server's usage rows as the server sent them: which meters apply, their scope, labels, severity, and order are the server's, so render the rows verbatim.
2109
2110* An empty array means the server reported no meters.
2111* `null` means Claude Code has no rows to report.
2112
2113Each row of `limits` describes one usage meter:
2114
2115| Field | Type | Description |
2116| - | - | - |
2117| `kind` | `string` | The server's meter kind, such as `session`, `weekly_all`, or `weekly_scoped`. Classify a row on this, never on a label |
2118| `group` | `string` | The server's row group, such as `session` or `weekly`. Rows render grouped under it, in the server's order |
2119| `percent` | `number` | Share of the window used, 0-100 |
2120| `resets_at` | `string \| null` | ISO 8601 timestamp when the window resets |
2121| `scope` | `object \| null` | Optional. What a scoped row is for, a model or a surface, with the server's display label |
2122| `severity` | `string` | The server's reading of the row for a meter's color, such as `normal`, `warning`, or `critical` |
2123| `is_active` | `boolean` | `true` on the row the server picks for a single-value indicator to show |
2124
2125Before Agent SDK v0.3.277, the type declared `severity` and `is_active` as optional and nullable, and a row could arrive without them.
2126
2127`extra_usage` is the [usage credits](https://support.claude.com/en/articles/12429409-extra-usage-for-paid-claude-plans) spend and cap for the billing period as the server reports them, present when the plan has usage credits. Amounts are in minor units of `currency`, cents for USD.
2128
2129* `monthly_limit` is `null` when this account has no spending cap of its own. On Team and Enterprise plans, don't render `null` as unlimited.
2130* `is_enabled` is `false` while usage credits can't pay for requests.
2131
20522132### `SDKMessageOrigin`
20532133
20542134Provenance of a user-role message. This appears as `origin` on [`SDKUserMessage`](#sdkusermessage) and is forwarded onto the corresponding [`SDKResultMessage`](#sdkresultmessage) so you can tell what triggered a given turn.
from line 5196
51165196 task_id: string;
51175197 tool_use_id?: string;
51185198 status: "completed" | "failed" | "stopped";
5199 reason?: "worker_restart";
51195200 output_file: string;
51205201 summary: string;
51215202 ambient?: boolean;
from line 5211
51305211};
51315212```
51325213
5214`reason` is set when a task ends for a cause other than its own completion, failure, or stop, and requires Agent SDK v0.3.273 or later. Claude Code sets it only in sessions that connect through claude.ai: cloud sessions, including those on self-hosted runners, and Remote Control sessions. A local `query()` call never sets it. Its one value, `worker_restart`, means the Claude Code process that was running the task restarted. The notification carries status `"stopped"`, so treat the task as neither completed nor failed.
5215
51335216When Claude Code [moves a long MCP tool call to the background](/docs/en/mcp#automatic-backgrounding-of-long-tool-calls), the `tool_result` block for that call holds only a placeholder and the call's real result arrives in this notification. Match the notification to the call with `tool_use_id`. On a `completed` notification, `resource_links` lists the files the tool returned by reference as [`SDKMcpResourceLink`](#sdkmcpresourcelink) entries, with the same 50-link and 64 KiB limits as [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omits `resource_links` when the result had no links and on notifications for tasks that aren't MCP tool calls. `resource_links` requires Agent SDK v0.3.257 or later.
51345217
51355218Claude Code prepends a notice to every task notification it sends to the model, except deliveries stamped with the [`scheduled-trigger` subkind](#task-notification-subkinds), which carry an assigned-task framing instead. The notice states that no human input has occurred, so the model doesn't treat the notification as a user instruction or approval.
from line 5325
52425325To render a retry indicator from `subagent_retry`:
52435326
52445327* Track the indicator by `parent_tool_use_id`, which is unique per subagent. `tool_use_id` is shared by parallel subagents from one assistant turn, so tracking by it would let one subagent's update clear another's indicator.
5245* Clear the indicator when a later `tool_progress` for the same `parent_tool_use_id` arrives with neither `subagent_retry` nor `heartbeat: true`, or when the tool's result message arrives. Frames with `heartbeat: true` report liveness only, so keep the indicator when one arrives. `attempt` can exceed `max_retries` under persistent retry, so don't derive clearing from the counters.
5246* Treat `error_category` as a token for choosing your own message text, not as display text. The values are `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error`, and `unknown`. Handle a value you don't recognize the way you handle `unknown`, because later releases can add values.
5247
5248### `SDKAuthStatusMessage`
5249
5250Emitted during authentication flows.
5251
5252```typescript theme={null}
5253type SDKAuthStatusMessage = {
5254 type: "auth_status";
5255 isAuthenticating: boolean;
5256 output: string[];
5257 error?: string;
5258 uuid: UUID;
5259 session_id: string;
5260};
5261```
5262
5263### `SDKTaskStartedMessage`
5264
5265Emitted when a task begins. The `task_type` field is `"local_bash"` for Bash commands and [Monitor](#monitor) watches, `"local_agent"` for subagents, or `"remote_agent"`.
5266
5267```typescript theme={null}
5268type SDKTaskStartedMessage = {
5269 type: "system";
5270 subtype: "task_started";
5271 task_id: string;
5272 tool_use_id?: string;
5273 description: string;
5274 task_type?: string;
5275 is_backgrounded?: boolean;
5276 spawn_depth?: number;
5277 parent_task_id?: string;
5278 ambient?: boolean;
5279 uuid: UUID;
5280 session_id: string;
5281};
5282```
5283
5284`ambient` is `true` for tasks that aren't part of the session's work, such as tasks Claude Code runs for its own operation. Live-update watchers are also ambient, including watchers the user asked for. Exclude ambient tasks from activity indicators. The field requires Agent SDK v0.3.247 or later.
5285
5286`ambient` also appears on [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) and on [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage) entries.
5287
5288`is_backgrounded` and `spawn_depth` describe how Claude Code started the task. Both fields require Agent SDK v0.3.238 or later.
5289
5290* `is_backgrounded`: Claude Code sets it on `"local_agent"` and `"local_bash"` tasks. `true` means the task runs in the background. `false` means the task runs in the foreground, and the tool call that started it stays blocked until the task finishes or moves to the background.
5291* `spawn_depth`: Claude Code sets it on `"local_agent"` tasks only. A subagent that the main thread spawned has depth `1`. A subagent that a depth `1` subagent spawned has depth `2`, and so on.
5292
5293A [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`.
5294
5295`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:
5296
5297* The main thread launched the task
5298* Claude Code no longer tracks the parent task
5299* A [teammate](/docs/en/agent-teams) or an agent inside a workflow launched the task
5300
5301The parent can be a foreground task or one that already ended, so treat an ID you don't recognize as no parent.
5302
5303### `SDKTaskProgressMessage`
5304
5305Emitted periodically while a subagent or background task is running.
5306
5307For a subagent task, the `summary` field carries a model-generated progress summary and is populated only when [`agentProgressSummaries`](#options) is enabled. For a [backgrounded MCP tool call](/docs/en/mcp#automatic-backgrounding-of-long-tool-calls), `summary` carries the MCP server's latest reported progress and doesn't depend on that option.
5308
5309```typescript theme={null}
5310type SDKTaskProgressMessage = {
5311 type: "system";
5312 subtype: "task_progress";
5313 task_id: string;
5314 tool_use_id?: string;
5315 description: string;
5316 subagent_type?: string;
5317 usage: {
5318 total_tokens: number;
5319 tool_uses: number;
5320 duration_ms: number;
5321 };
5322 last_tool_name?: string;
5323 summary?: string;
5324 uuid: UUID;
5325 session_id: string;
5326};
5327```
5328
5329### `SDKTaskUpdatedMessage`
5330
5331Emitted when a background task's state changes, such as when it transitions from `running` to `completed`. Merge `patch` into your local task map keyed by `task_id`. The `end_time` field is a Unix epoch timestamp in milliseconds, comparable with `Date.now()`.
5332
5333```typescript theme={null}
5334type SDKTaskUpdatedMessage = {
5335 type: "system";
5336 subtype: "task_updated";
5337 task_id: string;
5338 patch: {
5339 status?: "pending" | "running" | "completed" | "failed" | "killed";
5340 description?: string;
5341 end_time?: number;
5342 total_paused_ms?: number;
5343 error?: string;
5344 is_backgrounded?: boolean;
5345 };
5346 uuid: UUID;
5347 session_id: string;
5348};
5349```
5350
5351### `SDKBackgroundTasksChangedMessage`
5352
5353Emitted 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`](#sdktas
5328* Clear the indicator when a later `tool_progress` for the same `parent_tool_use_id` arrives with neither `subagent_retry` nor `heartbeat: true
No line in this hunk matches that.