Agent SDK reference - TypeScript changedagent-sdk/typescript
Upstream edited this page at 25 Oct 2026 14:23 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 25 Oct 2026 14:37 UTC.
Upstream edited
Recorded here
Lines+59added
Lines−1removed
From line
305
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits121to this page, all time
#### `setMcpPermissionModeOverride()` #### `seedReadState()` #### `backgroundTasks()`
The whole hunk
from line 305, 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 305
305305| `options.dir` | `string` | `undefined` | Project directory to find the session in. When omitted, searches all projects |
306306| `options.limit` | `number` | `undefined` | Maximum number of messages to return |
307307| `options.offset` | `number` | `undefined` | Number of messages to skip from the start |
308| `options.includeSystemMessages` | `boolean` | `false` | When `true`, also return system messages such as compact boundaries alongside user and assistant messages |
308309
309310#### Return type: `SessionMessage`
310311
311312| Property | Type | Description |
312313| :- | :- | :- |
313| `type` | `"user" \| "assistant"` | Message role |
314| `type` | `"user" \| "assistant" \| "system"` | Message role. `"system"` appears only when `options.includeSystemMessages` is `true` |
314315| `uuid` | `string` | Unique message identifier |
315316| `session_id` | `string` | Session this message belongs to |
316317| `message` | `unknown` | Raw message payload from the transcript |
from line 629
628629 }): Promise<SDKControlReloadPluginsResponse>;
629630 reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
630631 reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
632 seedReadState(path: string, mtime: number): Promise<void>;
631633 accountInfo(): Promise<AccountInfo>;
632634 reconnectMcpServer(serverName: string): Promise<void>;
633635 toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
634636 setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
637 setMcpPermissionModeOverride(
638 serverName: string,
639 mode: 'default' | 'auto' | null
640 ): Promise<{ warning?: string }>;
635641 readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
636642 streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
637643 stopTask(taskId: string): Promise<void>;
644 backgroundTasks(toolUseId?: string): Promise<boolean>;
638645 close(): void;
639646}
640647```
from line 668
661668| `reloadPlugins(options?)` | Reloads plugins from disk, so plugins you install or edit mid-session reach the running session. Resolves with an [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) listing the session's commands, subagents, plugins, and MCP server status. Requires Agent SDK v0.2.85 or later. The [`holdOnCacheImpact` option](#sdkcontrolreloadpluginsresponse) requires Agent SDK v0.3.268 or later |
662669| `reloadSkills()` | Reloads skills from disk, so skills you add or edit mid-session become available to the running session. Resolves with an [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) listing the skills available after the reload. Requires Agent SDK v0.3.163 or later |
663670| `reloadOutputStyles()` | Re-reads [output styles](https://code.claude.com/docs/en/output-styles.md) from disk, so a style file you add or edit mid-session becomes available to the running session. Resolves with an [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) listing the style names available after the reload. Requires Agent SDK v0.3.261 or later |
671| `seedReadState(path, mtime)` | Marks a file as already read so a later Edit doesn't fail with `File has not been read yet`. See [`seedReadState()`](#seedreadstate). Requires TypeScript SDK v0.2.83 or later |
664672| `accountInfo()` | Returns account information |
665673| `reconnectMcpServer(serverName)` | Reconnect an MCP server by name. If the name also matches an entry in a settings file such as `.mcp.json` or `~/.claude.json`, Claude Code reconnects the server you configured through [`mcpServers`](#options) or `setMcpServers()`, not the settings-file entry. That resolution order requires Claude Code v2.1.257 or later |
666674| `toggleMcpServer(serverName, enabled)` | Enable or disable an MCP server by name, with the same name resolution as `reconnectMcpServer()`. Disabling a server disconnects it and removes its tools. See [`toggleMcpServer()`](#togglemcpserver) for the Claude Code version this needs for each kind of server |
667675| `setMcpServers(servers)` | Replace the MCP servers this method manages: servers added through it and [in-process SDK servers](#createsdkmcpserver). Resolves with an [`McpSetServersResult`](#mcpsetserversresult) naming which servers were added and removed, and any errors; that section says which other servers stay connected |
676| `setMcpPermissionModeOverride(serverName, mode)` | Overrides the permission mode for one MCP server's tools with a stricter mode than the session's, or clears the override with `null`. Only available in streaming input mode. See [`setMcpPermissionModeOverride()`](#setmcppermissionmodeoverride). Requires TypeScript SDK v0.3.187 or later |
668677| `readMcpResource(serverName, uri)` | *Alpha.* Reads one MCP Apps `ui://` resource from a connected MCP server so your application can render a tool's widget. Resolves with an [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requires TypeScript Agent SDK v0.3.280 or later |
669678| `streamInput(stream)` | Stream input messages to the query for multi-turn conversations |
670679| `stopTask(taskId)` | Stop a running background task by ID |
680| `backgroundTasks(toolUseId?)` | Moves the running Bash commands and subagents that the turn is waiting on to the background, the same as pressing Ctrl+B in the interactive terminal. See [`backgroundTasks()`](#backgroundtasks). Requires TypeScript SDK v0.2.139 or later |
671681| `close()` | Close the query and terminate the underlying process. Forcefully ends the query and cleans up all resources |
672682
683#### `setMcpPermissionModeOverride()`
684
685Overrides the permission mode for one MCP server's tools with a stricter mode than the session's, or clears the override with `null`. Use it when a session runs in a mode that skips per-action prompts but one server's tools should still be reviewed. Requires TypeScript SDK v0.3.187 or later.
686
687Pass one of three values as `mode`:
688
689* `'default'`: Claude Code evaluates that server's tool calls as [Manual mode](https://code.claude.com/docs/en/permission-modes.md#available-modes) does.
690* `'auto'`: Claude Code routes that server's tool calls through the [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) classifier. Claude Code rejects this value when the classifier isn't available to the session.
691* `null`: clears the override.
692
693The override only takes effect while the session is in a mode that skips per-action prompts: `bypassPermissions` or `auto`. In any other session mode Claude Code ignores the override, so it can never widen what the session allows.
694
695The promise resolves with `{ warning }` when no server by that name is known yet. Claude Code stores the override anyway and applies it once a server with that exact name connects, so the warning is a typo check, not a failure.
696
697Only available in streaming input mode, the same constraint as `setModel()` and `setPermissionMode()`.
698
699#### `seedReadState()`
700
701Marks a file as already read so a later Edit doesn't fail with `File has not been read yet`. Use it when your application has dropped an earlier `Read` result from the conversation context and Claude will edit that file next. Requires TypeScript SDK v0.2.83 or later.
702
703Pass `mtime` as the file's modification time at the moment of that earlier read, in whole milliseconds since the epoch, for example `Math.floor(stat.mtimeMs)`. If the file on disk changed after that time, Claude Code skips the mark.
704
705The promise resolves whether or not the file was marked, so a resolved promise doesn't tell you which happened.
706
707#### `backgroundTasks()`
708
709Moves the running Bash commands and subagents that the turn is waiting on to the background, the same as pressing Ctrl+B in the interactive terminal. Pass the `toolUseId` of a tool call to background only the Bash command or subagent that call started, or omit it to background every foreground task. Requires TypeScript SDK v0.2.139 or later.
710
711Each backgrounded tool call returns to Claude immediately with a running-in-the-background result, the turn continues, and Claude Code emits an [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) when the task finishes.
712
713In a session where background tasks are enabled, the promise resolves to a boolean:
714
715* **`true`**: a task was backgrounded, or you omitted `toolUseId`.
716* **`false`**: the `toolUseId` you passed matched no foreground task.
717
718If background tasks are disabled for the session, such as with [`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS`](https://code.claude.com/docs/en/env-vars), the promise rejects instead and nothing is backgrounded.
719
673720#### `applyFlagSettings()`
674721
675722Changes [settings](https://code.claude.com/docs/en/settings.md) on a running session without restarting the query. Use it when a setting that has no dedicated setter needs to change mid-session, such as tightening `permissions` after the agent reads untrusted input. `setModel()` and `setPermissionMode()` are dedicated setters for those two keys; `applyFlagSettings()` is the general form that accepts any subset of the settings keys, and passing `model` here behaves the same as `setModel()`.
from line 1515
14681515 | SDKPermissionDeniedMessage
14691516 | SDKPromptSuggestionMessage
14701517 | SDKAPIRetryMessage
1518 | SDKControlRequestProgressMessage
1519 | SDKModelRefusalFallbackMessage
1520 | SDKModelRefusalNoFallbackMessage
14711521 | SDKMirrorErrorMessage
14721522 | SDKInformationalMessage
14731523 | SDKConversationResetMessage;
14741524```
14751525
1526Three messages in this union report control-request progress and model refusals. Each has `type: "system"`, so tell them apart by the `subtype` listed with each one:
1527
1528* `SDKControlRequestProgressMessage`, `subtype: "control_request_progress"`: reports progress on a long-running control request that your client sent. `request_id` matches the message to that request, and `status` is `"started"` or `"api_retry"`. Requires Agent SDK v0.3.203 or later.
1529* `SDKModelRefusalFallbackMessage`, `subtype: "model_refusal_fallback"`: emitted when the model ends the stream with a refusal and the turn is retried on a fallback model. Carries `original_model` and `fallback_model`. Requires Agent SDK v0.3.170 or later.
1530* `SDKModelRefusalNoFallbackMessage`, `subtype: "model_refusal_no_fallback"`: emitted when the model ends the stream with a refusal and no retry runs, for example because no fallback model is configured. Carries `original_model`. Requires Agent SDK v0.3.193 or later.
1531
14761532### `SDKAssistantMessage`
14771533
14781534Assistant response message.
from line 1688
16321688 stop_reason: string | null;
16331689 ttft_ms?: number;
16341690 ttft_stream_ms?: number;
1691 time_to_request_ms?: number;
16351692 user_message_uuid?: string;
16361693 user_message_uuids?: string[];
16371694 resume_reason?: string;
from line 1754
16971754* `api_error_status`: the HTTP status code of the API error that terminated the conversation. Absent or `null` when the turn ended without an API error.
16981755* `ttft_ms`: time to first token in milliseconds, measured when the first complete assistant message arrives. Present on the success arm only.
16991756* `ttft_stream_ms`: time in milliseconds until the first `message_start` stream event, when the response stream opens. Lower than `ttft_ms`; the gap between the two is time spent streaming the first message. Present on the success arm only.
1757* `time_to_request_ms`: time in milliseconds from the start of the turn until Claude Code sends the API request. Present on the success arm only. Requires Claude Code v2.1.162 or later.
17001758* `user_message_uuid`: the `uuid` of the message you sent that this turn answered. See [`user_message_uuid`](#user_message_uuid) for which results carry it.
17011759* `user_message_uuids`: the `uuid`s of every message you sent that Claude Code answered in this turn. See [`user_message_uuids`](#user_message_uuids).
17021760* `resume_reason`: why this turn continues one that a restart interrupted. Present on both arms. See [`resume_reason`](#resume_reason).
from line 5103
50455103
50465104### `ModelUsage`
50475105
5048Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md) for billing caveats.
5049
5050```typescript theme={null}
5051type ModelUsage = {
5052 inputTokens: number;
5053 outputTokens: number;
5054 thinkingTokens?: number;
5055 cacheReadInputTokens: number;
5056 cacheCreationInputTokens: number;
5057 webSearchRequests: number;
5058 costUSD: number;
5059 contextWindow: number;
5060 maxOutputTokens: number;
5061 canonicalModel?: string;
5062 provider?: string;
5063 costBasis?: 'list' | 'managed' | 'unknown';
5064};
5065```
5066
5067`thinkingTokens` counts the thinking tokens this model generated. `outputTokens` already includes them, so don't add the two together. The field is absent until a turn runs on a Claude Code version that records it, so a resumed session that began on an earlier version reports a partial count. `thinkingTokens` requires Agent SDK v0.3.257 or later.
5068
5069The `canonicalModel` and `provider` fields require Claude Code v2.1.218 or later. `canonicalModel` is the canonical model ID that the pricing lookup uses; it can differ from the raw model string that keys the entry, for example when that string is a provider-specific ID or an alias.
5070
5071`provider` names the API backend that served the model, such as `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, or `gateway`.
5072
5073`costBasis` names the price table that priced the model's latest request: `list` for list price, `managed` for a [`modelPricing`](https://code.claude.com/docs/en/settings-reference#modelpricing) table, or `unknown` when neither matched the model ID. The field requires Claude Code v2.1.246 or later.
5074
5075### `ConfigScope`
5076
5077```typescript theme={null}
5078type ConfigScope = "local" | "user" | "project";
5079```
5080
5081### `NonNullableUsage`
5082
5083A version of [`Usage`](#usage) with every nullable field made non-nullable except `fallback_credit`, which can still be `null`.
5084
5085```typescript theme={null}
5086type NonNullableUsage = {
5087 [K in keyof Usage]: K extends "fallback_credit"
5088 ? Usage[K]
5089 : NonNullable<Usage[K]>;
5090};
5091```
5092
5093### `Usage`
5094
5095Token usage statistics. This is the `BetaUsage` type from `@anthropic-ai/sdk`.
5096
5097```typescript theme={null}
5098type Usage = {
5099 input_tokens: number;
5100 output_tokens: number;
5101 cache_creation_input_tokens: number | null;
5102 cache_read_input_tokens: number | null;
5103 cache_creation: {
5104 ephemeral_5m_input_tokens: number;
5105 ephemeral_1h_input_tokens: number;
5106 } | null;
5107 server_tool_use: BetaServerToolUsage | null;
5108 service_tier: "standard" | "priority" | "batch" | null;
5109 speed: "standard" | "fast" | null;
5110 inference_geo: string | null;
5111 iterations: BetaIterationsUsage | null;
5112 output_tokens_details: BetaOutputTokensDetails | null;
5113 fallback_credit: BetaFallbackCreditUsage | null;
5114};
5115```
5116
5117`BetaServerToolUsage`, `BetaIterationsUsage`, `BetaOutputTokensDetails`, and `BetaFallbackCreditUsage` are defined in `@anthropic-ai/sdk`.
5118
5119`output_tokens_details` breaks the billed output down by category. It currently carries one field, `thinking_tokens: number`, counting the output tokens the model generated as internal reasoning, including the thinking-block delimiters. The `output_tokens_details` field requires TypeScript SDK v0.3.228 or later, which bundles Claude Code v2.1.228.
5120
5121* **Billing**: read the breakdown for observability, not for billing. `output_tokens` stays the authoritative total, and `output_tokens - thinking_tokens` approximates the non-reasoning output.
5122* **What the count covers**: the raw reasoning the model produced, which can be longer than the thinking text returned in the response body. The API computes it by re-tokenizing that raw text, so it can differ from the model's exact generation count by a few tokens.
5123* **Streaming**: on streamed assistant messages this breakdown, like `output_tokens`, is a `message_start` placeholder and carries no real count, so read it from the result message's `usage` as [Read output tokens from the result message](https://code.claude.com/docs/en/agent-sdk/cost-tracking.md#read-output-tokens-from-the-result-message) describes. On the result message, `thinking_tokens` reads `0` when the model or provider reports no breakdown.
5124* **`null` cases**: `output_tokens_details` itself is `null` on assistant messages Claude Code synthesizes, such as API-error messages.
5125
5126Whether `Usage` carries `fallback_credit` depends on your installed `@anthropic-ai/sdk`, which added it in 0.115.0.
5127
5128### `CallToolResult`
5129
5130MCP tool result type (from `@modelcontextprotocol/sdk/types.js`). `structuredContent` is a JSON object that can be returned alongside `content`, including image blocks. See [Return structured data](https://code.claude.com/docs/en/agent-sdk/custom-tools.md#return-structured-data).
5131
5132```typescript theme={null}
5133type CallToolResult = {
5134 content: Array<{
5135 type: "text" | "image" | "audio" | "resource" | "resource_link";
5136 // Additional fields vary by type
5137 }>;
5138 structuredContent?: Record<string, unknown>;
5139 isError?: boolean;
5140};
5141```
5142
5143### `SDKMcpResourceLink`
5144
5145One file an MCP tool returned by reference. Claude Code builds each entry from a `resource_link` block in the tool's result and delivers the list as `resourceLinks` on [`SDKUserMessage.tool_use_result`](#sdkusermessage), or as `resource_links` on [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) when the call finished in the background. Requires Agent SDK v0.3.257 or later.
5146
5147```typescript theme={null}
5148type SDKMcpResourceLink = {
5149 uri: string;
5150 name: string;
5151 title?: string;
5152 description?: string;
5153 mimeType?: string;
5154 size?: number;
5155 annotations?: Record<string, unknown>;
5156};
5157```
5158
5159Claude Code drops a block whose `uri` or `name` isn't a s
5106Per-model usage statistics returned in re
No line in this hunk matches that.