Agent SDK reference - TypeScript changedagent-sdk/typescript
Recorded here
Lines+97added
Lines−2removed
From line
657
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits114to this page, all time
### `SDKContextUsage` ### `SDKContextUsageCategory`
The whole hunk
from line 657, 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 657
657657
658658### `SDKControlGetContextUsageResponse`
659659
660Return type of [`getContextUsage()`](#query-object). This is the same payload the `/context` command renders in an interactive session, so alongside the token counts it carries display fields such as `color`, `gridRows`, and `percentage` that `/context` uses to draw its usage grid.
660Return type of [`getContextUsage()`](#query-object). This is the same payload Claude Code renders for the `/context` command in an interactive session, so alongside the token counts it carries display fields such as `color` and `gridRows` that Claude Code uses to draw the `/context` usage grid.
661661
662When you send `/context` as a prompt instead of calling the method, Claude Code attaches an [`SDKContextUsage`](#sdkcontextusage) payload to the `context_usage` field of the assistant message that delivers the result. That field requires Agent SDK v0.3.232 or later.
663
662664```typescript theme={null}
663665type SDKControlGetContextUsageResponse = {
664666 categories: {
from line 762
760762* `memoryFiles` lists each loaded memory file with its cost.
761763* `skills.skillFrontmatter` attributes the skill listing's tokens to each included skill. The per-skill counts measure each skill's listing entry as Claude Code actually sends it, which can be shorter than the skill's full frontmatter. Compare `skills.totalSkills` with `skills.includedSkills` to see whether every discovered skill made it into the listing.
762764
763`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
765`totalTokens` is the session's current context usage, and `maxTokens` is the window that usage is measured against. That window is the model's context window, or the lower auto-compaction window when one applies. `rawMaxTokens` carries the same value as `maxTokens`, and `percentage` is `totalTokens` as a rounded percentage of that window.
764766
767Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
768
765769### `SDKControlReadFileResponse`
766770
767771Return type of [`readFile()`](#query-object).
from line 1144
11401144 error?: SDKAssistantMessageError;
11411145 aborted?: true;
11421146 timestamp?: string;
1147 context_usage?: SDKContextUsage;
11431148};
11441149```
11451150
from line 1156
11511156
11521157`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.
11531158
1159`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.
1160
11541161### `SDKUserMessage`
11551162
11561163User input message.
from line 1467
14601467};
14611468```
14621469
1470### `SDKContextUsage`
1471
1472Structured form of the `/context` report, carried as `context_usage` on the [`SDKAssistantMessage`](#sdkassistantmessage) that delivers a `/context` result. Agent SDK v0.3.232 and later export the type. Unlike [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), it carries only the data needed to render the usage breakdown, without display fields such as `color` and `gridRows`.
1473
1474```typescript theme={null}
1475type SDKContextUsage = {
1476 model: string;
1477 total_tokens: number;
1478 raw_max_tokens: number;
1479 percentage: number;
1480 over_limit?: {
1481 tokens_over: number;
1482 kind: "hard_limit" | "compaction_window";
1483 };
1484 categories: SDKContextUsageCategory[];
1485 mcp_tools: {
1486 name: string;
1487 server_name: string;
1488 tokens: number;
1489 }[];
1490 memory_files: {
1491 path: string;
1492 type: string;
1493 tokens: number;
1494 }[];
1495 agents: {
1496 agent_type: string;
1497 source: string;
1498 tokens: number;
1499 }[];
1500 skills?: {
1501 name: string;
1502 source: string;
1503 plugin_name?: string;
1504 tokens: number;
1505 }[];
1506};
1507```
1508
1509The table lists what Claude Code puts in each field. The fields from `model` through `over_limit` describe the session as a whole, and the collection fields attribute tokens to individual items.
1510
1511| Field | Type | Description |
1512| ---------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
1513| `model` | `string` | The main loop's model Claude Code computed the usage for, not a subagent's |
1514| `total_tokens` | `number` | Claude Code's estimate of the tokens in use. Not clamped to the window, so it can exceed `raw_max_tokens` when the session is over the limit |
1515| `raw_max_tokens` | `number` | The model's context window, or the lower [auto-compact window](/docs/en/model-config#context-window-and-auto-compaction) when one applies, such as one you set or the 200K boundary Claude Code applies to some models with a 1M-token window. Claude Code measures `total_tokens` against this window |
1516| `percentage` | `number` | `total_tokens` as a rounded percentage of `raw_max_tokens`, so it can exceed 100 when the session is over the limit |
1517| `over_limit` | `object` | Present only when `total_tokens` exceeds `raw_max_tokens`. `tokens_over` is the amount over, and `kind` says how Claude Code resolved the window |
1518| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | One entry per row of the usage-by-category breakdown |
1519| `mcp_tools` | `object[]` | Tokens attributed to each MCP tool, with its wire name, such as `mcp__linear__create_issue`, and its `server_name` |
1520| `memory_files` | `object[]` | Tokens attributed to each loaded memory file, with its `path` and a source label such as `Project` or `User` in `type` |
1521| `agents` | `object[]` | Tokens attributed to each custom subagent definition, with a source identifier such as `projectSettings`, `userSettings`, or `plugin`. Built-in subagents aren't listed |
1522| `skills` | `object[]` | Tokens attributed to each skill in the skill listing, with a source identifier and, for plugin skills, the plugin's name in `plugin_name`. Absent when no skills contribute tokens |
1523
1524`over_limit.kind` records how Claude Code resolved the window, not whether the API accepts the next request:
1525
1526* `hard_limit`: the window is what Claude Code believes to be the model's own limit, past which the API refuses requests
1527* `compaction_window`: the window is a compaction-policy window, which may or may not coincide with the model's limit
1528
1529Claude Code evolves the type additively, adding new data as optional fields rather than reshaping existing ones. Read the fields you know and ignore any you don't recognize.
1530
1531### `SDKContextUsageCategory`
1532
1533One row of the `/context` usage-by-category breakdown.
1534
1535```typescript theme={null}
1536type SDKContextUsageCategory = {
1537 name: string;
1538 tokens: number;
1539 kind: "used" | "free" | "buffer" | "deferred";
1540};
1541```
1542
1543The table lists what Claude Code puts in each field of a row.
1544
1545| Field | Type | Description |
1546| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
1547| `name` | `string` | The row's display name as `/context` prints it, such as `Messages`. Classify rows by `kind`, not by name |
1548| `tokens` | `number` | The row's token count. Rows can carry zero tokens |
1549| `kind` | `string` | What the row represents: `used`, `free`, `buffer`, or `deferred` |
1550
1551Each `kind` value says what the row's tokens are:
1552
1553* `used`: content that occupies the context window
1554* `free`: the remaining window
1555* `buffer`: the compaction reserve
1556* `deferred`: tool schemas Claude Code holds out of the window and excludes from the usage calculation, listed for awareness
1557
14631558### `SDKMessageOrigin`
14641559
14651560Provenance 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 4321
42264321 | { type: "disabled" }; // No extended thinking
42274322```
42284323
4229The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in `thinking` blocks. Claude Code doesn't send `display` to Amazon Bedrock or Google Cloud's Agent Platform, so on those providers Opus 4.7 and later return empty `thinking` blocks even when you set `display` to `"summarized"`.
4230
4231### `SpawnedProcess`
4232
4233Interface for custom process spawning (used with `spawnClaudeCodeProcess` option). `ChildProcess` already satisfies this interface.
4234
4235```typescript theme={null}
4236interface SpawnedProcess {
4237 stdin: Writable;
4238 stdout: Readable;
4239 readonly killed: boolean;
4240 readonly exitCode: number | null;
4241 kill(signal: NodeJS.Signals): boolean;
4242 on(
4243 event: "exit",
4244 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4245 ): void;
4246 on(event: "error", listener: (error: Error) => void): void;
4247 once(
4248 event: "exit",
4249 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4250 ): void;
4251 once(event: "error", listener: (error: Error) => void): void;
4252 off(
4253 event: "exit",
4254 listener: (code: number | null, signal: NodeJS.Signals | null) => void
4255 ): void;
4256 off(event: "error", listener: (error: Error) => void): void;
4257}
4258```
4259
4260### `SpawnOptions`
4261
4262Options passed to the custom spawn function.
4263
4264```typescript theme={null}
4265interface SpawnOptions {
4266 command: string;
4267 args: string[];
4268 cwd?: string;
4269 env: Record<string, string | undefined>;
4270 signal: AbortSignal;
4271}
4272```
4273
4274<Note>
4275 The `signal` field tells your spawn function when to tear down the process. Pass it as the `signal` option to Node's `spawn()`, or pass it to your VM or container teardown handler.
4276
4277 This signal does not fire the instant [`Options.abortController`](#options) aborts. The SDK first closes the process's stdin and waits about two seconds so the CLI can shut down cleanly, then aborts this signal. To react the moment the caller aborts instead, listen on your own `Options.abortController.signal`, which your spawn function can reference from its enclosing scope.
4278</Note>
4279
4280### `McpSetServersResult`
4281
4282Result of a `setMcpServers()` operation.
4283
4284```typescript theme={null}
4285type McpSetServersResult = {
4286 added: string[];
4287 removed: string[];
4288 errors: Record<string, string>;
4289};
4290```
4291
4292### `RewindFilesResult`
4293
4294Result of a `rewindFiles()` operation.
4295
4296```typescript theme={null}
4297type RewindFilesResult = {
4298 canRewind: boolean;
4299 error?: string;
4300 filesChanged?: string[];
4301 insertions?: number;
4302 deletions?: number;
4303 skippedLinks?: number;
4304};
4305```
4306
4307`skippedLinks` counts the tracked paths the rewind refused to restore or delete for link safety: a symlink, hard link, or other non-regular file at the tracked path, a parent directory that no longer resolves to where it pointed when the checkpoint was taken, or a backup that couldn't be read safely. The field requires Claude Code v2.1.216 or later. A preview call with `rewindFiles(userMessageId, { dryRun: true })` never sets it.
4308
4309### `SDKStatusMessage`
4310
4311Status update message (e.g., compacting).
4312
4313```typescript theme={null}
4314type SDKStatusMessage = {
4315 type: "system";
4316 subtype: "status";
4317 status: "compacting" | null;
4318 permissionMode?: PermissionMode;
4319 uuid: UUID;
4320 session_id: string;
4321};
4322```
4323
4324### `SDKTaskNotificationMessage`
4325
4326Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents.
4327
4328```typescript theme={null}
4329type SDKTaskNotificationMessage = {
4330 type: "system";
4331 subtype: "task_notification";
4332 task_id: string;
4333 tool_use_id?: string;
4334 status: "completed" | "failed" | "stopped";
4335 output_file: string;
4336 summary: string;
4337 usage?: {
4338 total_tokens: number;
4339 tool_uses: number;
4340 duration_ms: number;
4341 };
4342 uuid: UUID;
4343 session_id: string;
4344};
4345```
4346
4347Claude 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.
4348
4349To detect a task-notification turn, check `origin.kind === "task-notification"` on the [`SDKUserMessage`](#sdkusermessage) or [`SDKResultMessage`](#sdkresultmessage) rather than matching on the notice text. Read `subkind` from the same field if you need to know what raised it. Before v2.1.205, Claude Code left the notice off notifications that arrived while the session was idle.
4350
4351### `SDKToolUseSummaryMessage`
4352
4353Summary of tool usage in a conversation.
4354
4355```typescript theme={null}
4356type SDKToolUseSummaryMessage = {
4357 type: "tool_use_summary";
4358 summary: string;
4359 preceding_tool_use_ids: string[];
4360 uuid: UUID;
4361 session_id: string;
4362};
4363```
4364
4365### `SDKHookStartedMessage`
4366
4367Emitted when a hook begins executing.
4368
4369Claude Code delivers this message, [`SDKHookProgressMessage`](#sdkhookprogressmessage), and [`SDKHookResponseMessage`](#sdkhookresponsemessage) to the message stream immediately, including while a `SessionStart` or `Setup` hook is still running during session startup. Claude Code v2.1.169 through v2.1.203 delivered these messages in one batch after a `SessionStart` or `Setup` hook completed; v2.1.204 restored live delivery.
4370
4371```typescript theme={null}
4372type SDKHookStartedMessage = {
4373 type: "system";
4374 subtype: "hook_started";
4375 hook_id: string;
4376 hook_name: string;
4377 hook_event: string;
4378 uuid: UUID;
4379 session_id: string;
4380};
4381```
4382
4383### `SDKHookProgressMessage`
4384
4385Emitted while a hook is running, with stdout/stderr output.
4386
4387```typescript theme={null}
4388type SDKHookProgressMessage = {
4389 type: "system";
4390 subtype: "hook_progress";
4391 hook_id: string;
4392 hook_name: string;
4393 hook_event: string;
4394 stdout: string;
4395 stderr: string;
4396 output: string;
4397 uuid: UUID;
4398 session_id: string;
4399};
4400```
4401
4402### `SDKHookResponseMessage`
4403
4404Emitted when a hook finishes executing.
4405
4406```typescript theme={null}
4407type SDKHookResponseMessage = {
4408 type: "system";
4409 subtype: "hook_response";
4410 hook_id: string;
4411 hook_name: string;
4412 hook_event: string;
4413 output: string;
4414 stdout: string;
4415 stderr: string;
4416 exit_code?: number;
4417 outcome: "success" | "error" | "cancelled";
4418 uuid: UUID;
4419 session_id: string;
4420};
4421```
4422
4423### `SDKToolProgressMessage`
4424
4425Emitted periodically while a tool is executing to indicate progress.
4426
4427```typescript theme={null}
4428type SDKToolProgressMessage = {
4429 type: "tool_progress";
4430 tool_use_id: string;
4431 tool_name: string;
4432 parent_tool_use_id: string | null;
4433 elapsed_time_seconds: number;
4434 task_id?: string;
4435 heartbeat?: boolean;
4436 subagent_type?: string;
4437 subagent_retry?: {
4438 agent_id: string;
4439 attempt: number;
4440 max_retries: number;
4441 retry_delay_ms: number;
4442 error_status: number | null;
4443 error_category: string;
4444 };
4445 uuid: UUID;
4446 session_id: string;
4447};
4448```
4449
4450While a tool call runs in the main conversation, Claude Code emits a `tool_progress` message every 30 seconds with `heartbeat: true`. Each heartbeat carries the tool name and elapsed seconds, so you can distinguish a long-running call from a stalled session. Claude Code doesn't emit heartbeats for the Agent tool, whose subagents stream their own progress, or for tool calls inside a subagent. The `heartbeat` field requires Agent SDK v0.3.214 or later.
4451
4452On `tool_progress` messages for the Agent tool, `subagent_type` names the running subagent type, such as `general-purpose`. `subagent_retry` is present while that subagent waits out an API error backoff, such as a rate limit or overload, with one message per retry attempt. Both fields require Agent SDK v0.3.214 or later.
4453
4454To render a retry indicator from `subagent_retry`:
4455
4456* 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.
4457* Clear the indicator when a later `tool_progress` for the same `parent_tool_use_id` arrives without the field, or when the tool's result message arrives. `attempt` can exceed `max_retries` under persistent retry, so don't derive clearing from the counters.
4458* Treat `error_category` as a closed set of tokens for choosing your own message text, not as display text: `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, or `unknown`.
4459
4460### `SDKAuthStatusMessage`
4461
4462Emitted during authentication flows.
4463
4464```typescript theme={null}
4465type SDKAuthStatusMessage = {
4466 type: "auth_status";
4467 isAuthenticating: boolean;
4468 output: string[];
4469 error?: string;
4470 uuid: UUID;
4471 session_id: string;
4472};
4473```
4474
4475### `SDKTaskStartedMessage`
4476
4477Emitted when a background task begins. The `
4324The optional `display` field controls whether thinking text is returned `"summarized"` or `"omitted"`. On Claude Opus 4.7 and later, the API default is `"omitted"`, so set `"summarized"` to receive thinking content in `thinking` blocks. Claude Code doesn't send `display` to A
No line in this hunk matches that.