@anthropic-ai/claude-agent-sdk 0.1.55 → 0.1.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.1.55",
+  "version": "0.1.57",
   "main": "sdk.mjs",
   "types": "sdk.d.ts",
   "engines": {

package/sandboxTypes.d.ts

@@ -0,0 +1,144 @@
+/**
+ * Sandbox types for the Claude Code Agent SDK
+ *
+ * This file is the single source of truth for sandbox configuration types.
+ * Both the SDK and the settings validation import from here.
+ */
+import { z } from 'zod';
+/**
+ * Network configuration schema for sandbox.
+ */
+export declare const SandboxNetworkConfigSchema: z.ZodOptional<z.ZodObject<{
+    allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
+    allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+    httpProxyPort: z.ZodOptional<z.ZodNumber>;
+    socksProxyPort: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    allowUnixSockets?: string[];
+    allowAllUnixSockets?: boolean;
+    allowLocalBinding?: boolean;
+    httpProxyPort?: number;
+    socksProxyPort?: number;
+}, {
+    allowUnixSockets?: string[];
+    allowAllUnixSockets?: boolean;
+    allowLocalBinding?: boolean;
+    httpProxyPort?: number;
+    socksProxyPort?: number;
+}>>;
+/**
+ * Sandbox settings schema.
+ */
+export declare const SandboxSettingsSchema: z.ZodObject<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
+    allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
+    network: z.ZodOptional<z.ZodObject<{
+        allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
+        allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+        httpProxyPort: z.ZodOptional<z.ZodNumber>;
+        socksProxyPort: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }>>;
+    ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
+    excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ripgrep: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        command?: string;
+        args?: string[];
+    }, {
+        command?: string;
+        args?: string[];
+    }>>;
+}, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
+    allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
+    network: z.ZodOptional<z.ZodObject<{
+        allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
+        allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+        httpProxyPort: z.ZodOptional<z.ZodNumber>;
+        socksProxyPort: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }>>;
+    ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
+    excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ripgrep: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        command?: string;
+        args?: string[];
+    }, {
+        command?: string;
+        args?: string[];
+    }>>;
+}, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+    enabled: z.ZodOptional<z.ZodBoolean>;
+    autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
+    allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
+    network: z.ZodOptional<z.ZodObject<{
+        allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
+        allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
+        httpProxyPort: z.ZodOptional<z.ZodNumber>;
+        socksProxyPort: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }, {
+        allowUnixSockets?: string[];
+        allowAllUnixSockets?: boolean;
+        allowLocalBinding?: boolean;
+        httpProxyPort?: number;
+        socksProxyPort?: number;
+    }>>;
+    ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString, "many">>>;
+    enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
+    excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    ripgrep: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        command?: string;
+        args?: string[];
+    }, {
+        command?: string;
+        args?: string[];
+    }>>;
+}, z.ZodTypeAny, "passthrough">>;
+export type SandboxSettings = z.infer<typeof SandboxSettingsSchema>;
+export type SandboxNetworkConfig = NonNullable<z.infer<typeof SandboxNetworkConfigSchema>>;
+export type SandboxIgnoreViolations = NonNullable<SandboxSettings['ignoreViolations']>;

package/sdk-tools.d.ts

@@ -94,10 +94,7 @@ export interface BashOutputInput {
   filter?: string;
 }
 export interface ExitPlanModeInput {
-  /**
-   * The plan you came up with, that you want to run by the user for approval. Supports markdown. The plan should be pretty concise.
-   */
-  plan: string;
+  [k: string]: unknown;
 }
 export interface FileEditInput {
   /**

package/sdk.d.ts

@@ -4,6 +4,8 @@ import type { UUID } from 'crypto';
 import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
 import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { type z, type ZodRawShape, type ZodObject } from 'zod';
+import type { SandboxSettings, SandboxNetworkConfig, SandboxIgnoreViolations } from './sandboxTypes.js';
+export type { SandboxSettings, SandboxNetworkConfig, SandboxIgnoreViolations };
 export type NonNullableUsage = {
     [K in keyof Usage]: NonNullable<Usage[K]>;
 };
@@ -161,7 +163,7 @@ export type CanUseTool = (toolName: string, input: Record<string, unknown>, opti
     /** If running within the context of a sub-agent, the sub-agent's ID. */
     agentID?: string;
 }) => Promise<PermissionResult>;
