TypeScript SDK reference

This is the full reference for the @anthropic-ai/claude-agent-sdk package. It runs from installation through functions, the Options object and the Query handle, then message types, hooks, built-in tool schemas, permission types, supporting types and sandbox settings. Guides that explain the ideas behind each area are linked as you go.

Version notes matter a lot in this SDK. The SDK version tracks the bundled Claude Code version: SDK v0.3.191 ships Claude Code v2.1.191. So when a feature says "Claude Code v2.1.N", you need SDK v0.3.N or later unless you point at your own binary.

Installing

npm install @anthropic-ai/claude-agent-sdk

A native Claude Code binary for your platform comes in as an optional dependency, such as @anthropic-ai/claude-agent-sdk-darwin-arm64, so most installs need nothing else.

• If your package manager skips optional dependencies, you get Native CLI binary for <platform>-<arch> not found. Install Claude Code separately and set pathToClaudeCodeExecutable.
• Package managers that ignore npm's libc field (Yarn 1.x, for example) install both the glibc and musl Linux packages. From SDK v0.2.141 the right one is still chosen. In a container image you can delete the unused one, for example rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl on a glibc x64 runtime.

Single-file executables with Bun

bun build --compile breaks binary resolution, because require.resolve cannot see into the compiled executable's $bunfs filesystem. From SDK v0.3.144, embed the binary as a file asset and extract it at start-up:

import cliAsset from "@anthropic-ai/claude-agent-sdk-linux-x64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cli = extractFromBunfs(cliAsset);   // copies to a per-user temp dir; a no-op outside a compiled binary

for await (const m of query({ prompt: "List the services in docker-compose.yml", options: { pathToClaudeCodeExecutable: cli } })) {
  if (m.type === "result") console.log(m.subtype);
}

Each executable embeds one platform's binary, so match the import to your --target. To cross-compile, force-install the other platform package (npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force). On Windows the subpath is claude.exe.

The /core entry point for bundlers

If you bundle the SDK with your own dependencies, import from @anthropic-ai/claude-agent-sdk/core (SDK v0.3.282+, TypeScript 5.0+ for its types).

• It exports query(), startup(), tool(), createSdkMcpServer(), resolveSettings(), the rename, tag and delete session helpers, AbortError, runtime constants and every type.
• It omits prewarm(), InMemorySessionStore, and the helpers that list, read, fork, import and summarise sessions. Use the root entry if you need those.
• The root entry inlines its own zod and @modelcontextprotocol/sdk; /core imports them from your node_modules at the peer dependency ranges, avoiding duplicate copies.
• Use one entry per process. Loading both gives you two copies of the SDK's classes and state.

Functions

query()

function query(params: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

The main entry point. Pass a string for a one-shot run, or an async iterable of SDKUserMessage for streaming input. Returns a Query, which is an async generator of SDKMessage with extra control methods.

startup()

Spawns the CLI and completes its initialise handshake before you have a prompt, so the first real query starts instantly.

function startup(params?: { options?: Options; initializeTimeoutMs?: number }): Promise<WarmQuery>;

initializeTimeoutMs defaults to 60000; the promise rejects if the handshake takes longer.

import { startup } from "@anthropic-ai/claude-agent-sdk";

const warm = await startup({ options: { cwd: "/srv/app", maxTurns: 10 } });   // at boot

// ...later, on the first request:
for await (const m of warm.query("Summarise today's error log")) { /* ... */ }

If you will not know the working directory until later, use prewarm().

prewarm()

Alpha, SDK v0.3.282+. Starts a spare process that is not yet tied to a session, which you later bind with claim(). Useful for apps that boot before the user picks a folder.

function prewarm(params?: { options?: Options; initializeTimeoutMs?: number }): Promise<SpareProcess>;

• The spare waits in options.cwd if set, otherwise in a private temp directory under your Claude Code config directory. If spawnClaudeCodeProcess runs Claude Code elsewhere, set options.cwd to a path that exists there.
• The working directory, SessionStart hooks, stdio MCP servers, CLAUDE.md and git context all wait for the claim.
• A spare uses roughly 230 to 260 MB while waiting.
• prewarm() throws if options sets resume, continue or forkSession.
• Anything a claim cannot change (mcpServers, hooks, canUseTool, settingSources, systemPrompt, plugins and so on) is fixed for the spare's life, so keep one spare per distinct configuration.

import { prewarm } from "@anthropic-ai/claude-agent-sdk";

const spare = await prewarm({ options: { maxTurns: 20 } });

const q = spare.claim({ prompt: "What does this repo do?", options: { cwd: chosenFolder } });
spare.claimed.catch(err => {
  if (!String(err.message).startsWith("option_not_applied")) startFreshWithQuery();  // prompt never ran
});
try {
  for await (const m of q) { /* ... */ }
} catch (err) { /* a refused claim throws after yielding its error result */ }

tool()

Defines a type-safe tool for an in-process MCP server, using a Zod shape (Zod 3 or 4).

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
): SdkMcpToolDefinition<Schema>;

