@anthropic-ai/claude-agent-sdk 0.3.325 → 0.3.327

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/sdk.d.ts CHANGED
@@ -56,6 +56,9 @@ export declare type AgentDefinition = {
56
56
  * Model alias (e.g. 'fable', 'opus', 'sonnet', 'haiku') or full model ID (e.g. 'claude-fable-5'). 'inherit' uses the main model; if omitted, uses the default subagent model when one is configured, else the main model
57
57
  */
58
58
  model?: string;
59
+ /**
60
+ * MCP servers for this agent, by name or as inline config. Passing a createSdkMcpServer() server here is deprecated. It is ignored with a warning and will be an error in a later release, so put it in the top-level mcpServers option.
61
+ */
59
62
  mcpServers?: AgentMcpServerSpec[];
60
63
  /**
61
64
  * Experimental: Critical reminder added to system prompt
@@ -226,7 +229,7 @@ export declare type BaseOutputFormat = {
226
229
  *
227
230
  * @alpha
228
231
  */
229
- export declare const BUILTIN_TOOL_NAMES: readonly ['Agent', 'Artifact', 'AskUserQuestion', 'Bash', 'ClaudeDesign', 'CronCreate', 'CronDelete', 'CronList', 'Edit', 'EndConversation', 'EnterPlanMode', 'EnterWorktree', 'ExitPlanMode', 'ExitWorktree', 'Glob', 'Grep', 'ListAgents', 'ListMcpResourcesTool', 'LSP', 'Monitor', 'NotebookEdit', 'OfferChromeSetup', 'PowerShell', 'Projects', 'propose_skills', 'ProposeGoal', 'PushNotification', 'Read', 'ReadMcpResourceDirTool', 'ReadMcpResourceTool', 'ReadNotifications', 'RemoteTrigger', 'ReportFindings', 'ScheduleWakeup', 'SendFeedback', 'SendMessage', 'SendUserFile', 'SendUserMessage', 'ShareOnboardingGuide', 'ShowOnboardingRolePicker', 'Skill', 'SubagentHandback', 'TaskCreate', 'TaskGet', 'TaskList', 'TaskStop', 'TaskUpdate', 'TodoWrite', 'ToolSearch', 'WaitForMcpServers', 'WebFetch', 'WebSearch', 'Workflow', 'Write'];
232
+ export declare const BUILTIN_TOOL_NAMES: readonly ['Agent', 'Artifact', 'AskUserQuestion', 'Bash', 'ClaudeDesign', 'CronCreate', 'CronDelete', 'CronList', 'Edit', 'EndConversation', 'EnterPlanMode', 'EnterWorktree', 'ExitPlanMode', 'ExitWorktree', 'Glob', 'Grep', 'ListAgents', 'ListMcpResourcesTool', 'LSP', 'Monitor', 'NotebookEdit', 'OfferChromeSetup', 'PowerShell', 'Projects', 'propose_skills', 'PushNotification', 'Read', 'ReadMcpResourceDirTool', 'ReadMcpResourceTool', 'ReadNotifications', 'RemoteTrigger', 'ReportFindings', 'ScheduleWakeup', 'SendFeedback', 'SendMessage', 'SendUserFile', 'SendUserMessage', 'SetGoal', 'ShareOnboardingGuide', 'ShowOnboardingRolePicker', 'Skill', 'SubagentHandback', 'TaskCreate', 'TaskGet', 'TaskList', 'TaskStop', 'TaskUpdate', 'TodoWrite', 'ToolSearch', 'WaitForMcpServers', 'WebFetch', 'WebSearch', 'Workflow', 'Write'];
230
233
 
231
234
  /**
232
235
  * Permission callback function for controlling tool usage.
@@ -1054,6 +1057,9 @@ export declare interface HookCallbackMatcher {
1054
1057
  * the first prompt is sent only once those checks have passed.
1055
1058
  */
1056
1059
  onFailure?: 'continue' | 'block';
1060
+
1061
+
1062
+
1057
1063
  }
1058
1064
 
1059
1065
  export declare type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'PostToolBatch' | 'Notification' | 'UserPromptSubmit' | 'UserPromptExpansion' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PostCompact' | 'PreModelSwitch' | 'PostModelSwitch' | 'PermissionRequest' | 'PermissionDenied' | 'Setup' | 'TeammateIdle' | 'TaskCreated' | 'TaskCompleted' | 'Elicitation' | 'ElicitationResult' | 'ConfigChange' | 'WorktreeCreate' | 'WorktreeRemove' | 'InstructionsLoaded' | 'CwdChanged' | 'FileChanged' | 'DirectoryAdded' | 'MessageDisplay';
@@ -1310,8 +1316,9 @@ export declare type McpSdkServerConfig = {
1310
1316
 
1311
1317
 
1312
1318
 
1319
+
1313
1320
  /**
1314
- * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
1321
+ * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied, except a mod's own ($.tool.call, $.mcp.call). always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
1315
1322
  */
1316
1323
  tools?: McpServerToolPolicy[];
1317
1324
  };
