Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.307, published 2 hours after 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 21 Oct 2026 17:52 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 21 Oct 2026 18:07 UTC.
Upstream edited
Recorded here
Lines+21added
Lines−0removed
From line
999
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits113to this page, all time
#### Find a row by ID, a server's instruction tokens, or an entry's plugin and file
The whole hunk
from line 999, 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 999
999999
10001000Claude Code leaves the optional `deferredBuiltinTools`, `systemTools`, and `systemPromptSections` diagnostics unset, so expect them to be absent even though the type declares them.
10011001
1002#### Find a row by ID, a server's instruction tokens, or an entry's plugin and file
1003
1004MCP server instructions are the usage notes that connected servers supply and Claude Code adds to context, and the `mcp_instructions` row of `categories` counts their tokens. Use these [`getContextUsage()`](#query-object) fields to pick out one `categories` row by `id`, split the `mcp_instructions` tokens by server, or find the plugin and file behind an agent or skill entry:
1005
1006| Field | Found on | What it holds |
1007| :- | :- | :- |
1008| `id` | Each `categories` row | The row's identifier, one of the values the [response type](#sdkcontrolgetcontextusageresponse) lists, such as `mcp_instructions`. Match on `id` to pick out one row, or on `kind` to group rows. A later Claude Code version can send a value your installed types don't list, so treat an `id` you don't recognize as absent |
1009| `mcpInstructions` | The response | One `{ serverName, tokens }` entry per connected MCP server that supplies instructions, or an empty array when none does. The `tokens` values are estimates that add up to the `mcp_instructions` row's `tokens`. `serverName` is the `name` that [`mcpServerStatus()`](#query-object) reports for that server |
1010| `pluginId` | `agents` and `skills.skillFrontmatter` entries | Names the plugin the entry comes from, as an ID in the form `name@marketplace`, and is absent for an entry that doesn't come from a plugin. When the plugin didn't come from a marketplace, the part after `@` names [its origin](/docs/en/plugins/loading#find-where-a-plugin-came-from) instead, such as `inline` for one you loaded through the [`plugins`](#options) option |
1011| `path` | `agents` and `skills.skillFrontmatter` entries | Absolute path of the file that defines the agent or skill, on the machine where Claude Code runs. The field is absent when no file defines the entry, for example an agent from the [`agents`](#options) option or a skill built into Claude Code |
1012
1013As an example of matching on `id`, this sample finds the `mcp_instructions` row:
1014
1015```typescript theme={null}
1016// q is the Query object that query() returned
1017const usage = await q.getContextUsage();
1018// undefined if no connected server supplies instructions
1019const row = usage.categories.find((c) => c.id === "mcp_instructions");
1020```
1021
10021022### `SDKControlReadFileResponse`
10031023
10041024Return type of [`readFile()`](#query-object).
from line 5249
52295249* **Servers the call doesn't name**: outside a [cloud session](/docs/en/claude-code-on-the-web), Claude Code disconnects the servers an earlier `setMcpServers()` call added and the in-process SDK servers, and lists them in `removed`. Other servers keep running and aren't listed in `removed`, among them the stdio, HTTP, and SSE servers from the [`mcpServers`](#options) option, servers from settings files, and plugin-provided servers.
52305250* **Servers the call names**: Claude Code replaces a stdio, HTTP, or SSE server that an earlier `setMcpServers()` call added only when its config differs from the one you passed. An in-process SDK server already registered under that name stays as it is, so to swap one, leave it out of one call and add it in the next.
52315251* **Built-in servers the CLI started at startup**: if the call names one, Claude Code drops that entry and reports it in `errors`.
5232
5233The promise resolves after newly added stdio, HTTP, and SSE servers connect or fail, so tools from servers that connected are available on the next turn.
5234
5235`added` lists the servers Claude Code added or replaced, whether or not they connected. A server that failed to connect appears in both `added` and `errors`, with the failure text under `errors` and a `failed` row in [`mcpServerStatus()`](#methods). Before Claude Code v2.1.257, a server whose connection attempt threw was reported only under `errors`.
5236
5237### `RewindFilesResult`
5238
5239Result of a `rewindFiles()` operation.
5240
5241```typescript theme={null}
5242type RewindFilesResult = {
5243 canRewind: boolean;
5244 error?: string;
5245 filesChanged?: string[];
5246 insertions?: number;
5247 deletions?: number;
5248 skippedLinks?: number;
5249};
5250```
5251
5252`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.
5253
5254### `SDKStatusMessage`
5255
5256Status update message (for example, compacting).
5257
5258```typescript theme={null}
5259type SDKStatusMessage = {
5260 type: "system";
5261 subtype: "status";
5262 status: "compacting" | null;
5263 permissionMode?: PermissionMode;
5264 uuid: UUID;
5265 session_id: string;
5266};
5267```
5268
5269### `SDKTaskNotificationMessage`
5270
5271Notification when a background task completes, fails, or is stopped. Background tasks include `run_in_background` Bash commands, [Monitor](#monitor) watches, and background subagents. For the `run_id` and `ambient` fields, see [`SDKTaskStartedMessage`](#sdktaskstartedmessage), which defines them and their version requirements.
5272
5273```typescript theme={null}
5274type SDKTaskNotificationMessage = {
5275 type: "system";
5276 subtype: "task_notification";
5277 task_id: string;
5278 run_id?: string;
5279 tool_use_id?: string;
5280 status: "completed" | "failed" | "stopped";
5281 reason?: "worker_restart";
5282 output_file: string;
5283 summary: string;
5284 ambient?: boolean;
5285 usage?: {
5286 total_tokens: number;
5287 tool_uses: number;
5288 duration_ms: number;
5289 };
5290 resource_links?: SDKMcpResourceLink[];
5291 uuid: UUID;
5292 session_id: string;
5293};
5294```
5295
5296`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-ho
5252* **Stdio, HTTP, or SSE servers that share a name with one from an MCP installation scope such as `.mcp.json`**: under that name the session uses your server's tools rather than the [installation-scope server's](/docs/en/mcp#mcp-installation-scopes). Before Claude Code v2.1.305, Claude Code could dis
No line in this hunk matches that.