@anthropic-ai/claude-agent-sdk 0.2.141 → 0.3.142

package/manifest.json

@@ -1,47 +1,47 @@
 {
-  "version": "2.1.141",
-  "commit": "4f4623ddd339e1c1b87d659b7c9eb3b66397e7a3",
-  "buildDate": "2026-05-13T21:34:55Z",
+  "version": "2.1.142",
+  "commit": "880324aad10dc75b18dbac2782d9dfee7cbb1578",
+  "buildDate": "2026-05-14T16:45:24Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude",
-      "checksum": "31ac95bb19a33b1d0cddd3f3ff594bf8bfd2be5051cd2af7867109641cab705e",
-      "size": 207076896
+      "checksum": "772021afa051160b97e04d379738df84d4cacd311e8c199a325fb013b3eaa448",
+      "size": 207126432
     },
     "darwin-x64": {
       "binary": "claude",
-      "checksum": "fa9000fdf4a522fcaf30ea283555aca2ba5d0e76cdb8842154b7735b558c7c25",
-      "size": 209591056
+      "checksum": "d00bc6fb38d0837ce811cc862a3b6822795b33dbce8361703b1e5e903bd240fd",
+      "size": 209640592
     },
     "linux-arm64": {
       "binary": "claude",
-      "checksum": "dc931e24f62afbadc8dc68115278b08493825a3ed1ea753d587077181a6cc63b",
-      "size": 232437384
+      "checksum": "767b13fc28763ca9d663b00f90e501f134b356f1b72dcf0eea59b7e3bed86411",
+      "size": 232502920
     },
     "linux-x64": {
       "binary": "claude",
-      "checksum": "832be26e8f15b2ae99e520a22b034fc4bfad1cb5b84de6b706487072c56bb42e",
-      "size": 232572624
+      "checksum": "1249a1dadfe2d48f320bd4e1b657a1a0d82435da76deb11ce509822407cf24ec",
+      "size": 232625872
     },
     "linux-arm64-musl": {
       "binary": "claude",
-      "checksum": "e6e6a481c0aab084198b3529c6d96774e14d18da999aba7d22e207952ed8faf0",
-      "size": 225292120
+      "checksum": "43834a6c50954deb6ddb1b49937d15ccae71fbdb3d370e26a461e12c50c122ba",
+      "size": 225357656
     },
     "linux-x64-musl": {
       "binary": "claude",
-      "checksum": "8af1f6e19d3786cac74dcf369ff58f79df08be429813b29ae076247cc8d1ddae",
-      "size": 226966576
+      "checksum": "c645dc32d250a54bb8399630f0ffa88b4ee44ba8e6461e33ed95b2f64f836ea9",
+      "size": 227019824
     },
     "win32-x64": {
       "binary": "claude.exe",
-      "checksum": "3ab326c39d195dbe394c173f31126d880a80270f98ade74ef555429e2dadb19f",
-      "size": 228410016
+      "checksum": "0778b1c607ee3282ba8ea3f0c684edb05f597454cc0d21386a84576b5434b1c7",
+      "size": 228456096
     },
     "win32-arm64": {
       "binary": "claude.exe",
-      "checksum": "f622af48157bce7a24905fa6121191f5a472800ed9f77fa41c59bd5ecd161285",
-      "size": 224374432
+      "checksum": "95a966b0729f9f7c28c68df3d63e7f5ac6ac72abab209392800e9a40292f3bfc",
+      "size": 224420000
     }
   }
 }

package/manifest.zst.json