@@ -2075,6 +2082,9 @@ export declare type Options = {
2075
2082
  * MCP (Model Context Protocol) server configurations.
2076
2083
  * Keys are server names, values are server configurations.
2077
2084
  *
2085
+ * Servers that Claude Code runs or connects to (stdio, SSE, HTTP) reach it on its command
2086
+ * line unless `mcpServersDelivery` is `'initialize'`; see that option's deprecation notice.
2087
+ *
2078
2088
  * @example
2079
2089
  * ```typescript
2080
2090
  * mcpServers: {
@@ -2086,6 +2096,34 @@ export declare type Options = {
2086
2096
  * ```
2087
2097
  */
2088
2098
  mcpServers?: Record<string, McpServerConfig>;
2099
+ /**
2100
+ * How the `mcpServers` that Claude Code runs or connects to (stdio, SSE, HTTP) reach it.
2101
+ * In-process servers (`createSdkMcpServer`) are not affected.
2102
+ * - `'argv'` (default) - Sent in one `--mcp-config` flag: works with any Claude Code version,
2103
+ * but puts server `env` and `headers` on the command line, which other users of the
2104
+ * machine can read.
2105
+ * - `'initialize'` - Sent over stdin in the initialize request, so `env` and `headers` stay
2106
+ * off the command line. The prompt waits for Claude Code's answer, and an error answer ends
2107
+ * the session. Requires the Claude Code bundled with this SDK or newer: an older one started
2108
+ * through `pathToClaudeCodeExecutable` or `spawnClaudeCodeProcess` exits at startup with an
2109
+ * unknown-option error (before 2.1.261), or has its session ended by this SDK with an error
2110
+ * naming this option. `initializationResult().mcp_servers_applied` is true when Claude Code
2111
+ * took the servers at launch, which does not mean each connected.
2112
+ *
2113
+ * A launch given `--sdk-url` (through `extraArgs` or `executableArgs`) always uses
2114
+ * `--mcp-config`, because that session cannot read the request at launch.
2115
+ *
2116
+ * Deprecation notice: sending these servers on the command line is deprecated, and a future
2117
+ * release changes the default to `'initialize'`. An app that starts its own Claude Code through
2118
+ * `pathToClaudeCodeExecutable` or `spawnClaudeCodeProcess` should update it to at least the
2119
+ * bundled version and set `'initialize'`, or set `'argv'` to stay on the command line; while it
2120
+ * leaves this option unset, this SDK emits a `DeprecationWarning` once per process (code
2121
+ * `CLAUDE_SDK_MCP_SERVERS_ARGV_DEPRECATED`). Apps that use the bundled Claude Code need not
2122
+ * update it, get no warning, and can set `'initialize'` now.
2123
+ *
2124
+ * @default 'argv'
2125
+ */
2126
+ mcpServersDelivery?: 'argv' | 'initialize';
2089
2127
  /**
2090
2128
  * Claude model to use. Defaults to the CLI default model.
2091
2129
  * Examples: 'claude-sonnet-5', 'claude-opus-4-8', 'claude-fable-5'
@@ -2409,6 +2447,8 @@ export declare type Options = {
2409
2447
  */
2410
2448
  managedSettings?: Settings;
2411
2449
 
2450
+
2451
+
2412
2452
  /**
2413
2453
  * Control which filesystem settings to load.
2414
2454
  * - `'user'` - Global user settings (`~/.claude/settings.json`)
@@ -3016,6 +3056,108 @@ export declare type ProvenanceEntry = {
3016
3056
  policyOrigin?: PolicySettingsOrigin;
3017
3057
  };
3018
3058
 
3059
+ declare const PublishedSandboxSettingsSchema: () => z.ZodObject<{
3060
+ enabled: z.ZodOptional<z.ZodBoolean>;
3061
+ failIfUnavailable: z.ZodOptional<z.ZodBoolean>;
3062
+ autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
3063
+ allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
3064
+ network: z.ZodOptional<z.ZodObject<{
3065
+ allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
3066
+ deniedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
3067
+ strictAllowlist: z.ZodOptional<z.ZodBoolean>;
3068
+ allowManagedDomainsOnly: z.ZodOptional<z.ZodBoolean>;
3069
+ allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
3070
+ allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
3071
+ allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
3072
+ allowMachLookup: z.ZodOptional<z.ZodArray<z.ZodString>>;
3073
+ httpProxyPort: z.ZodOptional<z.ZodNumber>;
3074
+ socksProxyPort: z.ZodOptional<z.ZodNumber>;
3075
+ tlsTerminate: z.ZodOptional<z.ZodObject<{
3076
+ caCertPath: z.ZodOptional<z.ZodString>;
3077
+ caKeyPath: z.ZodOptional<z.ZodString>;
3078
+ }, z.core.$strip>>;
3079
+ }, z.core.$strip>>;
3080
+ filesystem: z.ZodOptional<z.ZodObject<{
3081
+ allowWrite: z.ZodOptional<z.ZodArray<z.ZodString>>;
3082
+ denyWrite: z.ZodOptional<z.ZodArray<z.ZodString>>;
3083
+ denyRead: z.ZodOptional<z.ZodArray<z.ZodString>>;
3084
+ allowRead: z.ZodOptional<z.ZodArray<z.ZodString>>;
3085
+ allowManagedReadPathsOnly: z.ZodOptional<z.ZodBoolean>;
3086
+ disabled: z.ZodOptional<z.ZodBoolean>;
3087
+ }, z.core.$strip>>;
3088
+ credentials: z.ZodOptional<z.ZodObject<{
3089
+ files: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
3090
+ path: z.ZodString;
3091
+ mode: z.ZodEnum<{
3092
+ deny: "deny";
3093
+ mask: "mask";
3094
+ }>;
3095
+ extract: z.ZodOptional<z.ZodString>;
3096
+ onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
3097
+ deny: "deny";
3098
+ error: "error";
3099
+ warn: "warn";
3100
+ }>>;
3101
+ decode: z.ZodOptional<z.ZodEnum<{
3102
+ jwt: "jwt";
3103
+ }>>;
3104
+ maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
3105
+ maskDuplicates: z.ZodOptional<z.ZodBoolean>;
3106
+ injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
3107
+ }, z.core.$strip>, unknown>>>;
3108
+ envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
3109
+ name: z.ZodString;
3110
+ mode: z.ZodEnum<{
3111
+ deny: "deny";
3112
+ mask: "mask";
3113
+ }>;
3114
+ extract: z.ZodOptional<z.ZodString>;
3115
+ onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
3116
+ deny: "deny";
3117
+ error: "error";
3118
+ warn: "warn";
3119
+ }>>;
3120
+ decode: z.ZodOptional<z.ZodEnum<{
3121
+ jwt: "jwt";
3122
+ }>>;
3123
+ maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
3124
+ injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
3125
+ }, z.core.$strip>, unknown>>>;
3126
+ allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
3127
+ awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
3128
+ accessKeyIdVar: z.ZodString;
3129
+ secretAccessKeyVar: z.ZodString;
3130
+ sessionTokenVar: z.ZodOptional<z.ZodString>;
3131
+ }, z.core.$strip>>>;
3132
+ sigv4: z.ZodOptional<z.ZodObject<{
3133
+ streaming: z.ZodOptional<z.ZodEnum<{
3134
+ deny: "deny";
3135
+ passthrough: "passthrough";
3136
+ }>>;
3137
+ presigned: z.ZodOptional<z.ZodEnum<{
3138
+ deny: "deny";
3139
+ passthrough: "passthrough";
3140
+ }>>;
3141
+ sigv4a: z.ZodOptional<z.ZodEnum<{
3142
+ deny: "deny";
3143
+ passthrough: "passthrough";
3144
+ }>>;
3145
+ }, z.core.$strip>>;
3146
+ }, z.core.$strip>>;
3147
+ ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
3148
+ enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
3149
+ allowNestedUserNamespaces: z.ZodOptional<z.ZodBoolean>;
3150
+ enableWeakerNetworkIsolation: z.ZodOptional<z.ZodBoolean>;
3151
+ allowAppleEvents: z.ZodOptional<z.ZodBoolean>;
3152
+ excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
3153
+ ripgrep: z.ZodOptional<z.ZodObject<{
3154
+ command: z.ZodString;
3155
+ args: z.ZodOptional<z.ZodArray<z.ZodString>>;
3156
+ }, z.core.$strip>>;
3157
+ bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
3158
+ socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
3159
+ }, z.core.$loose>;
3160
+
3019
3161
  /**
3020
3162
  * Query interface with methods for controlling query execution.
3021
3163
  * Extends AsyncGenerator and has methods, so not serializable.
@@ -3596,7 +3738,7 @@ export declare type RewindFilesResult = {
3596
3738
  insertions?: number;
3597
3739
  deletions?: number;
3598
3740
  /**
3599
- * Count of tracked files NOT restored or deleted because a symlink, hard link, or other non-regular file was detected at the tracked path, its parent directory no longer resolves to where it pointed when the checkpoint was taken, or its backup could not be safely read. Only populated by a real (non-dryRun) rewind — on a dryRun response the field is never set and the preview counts do not reflect link-safety refusals. Absent or 0 on a real rewind means no link-safety refusals occurred; other per-file failures (for example a missing backup file) are not counted here; they are reported in telemetry, and when every differing file fails to restore the rewind itself fails (canRewind: false).
3741
+ * Count of tracked files NOT restored or deleted because a symlink, hard link, or other non-regular file was detected at the tracked path, its parent directory no longer resolves to where it pointed when the checkpoint was taken, it is behind a link in a folder that sandboxed commands can write, or its backup could not be safely read. Only populated by a real (non-dryRun) rewind — on a dryRun response the field is never set and the preview counts do not reflect link-safety refusals. Absent or 0 on a real rewind means no link-safety refusals occurred; other per-file failures (for example a missing backup file) are not counted here; they are reported in telemetry, and when every differing file fails to restore the rewind itself fails (canRewind: false).
3600
3742
  */
3601
3743
  skippedLinks?: number;
3602
3744
  };
@@ -3701,112 +3843,7 @@ declare const SandboxNetworkConfigSchema: () => z.ZodOptional<z.ZodObject<{
3701
3843
  }, z.core.$strip>>;
3702
3844
  }, z.core.$strip>>;
3703
3845
 
