Agent SDK reference - TypeScript changedagent-sdk/typescript
Nearest release: v2.1.283, published 2 hours before 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 25 Sep 2026 21:30 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 Sep 2026 21:37 UTC.
Upstream edited
Recorded here
Lines+83added
Lines−2removed
From line
46
where the diff opens
First seen
14 Aug 2026
this site's first read of the page
Recorded edits58to this page, all time
### Import the `/core` entry when you bundle the Agent SDK ### `prewarm()` ### `SpareProcess` #### Members
The whole hunk
from line 46, 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 46
4646* To cross-compile, install the non-matching platform package, for example `npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force`.
4747* On Windows, the binary subpath is `claude.exe`, for example `@anthropic-ai/claude-agent-sdk-win32-x64/claude.exe`.
4848
49### Import the `/core` entry when you bundle the Agent SDK
50
51If your application bundles the Agent SDK together with its own dependencies, import from `@anthropic-ai/claude-agent-sdk/core` instead of the package root. The `/core` entry requires TypeScript Agent SDK v0.3.282 or later, and its types require TypeScript 5.0 or later.
52
53The `/core` entry exports the same `query()`, `startup()`, `tool()`, `createSdkMcpServer()`, and `resolveSettings()` as the root entry, along with the functions that rename, tag, and delete sessions, `AbortError`, the runtime constants, and every type. It adds no names of its own. To keep the code your application loads small, `/core` leaves out some root exports, including `prewarm()`, the `InMemorySessionStore` class, and the helpers that list, read, fork, import, and summarize sessions. If you need one of them, use the root entry instead.
54
55The root entry inlines its own copies of `zod` and `@modelcontextprotocol/sdk`. The `/core` entry imports them from your `node_modules` at the ranges the Agent SDK's `peerDependencies` declare, so a bundle that already includes them doesn't carry a second copy. Import from either the root or `/core` in a given process, not both: they are separate bundles, and loading both gives you two copies of the Agent SDK's classes and state.
56
4957## Functions
5058
5159### `query()`
from line 83
7583
7684### `startup()`
7785
78Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warmquery) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline.
86Pre-warms the CLI subprocess by spawning it and completing the initialize handshake before a prompt is available. The returned [`WarmQuery`](#warmquery) handle accepts a prompt later and writes it to an already-ready process, so the first `query()` call resolves without paying subprocess spawn and initialization cost inline. If you don't know the session's working directory yet, use [`prewarm()`](#prewarm) instead.
7987
8088```typescript theme={null}
8189function startup(params?: {
from line 119
111119}
112120```
113121
122### `prewarm()`
123
124*Alpha.* Starts a Claude Code process as a spare before you know which session it will serve, so you can bind it to a session later with [`claim()`](#spareprocess). Use it in an application that boots before the user picks a folder. Requires TypeScript Agent SDK v0.3.282 or later.
125
126`prewarm()` completes the same initialize handshake as [`startup()`](#startup), with the process waiting in `options.cwd` when you set it and otherwise in a private temporary directory under your Claude Code config directory. The session's working directory, its `SessionStart` hooks, its stdio MCP servers, and its CLAUDE.md and git context wait for the claim. A spare holds roughly 230 to 260 MB of memory while it waits. If your [`spawnClaudeCodeProcess`](#options) runs Claude Code on another machine or in a container, set `options.cwd` to a directory that exists there for the spare to wait in.
127
128```typescript theme={null}
129function prewarm(params?: {
130 options?: Options;
131 initializeTimeoutMs?: number;
132}): Promise<SpareProcess>;
133```
134
135`options` and `initializeTimeoutMs` mean the same as for `startup()`, except that `options.cwd` sets only the directory the spare waits in. The promise resolves with a [`SpareProcess`](#spareprocess) once the process has completed its initialize handshake. `prewarm()` throws if `options` sets `resume`, `continue`, or `forkSession`, because a spare has no session yet. Everything a claim can't set, such as `mcpServers`, `hooks`, `canUseTool`, `settingSources`, `systemPrompt`, and `plugins`, is fixed for the life of the spare, so keep one spare per distinct set of those options and prewarm again when they change.
136
137#### Example
138
139Prewarm on application boot, then claim the spare when the user starts a session:
140
141```typescript theme={null}
142import { prewarm } from "@anthropic-ai/claude-agent-sdk";
143
144// On application boot, before the session's folder is known
145const spare = await prewarm({ options: { maxTurns: 3 } });
146
147// Later, when the user starts a session in a folder
148const claimedQuery = spare.claim({
149 prompt: "What files are here?",
150 options: { cwd: "/path/to/project" },
151});
152
153spare.claimed.catch((error: Error) => {
154 // Unless the message starts with "option_not_applied", the prompt didn't run:
155 // start this session with query() instead
156 console.error("Claim failed:", error.message);
157});
158
159for await (const message of claimedQuery) {
160 console.log(message);
161}
162```
163
114164### `tool()`
115165
116166Creates a type-safe MCP tool definition for use with SDK MCP servers.
from line 703
653703
654704`WarmQuery` implements `AsyncDisposable`, so it can be used with `await using` for automatic cleanup.
655705
706### `SpareProcess`
707
708*Alpha.* Handle returned by [`prewarm()`](#prewarm): a started Claude Code process that isn't bound to a session yet and can be claimed once. Requires TypeScript Agent SDK v0.3.282 or later.
709
710```typescript theme={null}
711interface SpareProcess extends AsyncDisposable {
712 claim(params: {
713 prompt: string | AsyncIterable<SDKUserMessage>;
714 options: ClaimOptions;
715 }): Query;
716 readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;
717 readonly exited: Promise<void>;
718 close(): void;
719}
720```
721
722#### Members
723
724| Member | Description |
725| :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
726| `claim({ prompt, options })` | Bind the spare to a session in `options.cwd` and send its first message. Returns a [`Query`](#query-object) synchronously, as `query()` does. Can only be called once |
727| `claimed` | Resolves with the session's working directory and ID once Claude Code accepts the claim. Rejects when Claude Code refuses the claim, when the process exited or was closed first, and, with a message that starts with `option_not_applied`, when the session is running without the `model` or `maxThinkingTokens` you asked for |
728| `exited` | Settles when the process exits, claimed or not. Replace a spare that exits before you claim it |
729| `close()` | Terminate the process. Before a claim this discards the spare and rejects `claimed` |
730
731`options.cwd` is required. A claim can also set `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, a flag-settings overlay in `settings`, `appendSystemPrompt`, `title`, `agents`, and per-session tokens in `env`.
732
733Claude Code can refuse a claim, for example for a folder that doesn't exist or one whose project settings set `env`, `agent`, or `model`. When `claimed` rejects with a message that starts with `option_not_applied`, the session is running without the `model` or `maxThinkingTokens` you asked for. After any other rejection your prompt hasn't run, so start the session with `query()` instead.
734
656735### `SDKControlInitializeResponse`
657736
658737Return type of `initializationResult()`. Contains session initialization data.
from line 963
884963
885964Pass `readMcpResource()` the server name as `mcpServerStatus()` reports it and a `ui://` URI, such as the `ui.resourceUri` a tool declares in its [`_meta`](#mcpserverstatus). The call rejects for any other URI scheme, for an [SDK MCP server](#createsdkmcpserver) your application hosts itself, and for a server that isn't connected. It's available when the init message's [`capabilities`](#sdksystemmessage) include `mcp_read_resource_v1`.
886965
887Each `contents` entry is one content item as the server sent it. `blob` holds base64 data for a binary item, and `_meta` is the item's own `_meta`, where an MCP Apps server puts the resource's `ui.csp` and `ui.permissions`. The contents are untrusted third-party HTML, so render them in a sandbox.
966Each `contents` entry is one content item as the server sent it, minus any `_meta` key under the `com.anthropic/` prefix, which is reserved for Claude Code. `blob` holds base64 data for a binary item, and `_meta` is the item's own `_meta`, where an MCP Apps server puts the resource's `ui.csp` and `ui.permissions`.
888967
968The contents are untrusted third-party HTML, so render them in a sandbox.
969
889970### `AgentDefinition`
890971
891972Configuration for a subagent defined programmatically.
from line 2421
23402421type InstructionsLoadedHookInput = BaseHookInput & {
23412422 hook_event_name: "InstructionsLoaded";
23422423 file_path: string;
2343 memory_type: "User" | "Project" | "Local" | "Managed";
2344 load_reason:
2345 | "session_start"
2346 | "nested_traversal"
2347 | "path_glob_match"
2348 | "include"
2349 | "compact";
2350 globs?: string[];
2351 trigger_file_path?: string;
2352 parent_file_path?: string;
2353};
2354```
2355
2356#### `DirectoryAddedHookInput`
2357
2358```typescript theme={null}
2359type DirectoryAddedHookInput = BaseHookInput & {
2360 hook_event_name: "DirectoryAdded";
2361 directory: string;
2362 source: "slash_command" | "register_repo_root";
2363};
2364```
2365
2366`directory` is the absolute path of the directory that was added. `source` is `"slash_command"` when `/add-dir` added it and `"register_repo_root"` when the SDK control request did.
2367
2368#### `WorktreeCreateHookInput`
2369
2370```typescript theme={null}
2371type WorktreeCreateHookInput = BaseHookInput & {
2372 hook_event_name: "WorktreeCreate";
2373 name: string;
2374};
2375```
2376
2377#### `WorktreeRemoveHookInput`
2378
2379```typescript theme={null}
2380type WorktreeRemoveHookInput = BaseHookInput & {
2381 hook_event_name: "WorktreeRemove";
2382 worktree_path: string;
2383};
2384```
2385
2386#### `CwdChangedHookInput`
2387
2388```typescript theme={null}
2389type CwdChangedHookInput = BaseHookInput & {
2390 hook_event_name: "CwdChanged";
2391 old_cwd: string;
2392 new_cwd: string;
2393};
2394```
2395
2396#### `FileChangedHookInput`
2397
2398```typescript theme={null}
2399type FileChangedHookInput = BaseHookInput & {
2400 hook_event_name: "FileChanged";
2401 file_path: string;
2402 event: "change" | "add" | "unlink";
2403};
2404```
2405
2406#### `MessageDisplayHookInput`
2407
2408```typescript theme={null}
2409type MessageDisplayHookInput = BaseHookInput & {
2410 hook_event_name: "MessageDisplay";
2411 turn_id: string;
2412 message_id: string;
2413 index: number;
2414 final: boolean;
2415 delta: string;
2416};
2417```
2418
2419### `HookJSONOutput`
2420
2421Hook return value.
2422
2423```typescript theme={null}
2424type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
2425```
2426
2427#### `AsyncHookJSONOutput`
2428
2429```typescript theme={null}
2430type AsyncHookJSONOutput = {
2431 async: true;
2432 asyncTimeout?: number;
2433};
2434```
2435
2436#### `SyncHookJSONOutput`
2437
2438```typescript theme={null}
2439type SyncHookJSONOutput = {
2440 continue?: boolean;
2441 suppressOutput?: boolean;
2442 stopReason?: string;
2443 decision?: "approve" | "block";
2444 systemMessage?: string;
2445 /**
2446 * A terminal escape sequence (e.g. OSC 9 / OSC 777 desktop-notification)
2447 * for Claude Code to emit on your behalf. Only notification/title OSCs
2448 * (0, 1, 2, 9, 99, 777) and BEL are permitted; a value containing
2449 * anything else is ignored as a whole. Only the interactive CLI emits
2450 * it; the SDK ignores the field.
2451 */
2452 terminalSequence?: string;
2453 reason?: string;
2454 hookSpecificOutput?:
2455 | {
2456 hookEventName: "PreToolUse";
2457 permissionDecision?: "allow" | "deny" | "ask" | "defer";
2458 permissionDecisionReason?: string;
2459 updatedInput?: Record<string, unknown>;
2460 additionalContext?: string;
2461 }
2462 | {
2463 hookEventName: "UserPromptSubmit";
2464 additionalContext?: string;
2465 sessionTitle?: string;
2466 /** When decision is "block", omit the original prompt from the block message. */
2467 suppressOriginalPrompt?: boolean;
2468 }
2469 | {
2470 hookEventName: "UserPromptExpansion";
2471 additionalContext?: string;
2472 }
2473 | {
2474 hookEventName: "SessionStart";
2475 additionalContext?: string;
2476 initialUserMessage?: string;
2477 sessionTitle?: string;
2478 watchPaths?: string[];
2479 /**
2480 * Re-scan skill and command directories after SessionStart hooks
2481 * complete, so skills installed by the hook are available in the
2482 * same session.
2483 */
2484 reloadSkills?: boolean;
2485 }
2486 | {
2487 hookEventName: "Setup";
2488 additionalContext?: string;
2489 }
2490 | {
2491 hookEventName: "PreModelSwitch";
2492 /**
2493 * Same contract as PreToolUse: "allow" proceeds, "deny" cancels
2494 * the switch, "ask" asks the user to confirm. Only /model in an
2495 * interactive session shows that prompt; every other surface,
2496 * set_model requests included, treats "ask" as a refusal.
2497 */
2498 permissionDecision?: "allow" | "deny" | "ask";
2499 permissionDecisionReason?: string;
2500 }
2501 | {
2502 hookEventName: "PostModelSwitch";
2503 /** Reaches the model with the next request the new model serves. */
2504 additionalContext?: string;
2505 }
2506 | {
2507 hookEventName: "SubagentStart";
2508 additionalContext?: string;
2509 }
2510 | {
2511 hookEventName: "PostToolUse";
2512 additionalContext?: string;
2513 /**
2514 * Short note about this tool call's result for the auto mode
2515 * permission classifier. Capped at 2000 characters, shared across
2516 * all hooks that respond to the same call; honored on synchronous
2517 * hook responses only. Don't copy untrusted tool output into it.
2518 */
2519 classifierContext?: string;
2520 updatedToolOutput?: unknown;
2521 /** @deprecated Use `updatedToolOutput`, which works for all tools. */
2522 updatedMCPToolOutput?: unknown;
2523 }
2524 | {
2525 hookEventName: "PostToolUseFailure";
2526 additionalContext?: string;
2527 }
2528 | {
2529 hookEventName: "PostToolBatch";
2530 additionalContext?: string;
2531 }
2532 | {
2533 hookEventName: "Stop";
2534 additionalContext?: string;
2535 }
2536 | {
2537 hookEventName: "SubagentStop";
2538 additionalContext?: string;
2539 }
2540 | {
2541 hookEventName: "PermissionDenied";
2542 retry?: boolean;
2543 }
2544 | {
2545 hookEventName: "Notification";
2546 additionalContext?: string;
2547 }
2548 | {
2549 hookEventName: "PermissionRequest";
2550 decision:
2551 | {
2552 behavior: "allow";
2553 updatedInput?: Record<string, unknown>;
2554 updatedPermissions?: PermissionUpdate[];
2555 }
2556 | {
2557 behavior: "deny";
2558 message?: string;
2559 interrupt?: boolean;
2560 };
2561 }
2562 | {
2563 hookEventName: "Elicitation";
2564 action?: "accept" | "decline" | "cancel";
2565 content?: Record<string, unknown>;
2566 }
2567 | {
2568 hookEventName: "ElicitationResult";
2569 action?: "accept" | "decline" | "cancel";
2570 content?: Record<string, unknown>;
2571 }
2572 | {
2573 hookEventName: "CwdChanged";
2574 watchPaths?: string[];
2575 }
2576 | {
2577 hookEventName: "FileChanged";
2578 watchPaths?: string[];
2579 }
2580 | {
2581 hookEventName: "WorktreeCreate";
2582 worktreePath: string;
2583 }
2584 | {
2585 hookEventName: "MessageDisplay";
2586 /** Text displayed in place of the delta. Omit (or return the delta unchanged) to display the original. */
2587 displayContent?: string;
2588 };
2589};
2590```
2591
2592## Tool Input Types
2593
2594Documentation of input schemas for all built-in Claude Code tools. These types are exported from `@anthropic-ai/claude-agent-sdk` and can be used for type-safe tool interactions.
2595
2596### `ToolInputSchemas`
2597
2598Union of tool input types exported from `@anthropic-ai/claude-agent-sdk`; members include:
2599
2600```typescript theme={null}
2601type ToolInputSchemas =
2602 | AgentInput
2603 | ArtifactInput
2604 | AskUserQuestionInput
2605 | BashInput
2606 | CronCreateInput
2607 | CronDeleteInput
2608 | CronListInput
2609 | EnterPlanModeInput
2610 | EnterWorktreeInput
2611 | ExitPlanModeInput
2612 | ExitWorktreeInput
2613 | FileEditInput
2614 | FileReadInput
2615 | FileWriteIn
2424 memory_type: "Us
No line in this hunk matches that.