ToolAnnotations (from @modelcontextprotocol/sdk/types.js; hints only, never a security control):

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const lookupPostcode = tool(
  "lookup_postcode",
  "Return the local authority and ward for a UK postcode",
  { postcode: z.string().regex(/^[A-Z0-9 ]{5,8}$/i) },
  async ({ postcode }) => {
    const info = await geo.lookup(postcode);
    return { content: [{ type: "text", text: `${info.authority}, ${info.ward}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

createSdkMcpServer()

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  instructions?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
  alwaysLoad?: boolean;
  timeout?: number;
}): McpSdkServerConfigWithInstance;

See custom tools for a full walkthrough.

Session helpers

SDKSessionInfo

SessionMessage: type (user or assistant), uuid, session_id, message (raw payload), parent_tool_use_id (the Agent or Skill call that started a subagent, else null), parent_agent_id (the spawning subagent's ID for nested subagents; Claude Code v2.1.202+).

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [last] = await listSessions({ dir: "/srv/app", limit: 1 });
if (last) {
  for (const m of await getSessionMessages(last.sessionId, { dir: "/srv/app", limit: 50 })) {
    console.log(m.type, m.uuid);
  }
}

resolveSettings()

Alpha. Computes the effective settings for a directory with the CLI's own merge engine, without spawning anything.

function resolveSettings(options?: {
  cwd?: string;                     // default process.cwd()
  settingSources?: SettingSource[]; // default: all
  managedSettings?: Settings;
  serverManagedSettings?: Settings;
}): Promise<ResolvedSettings>;

It returns effective (the merged settings), provenance (which source supplied each top-level key) and sources (each source's raw settings, lowest precedence first, with optional path and policyOrigin).

It differs from a live session in three ways: it reads MDM sources but does not run a policyHelper; it only includes server-managed settings you pass in; and it reports permissions.defaultMode verbatim from every tier, including auto and bypassPermissions from project or local files that a live session would ignore.

const { effective, provenance } = await resolveSettings({ cwd: "/srv/app" });
console.log(effective.cleanupPeriodDays, "from", provenance.cleanupPeriodDays?.source);

Options

Grouped by purpose. All are optional.

Tools and permissions

Prompt, model and reasoning

systemPrompt accepts:

• a string (custom prompt);
• a string[] with SYSTEM_PROMPT_DYNAMIC_BOUNDARY between static and per-request parts;
• { type: 'custom'; prompt: string | string[]; snapshot?: boolean };
• { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }.

The custom object form and snapshot need SDK v0.3.257. Details in modifying system prompts. Note that outputStyle is not an option: set it inside settings.

Limits

Sessions

Process and environment

Configuration sources and extensions

Stream shape and extras

Slow or stalled APIs

Pass these in env (remember to spread process.env):

With includePartialMessages, a gateway that keeps a response alive with pings yields ping stream events; treat them as liveness.

The Query object

query() returns this. It is an AsyncGenerator<SDKMessage, void> with control methods. Several only work in streaming input mode.

applyFlagSettings()

Changes settings on a running session (TypeScript only; streaming input only). It writes to the flag-settings layer over whatever settings set at start-up.

Rules:

• Successive calls shallow-merge top-level keys, so a second permissions object replaces the first entirely.
• Pass null to clear a key; it falls back to the settings option and then lower sources. undefined does nothing (JSON drops it).
• Clearing model resets to Claude Code's default even if a settings file sets one.
• effortLevel: null returns to the model's default effort; agent: null runs with no agent from next turn (and drops any model the agent applied); ultracode: null turns it off without changing effort.
• effortLevel also accepts "ultracode" at runtime (v2.1.203+), but the type does not declare it, so in TypeScript pass { ultracode: true, effortLevel: "xhigh" } instead. Before v2.1.284, ultracode alone also set xhigh.

const q = query({ prompt: userTurns() });
await q.applyFlagSettings({ permissions: { deny: ["WebFetch", "Bash(curl *)"] } });  // after reading untrusted input
await q.applyFlagSettings({ model: "claude-opus-4-6" });
await q.applyFlagSettings({ model: null });   // back to the default

updateSettings()

Persists exactly one allowlisted string key:

• "localSettings" accepts outputStyle, merged into .claude/settings.local.json; applies on the next request.
• "userSettings" accepts effortLevel, saved as the default for the current model under modelSettings in your user settings. max writes nothing (session-only). The running session's effort is unchanged; use applyFlagSettings() for that. Needs SDK v0.3.277.

It rejects other keys, remote transports, and sources excluded by settingSources. Deleting keys is not supported.

toggleMcpServer() version notes

Disabling a stdio, SSE or HTTP server added with setMcpServers() removes its tools from Claude Code v2.1.285. Disabling an in-process server (from createSdkMcpServer()) disconnects it from v2.1.286, and its running calls fail immediately with error results.

WarmQuery

Returned by startup(). Implements AsyncDisposable, so await using works.

SpareProcess

Alpha. Returned by prewarm(). Implements AsyncDisposable.

A claim can set additionalDirectories, model, permissionMode, maxThinkingTokens, a flag-settings overlay in settings, appendSystemPrompt, title, agents and per-session tokens in env. Claims are refused for a folder that does not exist or whose project settings set env, agent or model; the prompt then gets an error result starting not_claimed and the query throws. On any rejection other than option_not_applied, the prompt did not run.

Control responses

SDKControlInitializeResponse

From initializationResult() and reinitialize():

The response wrapper (not the payload) also carries pending_permission_requests: complete control_request messages this process issued and has not resolved. The SDK re-dispatches them to canUseTool, so handle repeated request IDs idempotently. Always present from v2.1.268.

SDKControlInterruptResponse

type SDKControlInterruptResponse = { still_queued: string[]; cancelled?: string[] };

still_queued lists UUIDs of user messages pending when the interrupt arrived (including ones already taken for the next turn). After the first turn has started, they will still be processed, possibly merged into one turn, so do not resend them. If you interrupt before the first turn starts, that turn aborts and its messages get no reply.

Caveats: only messages with a UUID appear; only main-thread messages; and you may see UUIDs you never sent (scheduled task triggers, for example), which you should ignore.

Clients driving the control protocol directly can send cancel_queued: true (advertised as interrupt_cancel_queued_v1, v2.1.219+) to cancel those messages; they then appear under cancelled. interrupt() itself never sends it. The receipt is a snapshot taken when the interrupt is processed and arrives before the interrupted turn's result, so read it rather than inspecting the queue afterwards.

SDKControlGetContextUsageResponse

From getContextUsage(). The default detail: 'full' counts each category with token-counting requests (not in the stream, not billed on the Anthropic API). detail: 'summary' uses the last response and local estimates instead: no extra requests, approximate numbers.

deferredBuiltinTools, systemTools and systemPromptSections are declared but left unset. Sending /context as a prompt instead attaches an SDKContextUsage to the reply (SDK v0.3.232+).

Other control responses

Configuration types

AgentDefinition

type AgentDefinition = {
  description: string;
  prompt: string;
  tools?: string[];
  disallowedTools?: string[];
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  background?: boolean;
  omitClaudeMd?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>, where the latter is any of stdio, SSE, HTTP or SDK config. See subagents.

SettingSource and precedence

Omitting settingSources loads all three, like the CLI. Include 'project' to load CLAUDE.md. Precedence, highest first: local, project, user; programmatic options (agents, allowedTools, settings) beat all three; managed policy beats programmatic options. Claude Code features in the SDK lists inputs that load regardless.

PermissionMode

"default" | "acceptEdits" | "bypassPermissions" | "plan" | "dontAsk" | "auto". Behaviour is described in permissions.

CanUseTool

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    mcpServer?: { name: string; source: string };
    decisionReason?: string;
    defaultToNo?: boolean;
    suppressAlwaysAllowRule?: boolean;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

Return a PermissionResult normally. Return null only if your app already sent the control_response for this requestId through its own channel; otherwise the call blocks forever, since prompts never time out. requestId and null need Claude Code v2.1.199.

type PermissionResult =
  | { behavior: "allow"; updatedInput?: Record<string, unknown>; updatedPermissions?: PermissionUpdate[]; toolUseID?: string }
  | { behavior: "deny"; message: string; interrupt?: boolean; toolUseID?: string };

ToolConfig

{ askUserQuestion?: { previewFormat?: "markdown" | "html" } }. Setting previewFormat opts in to the preview field on AskUserQuestion options; without it Claude sends no previews. See user input.

MCP server configs

McpServerConfig is the union of the first four.

SdkPluginConfig

{ type: "local"; path: string; skipMcpDiscovery?: boolean }. skipMcpDiscovery loads the plugin's skills, hooks, agents and commands but ignores its .mcp.json and manifest mcpServers, for when your app manages those connections.

Messages

The SDKMessage union

Everything the query yields is one of these. Switch on type, and for type: "system" on subtype.

The union also includes SDKNotificationMessage, SDKMemoryRecallMessage, SDKElicitationCompleteMessage, SDKAPIRetryMessage and SDKMirrorErrorMessage (the mirror_error system message emitted when a session store batch cannot be delivered).

SDKAssistantMessage

SDKAssistantMessageError values: authentication_failed, oauth_org_not_allowed, account_on_hold, billing_error, rate_limit (429 against your quota), overloaded (529, server at capacity), invalid_request, model_not_found (model missing or not available to you), server_error, max_output_tokens, cloud_credential_error (no usable AWS or Google Cloud credentials on the machine; usually an expired sign-in; SDK v0.3.267+) and unknown.

Per-message usage.output_tokens is a placeholder from message_start; read real output counts from the result. One API response can produce several assistant messages sharing a message.id.

SDKUserMessage

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  message: MessageParam;
  pasted_content?: MessageParam["content"][];
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  priority?: "now" | "next" | "later";
  origin?: SDKMessageOrigin;
  inline_pastes?: string[];
};

Fields you set when sending:

priority:

• 'next' or absent: read in the same turn once current tool calls finish; starts the next turn if the turn ends first.
• 'later': held until the turn ends, then sent as a new turn.
• 'now' with origin: { kind: "human" }: from v2.1.286, movable work (shell commands, subagents, MCP calls; WebFetch and WebSearch from v2.1.287) moves to the background and Claude reads the message in the same turn. Otherwise the turn is interrupted.
• 'now' without that origin: interrupt, then read.

const redirect: SDKUserMessage = {
  type: "user",
  message: { role: "user", content: "Stop the migration and just report what is done" },
  parent_tool_use_id: null,
  priority: "now",
  origin: { kind: "human" }
};

Reading tool_use_result

On a user message carrying a tool_result, tool_use_result is the tool's structured output (see tool output types), typed unknown. Special cases:

• Agent: an AgentOutput. Render from it, not from the text. A completed result's content holds the report, or a short note if the subagent reported through a SubagentHandback call. In auto mode from v2.1.271 every non-fork subagent reports that way, and Claude receives the report as a separate message.
• Detached WebFetch or WebSearch: when moved to the background to deliver a 'now' message, tool_use_result is { detachedToolCall: true } and no second result follows for that tool_use_id. Mark the row as backgrounded (v2.1.287+).
• MCP resource_link blocks: { resourceLinks: SDKMcpResourceLink[] }. Omitted when none and on subagent results; at most 50 links or 64 KiB (SDK v0.3.257+).
• MCP structuredContent: tool_use_result.structuredContent holds it and .content holds the McpOutput. Not on subagent results.
• Oversized structuredContent: above 1,048,576 characters of JSON it is dropped and structuredContentOmitted: true is set instead; in-process SDK servers and tools with an MCP Apps _meta.ui resource are exempt (v2.1.287+).

SDKUserMessageReplay

Like SDKUserMessage but with a required uuid and session_id, and isReplay: true. Turns injected from outside (origin peer or channel) always appear as replays, whether they arrived mid-turn or started a turn while idle (from v2.1.207).

SDKResultMessage

Two arms: subtype: "success" and the error subtypes error_max_turns, error_during_execution, error_max_budget_usd, error_max_structured_output_retries.

Fields on both arms:

Success only: result (final text), api_error_status, ttft_ms (to first complete assistant message), ttft_stream_ms (to message_start), local_command (the command a turn ran without entering the loop, lowercased with underscores, e.g. reload_plugins; mcp for MCP commands and /mcp; custom for your own; SDK v0.3.268+), request_sent_wall_ms (epoch ms the API request went out, alongside user_message_uuid), first_content_frame_ms (to the first content block event, thinking included; SDK v0.3.260+), structured_output, deferred_tool_use ({ id, name, input } when a hook returned defer), and the first_stream_post_* / first_text_post_* upload timings that only claude.ai-streamed sessions record.

Error only: errors (strings) and startup_failure_reason.

terminal_reason values: completed, max_turns, tool_deferred, aborted_streaming, aborted_tools, hook_stopped, stop_hook_prevented, background_requested, blocking_limit, rapid_refill_breaker, prompt_too_long, image_error, model_error, api_error, malformed_tool_use_exhausted, budget_exhausted, structured_output_retry_exhausted, tool_deferred_unavailable, turn_setup_failed.

fast_mode_disabled_reason codes (v2.1.219+; also on the init message and initialise response):

During a post-rate-limit cooldown you get fast_mode_state: "cooldown" with no reason.

Origins on results. Injected follow-ups (finished background tasks, routine triggers, verified messages from your other sessions) carry origin.kind === "task-notification". Declared scheduled runs do too, so do not suppress on kind alone. When several task completions are answered in one turn, each still gets a result, with all but the last empty and num_turns: 0. Results before any user turn (start-up errors) have no origin.

startup_failure_reason

On the error_during_execution result written before exit on a known start-up failure (SDK v0.3.274+), with zeroed totals and errors matching stderr. By default only worktree resume failures and a refused continue of a background-held session produce this result; set CLAUDE_CODE_STARTUP_FAILURE_RESULTS=1 to get it for every reason.

Matching replies to your messages

Set a uuid on each SDKUserMessage and Claude Code echoes it back.

• user_message_uuid names the message a turn is answering. If several messages were merged into one turn, it names the last; user_message_uuids (SDK v0.3.259+, up to 64 entries, always including user_message_uuid) lists all of them, plus any regular message picked up mid-turn.
• For a synthetic message (isSynthetic: true), the turn answers it until a regular message is picked up between tool calls (echo needs SDK v0.3.265).
• For a turn re-run under CLAUDE_CODE_RESUME_INTERRUPTED_TURN, the re-run answers the interrupted turn's last regular message (SDK v0.3.268) and carries resume_reason (a token such as interrupted_turn) on its result and on reply frames that carry user_message_uuid.
• Other self-generated turns answer nothing of yours until they pick up a message.

Where the echo appears: every result of a turn that answered one of your messages (complete from SDK v0.3.265); the turn's first assistant message and, with partial messages on, the first non-ping stream event (SDK v0.3.246+), again whenever the answered message changes; and every thinking_tokens frame (SDK v0.3.260+). It never appears on other reply frames, subagent frames, turns that answer nothing of yours, messages you sent without a uuid, or crash results.

SDKSystemMessage (init)

capabilities values: interrupt_receipt_v1, interrupt_cancel_queued_v1 (v2.1.219+), sdk_mcp_manifests and sdk_mcp_tools_list_changed (v2.1.286+; the latter means a tools/list_changed from an SDK MCP server re-lists its tools), plus mcp_read_resource_v1 and mcp_tool_ui_meta_v1 for MCP Apps. Treat it as an open set and feature-detect.

Other common messages

SDKPermissionDeniedMessage

tool_name, tool_use_id, agent_id?, decision_reason_type? (rule, mode, classifier, asyncAgent...), decision_reason?, message (what the model was told).

What it reports depends on configuration:

Denials on the PreToolUse hook path are never reported here, and emission is best-effort. Use the result's permission_denials as the record.

SDKContextUsage

Attached to the reply to a /context prompt. Snake_case, without display fields.

The type grows additively; ignore unknown fields.

SDKMessageOrigin

Where a user-role message came from. Forwarded onto the result.

Task-notification subkinds (v2.1.213+), set when Anthropic servers verified the source or when you declare a scheduled run:

• scheduled-trigger: a routine fired (schedule, API, GitHub or Run now), or your declared scheduled run. Framed to the model as its assigned task.
• peer-send-message: a verified send_message from another cloud session in the same private group (v2.1.224+). Not the cross-session SendMessage tool, whose messages are kind: "peer".

fireReason is a short token such as scheduled, manual, retry, catch_up or api (SDK v0.3.280+).

Declaring your own scheduled runs (SDK v0.3.280+): start the session with CLAUDE_CODE_HOST_SCHEDULED_RUN=1 in env, then send the run's message with origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" } and without isSynthetic. Ignored without that variable, or if the environment has CLAUDECODE or CLAUDE_CODE_CHILD_SESSION. fireReason must be 1 to 32 lowercase letters or underscores.

Peer fields:

Background task messages

A task is a backgrounded Bash command, a Monitor watch, a subagent or a remote agent.

Notes:

• ambient: true marks tasks that are not part of the session's work (Claude Code's own, and live-update watchers). Exclude them from activity indicators (SDK v0.3.247+).
• Resumed subagents always report is_backgrounded: true. A foreground task that later moves to the background reports it via task_updated.
• summary on progress is model-generated for subagents only with agentProgressSummaries; for backgrounded MCP calls it is the server's own progress.
• Backgrounded MCP calls deliver their real result in the notification, with resource_links (SDK v0.3.257+). Match by tool_use_id.
• Every task notification sent to the model carries a "no human input" notice, except scheduled-trigger deliveries. Detect task-notification turns by origin.kind, not the notice text.
• For background_tasks_changed, replace your cached set with each payload; nothing is sent at start-up, so reset to empty when the process (re)starts. A repeated initialize (such as reinitialize()) is followed by a snapshot from SDK v0.3.239.

Progress and state messages

Hook lifecycle messages are delivered live, including during start-up hooks (they were batched from v2.1.169 to v2.1.203).

SDKRateLimitEvent

rate_limit_info: status (allowed, allowed_warning, rejected), resetsAt?, utilization?, and for exhausted claude.ai subscriptions errorCode: "credits_required" with canUserPurchaseCredits and hasChargeableSavedPaymentMethod (v2.1.181+).

SDKConversationResetMessage

new_conversation_id, uuid, session_id, and from v2.1.281 trigger? (clear, plan_mode_exit, fresh_session, onboarding), user_message_uuid? and timestamp?. In query() only /clear and its aliases produce it. Start an empty transcript under the new ID and drop any cached title, whatever the trigger. Declared in typings from v2.1.203.

AbortError

class AbortError extends Error {}. The only typed error class. Other failures (process exits, launch failures) reject iteration with untyped errors; see troubleshooting.

Hooks

Guide: hooks in the SDK.

type HookCallback = (input: HookInput, toolUseID: string | undefined, options: { signal: AbortSignal }) => Promise<HookJSONOutput>;

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number;   // seconds, for every hook in this matcher
}

Base input

Every input has session_id, transcript_path, cwd, and optionally prompt_id (UUID of the prompt being processed, matching OpenTelemetry prompt.id; v2.1.196+), permission_mode, effort: { level }, agent_id and agent_type.

Inputs by event

BackgroundTaskSummary is { id, type, status, description, command?, agent_type?, server?, tool?, name? }; SessionCronSummary is { id, schedule, recurring, prompt }. mcp_server (an McpServerProvenance) needs SDK v0.3.274.

Outputs

HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput. The async form is { async: true; asyncTimeout?: number }.

Top-level sync fields: continue, suppressOutput, stopReason, decision (approve or block), systemMessage, reason, terminalSequence (an allowed OSC or BEL sequence for the interactive CLI; the SDK ignores it) and hookSpecificOutput.

Tool input types

Exported from @anthropic-ai/claude-agent-sdk/sdk-tools as the union ToolInputSchemas (and ToolOutputSchemas for outputs).

Files and search

For PDFs, the Read tool_result carries a summary text block plus a document block (pdf output) or one block per page (parts output). Before SDK v0.3.242 PDF contents came in a separate user message.

Shell and background work

TaskOutput was removed in v2.1.277; deny rules naming it are silently ignored. The experimental REPL tool was removed in v2.1.275.

Web

Agents, workflows and planning

Tasks

On by default only for Claude 3.x, Opus 4 to 4.7, Sonnet 4 to 4.6 and Haiku 4.5 (Claude Code v2.1.268+); opt in elsewhere as in todo tracking.

Scheduling and notifications

MCP and claude.ai

Tool output types

Files and search

structuredPatch hunks have oldStart, oldLines, newStart, newLines, lines. gitDiff has filename, status (modified, added), additions, deletions, changes, patch, repository?.

Shell

BashOutput: stdout (stdout and stderr interleaved), stderr (the tool's own notices), interrupted, plus optional rawOutputPath, isImage, backgroundTaskId, backgroundedByUser, timedOutAfterMs and backgroundCwdHint (v2.1.210+), backgroundEndsWithFinalResponse (true when a foreground subagent owns the command, so it ends with that subagent; v2.1.227+), dangerouslyDisableSandbox, returnCodeInterpretation, noOutputExpected, structuredContent, persistedOutputPath, persistedOutputSize, staleReadFileStateHint, ghRateLimitHint, and gitOperation:

MonitorOutput: taskId (use with TaskStop), timeoutMs, persistent?. TaskStopOutput: message, task_id, task_type, command?.

Web

Agents and workflows

AgentOutput, discriminated on status:

• completed: agentId, agentType?, content (text blocks with citations?), resolvedModel? (v2.1.174+), modelsUsed? (only after a mid-run swap; v2.1.212+), totalToolUseCount, totalDurationMs, totalTokens, usage, toolStats? (readCount, searchCount, bashCount, editFileCount, linesAdded, linesRemoved, otherToolCount, frameCount?), prompt, worktreePath?, worktreeBranch?.
• async_launched: isAsync?, agentId, description, resolvedModel? (model when backgrounded), modelsUsed?, prompt, outputFile, canReadOutputFile?.
• remote_launched: taskId, sessionUrl, description, prompt, outputFile.

usage and totalTokens come from the subagent's final request only. usage includes service_tier, cache_creation, server_tool_use, inference_geo, speed, iterations, output_tokens_details (SDK v0.3.228+; guard every level, e.g. usage.output_tokens_details?.thinking_tokens ?? 0) and fallback_credit (SDK v0.3.285+). The type was narrower before v2.1.207, so older results may lack optional fields.

WorkflowOutput returns as soon as the run is accepted; the result arrives later as a task completion.

Planning, worktrees and questions

Tasks, scheduling and notifications

MCP and claude.ai

Permission types

type PermissionUpdate =
  | { type: "addRules" | "replaceRules" | "removeRules"; rules: PermissionRuleValue[]; behavior: PermissionBehavior; destination: PermissionUpdateDestination }
  | { type: "setMode"; mode: PermissionMode; destination: PermissionUpdateDestination }
  | { type: "addDirectories" | "removeDirectories"; directories: string[]; destination: PermissionUpdateDestination };

type PermissionBehavior = "allow" | "deny" | "ask";
type PermissionUpdateDestination = "userSettings" | "projectSettings" | "localSettings" | "session" | "cliArg";
type PermissionRuleValue = { toolName: string; ruleContent?: string };

Other types

Account, models and agents

ApiKeySource reports one of four values: ANTHROPIC_API_KEY, apiKeyHelper, /login managed key (Claude Console login) or none (claude.ai login, bearer token or cloud provider). The type also keeps user, project, org, temporary and oauth for compatibility, but they are not reported.

SdkBeta is "context-1m-2025-08-07". It is retired for Sonnet 4.5 and Sonnet 4 on the Claude API, and over-200K requests then fail. For 1M context, use a model that has it by default such as claude-sonnet-5-5 or claude-opus-5-5, or a [1m] variant such as claude-opus-4-6[1m].

MCP status and provenance

McpServerStatus: name, status (connected, failed, needs-auth, pending, disabled), serverInfo?, error?, config? (an McpServerStatusConfig, any transport plus claudeai-proxy), scope?, source? (SDK v0.3.274+), tools? (name, description?, annotations? with readOnly, destructive, openWorld, and _meta?). Tool _meta carries only the MCP Apps ui object (resourceUri, visibility) and the deprecated ui/resourceUri, when init capabilities include mcp_tool_ui_meta_v1 (SDK v0.3.280+).

McpServerProvenance: { name, source }, carried as mcp_server on tool hook inputs and mcpServer in canUseTool options. source is sdk (only your app can register these), plugin (name is plugin:<plugin>:<server>), or a scope: user, project (.mcp.json), local, dynamic (your mcpServers option, non-SDK), managed, enterprise, claudeai or agent. Base trust on source, never on the name, and escape names from non-sdk sources.

McpSetServersResult: added, removed, errors. Rules for setMcpServers():

• Servers you omit: outside cloud sessions, servers added by earlier setMcpServers() calls and in-process SDK servers are disconnected and listed in removed. Servers from the mcpServers option (stdio, HTTP, SSE), settings files and plugins keep running.
• Servers you name: an earlier setMcpServers() stdio, HTTP or SSE server is replaced only if its config changed. An in-process SDK server under that name stays; to swap it, omit it in one call and add it in the next.
• Built-in servers started by the CLI are dropped and reported in errors.
• The promise resolves after new servers connect or fail. A failed server appears in both added and errors and as failed in status (from v2.1.257).

SDKMcpResourceLink: uri, name, title?, description?, mimeType?, size?, annotations?. Blocks without string uri and name are dropped (SDK v0.3.257+).

CallToolResult: content (blocks of text, image, audio, resource, resource_link), structuredContent?, isError?.

Usage

ModelUsage: inputTokens, outputTokens, thinkingTokens? (already in outputTokens; SDK v0.3.257+), cacheReadInputTokens, cacheCreationInputTokens, webSearchRequests, costUSD, contextWindow, maxOutputTokens, canonicalModel? and provider? (v2.1.218+; providers firstParty, bedrock, vertex, foundry, anthropicAws, mantle, gateway), costBasis? (list, managed, unknown; v2.1.246+).

Usage is BetaUsage from @anthropic-ai/sdk: input_tokens, output_tokens, cache_creation_input_tokens, cache_read_input_tokens, cache_creation (5m and 1h), server_tool_use, service_tier, speed (standard, fast), inference_geo, iterations, output_tokens_details (thinking_tokens; SDK v0.3.228+), fallback_credit (present if your @anthropic-ai/sdk is 0.115.0+). NonNullableUsage makes every field non-null except fallback_credit.

On output_tokens_details.thinking_tokens: use it for observability, not billing (output_tokens is authoritative); it counts raw reasoning including delimiters and may differ by a few tokens; on streamed assistant messages it is a placeholder; on the result it reads 0 when no breakdown is reported; the object is null on synthesised messages such as API errors.

Thinking

type ThinkingConfig =
  | { type: "adaptive"; display?: "summarized" | "omitted" }
  | { type: "enabled"; budgetTokens?: number; display?: "summarized" | "omitted" }
  | { type: "disabled" };

Adaptive needs Opus 4.6 or later. On Opus 4.7+ the API defaults display to omitted; set summarized to get text. Bedrock and Google Cloud's Agent Platform do not receive display, so Opus 4.7+ thinking blocks are empty there.

Custom process spawning

SpawnOptions: command, args, cwd?, env, signal. SpawnedProcess: stdin, stdout, killed, exitCode, kill(signal), and on/once/off for exit and error; a Node ChildProcess already satisfies it.

The signal does not fire the instant your abortController aborts: the SDK closes stdin, waits about two seconds for a clean shutdown, then aborts it. Listen on your own abortController.signal to react immediately.

import { spawn } from "node:child_process";

const options = {
  spawnClaudeCodeProcess: ({ command, args, env, signal }) =>
    spawn("docker", ["exec", "-i", "agent-box", command, ...args], { env, signal, stdio: ["pipe", "pipe", "inherit"] })
};

RewindFilesResult

canRewind, error?, filesChanged?, insertions?, deletions?, skippedLinks? (paths refused for link safety; v2.1.216+; never set on dryRun).

Sandbox

SandboxSettings

Linux needs bubblewrap and socat. If the sandbox cannot start with the default failIfUnavailable, the run ends in error_during_execution with the reason in errors, and a one-shot query() then throws.

SandboxNetworkConfig

Applies to sandboxed Bash only; WebFetch uses permission rules.

Warning: Allowing /var/run/docker.sock hands over the host. The proxy filters by hostname without inspecting TLS, so domain fronting can bypass it; see secure deployment.

Gating unsandboxed requests

With allowUnsandboxedCommands on, a Bash call with dangerouslyDisableSandbox: true reaches canUseTool:

for await (const m of query({
  prompt: "Run the end-to-end suite",
  options: {
    sandbox: { enabled: true, allowUnsandboxedCommands: true },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        const ok = String(input.command).startsWith("npx playwright ");
        return ok
          ? { behavior: "allow", updatedInput: input }
          : { behavior: "deny", message: "Only Playwright may run outside the sandbox" };
      }
      return { behavior: "allow", updatedInput: input };
    }
  }
})) { /* ... */ }

Warning: Never combine bypassPermissions with allowUnsandboxedCommands: the model could leave the sandbox without asking anyone, apart from the actions no mode auto-approves.

Related

• Python SDK reference
• Agent SDK overview
• Agent loop
• Custom tools
• CLI reference