3704
- export declare type SandboxSettings = z.infer<ReturnType<typeof SandboxSettingsSchema>>;
3705
-
3706
- /**
3707
- * Sandbox settings schema.
3708
- */
3709
- declare const SandboxSettingsSchema: () => z.ZodObject<{
3710
- enabled: z.ZodOptional<z.ZodBoolean>;
3711
- failIfUnavailable: z.ZodOptional<z.ZodBoolean>;
3712
- autoAllowBashIfSandboxed: z.ZodOptional<z.ZodBoolean>;
3713
- allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
3714
- network: z.ZodOptional<z.ZodObject<{
3715
- allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
3716
- deniedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
3717
- strictAllowlist: z.ZodOptional<z.ZodBoolean>;
3718
- allowManagedDomainsOnly: z.ZodOptional<z.ZodBoolean>;
3719
- allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
3720
- allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
3721
- allowLocalBinding: z.ZodOptional<z.ZodBoolean>;
3722
- allowMachLookup: z.ZodOptional<z.ZodArray<z.ZodString>>;
3723
- httpProxyPort: z.ZodOptional<z.ZodNumber>;
3724
- socksProxyPort: z.ZodOptional<z.ZodNumber>;
3725
- tlsTerminate: z.ZodOptional<z.ZodObject<{
3726
- caCertPath: z.ZodOptional<z.ZodString>;
3727
- caKeyPath: z.ZodOptional<z.ZodString>;
3728
- }, z.core.$strip>>;
3729
- }, z.core.$strip>>;
3730
- filesystem: z.ZodOptional<z.ZodObject<{
3731
- allowWrite: z.ZodOptional<z.ZodArray<z.ZodString>>;
3732
- denyWrite: z.ZodOptional<z.ZodArray<z.ZodString>>;
3733
- denyRead: z.ZodOptional<z.ZodArray<z.ZodString>>;
3734
- allowRead: z.ZodOptional<z.ZodArray<z.ZodString>>;
3735
- allowManagedReadPathsOnly: z.ZodOptional<z.ZodBoolean>;
3736
- disabled: z.ZodOptional<z.ZodBoolean>;
3737
- }, z.core.$strip>>;
3738
- credentials: z.ZodOptional<z.ZodObject<{
3739
- files: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
3740
- path: z.ZodString;
3741
- mode: z.ZodEnum<{
3742
- deny: "deny";
3743
- mask: "mask";
3744
- }>;
3745
- extract: z.ZodOptional<z.ZodString>;
3746
- onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
3747
- deny: "deny";
3748
- error: "error";
3749
- warn: "warn";
3750
- }>>;
3751
- decode: z.ZodOptional<z.ZodEnum<{
3752
- jwt: "jwt";
3753
- }>>;
3754
- maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
3755
- maskDuplicates: z.ZodOptional<z.ZodBoolean>;
3756
- injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
3757
- }, z.core.$strip>, unknown>>>;
3758
- envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
3759
- name: z.ZodString;
3760
- mode: z.ZodEnum<{
3761
- deny: "deny";
3762
- mask: "mask";
3763
- }>;
3764
- extract: z.ZodOptional<z.ZodString>;
3765
- onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
3766
- deny: "deny";
3767
- error: "error";
3768
- warn: "warn";
3769
- }>>;
3770
- decode: z.ZodOptional<z.ZodEnum<{
3771
- jwt: "jwt";
3772
- }>>;
3773
- maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
3774
- injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
3775
- }, z.core.$strip>, unknown>>>;
3776
- allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
3777
- awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
3778
- accessKeyIdVar: z.ZodString;
3779
- secretAccessKeyVar: z.ZodString;
3780
- sessionTokenVar: z.ZodOptional<z.ZodString>;
3781
- }, z.core.$strip>>>;
3782
- sigv4: z.ZodOptional<z.ZodObject<{
3783
- streaming: z.ZodOptional<z.ZodEnum<{
3784
- deny: "deny";
3785
- passthrough: "passthrough";
3786
- }>>;
3787
- presigned: z.ZodOptional<z.ZodEnum<{
3788
- deny: "deny";
3789
- passthrough: "passthrough";
3790
- }>>;
3791
- sigv4a: z.ZodOptional<z.ZodEnum<{
3792
- deny: "deny";
3793
- passthrough: "passthrough";
3794
- }>>;
3795
- }, z.core.$strip>>;
3796
- }, z.core.$strip>>;
3797
- ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
3798
- enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
3799
- allowNestedUserNamespaces: z.ZodOptional<z.ZodBoolean>;
3800
- enableWeakerNetworkIsolation: z.ZodOptional<z.ZodBoolean>;
3801
- allowAppleEvents: z.ZodOptional<z.ZodBoolean>;
3802
- excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
3803
- ripgrep: z.ZodOptional<z.ZodObject<{
3804
- command: z.ZodString;
3805
- args: z.ZodOptional<z.ZodArray<z.ZodString>>;
3806
- }, z.core.$strip>>;
3807
- bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
3808
- socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
3809
- }, z.core.$loose>;
3846
+ export declare type SandboxSettings = z.infer<ReturnType<typeof PublishedSandboxSettingsSchema>>;
3810
3847
 
3811
3848
  /**
3812
3849
  * Emitted when the user's /goal Stop hook reports met (clears) or not-yet-met (bumps iterations + last_reason). Any surface with a goal indicator re-renders from this. value is null when the goal is cleared. From internal QueryEvent 'active_goal'.
@@ -4342,6 +4379,7 @@ export declare type SDKControlGetContextUsageResponse = {
4342
4379
  cache_read_input_tokens: number;
4343
4380
  } | null;
4344
4381
 
4382
+
4345
4383
  };
4346
4384
 
4347
4385
  /**
@@ -4479,7 +4517,7 @@ declare type SDKControlGetHooksListingResponse = {
4479
4517
  exitHint: string;
4480
4518
  };
4481
4519
  /**
4482
- * Present only under --bare / CLAUDE_CODE_SIMPLE with the hooks surface gated off: settings-file, flag, policy, and plugin hooks never fire there; session hooks still run.
4520
+ * Present only under --bare / CLAUDE_CODE_SIMPLE with the hooks surface gated off: settings-file, flag, policy, and a person's plugin hooks never fire there; session hooks and the hooks of plugins managed settings enable still run.
4483
4521
  */
