@anthropic-ai/claude-agent-sdk 0.3.283 → 0.3.285
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/bridge.mjs +101 -111
- package/browser-sdk.js +94 -95
- package/core-rf2bg9hj.mjs +33 -0
- package/core-w2yya30y.mjs +40 -0
- package/core.mjs +18 -18
- package/manifest.json +22 -22
- package/manifest.zst.json +26 -26
- package/package.json +12 -12
- package/sdk-tools.d.ts +24 -5
- package/sdk.d.ts +85 -51
- package/sdk.mjs +86 -94
- package/core-3mr1yqt9.mjs +0 -31
- package/core-rg0sgcv0.mjs +0 -38
package/sdk.d.ts
CHANGED
|
@@ -679,11 +679,7 @@ export declare type DirectoryAddedHookInput = BaseHookInput & {
|
|
|
679
679
|
/**
|
|
680
680
|
* Effort level for controlling how much thinking/reasoning Claude applies.
|
|
681
681
|
*
|
|
682
|
-
* -
|
|
683
|
-
* - `'medium'` — Moderate thinking
|
|
684
|
-
* - `'high'` — Deep reasoning (default)
|
|
685
|
-
* - `'xhigh'` — Deeper than high (Fable 5, Opus 4.7+, Sonnet 5; falls back to `'high'` elsewhere)
|
|
686
|
-
* - `'max'` — Maximum effort (select models only)
|
|
682
|
+
* @see https://platform.claude.com/docs/en/build-with-claude/effort
|
|
687
683
|
*/
|
|
688
684
|
export declare type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
|
|
689
685
|
|
|
@@ -1183,7 +1179,7 @@ export declare type McpHttpServerConfig = {
|
|
|
1183
1179
|
timeout?: number;
|
|
1184
1180
|
|
|
1185
1181
|
/**
|
|
1186
|
-
* When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1182
|
+
* When true, all tools from this server are always included in the prompt and never deferred behind tool search, except a tool the server itself lists with _meta anthropic/alwaysLoad set to false. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1187
1183
|
*/
|
|
1188
1184
|
alwaysLoad?: boolean;
|
|
1189
1185
|
|
|
@@ -1322,7 +1318,7 @@ export declare type McpSSEServerConfig = {
|
|
|
1322
1318
|
timeout?: number;
|
|
1323
1319
|
|
|
1324
1320
|
/**
|
|
1325
|
-
* When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1321
|
+
* When true, all tools from this server are always included in the prompt and never deferred behind tool search, except a tool the server itself lists with _meta anthropic/alwaysLoad set to false. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1326
1322
|
*/
|
|
1327
1323
|
alwaysLoad?: boolean;
|
|
1328
1324
|
|
|
@@ -1338,7 +1334,7 @@ export declare type McpStdioServerConfig = {
|
|
|
1338
1334
|
*/
|
|
1339
1335
|
timeout?: number;
|
|
1340
1336
|
/**
|
|
1341
|
-
* When true, all tools from this server are always included in the prompt and never deferred behind tool search. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1337
|
+
* When true, all tools from this server are always included in the prompt and never deferred behind tool search, except a tool the server itself lists with _meta anthropic/alwaysLoad set to false. Equivalent to setting defer_loading: false on the API. Default: tools are deferred when tool search is enabled. As a side effect this also blocks startup until the server is connected (capped at the standard 5s connect timeout) even though MCP startup is otherwise non-blocking by default, since the tools must be present when the turn-1 prompt is built.
|
|
1342
1338
|
*/
|
|
1343
1339
|
alwaysLoad?: boolean;
|
|
1344
1340
|
|
|
@@ -1454,7 +1450,7 @@ export declare type ModelUsage = {
|
|
|
1454
1450
|
};
|
|
1455
1451
|
|
|
1456
1452
|
export declare type NonNullableUsage = {
|
|
1457
|
-
[K in keyof BetaUsage]: NonNullable<BetaUsage[K]>;
|
|
1453
|
+
[K in keyof BetaUsage]: K extends 'fallback_credit' ? BetaUsage[K] : NonNullable<BetaUsage[K]>;
|
|
1458
1454
|
};
|
|
1459
1455
|
|
|
1460
1456
|
export declare type NotificationHookInput = BaseHookInput & {
|
|
@@ -1905,12 +1901,6 @@ export declare type Options = {
|
|
|
1905
1901
|
* Controls how much effort Claude puts into its response.
|
|
1906
1902
|
* Works with adaptive thinking to guide thinking depth.
|
|
1907
1903
|
*
|
|
1908
|
-
* - `'low'` — Minimal thinking, fastest responses
|
|
1909
|
-
* - `'medium'` — Moderate thinking
|
|
1910
|
-
* - `'high'` — Deep reasoning (default)
|
|
1911
|
-
* - `'xhigh'` — Deeper than high (Fable 5, Opus 4.7+, Sonnet 5)
|
|
1912
|
-
* - `'max'` — Maximum effort (Fable 5, Opus 4.6+, Sonnet 4.6+)
|
|
1913
|
-
*
|
|
1914
1904
|
* @see https://platform.claude.com/docs/en/build-with-claude/effort
|
|
1915
1905
|
*/
|
|
1916
1906
|
effort?: EffortLevel;
|
|
@@ -2913,8 +2903,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2913
2903
|
* / `--thinking-display`) is kept — a session started with thinking
|
|
2914
2904
|
* disabled has none, so re-enabling without this param gets that default.
|
|
2915
2905
|
* `'highlights'` (the API's one-line thinking titles) is honored by the API
|
|
2916
|
-
* only for Anthropic-hosted remote sessions; the
|
|
2917
|
-
*
|
|
2906
|
+
* only for Anthropic-hosted remote sessions; when the session cannot send it
|
|
2907
|
+
* to the API the promise rejects and the display stays as it was, while
|
|
2908
|
+
* `maxThinkingTokens` still applies.
|
|
2918
2909
|
*/
|
|
2919
2910
|
setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | 'highlights' | null): Promise<void>;
|
|
2920
2911
|
/**
|
|
@@ -2933,6 +2924,11 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2933
2924
|
* main-thread agent, and `ultracode` to off with the current effort kept.
|
|
2934
2925
|
* Only available in streaming input mode.
|
|
2935
2926
|
*
|
|
2927
|
+
* `ultracode: true` or `false` turns ultracode on or off and leaves the
|
|
2928
|
+
* effort level alone. An `effortLevel` that moves the session to a
|
|
2929
|
+
* different level, sent without an `ultracode` key, also turns ultracode
|
|
2930
|
+
* off; send both keys to change the level and keep it on.
|
|
2931
|
+
*
|
|
2936
2932
|
* @param settings - A partial settings object to merge into the flag
|
|
2937
2933
|
* settings. `effortLevel` also accepts `'max'` (never written to settings
|
|
2938
2934
|
* files, so the persisted {@link Settings.effortLevel} excludes it): it is
|
|
@@ -3373,7 +3369,7 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
|
|
|
3373
3369
|
maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3374
3370
|
maskDuplicates: z.ZodOptional<z.ZodBoolean>;
|
|
3375
3371
|
injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3376
|
-
}, z.core.$strip
|
|
3372
|
+
}, z.core.$strip>, unknown>>>;
|
|
3377
3373
|
envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
|
|
3378
3374
|
name: z.ZodString;
|
|
3379
3375
|
mode: z.ZodEnum<{
|
|
@@ -3391,7 +3387,7 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
|
|
|
3391
3387
|
}>>;
|
|
3392
3388
|
maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3393
3389
|
injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3394
|
-
}, z.core.$strip
|
|
3390
|
+
}, z.core.$strip>, unknown>>>;
|
|
3395
3391
|
allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
|
|
3396
3392
|
awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
3397
3393
|
accessKeyIdVar: z.ZodString;
|
|
@@ -3505,7 +3501,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
|
|
|
3505
3501
|
maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3506
3502
|
maskDuplicates: z.ZodOptional<z.ZodBoolean>;
|
|
3507
3503
|
injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3508
|
-
}, z.core.$strip
|
|
3504
|
+
}, z.core.$strip>, unknown>>>;
|
|
3509
3505
|
envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
|
|
3510
3506
|
name: z.ZodString;
|
|
3511
3507
|
mode: z.ZodEnum<{
|
|
@@ -3523,7 +3519,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
|
|
|
3523
3519
|
}>>;
|
|
3524
3520
|
maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3525
3521
|
injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3526
|
-
}, z.core.$strip
|
|
3522
|
+
}, z.core.$strip>, unknown>>>;
|
|
3527
3523
|
allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
|
|
3528
3524
|
awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
|
|
3529
3525
|
accessKeyIdVar: z.ZodString;
|
|
@@ -3554,8 +3550,8 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
|
|
|
3554
3550
|
command: z.ZodString;
|
|
3555
3551
|
args: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
3556
3552
|
}, z.core.$strip>>;
|
|
3557
|
-
bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString>>>;
|
|
3558
|
-
socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString>>>;
|
|
3553
|
+
bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
|
|
3554
|
+
socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
|
|
3559
3555
|
}, z.core.$loose>;
|
|
3560
3556
|
|
|
3561
3557
|
/**
|
|
@@ -3739,6 +3735,7 @@ export declare type SDKCompactBoundaryMessage = {
|
|
|
3739
3735
|
|
|
3740
3736
|
|
|
3741
3737
|
|
|
3738
|
+
|
|
3742
3739
|
/**
|
|
3743
3740
|
* Relink info for messagesToKeep. Loaders splice the preserved segment at anchor_uuid (summary for suffix-preserving, boundary for prefix-preserving partial compact) so resume includes preserved content. Unset when compaction summarizes everything (no messagesToKeep).
|
|
3744
3741
|
*/
|
|
@@ -4516,6 +4513,7 @@ export declare type SDKControlInitializeResponse = {
|
|
|
4516
4513
|
|
|
4517
4514
|
|
|
4518
4515
|
|
|
4516
|
+
|
|
4519
4517
|
/**
|
|
4520
4518
|
* Whether the `hooks` this initialize carried were registered: true on a session's first initialize, and on a repeated initialize from the process that owns the CLI's stdin (its set replaces the one registered earlier); false when a repeated initialize's hooks were ignored (a client joining a remote session another client configured). Absent when the request carried no hooks, and on CLIs that predate the field — those ignored `hooks` on every repeated initialize.
|
|
4521
4519
|
*/
|
|
@@ -4539,6 +4537,8 @@ export declare type SDKControlInitializeResponse = {
|
|
|
4539
4537
|
|
|
4540
4538
|
|
|
4541
4539
|
|
|
4540
|
+
|
|
4541
|
+
|
|
4542
4542
|
};
|
|
4543
4543
|
|
|
4544
4544
|
/**
|
|
@@ -4558,7 +4558,7 @@ declare type SDKControlInterruptRequest = {
|
|
|
4558
4558
|
*/
|
|
4559
4559
|
export declare type SDKControlInterruptResponse = {
|
|
4560
4560
|
/**
|
|
4561
|
-
* Uuids of async user messages that survive this interrupt: commands still in the queue, plus any batch already dequeued for the imminent turn but not yet reachable by the abort. An interrupt — plain or cancel_queued:true — that lands during the FIRST-command prewait window (before the first turn of the session has armed a controller) is additionally LATCHED, scoped to the user-intent work pending at that instant — the batch already dequeued and parked for the imminent turn, plus the user-intent main-thread commands then in the queue (the work this list enumerates): the first turn to arm that carries any of that doomed work starts already aborted, exactly once, so the listed prewait batch is delivered into an immediately-aborted turn, its frames and result flowing through the normal abort path, instead of running to completion. A turn carrying none of it arms live and leaves the latch waiting: a system delivery turn (for example a replayed host event), or a prompt enqueued after the interrupt — post-interrupt work is never coalesced with the doomed work and never dies to the latch, so the Stop kills exactly what this receipt listed. The latch is released when the doomed work is retired without arming: if a parked prewait batch is entirely cancelled, the latch is released even when other queued commands remain (those arm and run normally); with nothing parked, it is released once none of the doomed commands remains queued — work enqueued after the interrupt neither holds it up nor is aborted by it. Survivors that ride any later turn run normally. These WILL run (subject to that latch) unless cancelled first (or unless the request set cancel_queued:true, in which case every uuid-stamped survivor this process holds is removed, emitted a terminal `cancelled` synchronously, and listed under `cancelled` instead — leaving here only what a client driving a hosted session can no longer recall: a send already in flight to that session, or the first prompt the session was created with; a send that client still holds on its own machine behind a send gate (
|
|
4561
|
+
* Uuids of async user messages that survive this interrupt: commands still in the queue, plus any batch already dequeued for the imminent turn but not yet reachable by the abort. An interrupt — plain or cancel_queued:true — that lands during the FIRST-command prewait window (before the first turn of the session has armed a controller) is additionally LATCHED, scoped to the user-intent work pending at that instant — the batch already dequeued and parked for the imminent turn, plus the user-intent main-thread commands then in the queue (the work this list enumerates): the first turn to arm that carries any of that doomed work starts already aborted, exactly once, so the listed prewait batch is delivered into an immediately-aborted turn, its frames and result flowing through the normal abort path, instead of running to completion. A turn carrying none of it arms live and leaves the latch waiting: a system delivery turn (for example a replayed host event), or a prompt enqueued after the interrupt — post-interrupt work is never coalesced with the doomed work and never dies to the latch, so the Stop kills exactly what this receipt listed. The latch is released when the doomed work is retired without arming: if a parked prewait batch is entirely cancelled, the latch is released even when other queued commands remain (those arm and run normally); with nothing parked, it is released once none of the doomed commands remains queued — work enqueued after the interrupt neither holds it up nor is aborted by it. Survivors that ride any later turn run normally. These WILL run (subject to that latch) unless cancelled first (or unless the request set cancel_queued:true, in which case every uuid-stamped survivor this process holds is removed, emitted a terminal `cancelled` synchronously, and listed under `cancelled` instead — leaving here only what a client driving a hosted session can no longer recall: a send already in flight to that session, or the first prompt the session was created with; a send that client still holds on its own machine behind a send gate (it waits there until that session is ready to take it) has not gone out, so it is withdrawn and listed under `cancelled` like a queued one, and cancel_async_message can withdraw it too, while a plain interrupt leaves it held and lists it here). Cancellation granularity: uuids still in the queue are individually cancellable via cancel_async_message; once a batch is dequeued and coalesced into one turn, cancelling a NON-representative member uuid is a no-op (its content still runs), while cancelling the batch-representative uuid drops the WHOLE coalesced batch — in both cases the cancel response reports cancelled:false because the message was no longer in the queue. Coverage caveats: only uuid-STAMPED messages appear (a message enqueued without a uuid still runs but is never listed, so [] does not mean "nothing will run"); only main-thread messages are listed (subagent-addressed messages are out of scope); and the list may include internally-enqueued uuids the client never sent (cron triggers, auto-resume continuations) — ignore unknown uuids rather than treating them as an error. Ordering: on a clean interrupt this receipt is written before the interrupted turn result; a turn that crashes during interrupt handling emits its error result on a direct-write path that may precede the receipt. Snapshot is taken synchronously with abort processing — probing the queue after the interrupted result instead always loses the race against the drain loop, which starts the next queued turn immediately.
|
|
4562
4562
|
*/
|
|
4563
4563
|
still_queued: string[];
|
|
4564
4564
|
/**
|
|
@@ -5007,7 +5007,7 @@ declare type SDKControlSetColorRequest = {
|
|
|
5007
5007
|
};
|
|
5008
5008
|
|
|
5009
5009
|
/**
|
|
5010
|
-
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is null, thinking resets to the session default: any mid-session budget override is cleared (back to the spawn-time budget, if one was set), and thinking stays off for sessions that have it disabled. When max_thinking_tokens is omitted, the budget is left as it is, so a request that only changes thinking_display can leave the field out. thinking_display optionally sets the thinking display mode for the rest of the session: a value replaces the session display mode, null clears that override so Claude Code's default display handling applies again, and when omitted the display mode from session start (--thinking-display) is kept. 'highlights' returns one short title per stretch of thinking instead of a prose summary. The API accepts it only from Claude Code sessions that Anthropic hosts; if the API rejects it, the session sends 'omitted' (no thinking text) in its place from then on. A request for 'highlights'
|
|
5010
|
+
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is null, thinking resets to the session default: any mid-session budget override is cleared (back to the spawn-time budget, if one was set), and thinking stays off for sessions that have it disabled. When max_thinking_tokens is omitted, the budget is left as it is, so a request that only changes thinking_display can leave the field out. thinking_display optionally sets the thinking display mode for the rest of the session: a value replaces the session display mode, null clears that override so Claude Code's default display handling applies again, and when omitted the display mode from session start (--thinking-display) is kept. 'highlights' returns one short title per stretch of thinking instead of a prose summary. The API accepts it only from Claude Code sessions that Anthropic hosts; if the API rejects it, the session sends 'omitted' (no thinking text) in its place from then on. A request for 'highlights' gets an error reply after such a rejection, on Amazon Bedrock, Google Vertex AI or another provider without Anthropic's first-party beta features, when experimental betas are off (CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or organization policy), or on a Claude 3 model (except on Microsoft Foundry). The error names which of these it was; the display stays as it was, and max_thinking_tokens still applies when the request has it.
|
|
5011
5011
|
*/
|
|
5012
5012
|
declare type SDKControlSetMaxThinkingTokensRequest = {
|
|
5013
5013
|
subtype: 'set_max_thinking_tokens';
|
|
@@ -5318,6 +5318,7 @@ export declare type SDKMessageOrigin = {
|
|
|
5318
5318
|
* On a 'scheduled-trigger' delivery, why it fired: a short lowercase token such as 'scheduled', 'manual', 'retry', 'catch_up' or 'api'. Set by the server for cloud routines, or declared by a local host for its own scheduled runs, which is honored only in a process the host started with CLAUDE_CODE_HOST_SCHEDULED_RUN=1 (a local host's value is kept only if it is 1 to 32 lowercase letters or underscores); absent when neither sent one.
|
|
5319
5319
|
*/
|
|
5320
5320
|
fireReason?: string;
|
|
5321
|
+
|
|
5321
5322
|
} | {
|
|
5322
5323
|
kind: 'coordinator';
|
|
5323
5324
|
} | {
|
|
@@ -5676,6 +5677,11 @@ export declare type SDKResultSuccess = {
|
|
|
5676
5677
|
ttft_ms?: number;
|
|
5677
5678
|
ttft_stream_ms?: number;
|
|
5678
5679
|
time_to_request_ms?: number;
|
|
5680
|
+
|
|
5681
|
+
|
|
5682
|
+
|
|
5683
|
+
|
|
5684
|
+
|
|
5679
5685
|
user_message_uuid?: string;
|
|
5680
5686
|
user_message_uuids?: string[];
|
|
5681
5687
|
resume_reason?: string;
|
|
@@ -5691,6 +5697,8 @@ export declare type SDKResultSuccess = {
|
|
|
5691
5697
|
|
|
5692
5698
|
|
|
5693
5699
|
|
|
5700
|
+
|
|
5701
|
+
|
|
5694
5702
|
first_text_post_ms?: number;
|
|
5695
5703
|
first_text_post_wall_ms?: number;
|
|
5696
5704
|
time_to_request_from_spawn_ms?: number;
|
|
@@ -5699,6 +5707,7 @@ export declare type SDKResultSuccess = {
|
|
|
5699
5707
|
is_error: boolean;
|
|
5700
5708
|
api_error_status?: number | null;
|
|
5701
5709
|
|
|
5710
|
+
|
|
5702
5711
|
num_turns: number;
|
|
5703
5712
|
result: string;
|
|
5704
5713
|
stop_reason: string | null;
|
|
@@ -5810,9 +5819,9 @@ export declare type SDKSettingsParseError = {
|
|
|
5810
5819
|
};
|
|
5811
5820
|
|
|
5812
5821
|
/**
|
|
5813
|
-
* 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. 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.
|
|
5822
|
+
* 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.
|
|
5814
5823
|
*/
|
|
5815
|
-
export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | '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';
|
|
5824
|
+
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';
|
|
5816
5825
|
|
|
5817
5826
|
export declare type SDKStatus = 'compacting' | 'requesting' | null;
|
|
5818
5827
|
|
|
@@ -7118,7 +7127,7 @@ export declare interface Settings {
|
|
|
7118
7127
|
*/
|
|
7119
7128
|
disableRemoteControl?: boolean;
|
|
7120
7129
|
/**
|
|
7121
|
-
* Disable the Workflows feature (
|
|
7130
|
+
* Disable the Workflows feature. Code Review on pull requests and /ultrareview run in Anthropic's cloud and are not stopped by this setting, except an /ultrareview that has to restart partway through. A machine that runs a review itself refuses it when that machine's own administrator set this, or CLAUDE_CODE_DISABLE_WORKFLOWS in an `env` block, in its managed settings (MDM, the managed-settings file or an administrator's policy helper). Set in the environment before Claude Code starts, CLAUDE_CODE_DISABLE_WORKFLOWS disables Workflows. Beyond the cases above it stops a review only when the review's own session starts with it set.
|
|
7122
7131
|
*/
|
|
7123
7132
|
disableWorkflows?: boolean;
|
|
7124
7133
|
/**
|
|
@@ -7178,7 +7187,7 @@ export declare interface Settings {
|
|
|
7178
7187
|
*/
|
|
7179
7188
|
httpHookAllowedEnvVars?: string[];
|
|
7180
7189
|
/**
|
|
7181
|
-
* When true (and set in managed settings), permission rules from user, project, local, and --settings files and allow rules from --allowedTools are ignored; only managed settings can add allow rules through settings. The allowed-tools frontmatter of skills and custom commands from user, project, and --add-dir sources, and of plugins
|
|
7190
|
+
* When true (and set in managed settings), permission rules from user, project, local, and --settings files and allow rules from --allowedTools are ignored; only managed settings can add allow rules through settings. The allowed-tools frontmatter of skills and custom commands from user, project, and --add-dir sources, and of plugins no managed setting vouches for, is ignored too. Plugins keep theirs only on an admin-backed channel: host-delivered --plugin-dir plugins, the official marketplace registered from its unpinned anthropics source, claude.ai-synced plugins Anthropic attests, the saved login organization's claude.ai-hosted marketplaces, marketplaces whose registered source managed extraKnownMarketplaces declares or an exact or owner-pinned (owner/*) strictKnownMarketplaces entry names at the path it pins (an npm marketplace source only when the registration and the declared entry pin the same registry, and a settings marketplace source only when every nested npm plugin entry pins one on a bare package name — unpinned, the package resolves through the member's own npm config, and a non-bare spelling packs as an exotic spec the pin does not bind, so nothing an entry names is what was fetched), and npm-direct (package\@npm) plugins whose recorded resolution a registry-pinned managed npm strictKnownMarketplaces entry names (host and path patterns and enabledPlugins ids do not vouch); managed and bundled skills keep theirs. --disallowedTools, skill disallowed-tools, and other deny and ask rules from the command line or the current session still apply.
|
|
7182
7191
|
*/
|
|
7183
7192
|
allowManagedPermissionRulesOnly?: boolean;
|
|
7184
7193
|
/**
|
|
@@ -7261,7 +7270,7 @@ export declare interface Settings {
|
|
|
7261
7270
|
};
|
|
7262
7271
|
};
|
|
7263
7272
|
/**
|
|
7264
|
-
* 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 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 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
|
|
7273
|
+
* 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 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.
|
|
7265
7274
|
*/
|
|
7266
7275
|
prependPlugins?: string[];
|
|
7267
7276
|
/**
|
|
@@ -7347,7 +7356,7 @@ export declare interface Settings {
|
|
|
7347
7356
|
*/
|
|
7348
7357
|
version?: string;
|
|
7349
7358
|
/**
|
|
7350
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/").
|
|
7359
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/"); under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
7351
7360
|
*/
|
|
7352
7361
|
registry?: string;
|
|
7353
7362
|
} | {
|
|
@@ -7391,7 +7400,7 @@ export declare interface Settings {
|
|
|
7391
7400
|
*/
|
|
7392
7401
|
name: string;
|
|
7393
7402
|
/**
|
|
7394
|
-
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
|
|
7403
|
+
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against. Under allowManagedPermissionRulesOnly, a settings marketplace keeps its plugins' allowed-tools only when every npm entry here pins a `registry` on a bare package name; unpinned, the package resolves through the member's own npm config, and a non-bare spelling (an `npm:` alias, a `name\@range`, a URL or git spec) packs as an exotic spec the pin does not bind — either way the marketplace vouches no tool grants.
|
|
7395
7404
|
*/
|
|
7396
7405
|
source: string | {
|
|
7397
7406
|
source: 'npm';
|
|
@@ -7599,7 +7608,7 @@ export declare interface Settings {
|
|
|
7599
7608
|
*/
|
|
7600
7609
|
version?: string;
|
|
7601
7610
|
/**
|
|
7602
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/").
|
|
7611
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/"); under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
7603
7612
|
*/
|
|
7604
7613
|
registry?: string;
|
|
7605
7614
|
} | {
|
|
@@ -7643,7 +7652,7 @@ export declare interface Settings {
|
|
|
7643
7652
|
*/
|
|
7644
7653
|
name: string;
|
|
7645
7654
|
/**
|
|
7646
|
-
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
|
|
7655
|
+
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against. Under allowManagedPermissionRulesOnly, a settings marketplace keeps its plugins' allowed-tools only when every npm entry here pins a `registry` on a bare package name; unpinned, the package resolves through the member's own npm config, and a non-bare spelling (an `npm:` alias, a `name\@range`, a URL or git spec) packs as an exotic spec the pin does not bind — either way the marketplace vouches no tool grants.
|
|
7647
7656
|
*/
|
|
7648
7657
|
source: string | {
|
|
7649
7658
|
source: 'npm';
|
|
@@ -7846,7 +7855,7 @@ export declare interface Settings {
|
|
|
7846
7855
|
*/
|
|
7847
7856
|
version?: string;
|
|
7848
7857
|
/**
|
|
7849
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/").
|
|
7858
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/"); under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
7850
7859
|
*/
|
|
7851
7860
|
registry?: string;
|
|
7852
7861
|
} | {
|
|
@@ -7890,7 +7899,7 @@ export declare interface Settings {
|
|
|
7890
7899
|
*/
|
|
7891
7900
|
name: string;
|
|
7892
7901
|
/**
|
|
7893
|
-
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
|
|
7902
|
+
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against. Under allowManagedPermissionRulesOnly, a settings marketplace keeps its plugins' allowed-tools only when every npm entry here pins a `registry` on a bare package name; unpinned, the package resolves through the member's own npm config, and a non-bare spelling (an `npm:` alias, a `name\@range`, a URL or git spec) packs as an exotic spec the pin does not bind — either way the marketplace vouches no tool grants.
|
|
7894
7903
|
*/
|
|
7895
7904
|
source: string | {
|
|
7896
7905
|
source: 'npm';
|
|
@@ -8083,7 +8092,7 @@ export declare interface Settings {
|
|
|
8083
8092
|
*/
|
|
8084
8093
|
version?: string;
|
|
8085
8094
|
/**
|
|
8086
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/").
|
|
8095
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/"); under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8087
8096
|
*/
|
|
8088
8097
|
registry?: string;
|
|
8089
8098
|
} | {
|
|
@@ -8127,7 +8136,7 @@ export declare interface Settings {
|
|
|
8127
8136
|
*/
|
|
8128
8137
|
name: string;
|
|
8129
8138
|
/**
|
|
8130
|
-
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
|
|
8139
|
+
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against. Under allowManagedPermissionRulesOnly, a settings marketplace keeps its plugins' allowed-tools only when every npm entry here pins a `registry` on a bare package name; unpinned, the package resolves through the member's own npm config, and a non-bare spelling (an `npm:` alias, a `name\@range`, a URL or git spec) packs as an exotic spec the pin does not bind — either way the marketplace vouches no tool grants.
|
|
8131
8140
|
*/
|
|
8132
8141
|
source: string | {
|
|
8133
8142
|
source: 'npm';
|
|
@@ -8320,7 +8329,7 @@ export declare interface Settings {
|
|
|
8320
8329
|
*/
|
|
8321
8330
|
version?: string;
|
|
8322
8331
|
/**
|
|
8323
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/").
|
|
8332
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). In a policy entry: the origin and path prefix the package's RESOLVED tarball URL must fall under (e.g. "https://npm.example.com/api/npm/internal/"); under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8324
8333
|
*/
|
|
8325
8334
|
registry?: string;
|
|
8326
8335
|
} | {
|
|
@@ -8364,7 +8373,7 @@ export declare interface Settings {
|
|
|
8364
8373
|
*/
|
|
8365
8374
|
name: string;
|
|
8366
8375
|
/**
|
|
8367
|
-
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
|
|
8376
|
+
* Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against. Under allowManagedPermissionRulesOnly, a settings marketplace keeps its plugins' allowed-tools only when every npm entry here pins a `registry` on a bare package name; unpinned, the package resolves through the member's own npm config, and a non-bare spelling (an `npm:` alias, a `name\@range`, a URL or git spec) packs as an exotic spec the pin does not bind — either way the marketplace vouches no tool grants.
|
|
8368
8377
|
*/
|
|
8369
8378
|
source: string | {
|
|
8370
8379
|
source: 'npm';
|
|
@@ -8512,13 +8521,17 @@ export declare interface Settings {
|
|
|
8512
8521
|
*/
|
|
8513
8522
|
parentSettingsBehavior?: 'first-wins' | 'merge';
|
|
8514
8523
|
/**
|
|
8515
|
-
* 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, 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). 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.
|
|
8524
|
+
* 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). 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.
|
|
8516
8525
|
*/
|
|
8517
8526
|
managedSourcesBehavior?: 'first-wins' | 'merge';
|
|
8518
8527
|
/**
|
|
8519
8528
|
* 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.
|
|
8520
8529
|
*/
|
|
8521
8530
|
forceLoginOrgUUID?: string | string[];
|
|
8531
|
+
/**
|
|
8532
|
+
* 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 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".
|
|
8533
|
+
*/
|
|
8534
|
+
allowedProviders?: ('anthropic' | 'customEndpoint' | 'bedrock' | 'vertex' | 'foundry' | 'anthropicAws' | 'mantle' | 'gateway')[];
|
|
8522
8535
|
/**
|
|
8523
8536
|
* When set in managed settings, the CLI blocks startup until remote managed settings are freshly fetched, and exits if the fetch fails
|
|
8524
8537
|
*/
|
|
@@ -8544,24 +8557,30 @@ export declare interface Settings {
|
|
|
8544
8557
|
*/
|
|
8545
8558
|
skipWebFetchPreflight?: boolean;
|
|
8546
8559
|
sandbox?: {
|
|
8560
|
+
/**
|
|
8561
|
+
* Run Bash commands inside the sandbox. Default: false. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, and managed, --settings or user settings set true, false from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (true there still applies).
|
|
8562
|
+
*/
|
|
8547
8563
|
enabled?: boolean;
|
|
8548
8564
|
/**
|
|
8549
|
-
* Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed-settings deployments that require sandboxing as a hard gate.
|
|
8565
|
+
* Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed-settings deployments that require sandboxing as a hard gate. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, and managed, --settings or user settings set true, false from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (true there still applies).
|
|
8550
8566
|
*/
|
|
8551
8567
|
failIfUnavailable?: boolean;
|
|
8552
8568
|
autoAllowBashIfSandboxed?: boolean;
|
|
8553
8569
|
/**
|
|
8554
|
-
* Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When false, the dangerouslyDisableSandbox parameter is completely ignored and all commands must run sandboxed. Default: true.
|
|
8570
|
+
* Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When false, the dangerouslyDisableSandbox parameter is completely ignored and all commands must run sandboxed. Default: true. A false in managed, --settings or user settings holds whatever project settings (.claude/settings.json and .claude/settings.local.json) say (false there still applies).
|
|
8555
8571
|
*/
|
|
8556
8572
|
allowUnsandboxedCommands?: boolean;
|
|
8557
8573
|
network?: {
|
|
8574
|
+
/**
|
|
8575
|
+
* Domains sandboxed commands may reach without a prompt (wildcards such as *.example.com supported). Merged with WebFetch(domain:…) allow rules and 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. With network.allowManagedDomainsOnly, only managed settings supply it.
|
|
8576
|
+
*/
|
|
8558
8577
|
allowedDomains?: string[];
|
|
8559
8578
|
/**
|
|
8560
8579
|
* Domains that are always blocked, even if matched by allowedDomains. Supports the same wildcard syntax as allowedDomains. Merged from all settings sources regardless of allowManagedDomainsOnly.
|
|
8561
8580
|
*/
|
|
8562
8581
|
deniedDomains?: string[];
|
|
8563
8582
|
/**
|
|
8564
|
-
* When true, the sandbox runtime deterministically denies hosts not in allowedDomains instead of prompting. Enforced for sandboxed commands only — in-process tools such as WebFetch are not gated by this setting. Only honored from user, managed/policy, or CLI (--settings) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
|
|
8583
|
+
* When true, the sandbox runtime deterministically denies hosts not in allowedDomains instead of prompting. Enforced for sandboxed commands only — in-process tools such as WebFetch are not gated by this setting. Only honored from user, managed/policy, or CLI (--settings) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored, and while it is on their allowedDomains and WebFetch(domain:…) allow rules are left out of the allowlist.
|
|
8565
8584
|
*/
|
|
8566
8585
|
strictAllowlist?: boolean;
|
|
8567
8586
|
/**
|
|
@@ -8569,19 +8588,28 @@ export declare interface Settings {
|
|
|
8569
8588
|
*/
|
|
8570
8589
|
allowManagedDomainsOnly?: boolean;
|
|
8571
8590
|
/**
|
|
8572
|
-
* macOS only: Unix socket paths to allow. Ignored on Linux (seccomp cannot filter by path).
|
|
8591
|
+
* macOS only: Unix socket paths to allow. Ignored on Linux (seccomp cannot filter by path). 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.
|
|
8573
8592
|
*/
|
|
8574
8593
|
allowUnixSockets?: string[];
|
|
8575
8594
|
/**
|
|
8576
|
-
* If true, allow all Unix sockets (disables blocking on both platforms).
|
|
8595
|
+
* If true, allow all Unix sockets (disables blocking on both platforms). When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, true from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (false there still applies).
|
|
8577
8596
|
*/
|
|
8578
8597
|
allowAllUnixSockets?: boolean;
|
|
8598
|
+
/**
|
|
8599
|
+
* macOS only: If true, sandboxed commands can bind to localhost ports. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, true from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (false there still applies).
|
|
8600
|
+
*/
|
|
8579
8601
|
allowLocalBinding?: boolean;
|
|
8580
8602
|
/**
|
|
8581
|
-
* macOS only: Additional XPC/Mach service names to allow looking up. Supports trailing-wildcard prefix matching (e.g., "com.apple.coresimulator.*"). Needed for tools that communicate via XPC such as the iOS Simulator or Playwright.
|
|
8603
|
+
* macOS only: Additional XPC/Mach service names to allow looking up. Supports trailing-wildcard prefix matching (e.g., "com.apple.coresimulator.*"). Needed for tools that communicate via XPC such as the iOS Simulator or Playwright. 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.
|
|
8582
8604
|
*/
|
|
8583
8605
|
allowMachLookup?: string[];
|
|
8606
|
+
/**
|
|
8607
|
+
* Local TCP port of your own HTTP proxy for sandboxed traffic, used instead of the proxy Claude Code runs. When managed settings or a --settings file set allowUnsandboxedCommands: false, network.deniedDomains or a WebFetch(domain:…) deny rule, when managed settings set network.allowManagedDomainsOnly: true, or when managed, --settings or user settings set network.strictAllowlist: true, values from project settings (.claude/settings.json and .claude/settings.local.json) are ignored. With network.allowManagedDomainsOnly, only managed settings may set it.
|
|
8608
|
+
*/
|
|
8584
8609
|
httpProxyPort?: number;
|
|
8610
|
+
/**
|
|
8611
|
+
* Local TCP port of your own SOCKS5 proxy for sandboxed traffic, used instead of the proxy Claude Code runs. When managed settings or a --settings file set allowUnsandboxedCommands: false, network.deniedDomains or a WebFetch(domain:…) deny rule, when managed settings set network.allowManagedDomainsOnly: true, or when managed, --settings or user settings set network.strictAllowlist: true, values from project settings (.claude/settings.json and .claude/settings.local.json) are ignored. With network.allowManagedDomainsOnly, only managed settings may set it.
|
|
8612
|
+
*/
|
|
8585
8613
|
socksProxyPort?: number;
|
|
8586
8614
|
/**
|
|
8587
8615
|
* [EXPERIMENTAL] Enable in-process TLS termination so the per-request filter can see HTTPS request bodies. Provide a CA cert+key, or omit both to have sandbox-runtime generate an ephemeral one for the session. On native Windows an ephemeral CA cannot pass the sandbox trust check, so omitting the paths uses a persistent CA managed by the sandbox runtime (set up and trusted via /sandbox install); configured paths are passed to the sandbox runtime verbatim, which rejects a bad or incomplete pair at sandbox initialization. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
|
|
@@ -8593,7 +8621,7 @@ export declare interface Settings {
|
|
|
8593
8621
|
};
|
|
8594
8622
|
filesystem?: {
|
|
8595
8623
|
/**
|
|
8596
|
-
* Additional paths to allow writing within the sandbox. Merged with paths from Edit(...) allow permission rules.
|
|
8624
|
+
* Additional paths to allow writing within the sandbox. Merged with paths from Edit(...) allow permission rules. 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. When managed settings or a --settings file set filesystem.denyRead, a Read(…) deny rule or a credentials.files entry (deny or mask), a value from project settings (.claude/settings.json and .claude/settings.local.json) under or equal to a denied path, or spelled as a glob or a network path (UNC or automount), is ignored. A value inside a directory sandboxed commands can already write is re-checked before every command and dropped once it has been re-pointed into a denied read path.
|
|
8597
8625
|
*/
|
|
8598
8626
|
allowWrite?: string[];
|
|
8599
8627
|
/**
|
|
@@ -8605,7 +8633,7 @@ export declare interface Settings {
|
|
|
8605
8633
|
*/
|
|
8606
8634
|
denyRead?: string[];
|
|
8607
8635
|
/**
|
|
8608
|
-
* Paths to re-allow reading within denyRead regions. Takes precedence over denyRead for matching paths.
|
|
8636
|
+
* Paths to re-allow reading within denyRead regions. Takes precedence over denyRead for matching paths. When managed settings or a --settings file set allowUnsandboxedCommands: false, filesystem.denyRead, a Read(…) deny rule or a credentials.files entry (deny or mask), or managed settings set network.allowManagedDomainsOnly: true, a value from project settings (.claude/settings.json and .claude/settings.local.json) that would re-open a path managed, --settings or user settings deny reading is ignored, as is one spelled as a glob or a network path (UNC or automount); one carving out of the project's own denyRead still applies. A value inside a directory sandboxed commands can write is re-checked before every command and dropped once it has been re-pointed into a denied path.
|
|
8609
8637
|
*/
|
|
8610
8638
|
allowRead?: string[];
|
|
8611
8639
|
/**
|
|
@@ -8727,12 +8755,18 @@ export declare interface Settings {
|
|
|
8727
8755
|
sigv4a?: 'deny' | 'passthrough';
|
|
8728
8756
|
};
|
|
8729
8757
|
};
|
|
8758
|
+
/**
|
|
8759
|
+
* 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.
|
|
8760
|
+
*/
|
|
8730
8761
|
ignoreViolations?: {
|
|
8731
8762
|
[k: string]: string[];
|
|
8732
8763
|
};
|
|
8764
|
+
/**
|
|
8765
|
+
* Linux only: Run without the fresh /proc mount, for hosts such as unprivileged Docker containers that cannot create one. **Reduces security** — the host /proc stays readable by sandboxed commands. Default: false. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, true from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (false there still applies).
|
|
8766
|
+
*/
|
|
8733
8767
|
enableWeakerNestedSandbox?: boolean;
|
|
8734
8768
|
/**
|
|
8735
|
-
* macOS only: Allow access to com.apple.trustd.agent in the sandbox. Needed for Go-based CLI tools (gh, gcloud, terraform, etc.) to verify TLS certificates when using httpProxyPort with a MITM proxy and custom CA. **Reduces security** — opens a potential data exfiltration vector through the trustd service. Default: false
|
|
8769
|
+
* macOS only: Allow access to com.apple.trustd.agent in the sandbox. Needed for Go-based CLI tools (gh, gcloud, terraform, etc.) to verify TLS certificates when using httpProxyPort with a MITM proxy and custom CA. **Reduces security** — opens a potential data exfiltration vector through the trustd service. Default: false. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, true from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (false there still applies).
|
|
8736
8770
|
*/
|
|
8737
8771
|
enableWeakerNetworkIsolation?: boolean;
|
|
8738
8772
|
/**
|
|
@@ -8868,7 +8902,7 @@ export declare interface Settings {
|
|
|
8868
8902
|
};
|
|
8869
8903
|
};
|
|
8870
8904
|
/**
|
|
8871
|
-
* Enable ultracode for the session:
|
|
8905
|
+
* Enable ultracode for the session: standing dynamic-workflow orchestration at any effort level. Session-scoped — typically provided via --settings or the apply_flag_settings control request; interactive toggles never persist it. Requires workflows to be enabled and a model that supports ultracode.
|
|
8872
8906
|
*/
|
|
8873
8907
|
ultracode?: boolean;
|
|
8874
8908
|
/**
|