@anthropic-ai/claude-agent-sdk 0.1.56 → 0.1.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anthropic-ai/claude-agent-sdk",
-  "version": "0.1.56",
+  "version": "0.1.58",
   "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.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]>;
 };
@@ -27,6 +29,10 @@ export type JsonSchemaOutputFormat = BaseOutputFormat & {
 export type OutputFormat = JsonSchemaOutputFormat;
 export type ApiKeySource = 'user' | 'project' | 'org' | 'temporary';
 export type ConfigScope = 'local' | 'user' | 'project';
+/**
+ * Allowed beta headers that can be passed via SDK options.
+ */
+export type SdkBeta = 'context-1m-2025-08-07';
 export type McpStdioServerConfig = {
     type?: 'stdio';
     command: string;
@@ -403,6 +409,7 @@ export type SDKSystemMessage = {
     subtype: 'init';
     agents?: string[];
     apiKeySource: ApiKeySource;
+    betas?: string[];
     claude_code_version: string;
     cwd: string;
     tools: string[];
@@ -560,6 +567,7 @@ export type AgentDefinition = {
     disallowedTools?: string[];
     prompt: string;
     model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
+    criticalSystemReminder_EXPERIMENTAL?: string;
 };
 export type SettingSource = 'user' | 'project' | 'local';
 export type SdkPluginConfig = {
@@ -575,6 +583,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;
     };
@@ -587,6 +605,7 @@ export type Options = {
      * continuing the previous session. Use with --resume.
      */
     forkSession?: boolean;
+    betas?: SdkBeta[];
     hooks?: Partial<Record<HookEvent, HookCallbackMatcher[]>>;
     includePartialMessages?: boolean;
     maxThinkingTokens?: number;
@@ -621,6 +640,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;
@@ -656,4 +711,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.
+// (c) Anthropic PBC. All rights reserved. Use is subject to the Legal Agreements outlined here: https://code.claude.com/docs/en/legal-and-compliance.
 
-// Version: 0.1.56
+// Version: 0.1.58
 
 // Want to see the unminified source? We're hiring!
 // https://job-boards.greenhouse.io/anthropic/jobs/4816199008
@@ -6458,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;
@@ -6479,6 +6495,7 @@ class ProcessTransport {
     try {
       const {
         additionalDirectories = [],
+        betas,
         cwd,
         executable = isRunningWithBun() ? "bun" : "node",
         executableArgs = [],
@@ -6504,7 +6521,8 @@ class ProcessTransport {
         strictMcpConfig,
         canUseTool,
         includePartialMessages,
-        plugins
+        plugins,
+        sandbox
       } = this.options;
       const args = [
         "--output-format",
@@ -6523,6 +6541,9 @@ class ProcessTransport {
       }
       if (model)
         args.push("--model", model);
+      if (betas && betas.length > 0) {
+        args.push("--betas", betas.join(","));
+      }
       if (jsonSchema) {
         args.push("--json-schema", JSON.stringify(jsonSchema));
       }
@@ -6547,6 +6568,18 @@ 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 }));
       }
@@ -6589,7 +6622,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 {
@@ -15054,7 +15088,7 @@ function query({
   prompt,
   options
 }) {
-  const { systemPrompt, settingSources, ...rest } = options ?? {};
+  const { systemPrompt, settingSources, sandbox, ...rest } = options ?? {};
   let customSystemPrompt;
   let appendSystemPrompt;
   if (systemPrompt === undefined) {
@@ -15070,16 +15104,18 @@ function query({
     const dirname2 = join5(filename, "..");
     pathToClaudeCodeExecutable = join5(dirname2, "cli.js");
   }
-  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.56";
+  process.env.CLAUDE_AGENT_SDK_VERSION = "0.1.58";
   const {
     abortController = createAbortController(),
     additionalDirectories = [],
     agents,
     allowedTools = [],
+    betas,
     canUseTool,
     continue: continueConversation,
     cwd: cwd2,
     disallowedTools = [],
+    tools,
     env,
     executable = isRunningWithBun() ? "bun" : "node",
     executableArgs = [],
@@ -15133,6 +15169,7 @@ function query({
   const transport = new ProcessTransport({
     abortController,
     additionalDirectories,
+    betas,
     cwd: cwd2,
     executable,
     executableArgs,
@@ -15156,12 +15193,14 @@ function query({
     settingSources: settingSources ?? [],
     allowedTools,
     disallowedTools,
+    tools,
     mcpServers: allMcpServers,
     strictMcpConfig,
     canUseTool: !!canUseTool,
     hooks: !!hooks,
     includePartialMessages,
-    plugins
+    plugins,
+    sandbox
   });
   const initConfig = {
     systemPrompt: customSystemPrompt,