Agent SDK reference - TypeScript changedagent-sdk/typescript
Upstream edited this page at 10 Oct 2026 17:34 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 10 Oct 2026 17:37 UTC.
Upstream edited
Recorded here
Lines+28added
Lines−0removed
From line
396
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits113to this page, all time
### `forkSession()`
The whole hunk
from line 396, 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 396
396396| `tag` | `string \| null` | required | Tag string, or `null` to clear |
397397| `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories |
398398
399### `forkSession()`
400
401Copies a session's transcript into a new session so you can take the conversation in another direction while the original stays unchanged. To branch from an earlier point in the conversation, pass `upToMessageId`.
402
403```typescript theme={null}
404function forkSession(
405 sessionId: string,
406 options?: ForkSessionOptions
407): Promise<ForkSessionResult>;
408```
409
410#### Parameters
411
412| Parameter | Type | Default | Description |
413| :- | :- | :- | :- |
414| `sessionId` | `string` | required | UUID of the session to fork |
415| `options.dir` | `string` | `undefined` | Project directory path. When omitted, searches all project directories |
416| `options.upToMessageId` | `string` | `undefined` | Copy the transcript up to and including the message with this `uuid`: a value from [`getSessionMessages()`](#getsessionmessages), or a `uuid` you set on a streamed [`SDKUserMessage`](#sdkusermessage). When omitted, copies the whole transcript |
417| `options.title` | `string` | `undefined` | Title for the fork. When omitted, the SDK derives one from the original session, followed by `(fork)` |
418
419Returns `{ sessionId }`, the new session's UUID. Pass it as [`resume`](#options) to continue the fork. The fork doesn't include the original session's [file checkpoints](/docs/en/agent-sdk/file-checkpointing), so you can't rewind it to a checkpoint captured before the fork.
420
421`forkSession()` throws when:
422
423* `sessionId` is not a UUID
424* the session cannot be found, or has no messages
425* `upToMessageId` matches no message in the transcript
426
399427### `resolveSettings()`
400428
401429Resolves the effective Claude Code settings for a given directory using the same merge engine as the CLI, without spawning the Claude CLI. Use it to inspect what configuration a `query()` call would see before invoking one.
from line 5320
52925320 exit_code?: number;
52935321 outcome: "success" | "error" | "cancelled";
52945322 uuid: UUID;
5295 session_id: string;
5296};
5297```
5298
5299### `SDKToolProgressMessage`
5300
5301Emitted periodically while a tool is executing to indicate progress.
5302
5303```typescript theme={null}
5304type SDKToolProgressMessage = {
5305 type: "tool_progress";
5306 tool_use_id: string;
5307 tool_name: string;
5308 parent_tool_use_id: string | null;
5309 elapsed_time_seconds: number;
5310 task_id?: string;
5311 heartbeat?: boolean;
5312 subagent_type?: string;
5313 subagent_retry?: {
5314 agent_id: string;
5315 attempt: number;
5316 max_retries: number;
5317 retry_delay_ms: number;
5318 error_status: number | null;
5319 error_category: string;
5320 };
5321 uuid: UUID;
5322 session_id: string;
5323};
5324```
5325
5326While 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 tool calls inside a subagent. The `heartbeat` field requires Agent SDK v0.3.214 or later. Before v2.1.257, Claude Code didn't emit heartbeats for a foreground Agent tool call either.
5327
5328On `tool_progress` messages for the Agent tool other than heartbeats, `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.
5329
5330To render a retry indicator from `subagent_retry`:
5331
5332* Track the indicator by `pare
5323 ses
No line in this hunk matches that.