@@ -1,55 +1,55 @@
 {
-  "version": "2.1.141",
-  "commit": "4f4623ddd339e1c1b87d659b7c9eb3b66397e7a3",
-  "buildDate": "2026-05-13T21:41:28Z",
+  "version": "2.1.142",
+  "commit": "880324aad10dc75b18dbac2782d9dfee7cbb1578",
+  "buildDate": "2026-05-14T16:52:01Z",
   "platforms": {
     "darwin-arm64": {
       "binary": "claude.zst",
-      "checksum": "ded188fd6b63c8e03d95500760a7414ba6906876c626476b3c1aaf8e7d87f8a0",
-      "size": 42914116,
+      "checksum": "0f691f77c8f4d1e7a13813c10d8de3f611c486a24fb8a2f33470b785064f8718",
+      "size": 42921902,
       "bundle": {
-        "checksum": "27c366c8a650d90a4a48b624fd89d6a2daee2c2f53a2a1ad11a26eb603557855",
-        "size": 42918185
+        "checksum": "9e0823cd0d41df7bfa8d3f0864f3c8bb52cc4787aa495c0088afbcc8c7261058",
+        "size": 42924662
       }
     },
     "darwin-x64": {
       "binary": "claude.zst",
-      "checksum": "5bce9e6dbd397709c12d4ba19424dae4e185dc8b70179cf9f1bef07317d42d3f",
-      "size": 44816821,
+      "checksum": "958d1a9d396a23819ef413c94510619499b3ab04cc4968a6cea7c334999272ea",
+      "size": 44836769,
       "bundle": {
-        "checksum": "1b3be19bdea17a3b20fb214549ca10c064b9269d653d3a5e66aab615c7b078e7",
-        "size": 44837419
+        "checksum": "f3dd24e6cc318032c795fe12c4f259de64a70b58409c187cc231e39f65453595",
+        "size": 44841630
       }
     },
     "linux-arm64": {
       "binary": "claude.zst",
-      "checksum": "7327ee9b0488231f4a7ecfbc0110337877af508b25078e0f7a1561ec72c0f9b1",
-      "size": 50723547
+      "checksum": "75c7af4adb9bbd7b48b407d005cdad790a6ecb00e7e6b6de6c2b0c4acafcf81f",
+      "size": 50714165
     },
     "linux-x64": {
       "binary": "claude.zst",
-      "checksum": "b8be41003357a75527ceffe3f75b936427c5cd5ffb8d6847a29b6f165ba3ca1a",
-      "size": 51286205
+      "checksum": "7a9f89138613c26b815054bf009a086ed76f1c8c8265484090072d900f10d278",
+      "size": 51328541
     },
     "linux-arm64-musl": {
       "binary": "claude.zst",
-      "checksum": "899a1f33abb7bea21129aa379bd757956d38bde484bdbba5f0a7efb4e8d0270d",
-      "size": 49328098
+      "checksum": "76acedae2ff83dc06e5dc38066bd0fa42ca76c18a9aabb8e63742c01a07f5dfd",
+      "size": 49338045
     },
     "linux-x64-musl": {
       "binary": "claude.zst",
-      "checksum": "1fd02e4d619c5266b99c7f97cbad4fb6838f73a4cd717dd173b9ede93d70adcd",
-      "size": 50009722
+      "checksum": "e6425d37a4cc099cfd1b1b13298c0f2067302decfd8542d0c12c5eb5df435ac6",
+      "size": 50052852
     },
     "win32-x64": {
       "binary": "claude.exe.zst",
-      "checksum": "607ec8680c87ea6251f2785fa574d798851ef7470313eefd45b6b0f877d67d4c",
-      "size": 52034683
+      "checksum": "1183b899719c41f41f3f57fb8580e50845ee645c1878e29744138b8e459d897e",
+      "size": 52050022
     },
     "win32-arm64": {
       "binary": "claude.exe.zst",
-      "checksum": "c970ff7b932bee058f530a10e4dc0a0b8fff53acc49b64bb5b67b03432d299ee",
-      "size": 50306178
+      "checksum": "ca544b53e4fb45d12bd30f214de6ee85859ec9f89c7e14942bdcfb4a1db576f4",
+      "size": 50320973
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.2.141",
+  "version": "0.3.142",
   "main": "sdk.mjs",
   "types": "sdk.d.ts",
   "exports": {
@@ -55,14 +55,14 @@
     "zod": "^4.0.0"
   },
   "optionalDependencies": {
-    "@anthropic-ai/claude-agent-sdk-linux-x64": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.2.141",
-    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.2.141"
+    "@anthropic-ai/claude-agent-sdk-linux-x64": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-linux-x64-musl": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-linux-arm64-musl": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-darwin-x64": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-darwin-arm64": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-win32-x64": "0.3.142",
+    "@anthropic-ai/claude-agent-sdk-win32-arm64": "0.3.142"
   },
   "files": [
     "sdk.mjs",
@@ -78,5 +78,5 @@
     "manifest.json",
     "manifest.zst.json"
   ],
-  "claudeCodeVersion": "2.1.141"
+  "claudeCodeVersion": "2.1.142"
 }

package/sdk.d.ts

@@ -635,7 +635,7 @@ export declare type ForkSessionOptions = SessionMutationOptions & {
  * Result of a fork operation.
  */
 export declare type ForkSessionResult = {
-    /** New session UUID. Resumable via `resumeSession(sessionId)`. */
+    /** New session UUID. Resumable via `query({ options: { resume: sessionId } })`. */
     sessionId: string;
 };
 
@@ -954,7 +954,7 @@ export declare type McpHttpServerConfig = {
     headers?: Record<string, string>;
     tools?: McpServerToolPolicy[];
     /**
-     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even when MCP_CONNECTION_NONBLOCKING=1, since the tools must be present when the turn-1 prompt is built.
+     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
      */
     alwaysLoad?: boolean;
 };
@@ -1059,7 +1059,7 @@ export declare type McpSSEServerConfig = {
     headers?: Record<string, string>;
     tools?: McpServerToolPolicy[];
     /**
-     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even when MCP_CONNECTION_NONBLOCKING=1, since the tools must be present when the turn-1 prompt is built.
+     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
      */
     alwaysLoad?: boolean;
 };
@@ -1070,7 +1070,7 @@ export declare type McpStdioServerConfig = {
     args?: string[];
     env?: Record<string, string>;
     /**
-     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even when MCP_CONNECTION_NONBLOCKING=1, since the tools must be present when the turn-1 prompt is built.
+     * When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
      */
     alwaysLoad?: boolean;
 };
@@ -1226,6 +1226,32 @@ export declare type Options = {
      * otherwise be allowed.
      */
     disallowedTools?: string[];
+    /**
+     * Map of tool-name aliases applied before name resolution. When the
+     * model emits a `tool_use` whose name is a key in this map, the tool
+     * execution path resolves the mapped name instead.
+     *
+     * This lets SDK consumers redirect built-in tool names to their own
+     * tools. For example, a host that runs Bash inside a remote sandbox via
+     * an MCP tool can set `{ Bash: 'mcp__workspace__bash' }` so that if the
+     * model emits `Bash` (e.g. because a skill document instructed it to),
+     * the call is routed to the MCP tool instead of failing as unknown.
+     *
+     * The redirect is single-hop: an alias that points at another aliased
+     * name resolves that target literally rather than following a chain, so
+     * cycles like `{A: 'B', B: 'A'}` cannot loop.
+     *
+     * `toolAliases` is complementary to `disallowedTools`, not a replacement
+     * for it: the alias only affects name-based lookup of model-emitted
+     * `tool_use` blocks, whereas `disallowedTools` also blocks harness-internal
+     * direct calls that hold the tool object without a name lookup.
+     *
+     * @example
+     * ```typescript
+     * toolAliases: { Bash: 'mcp__workspace__bash' }
+     * ```
+     */
+    toolAliases?: Record<string, string>;
     /**
      * Specify the base set of available built-in tools.
      * - `string[]` - Array of specific tool names (e.g., `['Bash', 'Read', 'Edit']`)
@@ -2465,6 +2491,15 @@ export declare type SDKAssistantMessage = {
     error?: SDKAssistantMessageError;
     uuid: UUID;
     session_id: string;
+    request_id?: string;
+    /**
+     * Subagent type that produced this message.
+     */
+    subagent_type?: string;
+    /**
+     * Description of the subagent task that produced this message.
+     */
+    task_description?: string;
 };
 
 export declare type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'billing_error' | 'rate_limit' | 'invalid_request' | 'server_error' | 'unknown' | 'max_output_tokens';
@@ -2714,6 +2749,10 @@ declare type SDKControlInitializeRequest = {
      */
     planModeInstructions?: string;
 
+    /**
+     * Map of tool-name aliases applied before name resolution. When the model emits a tool_use whose name is a key in this map, the tool execution path resolves the mapped name instead. Single-hop (no chains). See Options.toolAliases.
+     */
+    toolAliases?: Record<string, string>;
     /**
      * When true, omit per-user dynamic sections (working directory, auto-memory path) from the cached system prompt and re-inject them as the first user message. Lets cross-user prompt caching hit on a static system prompt prefix. Tradeoff: the model sees this context slightly later in the prompt, so steering on the working directory and memory location is marginally less authoritative. Has no effect when a custom (non-preset) system prompt is in use.
      */
@@ -3316,6 +3355,7 @@ export declare type SDKResultSuccess = {
     subtype: 'success';
     duration_ms: number;
     duration_api_ms: number;
+    ttft_ms?: number;
     is_error: boolean;
     api_error_status?: number | null;
     num_turns: number;
@@ -3334,30 +3374,6 @@ export declare type SDKResultSuccess = {
     session_id: string;
 };
 
-/**
- * V2 API - UNSTABLE
- * Session interface for multi-turn conversations.
- * Has methods, so not serializable.
- * @deprecated Use `query()` instead. The V2 session API will be removed in a future release.
- * @alpha
- */
-export declare interface SDKSession {
-    /**
-     * The session ID. Available after receiving the first message.
-     * For resumed sessions, available immediately.
-     * Throws if accessed before the session is initialized.
-     */
-    readonly sessionId: string;
-    /** Send a message to the agent */
-    send(message: string | SDKUserMessage): Promise<void>;
-    /** Stream messages from the agent */
-    stream(): AsyncGenerator<SDKMessage, void>;
-    /** Close the session */
-    close(): void;
-    /** Async disposal support (calls close if not already closed) */
-    [Symbol.asyncDispose](): Promise<void>;
-}
-
 /**
  * Session metadata returned by listSessions and getSessionInfo.
  */
@@ -3404,85 +3420,6 @@ export declare type SDKSessionInfo = {
     createdAt?: number;
 };
 
-/**
- * V2 API - UNSTABLE
- * Options for creating a session.
- * @deprecated Use `query()` instead. The V2 session API will be removed in a future release.
- * @alpha
- */
-export declare type SDKSessionOptions = {
-    /** Model to use */
-    model: string;
-    /** Path to Claude Code executable */
-    pathToClaudeCodeExecutable?: string;
-    /** Executable to use (node, bun) */
-    executable?: 'node' | 'bun';
-    /** Arguments to pass to executable */
-    executableArgs?: string[];
-    /**
-     * Environment variables to pass to the Claude Code process.
-     * Defaults to `process.env`.
-     *
-     * SDK consumers can identify their app/library to include in the User-Agent header by setting:
-     * - `CLAUDE_AGENT_SDK_CLIENT_APP` - Your app/library identifier (e.g., "my-app/1.0.0", "my-library/2.1")
-     */
-    env?: {
-        [envVar: string]: string | undefined;
-    };
-    /**
-     * Working directory for the Claude Code process. Defaults to the current
-     * process's working directory.
-     */
-    cwd?: string;
-    /**
-     * Which settings sources to load (CLAUDE.md, `.claude/settings.json`).
-     * Defaults to `[]`: no project/user settings are loaded unless specified.
-     * Note that `query()` has the opposite default and loads all sources when
-     * this is omitted.
-     */
-    settingSources?: SettingSource[];
-    /**
-     * Must be set to `true` when using `permissionMode: 'bypassPermissions'`.
-     * This is a safety measure to ensure intentional bypassing of permissions.
-     */
-    allowDangerouslySkipPermissions?: boolean;
-    /**
-     * List of tool names that are auto-allowed without prompting for permission.
-     * These tools will execute automatically without asking the user for approval.
-     */
-    allowedTools?: string[];
-    /**
-     * List of tool names that are disallowed. These tools will be removed
-     * from the model's context and cannot be used.
-     */
-    disallowedTools?: string[];
-    /**
-     * Custom permission handler for controlling tool usage. Called before each
-     * tool execution to determine if it should be allowed, denied, or prompt the user.
-     */
-    canUseTool?: CanUseTool;
-    /**
-     * Hook callbacks for responding to various events during execution.
-     */
-    hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
-    /**
-     * Permission mode for the session.
-     * - `'default'` - Standard permission behavior, prompts for dangerous operations
-     * - `'acceptEdits'` - Auto-accept file edit operations
-     * - `'bypassPermissions'` - Bypass all permission checks (requires `allowDangerouslySkipPermissions`)
-     * - `'plan'` - Planning mode, no execution of tools
-     * - `'dontAsk'` - Don't prompt for permissions, deny if not pre-approved
-     */
-    permissionMode?: PermissionMode;
-    /**
-     * Custom workflow instructions for plan mode. When `permissionMode` is
-     * `'plan'`, this string replaces the default code-implementation workflow
-     * body in the plan-mode system reminder. The CLI still wraps it with the
-     * read-only enforcement preamble and the ExitPlanMode protocol footer.
-     */
-    planModeInstructions?: string;
-};
-
 /**
  * Mirrors notifySessionStateChanged. 'idle' fires after heldBackResult flushes and the bg-agent do-while exits — authoritative turn-over signal.
  */
@@ -3584,6 +3521,10 @@ export declare type SDKTaskProgressMessage = {
     task_id: string;
     tool_use_id?: string;
     description: string;
+    /**
+     * Subagent type for Task tool subagents.
+     */
+    subagent_type?: string;
     usage: {
         total_tokens: number;
         tool_uses: number;
@@ -3602,6 +3543,10 @@ export declare type SDKTaskStartedMessage = {
     task_id: string;
     tool_use_id?: string;
     description: string;
+    /**
+     * Subagent type for Task tool subagents.
+     */
+    subagent_type?: string;
     task_type?: string;
     /**
      * meta.name from the workflow script (e.g. 'spec'). Only set when task_type is 'local_workflow'.
@@ -3673,6 +3618,14 @@ export declare type SDKUserMessage = {
     timestamp?: string;
     uuid?: UUID;
     session_id?: string;
+    /**
+     * Subagent type that produced this message.
+     */
+    subagent_type?: string;
+    /**
+     * Description of the subagent task that produced this message.
+     */
+    task_description?: string;
 };
 
 export declare type SDKUserMessageReplay = {
@@ -5692,37 +5645,6 @@ export declare interface Transport {
     [Symbol.dispose]?(): void;
 }
 
-/**
- * V2 API - UNSTABLE
- * Create a persistent session for multi-turn conversations.
- * @deprecated Use `query()` instead. The V2 session API will be removed in a future release.
- * @alpha
- */
-export declare function unstable_v2_createSession(_options: SDKSessionOptions): SDKSession;
-
-/**
- * V2 API - UNSTABLE
- * One-shot convenience function for single prompts.
- * @deprecated Use `query()` instead. The V2 session API will be removed in a future release.
- * @alpha
- *
- * @example
- * ```typescript
- * const result = await unstable_v2_prompt("What files are here?", {
- *   model: 'claude-sonnet-4-6'
- * })
- * ```
- */
-export declare function unstable_v2_prompt(_message: string, _options: SDKSessionOptions): Promise<SDKResultMessage>;
-
-/**
- * V2 API - UNSTABLE
- * Resume an existing session by ID.
- * @deprecated Use `query()` instead. The V2 session API will be removed in a future release.
- * @alpha
- */
-export declare function unstable_v2_resumeSession(_sessionId: string, _options: SDKSessionOptions): SDKSession;
-
 export declare type UserPromptExpansionHookInput = BaseHookInput & {
     hook_event_name: 'UserPromptExpansion';
     expansion_type: 'slash_command' | 'mcp_prompt';