Agent SDK reference - TypeScript changedagent-sdk/typescript
Upstream edited this page at 5 Oct 2026 01:07 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 5 Oct 2026 01:37 UTC.
Upstream edited
Recorded here
Lines+13added
Lines−7removed
From line
3,645
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits74to this page, all time
The whole hunk
from line 3645, 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 3645
36453645 output_tokens_details?: {
36463646 thinking_tokens?: number | null;
36473647 } | null;
3648 fallback_credit?: unknown;
36483649 };
36493650 toolStats?: {
36503651 readCount: number;
from line 3690
36893690
36903691If Claude Code [kept the subagent's isolated worktree](/docs/en/worktrees#isolate-subagents-with-worktrees), `worktreePath` on the `completed` result is where to find it. `worktreeBranch` is its branch, present when Claude Code created the worktree with git.
36913692
3692Claude Code fills `usage` and `totalTokens` from the subagent's final API request, not from the whole run, so `usage.service_tier` is the service tier string the API reported on that request. When present, `usage.output_tokens_details.thinking_tokens` is the number of that request's output tokens that were thinking tokens. The `output_tokens_details` field requires TypeScript SDK v0.3.228 or later, which bundles Claude Code v2.1.228.
3693Claude Code fills `usage` and `totalTokens` from the subagent's final API request, not from the whole run, so `usage.service_tier` is the service tier string the API reported on that request. When present, `usage.output_tokens_details.thinking_tokens` is the number of that request's output tokens that were thinking tokens. The `output_tokens_details` field requires TypeScript SDK v0.3.228 or later, which bundles Claude Code v2.1.228. The `fallback_credit` field requires TypeScript SDK v0.3.285 or later, which bundles Claude Code v2.1.285.
36933694
36943695`usage.output_tokens_details` matches [`Usage.output_tokens_details`](#usage) in meaning, scoped to that final request, but every level of it is optional here. Guard both the object and the field, for example `usage.output_tokens_details?.thinking_tokens ?? 0`, rather than reading it directly.
36953696
from line 4868
48674868
48684869### `NonNullableUsage`
48694870
4870A version of [`Usage`](#usage) with all nullable fields made non-nullable.
4871A version of [`Usage`](#usage) with every nullable field made non-nullable except `fallback_credit`, which can still be `null`.
48714872
48724873```typescript theme={null}
48734874type NonNullableUsage = {
4874 [K in keyof Usage]: NonNullable<Usage[K]>;
4875 [K in keyof Usage]: K extends "fallback_credit"
4876 ? Usage[K]
4877 : NonNullable<Usage[K]>;
48754878};
48764879```
48774880
from line 4898
48954898 inference_geo: string | null;
48964899 iterations: BetaIterationsUsage | null;
48974900 output_tokens_details: BetaOutputTokensDetails | null;
4901 fallback_credit: BetaFallbackCreditUsage | null;
48984902};
48994903```
49004904
4901`BetaServerToolUsage`, `BetaIterationsUsage`, and `BetaOutputTokensDetails` are defined in `@anthropic-ai/sdk`.
4905`BetaServerToolUsage`, `BetaIterationsUsage`, `BetaOutputTokensDetails`, and `BetaFallbackCreditUsage` are defined in `@anthropic-ai/sdk`.
49024906
49034907`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.
49044908
from line 4911
49074911* **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](/docs/en/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message) describes. On the result message, `thinking_tokens` reads `0` when the model or provider reports no breakdown.
49084912* **`null` cases**: `output_tokens_details` itself is `null` on assistant messages Claude Code synthesizes, such as API-error messages.
49094913
4914Whether `Usage` carries `fallback_credit` depends on your installed `@anthropic-ai/sdk`, which added it in 0.115.0.
4915
49104916### `CallToolResult`
49114917
49124918MCP 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).
from line 5411
54055411
54065412### `SDKCommandsChangedMessage`
54075413
5408Emitted when the set of available commands changes mid-session, such as when Claude Code discovers skills as the agent enters a subdirectory. The `commands` array is the full updated list, so replace any cached command list with this payload. Calling [`supportedCommands()`](#query-object) after this message returns the same updated list, because the method tracks the latest push; this requires Agent SDK v0.3.216 or later. In earlier SDK versions, `supporte
5414Emitted when the set
No line in this hunk matches that.