Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.237, published an hour before this site recorded the change. Shown because the two are within 24 hours of each other. Nothing here says the release caused the edit.
Recorded here
Lines+39added
Lines−9removed
From line
1,327
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits113to this page, all time
The whole hunk
from line 1327, 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 1327
13271327 plugins: { name: string; path: string }[];
13281328 fast_mode_state?: FastModeState;
13291329 fast_mode_disabled_reason?: FastModeDisabledReason;
1330 effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
13301331 capabilities?: string[];
13311332};
13321333```
from line 1336
13351336
13361337`terminal_slash_commands` names the entries in `slash_commands` whose interface is bound to the local terminal, such as `exit`. You can send them like any other entry in `slash_commands`; the field exists so a remote or mobile client can hide them from its command menus. The field is present only when non-empty, and requires Agent SDK v0.3.229 or later.
13371338
1339* `effort`: the [effort level](/docs/en/model-config#adjust-effort-level) Claude Code sends on the session's next request, or `null` when it sends none. Claude Code sets the field only on the init message it sends to [Remote Control](/docs/en/remote-control) clients, and omits it from the init message your application reads. Requires Agent SDK v0.3.234 or later.
1340
13381341The `capabilities` array names the protocol behaviors this CLI implements, so you can feature-detect instead of comparing `claude_code_version` strings. It is an open set: ignore values you don't recognize, and check for the specific capability whose behavior you rely on. The field requires Claude Code v2.1.205 or later and is absent on earlier CLIs.
13391342
13401343| Capability | Meaning |
from line 1569
15661569 | {
15671570 kind: "peer";
15681571 from: string;
1572 fromMode?: "bypass" | "prompting";
15691573 name?: string;
15701574 fromSession?: string;
15711575 senderTaskId?: string;
from line 1609
16051609A `peer` origin identifies which agent sent the message: an in-process [teammate](/docs/en/agent-teams) sending to `main` with `SendMessage`, or a [cross-session peer](/docs/en/cross-session-messaging), another of your Claude Code sessions. A cross-session peer can run on the same machine, or on [another of your machines](/docs/en/cross-session-messaging#message-sessions-on-other-machines) or [Claude Code on the web](/docs/en/claude-code-on-the-web) when its message arrives through Remote Control. The two kinds of sender fill the fields differently:
16061610
16071611* `from`: the teammate's name, or the sender address for a cross-session peer. For a [one-way cross-machine message](/docs/en/cross-session-messaging#message-sessions-on-other-machines), the sender has no reply address and `from` is `"unknown"`. The value is sender-authored; `verifiedPeerPid` is the verified identity.
1612* `fromMode`: the sending session's permission class, `bypass` or `prompting`, declared by a host that relays a peer message between your sessions, such as the [desktop app](/docs/en/desktop#work-across-sessions). Claude Code reads it in the receiving session when it applies the [inbound controls](/docs/en/cross-session-messaging#control-inbound-messages). Requires Agent SDK v0.3.234 or later.
16081613* `senderTaskId`: the teammate's task ID. Absent for a cross-session peer.
16091614* `name`: the sender's display name, normalized by Claude Code: it strips Unicode control, format, surrogate, and line or paragraph separator code points, then trims the result and caps it at 64 code points with an ellipsis. Requires Claude Code v2.1.205 or later.
16101615* `body`: the decoded message body with the peer envelope stripped, byte-exact with what the model sees. Always present for a teammate message; for a cross-session peer, present only when the turn is exactly one peer envelope formed by Claude Code. Render `name` and `body` instead of re-parsing the message text. Requires Claude Code v2.1.205 or later.
from line 2926
29212926 label?: string;
29222927 url?: string;
29232928 force?: boolean;
2929 capabilities?: Record<string, unknown>;
2930 contract?: "latest" | string;
29242931};
29252932```
29262933
from line 2935
29282935
29292936Pass `"list"` to enumerate the user's published artifacts; only `limit` and `scope` may accompany it. `scope` defaults to `"mine"`, which lists artifacts the user owns; `"shared"` lists artifacts other people shared with the user, and `"all"` lists both.
29302937
2938* `capabilities`: the runtime capabilities the published page uses, keyed by capability name, such as the [connectors the page may call](/docs/en/artifacts#pull-live-data-with-mcp-connectors). The artifact service validates the declaration and rejects a publish that names a capability the account can't use or gives one an invalid config. Pass `{}` to clear a stored declaration, and omit the field on a redeploy to keep it. Requires Agent SDK v0.3.235 or later.
2939* `contract`: the runtime version the published page runs against. Omit it to keep the artifact's current version, pass `"latest"` to upgrade, or pass a specific version to pin or roll back. Requires Agent SDK v0.3.235 or later.
2940
29312941The types are exported, but the tool is off by default in Agent SDK sessions. Publishing also requires every condition in the [artifacts availability table](/docs/en/artifacts#availability), which sessions authenticated with an API key don't meet.
29322942
29332943### Projects
from line 3197
31873197 staleReadFileStateHint?: string;
31883198 ghRateLimitHint?: string;
31893199 gitOperation?: {
3190 commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked" };
3200 commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };
31913201 push?: { branch: string };
31923202 branch?: { ref: string; action: "merged" | "rebased" };
31933203 pr?: {
31943204 number: number;
31953205 url?: string;
3196 action: "created" | "edited" | "merged" | "commented" | "closed" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
3206 action: "created" | "edited" | "merged" | "commented" | "closed" | "reopened" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
31973207 };
31983208 };
31993209};
from line 3221
32113221
32123222When a subagent running in the foreground owns a backgrounded command, Claude Code terminates the command when that subagent gives its final response. Claude Code sets `backgroundEndsWithFinalResponse` to `true` on such commands, and omits the field when the command survives the turn, as commands started by the main conversation or by background subagents do. The field requires Claude Code v2.1.227 or later.
32133223
3224Claude Code sets `gitOperation.commit.branch` to the branch named in git's commit summary line, and omits it for a commit made on a detached HEAD. The field requires Agent SDK v0.3.227 or later. Claude Code reports a `gh pr reopen` command as the `reopened` PR action, which requires Agent SDK v0.3.234 or later.
3225
32143226### Monitor
32153227
32163228**Tool name:** `Monitor`
from line 4105
40934105
40944106### `ApiKeySource`
40954107
4108Where the API key for the session's requests came from, reported as `apiKeySource` on the [`SDKSystemMessage`](#sdksystemmessage) init message.
4109
40964110```typescript theme={null}
4097type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";
4111type ApiKeySource =
4112 | "ANTHROPIC_API_KEY"
4113 | "apiKeyHelper"
4114 | "/login managed key"
4115 | "none"
4116 | "user"
4117 | "project"
4118 | "org"
4119 | "temporary"
4120 | "oauth";
40984121```
40994122
4100<Note>
4101 At runtime, the `apiKeySource` field on the [`SDKSystemMessage`](#sdksystemmessage) init message can also be the string `"none"` when no API key is in use, for example when the session authenticates with an OAuth token. Handle values outside this union defensively.
4102</Note>
4123Claude Code reports one of four values:
41034124
4125| Value | Key in use |
4126| -------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
4127| `ANTHROPIC_API_KEY` | The key in the `ANTHROPIC_API_KEY` environment variable |
4128| `apiKeyHelper` | The key returned by your [`apiKeyHelper`](/docs/en/settings#available-settings) command |
4129| `/login managed key` | The key Claude Code stored when you logged in with a [Claude Console account](/docs/en/authentication#claude-console-authentication) |
4130| `none` | No API key. The session authenticates another way, such as a claude.ai login, a bearer token, or a cloud provider |
4131
4132Agent SDK v0.3.234 and later list these four values in the type. The type also keeps `user`, `project`, `org`, `temporary`, and `oauth` so older code still compiles, and Claude Code doesn't report them.
4133
41044134### `SdkBeta`
41054135
41064136Available beta features that can be enabled via the `betas` option. See [Beta headers](https://platform.claude.com/docs/en/api/beta-headers) for more information.
from line 4262
42324262
42334263### `ModelUsage`
42344264
4235Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for billing caveats.
4236
4237```typescript theme={null}
4238type ModelUsage = {
4239 inputTokens: number;
4240 outputTokens: number;
4241 cacheReadInputTokens: number;
4242 cacheCreationInputTokens: number;
4243 webSearchRequests: number;
4244 costUSD: number;
4245 contextWindow: number;
4246 maxOutputTokens: number;
4247 canonicalModel?: string;
4248 provider?: string;
4249};
4250```
4251
4252The `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.
4253
4254`provider` names the API backend that served the model, such as `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle`, or `gateway`.
4255
4256### `ConfigScope`
4257
4258```typescript theme={null}
4259type ConfigScope = "local" | "user" | "project";
4260```
4261
4262### `NonNullableUsage`
4263
4264A version of [`Usage`](#usage) with all nullable fields made non-nullable.
4265
4266```typescript theme={null}
4267type NonNullableUsage = {
4268 [K in keyof Usage]: NonNullable<Usage[K]>;
4269};
4270```
4271
4272### `Usage`
4273
4274Token usage statistics. This is the `BetaUsage` type from `@anthropic-ai/sdk`.
4275
4276```typescript theme={null}
4277type Usage = {
4278 input_tokens: number;
4279 output_tokens: number;
4280 cache_creation_input_tokens: number | null;
4281 cache_read_input_tokens: number | null;
4282 cache_creation: {
4283 ephemeral_5m_input_tokens: number;
4284 ephemeral_1h_input_tokens: number;
4285 } | null;
4286 server_tool_use: BetaServerToolUsage | null;
4287 service_tier: "standard" | "priority" | "batch" | null;
4288 speed: "standard" | "fast" | null;
4289 inference_geo: string | null;
4290 iterations: BetaIterationsUsage | null;
4291};
4292```
4293
4294`BetaServerToolUsage` and `BetaIterationsUsage` are defined in `@anthropic-ai/sdk`.
4295
4296### `CallToolResult`
4297
4298MCP 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](/docs/en/agent-sdk/custom-tools#return-structured-data).
4299
4300```typescript theme={null}
4301type CallToolResult = {
4302 content: Array<{
4303 type: "text" | "image" | "audio" | "resource" | "resource_link";
4304 // Additional fields vary by type
4305 }>;
4306 structuredContent?: Record<string, unknown>;
4307 isError?: boolean;
4308};
4309```
4310
4311### `ThinkingConfig`
4312
4313Controls Claude's thinking/reasoning behavior. Takes precedence over the deprecated `maxThinkingTokens`.
4314
4315```typescript theme={null}
4316type ThinkingDisplay = "summarized" | "omitted";
4317
4318type ThinkingConfig =
4319 | { type: "adaptive"; display?: ThinkingDisplay } // The model determines when and how much to reason (Opus 4.6+)
4320 | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Fixed thinking token budget
4321 | { type: "disabled" }; // No extended thinking
4322```
4323
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 Amazon Bedrock or Google Cloud's Agent Plat
4265Per-model usage statistics returned in result messages. The `costUSD` value is a client-side estimate. See [Track cost and usage](/docs/en/agent-sdk/cost-tracking) for billing ca
No line in this hunk matches that.