-export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest"];
+export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "SubagentStart", "SubagentStop", "PreCompact", "PermissionRequest"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
 export type HookCallback = (input: HookInput, toolUseID: string | undefined, options: {
     signal: AbortSignal;
@@ -197,6 +199,14 @@ export type PostToolUseHookInput = BaseHookInput & {
     tool_response: unknown;
     tool_use_id: string;
 };
+export type PostToolUseFailureHookInput = BaseHookInput & {
+    hook_event_name: 'PostToolUseFailure';
+    tool_name: string;
+    tool_input: unknown;
+    tool_use_id: string;
+    error: string;
+    is_interrupt?: boolean;
+};
 export type NotificationHookInput = BaseHookInput & {
     hook_event_name: 'Notification';
     message: string;
@@ -237,7 +247,7 @@ export type SessionEndHookInput = BaseHookInput & {
     hook_event_name: 'SessionEnd';
     reason: ExitReason;
 };
-export type HookInput = PreToolUseHookInput | PostToolUseHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PermissionRequestHookInput;
+export type HookInput = PreToolUseHookInput | PostToolUseHookInput | PostToolUseFailureHookInput | NotificationHookInput | UserPromptSubmitHookInput | SessionStartHookInput | SessionEndHookInput | StopHookInput | SubagentStartHookInput | SubagentStopHookInput | PreCompactHookInput | PermissionRequestHookInput;
 export type AsyncHookJSONOutput = {
     async: true;
     asyncTimeout?: number;
@@ -267,6 +277,9 @@ export type SyncHookJSONOutput = {
         hookEventName: 'PostToolUse';
         additionalContext?: string;
         updatedMCPToolOutput?: unknown;
+    } | {
+        hookEventName: 'PostToolUseFailure';
+        additionalContext?: string;
     } | {
         hookEventName: 'PermissionRequest';
         decision: {
@@ -564,6 +577,16 @@ export type Options = {
     continue?: boolean;
     cwd?: string;
     disallowedTools?: string[];
+    /**
+     * Specify the base set of available built-in tools.
+     * - `string[]` - Array of specific tool names (e.g., `['Bash', 'Read', 'Edit']`)
+     * - `[]` (empty array) - Disable all built-in tools
+     * - `{ type: 'preset'; preset: 'claude_code' }` - Use all default Claude Code tools
+     */
+    tools?: string[] | {
+        type: 'preset';
+        preset: 'claude_code';
+    };
     env?: {
         [envVar: string]: string | undefined;
     };
@@ -610,6 +633,42 @@ export type Options = {
      * The message ID is expected to be from SDKAssistantMessage.uuid.
      */
     resumeSessionAt?: string;
+    /**
+     * Sandbox settings for command execution isolation.
+     *
+     * When enabled, commands are executed in a sandboxed environment that restricts
+     * filesystem and network access. This provides an additional security layer.
+     *
+     * **Important:** Filesystem and network restrictions are configured via permission
+     * rules, not via these sandbox settings:
+     * - Filesystem access: Use `Read` and `Edit` permission rules
+     * - Network access: Use `WebFetch` permission rules
+     *
+     * These sandbox settings control sandbox behavior (enabled, auto-allow, etc.),
+     * while the actual access restrictions come from your permission configuration.
+     *
+     * @example Enable sandboxing with auto-allow
+     * ```typescript
+     * sandbox: {
+     *   enabled: true,
+     *   autoAllowBashIfSandboxed: true
+     * }
+     * ```
+     *
+     * @example Configure network options (not restrictions)
+     * ```typescript
+     * sandbox: {
+     *   enabled: true,
+     *   network: {
+     *     allowLocalBinding: true,
+     *     allowUnixSockets: ['/var/run/docker.sock']
+     *   }
+     * }
+     * ```
+     *
+     * @see https://docs.anthropic.com/en/docs/claude-code/settings#sandbox-settings
+     */
+    sandbox?: SandboxSettings;
     settingSources?: SettingSource[];
     stderr?: (data: string) => void;
     strictMcpConfig?: boolean;
@@ -645,4 +704,3 @@ export declare function unstable_v2_resumeSession(_sessionId: string, _options:
  * ```
  */
 export declare function unstable_v2_prompt(_message: string, _options: SDKSessionOptions): Promise<SDKResultMessage>;
-export {};

package/sdk.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 // (c) Anthropic PBC. All rights reserved. Use is subject to the Legal Agreements outlined here: https://docs.claude.com/en/docs/claude-code/legal-and-compliance.
 
-// Version: 0.1.55
+// Version: 0.1.57
 
 // Want to see the unminified source? We're hiring!
 // https://job-boards.greenhouse.io/anthropic/jobs/4816199008
@@ -6381,6 +6381,7 @@ function getFsImplementation() {
 var HOOK_EVENTS = [
   "PreToolUse",
   "PostToolUse",
+  "PostToolUseFailure",
   "Notification",
   "UserPromptSubmit",
   "SessionStart",
@@ -6457,6 +6458,22 @@ function logForSdkDebugging(message) {
   appendFileSync2(path, output);
 }
 
+// ../src/transport/sandboxUtils.ts
+function mergeSandboxIntoExtraArgs(extraArgs, sandbox) {
+  const effectiveExtraArgs = { ...extraArgs };
+  if (sandbox) {
+    let settingsObj = { sandbox };
+    if (effectiveExtraArgs.settings) {
+      try {
+        const existingSettings = JSON.parse(effectiveExtraArgs.settings);
+        settingsObj = { ...existingSettings, sandbox };
+      } catch {}
+    }
+    effectiveExtraArgs.settings = JSON.stringify(settingsObj);
+  }
+  return effectiveExtraArgs;
+}
+
 // ../src/transport/ProcessTransport.ts
 class ProcessTransport {
   options;
@@ -6478,7 +6495,6 @@ class ProcessTransport {
     try {
       const {
         additionalDirectories = [],
-        agents,
         cwd,
         executable = isRunningWithBun() ? "bun" : "node",
         executableArgs = [],
@@ -6486,8 +6502,6 @@ class ProcessTransport {
         pathToClaudeCodeExecutable,
         env = { ...process.env },
         stderr,
-        customSystemPrompt,
-        appendSystemPrompt,
         maxThinkingTokens,
         maxTurns,
         maxBudgetUsd,
@@ -6506,7 +6520,8 @@ class ProcessTransport {
         strictMcpConfig,
         canUseTool,
         includePartialMessages,
-        plugins
+        plugins,
+        sandbox
       } = this.options;
       const args = [
         "--output-format",
@@ -6515,10 +6530,6 @@ class ProcessTransport {
         "--input-format",
         "stream-json"
       ];
-      if (typeof customSystemPrompt === "string")
-        args.push("--system-prompt", customSystemPrompt);
-      if (appendSystemPrompt)
-        args.push("--append-system-prompt", appendSystemPrompt);
       if (maxThinkingTokens !== undefined) {
         args.push("--max-thinking-tokens", maxThinkingTokens.toString());
       }
@@ -6553,12 +6564,21 @@ class ProcessTransport {
       if (disallowedTools.length > 0) {
         args.push("--disallowedTools", disallowedTools.join(","));
       }
+      const { tools } = this.options;
+      if (tools !== undefined) {
+        if (Array.isArray(tools)) {
+          if (tools.length === 0) {
+            args.push("--tools", "");
+          } else {
+            args.push("--tools", tools.join(","));
+          }
+        } else {
+          args.push("--tools", "default");
+        }
+      }
       if (mcpServers && Object.keys(mcpServers).length > 0) {
         args.push("--mcp-config", JSON.stringify({ mcpServers }));
       }
-      if (agents && Object.keys(agents).length > 0) {
-        args.push("--agents", JSON.stringify(agents));
-      }
       if (settingSources) {
         args.push("--setting-sources", settingSources.join(","));
       }
@@ -6598,7 +6618,8 @@ class ProcessTransport {
       if (this.options.resumeSessionAt) {
         args.push("--resume-session-at", this.options.resumeSessionAt);
       }
-      for (const [flag, value] of Object.entries(extraArgs)) {
+      const effectiveExtraArgs = mergeSandboxIntoExtraArgs(extraArgs ?? {}, sandbox);
+      for (const [flag, value] of Object.entries(effectiveExtraArgs)) {
         if (value === null) {
           args.push(`--${flag}`);
         } else {
@@ -7676,6 +7697,7 @@ class Query {
   hooks;
   abortController;
   jsonSchema;
+  initConfig;
   pendingControlResponses = new Map;
   cleanupPerformed = false;
   sdkMessages;
@@ -7689,13 +7711,14 @@ class Query {
   firstResultReceivedPromise;
   firstResultReceivedResolve;
   streamCloseTimeout;
-  constructor(transport, isSingleUserTurn, canUseTool, hooks, abortController, sdkMcpServers = new Map, jsonSchema) {
+  constructor(transport, isSingleUserTurn, canUseTool, hooks, abortController, sdkMcpServers = new Map, jsonSchema, initConfig) {
     this.transport = transport;
     this.isSingleUserTurn = isSingleUserTurn;
     this.canUseTool = canUseTool;
     this.hooks = hooks;
     this.abortController = abortController;
     this.jsonSchema = jsonSchema;
+    this.initConfig = initConfig;
     this.streamCloseTimeout = 60000;
     if (typeof process !== "undefined" && process.env?.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT) {
       this.streamCloseTimeout = parseInt(process.env.CLAUDE_CODE_STREAM_CLOSE_TIMEOUT);
@@ -7888,7 +7911,10 @@ class Query {
       subtype: "initialize",
       hooks,
       sdkMcpServers,
-      jsonSchema: this.jsonSchema
+      jsonSchema: this.jsonSchema,
+      systemPrompt: this.initConfig?.systemPrompt,
+      appendSystemPrompt: this.initConfig?.appendSystemPrompt,
+      agents: this.initConfig?.agents
     };
     const response = await this.request(initRequest);
     return response.response;
@@ -8102,7 +8128,6 @@ class SessionImpl {
       executable: options.executable ?? (isRunningWithBun() ? "bun" : "node"),
       executableArgs: options.executableArgs ?? [],
       extraArgs: {},
-      customSystemPrompt: "",
       maxThinkingTokens: undefined,
       maxTurns: undefined,
       maxBudgetUsd: undefined,
@@ -15059,7 +15084,7 @@ function query({
   prompt,
   options
 }) {
-  const { systemPrompt, settingSources, ...rest } = options ?? {};
+  const { systemPrompt, settingSources, sandbox, ...rest } = options ?? {};
   let customSystemPrompt;
   let appendSystemPrompt;
   if (systemPrompt === undefined) {
@@ -15075,7 +15100,7 @@ function query({
     const dirname2 = join5(filename, "..");
     pathToClaudeCodeExecutable = join5(dirname2, "cli.js");
   }
-  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.55";
+  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.57";
   const {
     abortController = createAbortController(),
     additionalDirectories = [],
@@ -15085,6 +15110,7 @@ function query({
     continue: continueConversation,
     cwd: cwd2,
     disallowedTools = [],
+    tools,
     env,
     executable = isRunningWithBun() ? "bun" : "node",
     executableArgs = [],
@@ -15138,7 +15164,6 @@ function query({
   const transport = new ProcessTransport({
     abortController,
     additionalDirectories,
-    agents,
     cwd: cwd2,
     executable,
     executableArgs,
@@ -15147,8 +15172,6 @@ function query({
     env: processEnv,
     forkSession,
     stderr,
-    customSystemPrompt,
-    appendSystemPrompt,
     maxThinkingTokens,
     maxTurns,
     maxBudgetUsd,
@@ -15164,14 +15187,21 @@ function query({
     settingSources: settingSources ?? [],
     allowedTools,
     disallowedTools,
+    tools,
     mcpServers: allMcpServers,
     strictMcpConfig,
     canUseTool: !!canUseTool,
     hooks: !!hooks,
     includePartialMessages,
-    plugins
+    plugins,
+    sandbox
   });
-  const queryInstance = new Query(transport, isSingleUserTurn, canUseTool, hooks, abortController, sdkMcpServers, jsonSchema);
+  const initConfig = {
+    systemPrompt: customSystemPrompt,
+    appendSystemPrompt,
+    agents
+  };
+  const queryInstance = new Query(transport, isSingleUserTurn, canUseTool, hooks, abortController, sdkMcpServers, jsonSchema, initConfig);
   if (typeof prompt === "string") {
     transport.write(JSON.stringify({
       type: "user",