4484
4522
  bareMode?: {
4485
4523
  /**
@@ -4836,7 +4874,7 @@ declare type SDKControlInitializeRequest = {
4836
4874
  hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
4837
4875
  sdkMcpServers?: string[];
4838
4876
  /**
4839
- * Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout, disableAutoBackground, connectorId, autoModeVerdictTools and dataFlowServer apply when the server is first registered; tools (the per-tool permission policy) adds its ask and deny rules on every initialize that names the server. An initialize never removes a rule; mcp_set_servers replaces them.
4877
+ * Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout, disableAutoBackground, connectorId, autoModeVerdictTools, dataFlowServer and onPersonsMachine apply when the server is first registered; tools (the per-tool permission policy) adds its ask and deny rules on every initialize that names the server. An initialize never removes a rule; mcp_set_servers replaces them.
4840
4878
  */
4841
4879
  sdkMcpServerConfigs?: Record<string, {
4842
4880
  /**
@@ -4847,8 +4885,9 @@ declare type SDKControlInitializeRequest = {
4847
4885
 
4848
4886
 
4849
4887
 
4888
+
4850
4889
  /**
4851
- * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
4890
+ * Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied, except a mod's own ($.tool.call, $.mcp.call). always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
4852
4891
  */
4853
4892
  tools?: coreTypes.McpServerToolPolicy[];
4854
4893
  }>;
@@ -4914,10 +4953,17 @@ declare type SDKControlInitializeRequest = {
4914
4953
  perTaskStopAffordance?: boolean;
4915
4954
 
4916
4955
 
4956
+
4917
4957
  /**
4918
4958
  * Plugins to load for the session, in the same shape as the SDK `plugins` option: the stdin form of one --plugin-dir flag per entry (--plugin-dir-no-mcp when skipMcpDiscovery is set), so the launch command line does not grow with the plugin count. Loaded only by a CLI launched with --await-initialize, which reads this request during startup before any plugin work. Without that flag, on a repeated initialize, or over a remote session transport the field loads nothing; plugins_applied in the response reports whether the listed plugins are in fact loaded.
4919
4959
  */
4920
4960
  plugins?: coreTypes.SdkPluginConfig[];
4961
+ /**
4962
+ * MCP servers for Claude Code to run or connect to, keyed by server name: the serializable entries of the SDK `mcpServers` option (host-resident servers go in sdkMcpServers), as the stdin form of one --mcp-config item, which keeps server credentials (stdio `env`, http and sse `headers`) off the command line. Read only at launch under --await-initialize, and then handled as --mcp-config: an invalid entry is skipped and reported in system/init, not fatal; one difference is that a Claude Code process this one starts is not handed them. Without that flag, on a repeated initialize, or over a remote session transport it loads nothing; use mcp_set_servers in a running session. mcp_servers_applied in the response says whether these are the set read at launch.
4963
+ */
4964
+ mcpServers?: Record<string, coreTypes.McpServerConfigForProcessTransport>;
4965
+
4966
+
4921
4967
 
4922
4968
 
4923
4969
 
@@ -4954,6 +5000,7 @@ export declare type SDKControlInitializeResponse = {
4954
5000
  hook_on_failure_supported?: boolean;
4955
5001
 
4956
5002
 
5003
+
4957
5004
  /**
4958
5005
  * Whether every plugin this initialize listed is loaded: true when each one is among the plugins the process loaded at launch (from `plugins` under --await-initialize, or from --plugin-dir), so a re-sent initialize naming the launch set also reads true; false otherwise. The `plugins` field never loads anything after launch. Absent when the request listed no plugins, and on CLIs that predate the field (those never read `plugins`).
4959
5006
  */
@@ -4961,6 +5008,12 @@ export declare type SDKControlInitializeResponse = {
4961
5008
 
4962
5009
 
4963
5010
 
5011
+ /**
5012
+ * Whether the `mcpServers` in this initialize are the set the process read at launch under --await-initialize, so a re-sent initialize naming the same set also reads true; false otherwise. True says they were taken as an --mcp-config item, not that each one connected: a server missing from system/init mcp_servers was not loaded. The field loads nothing after launch. Absent when the request named none, and on CLIs that predate the field, which never read `mcpServers`: a host that sent servers must treat absence as not applied.
5013
+ */
5014
+ mcp_servers_applied?: boolean;
5015
+
5016
+
4964
5017
  /**
4965
5018
  * What became of each entry of this initialize's sdkMcpServerManifests, keyed by sdk server name, for the entries whose name is in sdkMcpServers. 'parked': kept for the connect that follows this reply, which answers the server's MCP initialize and first tools/list from it (a later failure to replay shows up as live mcp_message frames, as when no entry was sent). 'already_connected': this CLI already had a live client for the server. 'protocol_version_mismatch': initializeResult.protocolVersion is not the version this CLI's client requests. 'malformed': the entry is not of the documented shape, reported whether or not manifests were honoured (every name in sdkMcpServers gets this when the field itself is not an object); or an honoured entry is past the limits this CLI sets on a live answer. 'not_honoured': the CLI did not use the entry: manifests are switched off in this CLI, this remote session is not an interactive Cowork chat started from claude.ai, the session service has not recently told this remote-session worker that only the account owning the session can send events to it, or the request reached such a worker other than over its session stream (nothing for the host to change in any of these cases); or this CLI had read as many tool lists as it allows in a minute (send it again later); or it came over the session stream without sdkMcpServerManifestsOrigin or on a frame too old to trust (the host's to fix). Absent when the request carried no sdkMcpServerManifests or named no sdkMcpServers, and on CLIs that predate the field.
4966
5019
  */
@@ -5225,6 +5278,7 @@ declare type SDKControlPermissionRequest = {
5225
5278
  * True when the dialog must not offer the persistent "don't ask again" row for this ask: accepting it would write a whole-tool allow rule broader than the ask's own verb (PermissionAskDecision.suppressAlwaysAllowRule), or the ask comes from a run a plugin started, where Claude Code saves no rule from the answer, not even for the session. Hosts rendering approve options should omit any persistent-rule affordance when set.
5226
5279
  */
5227
5280
  suppress_always_allow_rule?: boolean;
5281
+
5228
5282
  /**
5229
5283
  * True when the ask must not be approvable by a single stray keystroke (PermissionAskDecision.defaultToNo): a terminal-style prompt opens on its decline option and takes no digit shortcut. Hosts rendering approve options should not pre-select approve when set.
5230
5284
  */
@@ -5650,6 +5704,9 @@ declare type SDKHookCallbackMatcher = {
5650
5704
  * What a failure of these callbacks does: the client answered the hook_callback request with an error, or with an answer that fails validation. 'continue' (default): the failure is reported and the action goes ahead. 'block': the failure counts as a block, as it does for a command hook, so the action the event guards (a tool call, a permission request, a prompt) is blocked. Ignored on Stop, SubagentStop, TaskCompleted and TeammateIdle.
5651
5705
  */
5652
5706
  onFailure?: 'continue' | 'block';
5707
+
5708
+
5709
+
5653
5710
  };
5654
5711
 
5655
5712
  /**
@@ -5673,6 +5730,7 @@ export declare type SDKHookProgressMessage = {
5673
5730
  stdout: string;
5674
5731
  stderr: string;
5675
5732
  output: string;
5733
+
5676
5734
  uuid: UUID;
5677
5735
  session_id: string;
5678
5736
  };
@@ -5698,6 +5756,9 @@ export declare type SDKHookStartedMessage = {
5698
5756
  hook_id: string;
5699
5757
  hook_name: string;
5700
5758
  hook_event: string;
5759
+
5760
+
5761
+
5701
5762
  uuid: UUID;
5702
5763
  session_id: string;
5703
5764
  };
@@ -5845,6 +5906,7 @@ export declare type SDKMessageOrigin = {
5845
5906
 
5846
5907
 
5847
5908
 
5909
+
5848
5910
  } | {
5849
5911
  kind: 'task-notification';
5850
5912
  /**
@@ -6090,6 +6152,7 @@ export declare type SdkPluginConfig = {
6090
6152
  * When true, the engine loads skills/hooks/agents/commands from this plugin but does NOT read its .mcp.json or manifest mcpServers. Use when the SDK host owns this plugin's MCP connections.
6091
6153
  */
6092
6154
  skipMcpDiscovery?: boolean;
6155
+
6093
6156
  };
6094
6157
 
6095
6158
  /**
@@ -6168,7 +6231,7 @@ export declare type SDKResultError = {
6168
6231
  num_turns: number;
6169
6232
  stop_reason: string | null;
6170
6233
  /**
6171
- * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, a resumed or forked session continues from the total its transcript saved, when it has one (so the first result already carries the earlier turns; maxBudgetUsd counts only the spend since this query() call started or last /clear), and a mid-session /clear resets the running total. An estimate, not a billing statement.
6234
+ * Cumulative estimated cost in USD for this query() call, covering the same calls as modelUsage (billed permission classifier calls and stopped or cut calls included, which maxBudgetUsd / --max-budget-usd therefore counts) and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, a resumed or forked session continues from the total its transcript saved, when it has one (so the first result already carries the earlier turns; maxBudgetUsd counts only the spend since this query() call started or last /clear), and a mid-session /clear resets the running total. An estimate, not a billing statement.
6172
6235
  */
6173
6236
  total_cost_usd: number;
6174
6237
  /**
@@ -6176,7 +6239,7 @@ export declare type SDKResultError = {
6176
6239
  */
6177
6240
  usage: NonNullableUsage;
6178
6241
  /**
6179
- * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, a resumed or forked session continues from the totals its transcript saved, when it has them (so the first result already carries the earlier turns), and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
6242
+ * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Auto mode's permission classifier calls are included where they are billed (not on Pro, Max or Team plans, nor on a claude.ai sign-in whose plan cannot be read), and so is a call stopped or cut mid-response, with its output tokens estimated from what had streamed (low when a long tool call was being written, since the API holds a call's input until it is whole). Other internal helper calls outside the query pipeline (e.g. token-count probes) are excluded; crash/startup-error results may carry zeroed usage, a resumed or forked session continues from the totals its transcript saved, when it has them (so the first result already carries the earlier turns), and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
6180
6243
  */
6181
6244
  modelUsage: Record<string, ModelUsage>;
6182
6245
 
@@ -6229,6 +6292,7 @@ export declare type SDKResultError = {
6229
6292
 
6230
6293
 
6231
6294
 
6295
+
6232
6296
  terminal_reason?: TerminalReason;
6233
6297
 
6234
6298
 
@@ -6295,6 +6359,7 @@ export declare type SDKResultSuccess = {
6295
6359
 
6296
6360
 
6297
6361
 
6362
+
6298
6363
 
6299
6364
 
6300
6365
  user_message_uuid?: string;
@@ -6341,7 +6406,7 @@ export declare type SDKResultSuccess = {
6341
6406
  result: string;
6342
6407
  stop_reason: string | null;
6343
6408
  /**
6344
- * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, a resumed or forked session continues from the total its transcript saved, when it has one (so the first result already carries the earlier turns; maxBudgetUsd counts only the spend since this query() call started or last /clear), and a mid-session /clear resets the running total. An estimate, not a billing statement.
6409
+ * Cumulative estimated cost in USD for this query() call, covering the same calls as modelUsage (billed permission classifier calls and stopped or cut calls included, which maxBudgetUsd / --max-budget-usd therefore counts) and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, a resumed or forked session continues from the total its transcript saved, when it has one (so the first result already carries the earlier turns; maxBudgetUsd counts only the spend since this query() call started or last /clear), and a mid-session /clear resets the running total. An estimate, not a billing statement.
6345
6410
  */
6346
6411
  total_cost_usd: number;
6347
6412
  /**
@@ -6349,7 +6414,7 @@ export declare type SDKResultSuccess = {
6349
6414
  */
6350
6415
  usage: NonNullableUsage;
6351
6416
  /**
6352
- * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, a resumed or forked session continues from the totals its transcript saved, when it has them (so the first result already carries the earlier turns), and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
6417
+ * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Auto mode's permission classifier calls are included where they are billed (not on Pro, Max or Team plans, nor on a claude.ai sign-in whose plan cannot be read), and so is a call stopped or cut mid-response, with its output tokens estimated from what had streamed (low when a long tool call was being written, since the API holds a call's input until it is whole). Other internal helper calls outside the query pipeline (e.g. token-count probes) are excluded; crash/startup-error results may carry zeroed usage, a resumed or forked session continues from the totals its transcript saved, when it has them (so the first result already carries the earlier turns), and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
6353
6418
  */
6354
6419
  modelUsage: Record<string, ModelUsage>;
6355
6420
 
@@ -6483,9 +6548,9 @@ export declare type SDKSettingsParseError = {
6483
6548
  };
6484
6549
 
6485
6550
  /**
6486
- * Why Claude Code refused to start, so a host can offer the fix instead of a retry. org_pin_api_key_conflict: managed settings pin a first-party or Cloud gateway sign-in, and an Anthropic API key or auth token is configured instead. provider_not_allowed: managed settings list the API providers this machine may use (allowedProviders), and the session is set up for one that is not listed. org_verify_failed: the sign-in's organization could not be verified against the pin (network, or a revoked token). org_pin_mismatch: the sign-in belongs to an organization the pin does not allow. managed_settings_invalid: managed policy settings could not be read, the pin names no organization, or managed model settings (deniedModels, or an availableModels list matched exactly) block the default model and leave no allowed model to use instead. remote_settings_required_unavailable: managed settings the organization requires could not be loaded. gateway_signin_required: the Cloud gateway ended this sign-in. gateway_access_denied: the Cloud gateway refused managed settings for this account. proxy_invalid: a proxy setting is not a complete URL. temp_dir_unusable: the per-user temp directory is unsafe or could not be created. cwd_unavailable: the working directory was deleted, moved or cannot be read. shell_tool_missing: Windows has no shell tool: Git Bash is missing, and PowerShell is missing or turned off by CLAUDE_CODE_USE_POWERSHELL_TOOL. session_held_by_background: the conversation to resume or continue is running as a background session. worktree_resume_refused: the resume was refused because the session's worktree failed its safety checks or the resume was launched from inside it; errors says whether a re-run continues without the worktree. worktree_unverified: the session's worktree could not be verified right now; retrying may succeed. cli_version_too_old: this Claude Code version is below the minimum Anthropic requires. bypass_root: bypass permissions mode was requested while running as root. org_config_required_unavailable: the organization requires its policy limits and managed settings before a session starts, and they could not be loaded (network, proxy, or an Anthropic error); retrying may succeed. org_config_refused: the organization requires its policy limits and managed settings, and Anthropic refused them for this sign-in (expired or revoked session, or the organization does not allow Claude Code for this account); signing in again or an admin's change is the fix, not a retry. sandbox_required_unavailable: a working sandbox is required and it cannot run in this session, for example because bubblewrap is missing or the platform is not supported; make the sandbox available or have the requirement changed. initialize_not_first: Claude Code was started with --await-initialize, and its first stdin line was not the initialize control request (another message, or not valid JSON). Either the host wrote something else first, or a wrapper script between the host and Claude Code read or changed that line; the fix is in the host or the wrapper script, not a retry. config_file_invalid: a configuration file read at start-up is not valid JSON; errors names the file and, for the global configuration file, how to restore or repair it, and invalid_config_file has the paths as fields. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help. managed_settings_not_delivered: Claude Code was started with --managed-settings-in-initialize and could not use the managed settings in the initialize control request. Stdin ended or failed first, or its first line was too long; the request has no managedSettings object, that object could not be used, or the request's plugins field is malformed; or the launch does not read that request at start-up or also passes --managed-settings. errors says which. Claude Code starts no session without them; the fix is in the host or in a wrapper script between it and Claude Code, not a retry.
6551
+ * Why Claude Code refused to start, so a host can offer the fix instead of a retry. org_pin_api_key_conflict: managed settings pin a first-party or Cloud gateway sign-in, and an Anthropic API key or auth token is configured instead. provider_not_allowed: managed settings list the API providers this machine may use (allowedProviders), and the session is set up for one that is not listed. org_verify_failed: the sign-in's organization could not be verified against the pin (network, or a revoked token). org_pin_mismatch: the sign-in belongs to an organization the pin does not allow. managed_settings_invalid: managed policy settings could not be read, the pin names no organization, or managed model settings (deniedModels, or an availableModels list matched exactly) block the default model and leave no allowed model to use instead. remote_settings_required_unavailable: managed settings the organization requires could not be loaded. gateway_signin_required: the Cloud gateway ended this sign-in. gateway_access_denied: the Cloud gateway refused managed settings for this account. proxy_invalid: a proxy setting is not a complete URL. temp_dir_unusable: the per-user temp directory is unsafe or could not be created. cwd_unavailable: the working directory was deleted, moved or cannot be read, or (not on Windows) a folder name in its path is not valid UTF-8 and a different file, folder or link stands at the name Claude Code reads it as, for that folder or one above it; start from another directory, rename that folder, or remove the other entry. shell_tool_missing: Windows has no shell tool: Git Bash is missing, and PowerShell is missing or turned off by CLAUDE_CODE_USE_POWERSHELL_TOOL. session_held_by_background: the conversation to resume or continue is running as a background session. worktree_resume_refused: the resume was refused because the session's worktree failed its safety checks or the resume was launched from inside it; errors says whether a re-run continues without the worktree. worktree_unverified: the session's worktree could not be verified right now; retrying may succeed. cli_version_too_old: this Claude Code version is below the minimum Anthropic requires. bypass_root: bypass permissions mode was requested while running as root. org_config_required_unavailable: the organization requires its policy limits and managed settings before a session starts, and they could not be loaded (network, proxy, or an Anthropic error); retrying may succeed. org_config_refused: the organization requires its policy limits and managed settings, and Anthropic refused them for this sign-in (expired or revoked session, or the organization does not allow Claude Code for this account); signing in again or an admin's change is the fix, not a retry. sandbox_required_unavailable: a working sandbox is required and it cannot run in this session, for example because bubblewrap is missing or the platform is not supported; make the sandbox available or have the requirement changed. initialize_not_first: Claude Code was started with --await-initialize, and its first stdin line was not the initialize control request (another message, or not valid JSON). Either the host wrote something else first, or a wrapper script between the host and Claude Code read or changed that line; the fix is in the host or the wrapper script, not a retry. config_file_invalid: a configuration file read at start-up is not valid JSON; errors names the file and, for the global configuration file, how to restore or repair it, and invalid_config_file has the paths as fields. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help. managed_settings_not_delivered: Claude Code was started with --managed-settings-in-initialize and could not use the managed settings in the initialize control request. Stdin ended or failed first, or its first line was too long; the request has no managedSettings object, that object could not be used, or the request's plugins or mcpServers field is malformed; or the launch does not read that request at start-up or also passes --managed-settings. errors says which. Claude Code starts no session without them; the fix is in the host or in a wrapper script between it and Claude Code, not a retry. initialize_fields_not_delivered: as managed_settings_not_delivered, for --initialize-fields and the settings or disallowedTools that it names; also when a named field's own flag (--settings, --disallowedTools) is passed too.
6487
6552
  */
6488
- export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | 'provider_not_allowed' | 'org_verify_failed' | 'org_pin_mismatch' | 'managed_settings_invalid' | 'remote_settings_required_unavailable' | 'gateway_signin_required' | 'gateway_access_denied' | 'proxy_invalid' | 'temp_dir_unusable' | 'cwd_unavailable' | 'shell_tool_missing' | 'session_held_by_background' | 'worktree_resume_refused' | 'worktree_unverified' | 'cli_version_too_old' | 'bypass_root' | 'org_config_required_unavailable' | 'org_config_refused' | 'sandbox_required_unavailable' | 'initialize_not_first' | 'config_file_invalid' | 'managed_settings_not_delivered';
6553
+ export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | 'provider_not_allowed' | 'org_verify_failed' | 'org_pin_mismatch' | 'managed_settings_invalid' | 'remote_settings_required_unavailable' | 'gateway_signin_required' | 'gateway_access_denied' | 'proxy_invalid' | 'temp_dir_unusable' | 'cwd_unavailable' | 'shell_tool_missing' | 'session_held_by_background' | 'worktree_resume_refused' | 'worktree_unverified' | 'cli_version_too_old' | 'bypass_root' | 'org_config_required_unavailable' | 'org_config_refused' | 'sandbox_required_unavailable' | 'initialize_not_first' | 'config_file_invalid' | 'managed_settings_not_delivered' | 'initialize_fields_not_delivered';
6489
6554
 
6490
6555
  export declare type SDKStatus = 'compacting' | 'requesting' | null;
6491
6556
 
@@ -6603,6 +6668,7 @@ export declare type SDKSystemMessage = {
6603
6668
 
6604
6669
 
6605
6670
 
6671
+
6606
6672
  uuid: UUID;
6607
6673
  session_id: string;
6608
6674
  };
@@ -6623,6 +6689,7 @@ export declare type SDKTaskNotificationMessage = {
6623
6689
  reason?: 'worker_restart';
6624
6690
  output_file: string;
6625
6691
  summary: string;
6692
+
6626
6693
  usage?: {
6627
6694
  total_tokens: number;
6628
6695
  tool_uses: number;
@@ -6709,6 +6776,9 @@ export declare type SDKTaskStartedMessage = {
6709
6776
  * meta.name from the workflow script (e.g. 'spec'). Only set when task_type is 'local_workflow'.
6710
6777
  */
6711
6778
  workflow_name?: string;
6779
+ /**
6780
+ * Text describing what this run was asked. Absent on a subagent run that Claude Code resumed with text of its own (such as a background task's notice); keep the prompt an earlier task_started gave. On a run that continues an interrupted turn, this is the task's description.
6781
+ */
6712
6782
  prompt?: string;
6713
6783
  /**
6714
6784
  * Ambient/housekeeping task. Consumers should hide this from the inline transcript; it may still appear in a tasks panel.
@@ -6908,6 +6978,7 @@ export declare type SDKUserMessage = {
6908
6978
 
6909
6979
 
6910
6980
 
6981
+
6911
6982
 
6912
6983
 
6913
6984
  /**
@@ -7011,6 +7082,7 @@ export declare type SDKUserMessageReplay = {
7011
7082
 
7012
7083
 
7013
7084
 
7085
+
7014
7086
 
7015
7087
 
7016
7088
  /**
@@ -7445,7 +7517,7 @@ export declare interface Settings {
7445
7517
  [k: string]: unknown;
7446
7518
  };
7447
7519
  /**
7448
- * The claude.ai Project this session names for your organization's usage reports: the Project's ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project. An empty string names none and stops lower-precedence files from naming one; the organization default still applies. Sent only when Claude Code uses your claude.ai login, connects directly to the Anthropic API, is not in a cloud session, and CLAUDE_CODE_ATTRIBUTION_HEADER is not 0. CLAUDE_CODE_ATTRIBUTION_PROJECT takes precedence over it. Set in managed settings, it overrides people's own settings files. A project's .claude/settings.json and settings.local.json count only once the folder is trusted; for runs in a folder nobody has trusted, such as CI, use CLAUDE_CODE_ATTRIBUTION_PROJECT.
7520
+ * The claude.ai Project this session names for your organization's usage reports: the Project's ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project. An empty string names none and stops lower-precedence files from naming one; the organization default still applies. A Project is sent only when Claude Code uses your claude.ai login, connects directly to the Anthropic API, is not in a cloud session, and CLAUDE_CODE_ATTRIBUTION_HEADER is not 0. CLAUDE_CODE_ATTRIBUTION_PROJECT takes precedence over it. Set in managed settings, it overrides people's own settings files. A project's .claude/settings.json and settings.local.json count only once the folder is trusted; for runs in a folder nobody has trusted, such as CI, use CLAUDE_CODE_ATTRIBUTION_PROJECT. Behind a Claude apps gateway that reports usage by group, name one of your groups instead, such as "payments"; CLAUDE_CODE_ATTRIBUTION_HEADER does not affect that.
7449
7521
  */
7450
7522
  attributionProject?: string;
7451
7523
  /**
@@ -7453,7 +7525,7 @@ export declare interface Settings {
7453
7525
  */
7454
7526
  attributionProjectPolicy?: {
7455
7527
  /**
7456
- * The Project used when neither CLAUDE_CODE_ATTRIBUTION_PROJECT nor attributionProject names one: its ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project.
7528
+ * The Project used when neither CLAUDE_CODE_ATTRIBUTION_PROJECT nor attributionProject names one: its ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project. Behind a Claude apps gateway that reports usage by group, a group name instead.
7457
7529
  */
7458
7530
  default?: string;
7459
7531
  };
@@ -7810,7 +7882,7 @@ export declare interface Settings {
7810
7882
  */
7811
7883
  onFailure?: 'continue' | 'block';
7812
7884
  /**
7813
- * Additional headers to include in the request. Values may reference environment variables using $VAR_NAME or ${VAR_NAME} syntax (e.g., "Authorization": "Bearer $MY_TOKEN"). Only variables listed in allowedEnvVars will be interpolated.
7885
+ * Additional headers to include in the request. Values may reference environment variables using $VAR_NAME or ${VAR_NAME} syntax (e.g., "Authorization": "Bearer $MY_TOKEN"). Only variables listed in allowedEnvVars will be interpolated. Content-Length and Transfer-Encoding given here are ignored: Claude Code works out the request's length from its body.
7814
7886
  */
7815
7887
  headers?: {
7816
7888
  [k: string]: string;
@@ -7912,11 +7984,11 @@ export declare interface Settings {
7912
7984
  */
7913
7985
  disableWorkflows?: boolean;
7914
7986
  /**
7915
- * Deprecated: use enableArtifact: false. Still honored — true disables the Artifact tool; false is ignored.
7987
+ * Deprecated: use enableArtifact: false. Still honored — true turns Artifacts off; false is ignored.
7916
7988
  */
7917
7989
  disableArtifact?: boolean;
7918
7990
  /**
7919
- * Turn the Artifact tool on or off. Off in any of managed, --settings, or user settings wins; project and local settings can only turn it off. Unset defaults to on once the feature is available.
7991
+ * Turn Artifacts on or off. Off in any of managed, --settings, or user settings wins; project and local settings can only turn it off. Unset defaults to on once the feature is available.
7920
7992
  */
7921
7993
  enableArtifact?: boolean;
7922
7994
  /**
@@ -7964,11 +8036,11 @@ export declare interface Settings {
7964
8036
  */
7965
8037
  allowManagedHooksOnly?: boolean;
7966
8038
  /**
7967
- * Allowlist of URL patterns that HTTP hooks may target. Supports * as a wildcard (e.g. "https://hooks.example.com/*"). When set, HTTP hooks with non-matching URLs are blocked. If undefined, all URLs are allowed. If empty array, no HTTP hooks are allowed. Arrays merge across settings sources (same semantics as allowedMcpServers).
8039
+ * Allowlist of URL patterns that HTTP hooks may target. Supports * as a wildcard (e.g. "https://hooks.example.com/*"). When set, HTTP hooks with non-matching URLs are blocked. If undefined, all URLs are allowed. If empty array, no HTTP hooks are allowed. Arrays merge across settings sources (same semantics as allowedMcpServers). Where managed settings do not set this list, a list in any other settings file does not apply to hooks that managed settings define, or that come from a plugin they enable from a local folder they name.
7968
8040
  */
7969
8041
  allowedHttpHookUrls?: string[];
7970
8042
  /**
7971
- * Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective allowedEnvVars is the intersection with this list. If undefined, no restriction is applied. Arrays merge across settings sources (same semantics as allowedMcpServers).
8043
+ * Allowlist of environment variable names HTTP hooks may interpolate into headers. When set, each hook's effective allowedEnvVars is the intersection with this list. If undefined, no restriction is applied. Arrays merge across settings sources (same semantics as allowedMcpServers). Where managed settings do not set this list, a list in any other settings file does not apply to hooks that managed settings define, or that come from a plugin they enable from a local folder they name.
7972
8044
  */
7973
8045
  httpHookAllowedEnvVars?: string[];
7974
8046
  /**
@@ -8040,7 +8112,7 @@ export declare interface Settings {
8040
8112
  [k: string]: unknown;
8041
8113
  })[];
8042
8114
  /**
8043
- * Deprecated: no longer has any effect. Subagent rows always use the default look.
8115
+ * Deprecated: still works, and will stop working in a future release. Custom per-subagent status line shown in the agent panel; receives row context as JSON on stdin
8044
8116
  */
8045
8117
  subagentStatusLine?: {
8046
8118
  type: 'command';
@@ -8055,7 +8127,7 @@ export declare interface Settings {
8055
8127
  };
8056
8128
  };
8057
8129
  /**
8058
- * Managed plugins (plugin\@marketplace ids that managed enabledPlugins sets true) whose hooks run first, outermost, in the listed order: the first id listed sees every event before any other plugin and every result after it. Managed plugins read in place from a local folder managed settings name, and not listed here or in appendPlugins, follow the listed ones; user, project and marketplace plugins come after those, with a managed plugin from a remote marketplace that neither key lists; then appendPlugins; then the built-in plugins. The bundled cc-plugin-sec-default\@builtin seats itself outermost (on a machine with managed settings and for Team and Enterprise organizations) unless this list is set, in which case list it where it should sit or leave it out. Name it there as sec-default\@builtin, the id every release reads, for as long as any machine in the organization may run a release from before its rename; a release that knows the new id reads either. Any other id that is not an enabled managed plugin is skipped; an id listed in both keys is prepended. Only honored from managed settings (or, on a machine with none, from user settings for your own plugins); ignored in project, local and --settings sources.
8130
+ * Managed plugins (plugin\@marketplace ids that managed enabledPlugins sets true) whose hooks run first, outermost, in the listed order: the first id listed sees every event before any other plugin and every result after it. Managed plugins from a local folder or a remote marketplace managed settings name, and not listed here or in appendPlugins, follow the listed ones; user, project and marketplace plugins come after those; then appendPlugins; then the built-in plugins. The bundled cc-plugin-sec-default\@builtin seats itself outermost (on a machine with managed settings and for Team and Enterprise organizations) unless this list is set, in which case list it where it should sit or leave it out. Name it there as sec-default\@builtin, the id every release reads, for as long as any machine in the organization may run a release from before its rename; a release that knows the new id reads either. Any other id that is not an enabled managed plugin is skipped; an id listed in both keys is prepended. Only honored from managed settings (or, on a machine with none, from user settings for your own plugins); ignored in project, local and --settings sources.
8059
8131
  */
8060
8132
  prependPlugins?: string[];
8061
8133
  /**
@@ -8319,7 +8391,7 @@ export declare interface Settings {
8319
8391
  */
8320
8392
  autoUpdate?: boolean;
8321
8393
  /**
8322
- * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it, declare its marketplace with a remote source and list it in prependPlugins or appendPlugins.
8394
+ * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it and declare its marketplace with a remote source.
8323
8395
  */
8324
8396
  pluginDigests?: {
8325
8397
  [k: string]: string[];
@@ -8583,7 +8655,7 @@ export declare interface Settings {
8583
8655
  */
8584
8656
  autoUpdate?: boolean;
8585
8657
  /**
8586
- * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it, declare its marketplace with a remote source and list it in prependPlugins or appendPlugins.
8658
+ * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it and declare its marketplace with a remote source.
8587
8659
  */
8588
8660
  pluginDigests?: {
8589
8661
  [k: string]: string[];
@@ -9348,13 +9420,17 @@ export declare interface Settings {
9348
9420
  */
9349
9421
  parentSettingsBehavior?: 'first-wins' | 'merge';
9350
9422
  /**
9351
- * Controls how the managed settings sources compose. "first-wins" (default): the highest-priority source present (server-managed > MDM (managed plist / HKLM) > managed-settings.json) is the managed tier alone. "merge": every present source deep-merges with fixed precedence server-managed > MDM > managed-settings.json — scalars take the highest source's value (a restrictive boolean or enum — the allowManaged*Only locks, the disable* switches, the sandbox lock family — takes the strictest value any source sets) and arrays union, except fallbackModel, the restriction allowlists allowedMcpServers, allowedProviders, availableModels, strictKnownMarketplaces and allowedChannelPlugins, and sandbox.credentials.awsPairs and sandbox.ripgrep (the highest source that sets one owns it whole), modelOverrides (the whole map of the highest source that sets it, dropped when that source sits below the one that sets availableModels), managedMcpServers (server names union; a name set by two sources takes the higher source's whole entry), and the keys taken from the highest source only: the auth pins forceLoginOrgUUID, forceLoginMethod, forceLoginGatewayUrl and gatewayInternalNetworks, the credential helpers apiKeyHelper, awsAuthRefresh, awsCredentialExport, gcpAuthRefresh, otelHeadersHelper and proxyAuthHelper, modelPicker, permissions.defaultMode, parentSettingsBehavior and the policyHelper configuration (env keeps its own per-key union). In both modes, a forceLoginOrgUUID, or a forceLoginMethod of claudeai or console, that this machine's own MDM policy or managed settings file sets applies ahead of server-managed settings. Honored only from the highest-priority source present; enable it only when every lower source is admin-controlled, since lower sources then contribute entries such as permissions.allow. HKCU and --managed-settings never take part in the merge.
9423
+ * Controls how the managed settings sources compose. "first-wins" (default): the highest-priority source present (server-managed > MDM (managed plist / HKLM) > managed-settings.json) is the managed tier alone. "merge": every present source deep-merges with fixed precedence server-managed > MDM > managed-settings.json — scalars take the highest source's value (a restrictive boolean or enum — the allowManaged*Only locks, the disable* switches, the sandbox lock family — takes the strictest value any source sets) and arrays union, except fallbackModel, the restriction allowlists allowedMcpServers, allowedProviders, availableModels, strictKnownMarketplaces and allowedChannelPlugins, and sandbox.credentials.awsPairs and sandbox.ripgrep (the highest source that sets one owns it whole), modelOverrides (the whole map of the highest source that sets it, dropped when that source sits below the one that sets availableModels), managedMcpServers (server names union; a name set by two sources takes the higher source's whole entry), and the keys taken from the highest source only: the auth pins forceLoginOrgUUID, forceLoginMethod, forceLoginGatewayUrl and gatewayInternalNetworks, allowNestedModelAccessUnderForceLogin, the credential helpers apiKeyHelper, awsAuthRefresh, awsCredentialExport, gcpAuthRefresh, otelHeadersHelper and proxyAuthHelper, modelPicker, permissions.defaultMode, parentSettingsBehavior and the policyHelper configuration (env keeps its own per-key union). In both modes, a forceLoginOrgUUID, or a forceLoginMethod of claudeai or console, that this machine's own MDM policy or managed settings file sets applies ahead of server-managed settings. Honored only from the highest-priority source present; enable it only when every lower source is admin-controlled, since lower sources then contribute entries such as permissions.allow. HKCU and --managed-settings never take part in the merge.
9352
9424
  */
9353
9425
  managedSourcesBehavior?: 'first-wins' | 'merge';
9354
9426
  /**
9355
9427
  * Organization UUID to require for OAuth login. Accepts a single UUID string or an array of UUIDs (any one is permitted). When set in managed settings, login fails if the authenticated account does not belong to a listed organization.
9356
9428
  */
9357
9429
  forceLoginOrgUUID?: string | string[];
9430
+ /**
9431
+ * Self-hosted runner hosts only. Set to true to let a Claude Code started by a runner session's command use the runner's model access (--nested-model-access) when this machine's managed settings set forceLoginOrgUUID or forceLoginMethod. It asks the runner which organization the session owner's sign-in belongs to, and stops if the pin does not permit it or the runner does not answer. Without this key it is left signed out. Any program on the machine can pretend to be the runner, so with this key the pin is not a security boundary: set it on runner hosts only, never in a profile that reaches people's own computers. Honored only from this machine's own administrator sources (MDM, the managed settings file, or a policy helper that they name); ignored in server-managed, user, project, local and --settings sources.
9432
+ */
9433
+ allowNestedModelAccessUnderForceLogin?: boolean;
9358
9434
  /**
9359
9435
  * Managed settings only (managed-settings.json, MDM, or server-managed). The API providers Claude Code may use on this machine: "anthropic" (the Anthropic API on Anthropic's own host, via a claude.ai or Console sign-in or an API key; pair it with forceLoginMethod / forceLoginOrgUUID to require a sign-in), "bedrock", "vertex", "foundry", "anthropicAws", "mantle" (each meaning that provider's own service: its regional, FIPS, private-endpoint and sovereign-cloud hosts), "customEndpoint" (the Anthropic API or a cloud provider's API sent to some other host — ANTHROPIC_BASE_URL, that provider's ANTHROPIC_*_BASE_URL, a Foundry resource name that is not a bare name, or for Bedrock the AWS SDK's AWS_ENDPOINT_URL[_BEDROCK[_RUNTIME]] — such as an LLM gateway; admitted only for the value pinned in the "env" block of the same managed source), or "gateway" (the Cloud gateway sign-in). A session on a provider that is not listed is refused at startup, at login, and when it next contacts the API, with a message naming what selected the provider and the entry that would allow it. Under a list, where first-party traffic goes (ANTHROPIC_BASE_URL, a gateway sign-in) is honored only when the same managed source pins it in "env" (or forceLoginGatewayUrl), and a claude ssh tunnel into the machine is refused. A cloud provider's credential and tenancy variables, and the network path and TLS trust (HTTPS_PROXY, NODE_EXTRA_CA_CERTS, CLAUDE_CODE_CERT_STORE), are not judged by this list; set those for the fleet in the managed "env" block, whose values replace the user's. To route Bedrock through a gateway for a fleet, pin ANTHROPIC_BEDROCK_BASE_URL there (it is what the clients use, ahead of an endpoint_url in ~/.aws/config, which this list does not judge); the AWS SDK's AWS_ENDPOINT_URL* pins only sanction where the SDK's own clients go and never stand in for the "bedrock" entry. Unset allows every provider; an empty array allows none. Only a list in managed-settings.json or MDM is enforcement on the machine: it cannot be widened or hidden by server-managed settings and reaches every session. A list set only in the admin console reaches only sessions that fetch your server-managed settings — not a session on a cloud provider, another organization or a non-Anthropic ANTHROPIC_BASE_URL, one authenticating only with apiKeyHelper or ANTHROPIC_AUTH_TOKEN, a Pro/Max/Ultra login, --bare without an API key, or a first launch before the fetch lands — all conditions the user controls. Versions that predate this setting ignore it; pair it with a minimum-version policy on a mixed fleet. 'claude auth status' reports the Anthropic API as apiProvider "firstParty".
9360
9436
  */
@@ -9585,6 +9661,7 @@ export declare interface Settings {
9585
9661
  sigv4a?: 'deny' | 'passthrough';
9586
9662
  };
9587
9663
  };
9664
+
9588
9665
  /**
9589
9666
  * Sandbox violations to leave unreported: a map of command patterns ("*" for every command) to the filesystem paths whose violations are ignored. Merged across settings sources. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, values from project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
9590
9667
  */
@@ -9734,7 +9811,7 @@ export declare interface Settings {
9734
9811
  */
9735
9812
  maxEffortLevel?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
9736
9813
  /**
9737
- * Auto-compact window for this model, in tokens (100000 to 1000000), or "auto" for the window tuned for the model. Within one settings file it replaces the top-level autoCompactWindow for the model. /autocompact saves here. The canonical model name as key also matches its dated, [1m], Bedrock and Vertex spellings.
9814
+ * Auto-compact window for this model, in tokens (at least 100000), or "auto" for the window tuned for the model. Within one settings file it replaces the top-level autoCompactWindow for the model. /autocompact saves here. The canonical model name as key also matches its dated, [1m], Bedrock and Vertex spellings.
9738
9815
  */
9739
9816
  autoCompactWindow?: 'auto' | number;
9740
9817
  [k: string]: unknown;
@@ -9994,6 +10071,8 @@ export declare interface Settings {
9994
10071
  */
9995
10072
  precomputeCompactionEnabled?: boolean;
9996
10073
 
10074
+
10075
+
9997
10076
  /**
9998
10077
  * Set to false to stop Claude Code from compacting a long conversation while the session is idle. Defaults to true.
9999
10078
  */
@@ -10235,6 +10314,7 @@ export declare interface SpareProcess extends AsyncDisposable {
10235
10314
  }>;
10236
10315
  /** Settles when the spare's process exits, claimed or not — a parked spare that dies should be replaced. */
10237
10316
  readonly exited: Promise<void>;
10317
+
10238
10318
  /**
10239
10319
  * Terminate the process. Before a claim this discards the spare (and
10240
10320
  * rejects `claimed`); after one it is the same as closing the Query.