@anthropic-ai/claude-agent-sdk 0.3.322 → 0.3.323

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
@@ -98,7 +98,7 @@ export declare type AgentDefinition = {
98
98
  */
99
99
  permissionMode?: PermissionMode;
100
100
  /**
101
- * Agent type auto-spawned as a background observer whenever this agent runs. The observer receives read-only activity digests and reports via the ObserverReport tool; it never participates in the task.
101
+ * Agent type auto-spawned as a background observer whenever this agent runs, or a comma-separated list of up to four, none of whose names has a comma. An observer receives read-only activity digests and reports via the ObserverReport tool; it never participates in the task.
102
102
  */
103
103
  observer?: string;
104
104
  /**
@@ -710,6 +710,18 @@ export declare type CwdChangedHookSpecificOutput = {
710
710
  */
711
711
  export declare function deleteSession(_sessionId: string, _options?: SessionMutationOptions): Promise<void>;
712
712
 
713
+ /**
714
+ * What {@link matchDeniedModels} answers.
715
+ *
716
+ * @alpha
717
+ */
718
+ export declare type DeniedModelsMatch = {
719
+ /** For each model asked about, in order: whether an entry blocks it. */
720
+ denied: boolean[];
721
+ /** The CLI's notes on entries: why one was ignored, or what one blocks where that may surprise. And a note on what was asked about but is no model name. */
722
+ warnings: string[];
723
+ };
724
+
713
725
  export declare type DirectoryAddedHookInput = BaseHookInput & {
714
726
  hook_event_name: 'DirectoryAdded';
715
727
  /**
@@ -884,7 +896,13 @@ export declare type ForkSessionOptions = SessionMutationOptions & {
884
896
  * Slice transcript up to the message whose `uuid` field equals this value
885
897
  * (inclusive). If omitted, full copy. Obtain the value from
886
898
  * {@link SessionMessage.uuid} via `getSessionMessages()`, or from the
887
- * `uuid` you supplied on a streamed {@link SDKUserMessage}.
899
+ * `uuid` you supplied on a streamed {@link SDKUserMessage}. With a compaction
900
+ * summary's id, the fork leaves out the messages kept after that summary.
901
+ * With the id of a `compact_boundary` message that a compaction wrote, or of a
902
+ * queued prompt or other non-message entry stored between that boundary and
903
+ * its summary, the fork ends before the boundary, and has no messages if none
904
+ * came before it. With the id of a boundary written by rewinding behind a
905
+ * compaction, the fork keeps that boundary and the messages it kept.
888
906
  */
889
907
  upToMessageId?: string;
890
908
  /** Custom title for the fork. If omitted, derives from original title + " (fork)". */
@@ -1224,6 +1242,22 @@ export declare type ListSubagentsOptions = {
1224
1242
  sessionStore?: SessionStore;
1225
1243
  };
1226
1244
 
1245
+ /**
1246
+ * Say which of `models` a managed `deniedModels` list blocks, without spawning
1247
+ * the Claude CLI. Pass `effective.deniedModels` from {@link resolveSettings}.
1248
+ * Nothing throws: a bad list or entry is ignored, a bad model is `false`, and
1249
+ * `models` that isn't a list gets an empty `denied`; `warnings` notes each.
1250
+ *
1251
+ * @remarks
1252
+ * **Not the CLI's enforcement: grant nothing by it.** It compares model IDs
1253
+ * with entries alone. `true` means that this version's CLI refuses the model
1254
+ * too; `false` promises nothing: the CLI also judges what an alias or a custom
1255
+ * name stands for, a model's other names, path tails and `modelOverrides`.
1256
+ *
1257
+ * @alpha
1258
+ */
1259
+ export declare function matchDeniedModels(_models: readonly string[], _deniedModels: readonly string[] | undefined): Promise<DeniedModelsMatch>;
1260
+
1227
1261
  export declare type McpClaudeAIProxyServerConfig = {
1228
1262
  type: 'claudeai-proxy';
1229
1263
  url: string;
@@ -1262,6 +1296,7 @@ export declare type McpSdkServerConfig = {
1262
1296
 
1263
1297
 
1264
1298
 
1299
+
1265
1300
  /**
1266
1301
  * 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.
1267
1302
  */
@@ -2158,7 +2193,7 @@ export declare type Options = {
2158
2193
  * true, the subagent's conversation is forked every ~30s to produce a short
2159
2194
  * present-tense description (e.g. "Analyzing authentication module"), emitted
2160
2195
  * on `task_progress` events via the `summary` field. The fork reuses the
2161
- * subagent's model and prompt cache, so cost is typically minimal.
2196
+ * subagent's model and prompt cache.
2162
2197
  *
2163
2198
  * Summaries are not a heartbeat. None is made while the conversation is
2164
2199
  * unchanged. A summary can also be delayed by up to 5 minutes while the
@@ -2167,6 +2202,8 @@ export declare type Options = {
2167
2202
  * finishes first, that summary is not sent.
2168
2203
  *
2169
2204
  * Applies to both foreground and background subagents. Defaults to false.
2205
+ * The `CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES=1` env var turns
2206
+ * summaries off even when this option is true.
2170
2207
  */
2171
2208
  agentProgressSummaries?: boolean;
2172
2209
 
@@ -2256,6 +2293,10 @@ export declare type Options = {
2256
2293
  * error result and exits rather than silently running commands unsandboxed.
2257
2294
  * Set `failIfUnavailable: false` to allow graceful degradation.
2258
2295
  *
2296
+ * **Invalid settings:** one value that fails validation rejects all of
2297
+ * `settings`, this option included. With `enabled: true`, `query()` then emits
2298
+ * the same error result and exits, unless `failIfUnavailable` is `false`.
2299
+ *
2259
2300
  * **With `settings`:** when `settings` is given inline (an object or JSON string,
2260
2301
  * not a file path) and has its own `sandbox` block, this option is merged into
2261
2302
  * it. A value this option sets replaces the value at the same path, and a
@@ -2354,6 +2395,7 @@ export declare type Options = {
2354
2395
  * ```
2355
2396
  */
2356
2397
  managedSettings?: Settings;
2398
+
2357
2399
  /**
2358
2400
  * Control which filesystem settings to load.
2359
2401
  * - `'user'` - Global user settings (`~/.claude/settings.json`)
@@ -2604,6 +2646,8 @@ export declare type PermissionRequestHookInput = BaseHookInput & {
2604
2646
  tool_input: unknown;
2605
2647
  permission_suggestions?: PermissionUpdate[];
2606
2648
  mcp_server?: McpServerProvenance;
2649
+
2650
+
2607
2651
  };
2608
2652
 
2609
2653
  export declare type PermissionRequestHookSpecificOutput = {
@@ -3119,6 +3163,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3119
3163
  * @returns A fresh initialization response
3120
3164
  */
3121
3165
  reinitialize(): Promise<SDKControlInitializeResponse>;
3166
+
3122
3167
  /**
3123
3168
  * Get the list of available skills for the current session.
3124
3169
  *
@@ -3311,28 +3356,33 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3311
3356
 
3312
3357
  /**
3313
3358
  * Dynamically set the MCP servers for this session.
3314
- * This replaces the current set of dynamically-added MCP servers with the provided set.
3315
- * Servers that are removed will be disconnected, and new servers will be connected.
3359
+ * This replaces the servers added by earlier calls to this method, and all
3360
+ * in-process SDK servers (including any passed in the `mcpServers` option),
3361
+ * with the provided set. Servers that are removed will be disconnected, and
3362
+ * new servers will be connected.
3316
3363
  *
3317
3364
  * Supports both process-based servers (stdio, sse, http) and SDK servers (in-process).
3318
3365
  * SDK servers are handled locally in the SDK process, while process-based servers
3319
3366
  * are managed by the CLI subprocess.
3320
3367
  *
3321
- * Note: This only affects servers added dynamically via this method or the SDK.
3368
+ * Note: Outside a cloud session, a call that leaves out a stdio, sse or http
3369
+ * server passed in the `mcpServers` option does not disconnect it or list it
3370
+ * in the result's `removed` list, unless an earlier call to this method named
3371
+ * that server. To be able to remove a server later, add it with this method
3372
+ * instead of in `mcpServers`.
3373
+ *
3322
3374
  * Servers configured via settings files are not affected. A `.mcp.json` or
3323
3375
  * local-scope server of the session's current folder stays up when omitted,
3324
- * unless enterprise policy denies it; once a payload has named such a server
3325
- * it is the host's, and a later payload that omits it removes it. Servers
3326
- * introduced by plugins are also exempt: they are managed by the plugin
3327
- * system, so omitting them from the payload does NOT remove them — they keep
3328
- * running (unless enterprise policy denies the server) and are simply absent
3329
- * from the result's `removed` list. In particular, `setMcpServers({})` no
3330
- * longer guarantees a session has zero dynamic MCP surface when plugins are
3331
- * loaded or its current folder has such servers. Naming a plugin server
3332
- * explicitly in the payload still replaces it (ownership is preserved
3333
- * CLI-side).
3334
- *
3335
- * @param servers - Record of server name to configuration. Pass an empty object to remove all dynamic servers (except plugin-owned ones and those of the session's current folder, which are retained as above).
3376
+ * unless enterprise policy denies it; once a call has named such a server, a
3377
+ * later call that omits it removes it. Servers introduced by plugins are also
3378
+ * exempt: they are managed by the plugin system, so omitting them from a call
3379
+ * does NOT remove them — they keep running (unless enterprise policy denies
3380
+ * the server) and are simply absent from the result's `removed` list. Naming a
3381
+ * plugin server explicitly in a call still replaces it. Because of these
3382
+ * exceptions, `setMcpServers({})` does not guarantee that a session has no MCP
3383
+ * servers left.
3384
+ *
3385
+ * @param servers - Record of server name to configuration. Pass an empty object to remove the servers this method replaces.
3336
3386
  * @returns Information about which servers were added, removed, and any connection errors
3337
3387
  */
3338
3388
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
@@ -3406,6 +3456,33 @@ export declare type ResolvedSettings = {
3406
3456
  path?: string;
3407
3457
  policyOrigin?: PolicySettingsOrigin;
3408
3458
  }>;
3459
+ /**
3460
+ * What became of this machine's own policy sources, in the host's own read
3461
+ * (not a Claude Code session's). `effective`, `provenance` and `sources` show
3462
+ * a source that was not read as absent, so a host that enforces managed
3463
+ * settings reads this first. An SDK that predates the member leaves it out,
3464
+ * which says nothing either way.
3465
+ */
3466
+ machinePolicy?: {
3467
+ /**
3468
+ * `false`, or the kinds of source that may be there and did not load:
3469
+ * `'profile'` (a macOS MDM profile), `'registry'` (the Windows HKLM policy
3470
+ * value; under WSL also the Windows folder's managed-settings files while
3471
+ * WSL does not inherit them), `'file'` (the managed-settings file or a
3472
+ * drop-in). Call again to try again: the file is read at every call, the
3473
+ * other two once their last read is 30 minutes old, or sooner after one
3474
+ * that gave no answer or was set aside; once one read has answered, a later
3475
+ * read that fails leaves this as it was. A source that the 30-minute
3476
+ * read finds gone counts so once a second read agrees, which the first call
3477
+ * 30 seconds or more later makes; outside WSL, a profile, or a value that
3478
+ * reg.exe handed over, that fails to load where neither of the two, nor a
3479
+ * per-user value (HKCU), held policy is named. `false` is no proof: a
3480
+ * registry query that fails for good shows as an absent value, and under
3481
+ * WSL a `wslInheritsWindowsSettings` that is neither true nor false is not
3482
+ * named.
3483
+ */
3484
+ didNotLoad: false | Array<'profile' | 'registry' | 'file'>;
3485
+ };
3409
3486
  };
3410
3487
 
3411
3488
  /**
@@ -3431,8 +3508,9 @@ export declare type ResolvedSettingSource = SettingSource | 'managed' | 'flag';
3431
3508
  * HKLM/HKCU, and `managedSettings`) **except** the admin-configured
3432
3509
  * `policyHelper` subprocess is not executed. MDM resolution may invoke
3433
3510
  * `plutil` (macOS, when an MDM plist exists) or `reg.exe` (Windows/WSL)
3434
- * on the first call per process. If your deployment relies on
3435
- * policyHelper to inject managed settings, results will differ.
3511
+ * on the first call per process, and again at later calls. If your
3512
+ * deployment relies on policyHelper to inject managed settings, results will
3513
+ * differ.
3436
3514
  * - **`permissions.defaultMode` is reported as-is across all tiers**
3437
3515
  * including project. The CLI applies a separate trust filter before
3438
3516
  * honoring escalating modes (`bypassPermissions`, `auto`, `acceptEdits`)
@@ -3770,7 +3848,7 @@ export declare type SDKAssistantMessage = {
3770
3848
  */
3771
3849
  resumed_from_incomplete_thinking?: true;
3772
3850
  /**
3773
- * Wire uuids of previously-delivered messages that this message replaces (refusal-fallback supersede). The list can include tombstoned tool_result frames from the refused leg, not only assistant frames. Evict the named messages on arrival and treat this frame as their canonical replacement. Idempotent with the end-of-turn model_refusal_fallback notice, whose retracted_message_uuids remains the complete audit record for the turn.
3851
+ * Uuids of earlier messages that this message replaces: after a refusal fallback, or after a response whose tool call could not be parsed. It can name user messages too, such as a refused attempt's tool results. Remove the named messages when this one arrives. After a refusal fallback it is idempotent with the end-of-turn model_refusal_fallback notice.
3774
3852
  */
3775
3853
  supersedes?: UUID[];
3776
3854
  /**
@@ -3870,6 +3948,7 @@ export declare type SDKBackgroundTasksChangedMessage = {
3870
3948
  */
3871
3949
  ambient?: boolean;
3872
3950
 
3951
+
3873
3952
  }[];
3874
3953
  uuid: UUID;
3875
3954
  session_id: string;
@@ -4725,7 +4804,7 @@ declare type SDKControlInitializeRequest = {
4725
4804
  hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
4726
4805
  sdkMcpServers?: string[];
4727
4806
  /**
4728
- * 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 and autoModeVerdictTools 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.
4807
+ * 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.
4729
4808
  */
4730
4809
  sdkMcpServerConfigs?: Record<string, {
4731
4810
  /**
@@ -4735,6 +4814,7 @@ declare type SDKControlInitializeRequest = {
4735
4814
 
4736
4815
 
4737
4816
 
4817
+
4738
4818
  /**
4739
4819
  * 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.
4740
4820
  */
@@ -4754,7 +4834,7 @@ declare type SDKControlInitializeRequest = {
4754
4834
  toolsListResult?: Record<string, unknown>;
4755
4835
  }>;
4756
4836
  /**
4757
- * The host's statement that it composed this request's sdkMcpServerManifests for this very send, from its servers' current state. Needed only by a host that reaches the CLI over a remote session transport, where an unmarked sdkMcpServerManifests is not used (a recorded registration could be handed to a later worker). The CLI also refuses a marked manifest whose session-stream frame is more than five minutes old, so capture the manifests when writing the request, not earlier; and it may still decline them when remote manifests are switched off in that CLI, or on any session where the session service has not told the CLI in the last five minutes that only the account owning the session can send events to it. sdk_mcp_manifests_parked in the response says what became of each entry. A value this CLI does not know counts as no marker. A host on the CLI's own stream-json stdio transport may omit this field; a host writing to the stdin of a remote-session worker cannot use manifests at all.
4837
+ * The host's statement that it composed this request's sdkMcpServerManifests for this very send, from its servers' current state. Needed only by a host that reaches the CLI over a remote session transport, where an unmarked sdkMcpServerManifests is not used (a recorded registration could be handed to a later worker). The CLI also refuses a marked manifest whose session-stream frame is more than five minutes old, so capture the manifests when writing the request, not earlier. It declines them too when manifests are switched off in that CLI. Over a remote session it also declines them in three more cases: in any session other than an interactive Cowork chat started from claude.ai; until Anthropic has served that CLI its manifests switch on (so not before its feature flags load); and where the session service has not recently told the CLI that only the account owning the session can send events to it. sdk_mcp_manifests_parked in the response says what became of each entry. A value this CLI does not know counts as no marker. A host on the CLI's own stream-json stdio transport may omit this field; a host writing to the stdin of a remote-session worker cannot use manifests at all.
4758
4838
  */
4759
4839
  sdkMcpServerManifestsOrigin?: 'host_per_send';
4760
4840
  jsonSchema?: Record<string, unknown>;
@@ -4809,6 +4889,7 @@ declare type SDKControlInitializeRequest = {
4809
4889
 
4810
4890
 
4811
4891
 
4892
+
4812
4893
  };
4813
4894
 
4814
4895
  /**
@@ -4847,8 +4928,9 @@ export declare type SDKControlInitializeResponse = {
4847
4928
  plugins_applied?: boolean;
4848
4929
 
4849
4930
 
4931
+
4850
4932
  /**
4851
- * 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 or remote manifests are switched off in this CLI, the session service has not told this remote-session worker in the last five minutes 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.
4933
+ * 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.
4852
4934
  */
4853
4935
  sdk_mcp_manifests_parked?: Record<string, 'parked' | 'already_connected' | 'protocol_version_mismatch' | 'malformed' | 'not_honoured'>;
4854
4936
 
@@ -4898,7 +4980,7 @@ declare type SDKControlInterruptRequest = {
4898
4980
  */
4899
4981
  export declare type SDKControlInterruptResponse = {
4900
4982
  /**
4901
- * 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, plus any user message this process has read but not yet queued, from its own input stream (held, for instance, while a model change is still being checked or behind start-up work; a message a Remote Control client sent that is still being ingested is not listed). 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 or held ahead of it (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 or held — 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 (the re-run of an interrupted turn that also answers for other client messages only if this interrupt was for it; see the response to that request); a listed uuid whose message the process running the session (never a client driving a hosted session) still keeps out of its queue, behind a model change or start-up work, is not yet cancellable that way: cancel_async_message answers cancelled:false for it and plants a cancel-pending mark, which the drain honours once the message is queued and the mid-turn fold of a running turn does not; 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.
4983
+ * 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, plus any user message this process has read but not yet queued, from its own input stream (held, for instance, while a model change is still being checked or behind start-up work; a message a Remote Control client sent that is still being ingested is not listed). 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 or held ahead of it (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. A worker of a cloud session may treat a plain interrupt from a person differently. If it reads the interrupt before its first turn, while it holds a prompt from the worker before it, the interrupt stops the turn of that prompt, and listed messages that no turn has started then run. 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 or held — 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 (the re-run of an interrupted turn that also answers for other client messages only if this interrupt was for it; see the response to that request); a listed uuid whose message the process running the session (never a client driving a hosted session) still keeps out of its queue, behind a model change or start-up work, is not yet cancellable that way: cancel_async_message answers cancelled:false for it and plants a cancel-pending mark, which the drain honours once the message is queued and the mid-turn fold of a running turn does not; 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.
4902
4984
  */
4903
4985
  still_queued: string[];
4904
4986
 
@@ -4935,7 +5017,7 @@ export declare type SDKControlListPermissionRulesResponse = {
4935
5017
  };
4936
5018
 
4937
5019
  /**
4938
- * Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes) unless check_permissions is set. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can invoke them directly without the subprocess round-trip. Result content passes through the same processing as model-turn MCP calls, unless result_not_for_model is set. Session expiry is not retried automatically; callers can mcp_reconnect and retry. UrlElicitationRequired (-32042) tries Elicitation hooks; if no hook resolves, the call errors with the URL in the message — open it out-of-band, then retry mcp_call. STAGED calls (input_files/output_files declared) additionally stage lane rows in/out around the call — see the input_files describe. Staged failures come back as a success-subtype response whose staging field carries a typed error_code; subtype:error is emitted only when the call could not be attempted at all (server not connected, kill switch, dispatch failure) and means nothing ran. A target server that is not yet connected is brought up on demand: dispatch runs the deferred plugin/MCP startup resolution (the work a first model turn would have done) and waits up to 30s — shortened by expires_at when that is sooner — for the server to connect before answering "MCP server not connected", so a dispatch that races plugin startup (e.g. after an idle-wake reattach) succeeds instead of failing until a turn runs. Standard RPC semantics: a redelivered request_id supersedes the in-flight run (it is aborted and its response suppressed — exactly one response per request_id); conversion is idempotent, so re-running is safe. Cancellable via control_cancel_request.
5020
+ * Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes) unless check_permissions is set. In a cloud session, tools on the user's own computer or browser are rejected. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can invoke them directly without the subprocess round-trip. Result content passes through the same processing as model-turn MCP calls, unless result_not_for_model is set. Session expiry is not retried automatically; callers can mcp_reconnect and retry. UrlElicitationRequired (-32042) tries Elicitation hooks; if no hook resolves, the call errors with the URL in the message — open it out-of-band, then retry mcp_call. STAGED calls (input_files/output_files declared) additionally stage lane rows in/out around the call — see the input_files describe. Staged failures come back as a success-subtype response whose staging field carries a typed error_code; subtype:error is emitted only when the call could not be attempted at all (server not connected, kill switch, dispatch failure) and means nothing ran. A target server that is not yet connected is brought up on demand: dispatch runs the deferred plugin/MCP startup resolution (the work a first model turn would have done) and waits up to 30s — shortened by expires_at when that is sooner — for the server to connect before answering "MCP server not connected", so a dispatch that races plugin startup (e.g. after an idle-wake reattach) succeeds instead of failing until a turn runs. Standard RPC semantics: a redelivered request_id supersedes the in-flight run (it is aborted and its response suppressed — exactly one response per request_id); conversion is idempotent, so re-running is safe. Cancellable via control_cancel_request.
4939
5021
  */
4940
5022
  declare type SDKControlMcpCallRequest = {
4941
5023
  subtype: 'mcp_call';
@@ -4955,6 +5037,7 @@ declare type SDKControlMcpCallRequest = {
4955
5037
  * Tool-execution timeout (staging and collection have their own transport timeouts); with check_permissions it also bounds hooks and the wait for an answer. Clamped to [1000, 600000]; default 120000. Sending timeout_ms routes the call through the staging engine — so it is always enforced when present and the response carries a staging result; omit it for a plain call. Staged calls are POSIX-worker-only: on a Windows worker any staged-field call fails with a typed staging refusal.
4956
5038
  */
4957
5039
  timeout_ms?: number;
5040
+
4958
5041
  /**
4959
5042
  * The caller hands the result to a program (a host that renders it, a script), not to a model, and bounds it itself. content is then the server's own content blocks as MCP defines them (the MCP SDK drops members it does not define), not what a model turn would be handed: no image is resized or put in the Messages API's shape, nothing is saved under tool-results, no embedded resource is flattened, and text blocks beside structuredContent stay. They are untrusted third-party data: any mimeType, images neither re-encoded nor bounded in pixels, each block's annotations and _meta unfiltered. The size check that protects a model's context is skipped too: no count_tokens request (which uploads the result), no truncation, no note in place of the content. Instead a result over 10485760 characters (content with its base64, structuredContent and _meta together) fails though the tool ran: a plain call answers the error subtype, a staged call staging.error_code tool_error with the text in detail, before its outputs are collected. A legacy toolResult still comes back as a string. Does not route the call through the staging engine. Absent or false: as before. Honoured only for a host on this process's own pipes, not over a remote transport nor on a lane that redacts what it persists. Feature-detected as `mcp_call_result_not_for_model_v1` in system/init.capabilities and in the initialize response's capabilities; where it is not said, and by a CLI without it, the member is ignored.
4960
5043
  */
@@ -5005,7 +5088,7 @@ declare type SDKControlMcpMessageRequest = {
5005
5088
  };
5006
5089
 
5007
5090
  /**
5008
- * Reads one MCP Apps (SEP-1865) UI resource — a `ui://` URI, typically the `_meta.ui.resourceUri` a tool declares — from a connected MCP server the CLI itself dialed, with `resources/read`, for a host that renders it. Read-only and no model turn. The reply is untrusted third-party content (HTML): render it sandboxed. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can read them directly. Errors name the cause: a non-ui:// URI, an unknown server, a server that managed policy blocks, that is disabled or that the project has not approved (the refusals mcp_reconnect gives), a server that is not connected (failed, pending or needs-auth: send mcp_reconnect; a connected server, or one still listed from the discovery cache, is read through the same connect path a tool call takes), a response over the size limit, or the server's own resources/read error (over a transport that stores frames, one fixed sentence in its place). Refused on a lane that redacts what it persists (a Remote Control bridge worker, a tenant worker) and by the client of a cloud-hosted session. Advertised as `mcp_read_resource_v1` in system/init.capabilities.
5091
+ * Reads one MCP Apps (SEP-1865) UI resource — a `ui://` URI, typically the `_meta.ui.resourceUri` a tool declares — from a connected MCP server the CLI itself dialed, with `resources/read`, for a host that renders it. Read-only and no model turn. The reply is untrusted third-party content (HTML): render it sandboxed. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can read them directly. Errors name the cause: a non-ui:// URI, an unknown server, in a cloud session a server on the user's own computer or browser, a server that managed policy blocks, that is disabled or that the project has not approved (the refusals mcp_reconnect gives), a server that is not connected (failed, pending or needs-auth: send mcp_reconnect; a connected server, or one still listed from the discovery cache, is read through the same connect path a tool call takes), a response over the size limit, or the server's own resources/read error (over a transport that stores frames, one fixed sentence in its place). Refused on a lane that redacts what it persists (a Remote Control bridge worker, a tenant worker) and by the client of a cloud-hosted session. Advertised as `mcp_read_resource_v1` in system/init.capabilities.
5009
5092
  */
5010
5093
  declare type SDKControlMcpReadResourceRequest = {
5011
5094
  subtype: 'mcp_read_resource';
@@ -5172,6 +5255,9 @@ declare type SDKControlReadFileRequest = {
5172
5255
  */
5173
5256
  encoding?: 'utf-8' | 'base64';
5174
5257
 
5258
+
5259
+
5260
+
5175
5261
  };
5176
5262
 
5177
5263
  /**
@@ -5186,10 +5272,16 @@ export declare type SDKControlReadFileResponse = {
5186
5272
  */
5187
5273
  encoding?: 'base64';
5188
5274
  /**
5189
- * Present on every utf-8 answer. True when the bytes read were not all valid UTF-8, so `contents` has U+FFFD where bytes were replaced and is not the file's own text: a binary file, text in another encoding, or a read cut inside a character when `truncated` is set. False when `contents` is exactly the bytes read, decoded, even if the file itself contains U+FFFD. Absent on a base64 answer, which is exact, and from an older CLI or tool container: a client that sees neither this nor `encoding: 'base64'` cannot tell whether `contents` is exact.
5275
+ * Present on every utf-8 answer. True when the bytes read were not all valid UTF-8, so `contents` has U+FFFD where bytes were replaced and is not the file's own text: a binary file, text in another encoding, or a read cut inside a character, at its end when `truncated` is set, or at its start when `offset` is set. False when `contents` is exactly the bytes read, decoded, even if the file itself contains U+FFFD. Absent on a base64 answer, which is exact, and from an older CLI or tool container: a client that sees neither this nor `encoding: 'base64'` cannot tell whether `contents` is exact.
5190
5276
  */
5191
5277
  lossy?: boolean;
5192
5278
 
5279
+
5280
+
5281
+
5282
+
5283
+
5284
+
5193
5285
  };
5194
5286
 
5195
5287
  /**
@@ -5856,6 +5948,7 @@ export declare type SDKPartialAssistantMessage = {
5856
5948
  * Why this frame's turn continues one that a worker restart interrupted. Such a turn is the automatic re-run of the interrupted turn (CLAUDE_CODE_RESUME_INTERRUPTED_TURN), or one that goes on from the answer to the permission prompt the new worker took over, or from that turn's tool calls still in flight. The value is the host's CLAUDE_CODE_RESUME_REASON when it set one (host_draining, checkpoint_restore, container_recreated, …), else 'interrupted_turn'. Stamped on the same reply frames as user_message_uuid (which on such a turn names the interrupted turn's own last user prompt), so a consumer can tell its first reply from the interrupted attempt's. Absent on every other turn (also one that goes on from the answer to any other permission prompt), on thinking_tokens frames, and from older producers.
5857
5949
  */
5858
5950
  resume_reason?: string;
5951
+
5859
5952
  };
5860
5953
 
5861
5954
  export declare type SDKPermissionDenial = {
@@ -5959,7 +6052,7 @@ export declare type SdkPluginConfig = {
5959
6052
  };
5960
6053
 
5961
6054
  /**
5962
- * Headless plugin installation progress (CLAUDE_CODE_SYNC_PLUGIN_INSTALL). started/completed bracket the whole install; installed/failed carry a per-marketplace name.
6055
+ * Headless plugin installation progress. installed/failed carry a per-marketplace name. Under CLAUDE_CODE_SYNC_PLUGIN_INSTALL started/completed bracket the whole install, ahead of init; without it the install runs in the background, so there is no bracket and a frame can come at any time, before or after init, or not at all if the process ends first. In the background case only the Claude desktop app gets them, once it asks for them, on a local transport (stdout). `error` comes without URL secrets; it is otherwise raw text: treat it as untrusted.
5963
6056
  */
5964
6057
  export declare type SDKPluginInstallMessage = {
5965
6058
  type: 'system';
@@ -6077,6 +6170,8 @@ export declare type SDKResultError = {
6077
6170
  terminal_reason?: TerminalReason;
6078
6171
 
6079
6172
 
6173
+
6174
+
6080
6175
  /**
6081
6176
  * Delivery sequence of this result within the run: how many results the run numbered before this one, starting at 0, in the order the process writes them. A result held back while background work finishes is numbered when it is finally written, not when its text was produced; a result whose write fails still consumes its number, so a gap in a stream-json sequence means a result was lost. Distinct from num_turns, which counts model round-trips within one turn. Numbered by the process that hosts the run (`claude -p`, stream-json): a local client relaying a cloud session passes the cloud session's numbering through and its own locally built error results carry none; the in-process engine surface does not number yet. Absent from older producers.
6082
6177
  */
@@ -6133,6 +6228,9 @@ export declare type SDKResultSuccess = {
6133
6228
 
6134
6229
 
6135
6230
 
6231
+
6232
+
6233
+
6136
6234
 
6137
6235
 
6138
6236
 
@@ -6317,9 +6415,9 @@ export declare type SDKSettingsParseError = {
6317
6415
  };
6318
6416
 
6319
6417
  /**
6320
- * 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. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help.
6418
+ * 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. 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.
6321
6419
  */
6322
- 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';
6420
+ 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';
6323
6421
 
6324
6422
  export declare type SDKStatus = 'compacting' | 'requesting' | null;
6325
6423
 
@@ -6384,7 +6482,7 @@ export declare type SDKSystemMessage = {
6384
6482
  version?: string;
6385
6483
  }[];
6386
6484
  /**
6387
- * Plugin load-time errors. A plugin that did not load (an unmet dependency, a --plugin-dir entry that failed) is absent from `plugins[]`; a plugin that loaded without one of its components keeps its row and gets an entry here too. `plugin` is `name@marketplace`, or the positional `inline[N]` / `synced[N]` tag for a directory entry that failed before it had a name; `type` is a category from an open set (path-not-found, generic-error, manifest-validation-error, dependency-unsatisfied, hook-load-failed, …) — treat a value you do not recognize as a generic failure; `message` is display text. The key is omitted when there are no errors; CI can fail on `(plugin_errors?.length ?? 0) > 0`. A session whose frames are persisted server-side (a Remote Control worker) always omits this key — plugin diagnostics stay in the local log there, so an omitted key does not assert a clean load.
6485
+ * Plugin load-time errors. A plugin that did not load (an unmet dependency, a --plugin-dir entry that failed, a plugin enabled by managed settings that the loader could not load) is absent from `plugins[]`; a plugin that loaded without one of its components keeps its row and gets an entry here too. `plugin` is `name@marketplace`, or the positional `inline[N]` / `synced[N]` tag for a directory entry that failed before it had a name; `type` is a category from an open set (path-not-found, generic-error, manifest-validation-error, dependency-unsatisfied, hook-load-failed, …) — treat a value you do not recognize as a generic failure; `message` is display text; over a transport that may store its frames (a cloud worker or a self-hosted runner), an entry that is here only because managed settings enable the plugin carries one fixed sentence in its place, with no path or URL. The key is omitted when there are no errors; CI can fail on `(plugin_errors?.length ?? 0) > 0`. That check also trips on a machine that has no copy yet of a plugin enabled by managed settings, which is every run on a throwaway CI runner; CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 makes the first turn wait for the install. A Remote Control worker and the hosted worker always omit this key — plugin diagnostics stay in the local log there, so an omitted key does not assert a clean load.
6388
6486
  */
6389
6487
  plugin_errors?: {
6390
6488
  plugin: string;
@@ -6498,6 +6596,7 @@ export declare type SDKTaskProgressMessage = {
6498
6596
  summary?: string;
6499
6597
 
6500
6598
 
6599
+
6501
6600
  uuid: UUID;
6502
6601
  session_id: string;
6503
6602
  };
@@ -6766,6 +6865,7 @@ export declare type SDKUserMessage = {
6766
6865
 
6767
6866
 
6768
6867
 
6868
+
6769
6869
  uuid?: UUID;
6770
6870
  /**
6771
6871
  * Content the user pasted into the prompt rather than typed: each entry a string or an array of content blocks. The CLI appends the text of each entry after the typed text, in order, and may wrap it in `<pasted_content>` tags. Blocks other than text are ignored; send images and documents in `message.content`. A list of over 1,000 entries and blocks in all is ignored.
@@ -6868,6 +6968,7 @@ export declare type SDKUserMessageReplay = {
6868
6968
 
6869
6969
 
6870
6970
 
6971
+
6871
6972
  uuid: UUID;
6872
6973
  session_id: string;
6873
6974
  isReplay: true;
@@ -7313,11 +7414,12 @@ export declare interface Settings {
7313
7414
  */
7314
7415
  disableBypassPermissionsMode?: 'disable';
7315
7416
  /**
7316
- * Refuse file-tool reads (Read, Grep, Glob, LSP) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Also set when the user picks "block" on the one-time auto-mode prompt for a read outside the working directories.
7417
+ * Refuse file-tool reads (Read, Grep, Glob, LSP) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Also binds shell commands: one that names a path outside them is asked about in every mode, and the sandbox, where it is on, denies such reads. Also set when the user picks "block" on the one-time auto-mode prompt for a read outside the working directories.
7317
7418
  */
7318
7419
  blockReadsOutsideWorkingDirectories?: boolean;
7420
+
7319
7421
  /**
7320
- * Refuse file-tool writes (Write, Edit, NotebookEdit) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Files that Claude Code keeps for the session are not refused: its plan files, scratchpad and background job folder, and the auto-memory of this project, unless a repository settings file points it elsewhere. Nothing runs them unless the model asks. Also refuses file-tool writes to Claude Code settings files, inside the working directories too, and takes EnterWorktree and ExitWorktree, which move the working directory, out of the tools on offer. Does not limit shell commands, MCP tools, the programs that hooks run, or the memory tools. Cloud sessions (Claude Code on the web), whose file tools run in a container that is itself the boundary, may not apply it.
7422
+ * Refuse file-tool writes (Write, Edit, NotebookEdit) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Files that Claude Code keeps for the session are not refused: its plan files, scratchpad and background job folder, and the auto-memory of this project, unless a repository settings file points it elsewhere (a setting of the program that starts Claude Code can narrow this and the working directories). Nothing runs them unless the model asks. Also refuses file-tool writes to Claude Code settings files, inside the working directories too, and takes EnterWorktree and ExitWorktree, which move the working directory, out of the tools on offer (a setting of the program that starts Claude Code can keep them). Does not limit shell commands, MCP tools, the programs that hooks run, or the memory tools. Cloud sessions (Claude Code on the web), whose file tools run in a container that is itself the boundary, may not apply it.
7321
7423
  */
7322
7424
  blockWritesOutsideWorkingDirectories?: boolean;
7323
7425
  /**
@@ -7794,7 +7896,7 @@ export declare interface Settings {
7794
7896
  */
7795
7897
  httpHookAllowedEnvVars?: string[];
7796
7898
  /**
7797
- * 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 (in Claude Desktop, only while this is not set by the organization's own managed settings), 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.
7899
+ * 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 (in Claude Desktop, only while this is not set by the organization's own managed settings), 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) (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.
7798
7900
  */
7799
7901
  allowManagedPermissionRulesOnly?: boolean;
7800
7902
  /**
@@ -7862,14 +7964,14 @@ export declare interface Settings {
7862
7964
  [k: string]: unknown;
7863
7965
  })[];
7864
7966
  /**
7865
- * Custom per-subagent status line shown in the agent panel; receives row context as JSON on stdin
7967
+ * Deprecated: no longer has any effect. Subagent rows always use the default look.
7866
7968
  */
7867
7969
  subagentStatusLine?: {
7868
7970
  type: 'command';
7869
7971
  command: string;
7870
7972
  };
7871
7973
  /**
7872
- * Enabled plugins using plugin-id\@marketplace-id format. Example: { "formatter\@anthropic-tools": true }. Also supports extended format with version constraints. Settings precedence is user < project < local < flag < policy, so to disable a plugin that project settings enable, set it to false in .claude/settings.local.json — setting false in ~/.claude/settings.json is overridden by the project.
7974
+ * Enabled plugins using plugin-id\@marketplace-id format. Example: { "formatter\@anthropic-tools": true }. Only true turns on a marketplace plugin: a list of versions is accepted but leaves it off. Settings precedence is user < project < local < flag < policy, so to disable a plugin that project settings enable, set it to false in .claude/settings.local.json — setting false in ~/.claude/settings.json is overridden by the project.
7873
7975
  */
7874
7976
  enabledPlugins?: {
7875
7977
  [k: string]: string[] | boolean | {
@@ -7955,7 +8057,7 @@ export declare interface Settings {
7955
8057
  } | {
7956
8058
  source: 'npm';
7957
8059
  /**
7958
- * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). In strictKnownMarketplaces / blockedMarketplaces an entry also governs plugins installed straight from the npm marketplace (`<package>\@npm`): an exact package name matches that package, and "\@acme/*" matches every package under the scope.
8060
+ * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
7959
8061
  */
7960
8062
  package: string;
7961
8063
  /**
@@ -7963,7 +8065,7 @@ export declare interface Settings {
7963
8065
  */
7964
8066
  version?: string;
7965
8067
  /**
7966
- * 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.
8068
+ * Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
7967
8069
  */
7968
8070
  registry?: string;
7969
8071
  } | {
@@ -8100,6 +8202,12 @@ export declare interface Settings {
8100
8202
  description?: string;
8101
8203
  version?: string;
8102
8204
  strict?: boolean;
8205
+ /**
8206
+ * Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
8207
+ */
8208
+ engines?: {
8209
+ [k: string]: unknown;
8210
+ };
8103
8211
  /**
8104
8212
  * HTTP headers sent when downloading this entry's `archive` source.
8105
8213
  */
@@ -8135,7 +8243,7 @@ export declare interface Settings {
8135
8243
  */
8136
8244
  autoUpdate?: boolean;
8137
8245
  /**
8138
- * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8246
+ * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link, .claude-directory-proof.json and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8139
8247
  */
8140
8248
  pluginDigests?: {
8141
8249
  [k: string]: string[];
@@ -8213,7 +8321,7 @@ export declare interface Settings {
8213
8321
  } | {
8214
8322
  source: 'npm';
8215
8323
  /**
8216
- * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). In strictKnownMarketplaces / blockedMarketplaces an entry also governs plugins installed straight from the npm marketplace (`<package>\@npm`): an exact package name matches that package, and "\@acme/*" matches every package under the scope.
8324
+ * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
8217
8325
  */
8218
8326
  package: string;
8219
8327
  /**
@@ -8221,7 +8329,7 @@ export declare interface Settings {
8221
8329
  */
8222
8330
  version?: string;
8223
8331
  /**
8224
- * 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.
8332
+ * Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
8225
8333
  */
8226
8334
  registry?: string;
8227
8335
  } | {
@@ -8358,6 +8466,12 @@ export declare interface Settings {
8358
8466
  description?: string;
8359
8467
  version?: string;
8360
8468
  strict?: boolean;
8469
+ /**
8470
+ * Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
8471
+ */
8472
+ engines?: {
8473
+ [k: string]: unknown;
8474
+ };
8361
8475
  /**
8362
8476
  * HTTP headers sent when downloading this entry's `archive` source.
8363
8477
  */
@@ -8393,7 +8507,7 @@ export declare interface Settings {
8393
8507
  */
8394
8508
  autoUpdate?: boolean;
8395
8509
  /**
8396
- * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8510
+ * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link, .claude-directory-proof.json and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8397
8511
  */
8398
8512
  pluginDigests?: {
8399
8513
  [k: string]: string[];
@@ -8466,7 +8580,7 @@ export declare interface Settings {
8466
8580
  } | {
8467
8581
  source: 'npm';
8468
8582
  /**
8469
- * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). In strictKnownMarketplaces / blockedMarketplaces an entry also governs plugins installed straight from the npm marketplace (`<package>\@npm`): an exact package name matches that package, and "\@acme/*" matches every package under the scope.
8583
+ * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
8470
8584
  */
8471
8585
  package: string;
8472
8586
  /**
@@ -8474,7 +8588,7 @@ export declare interface Settings {
8474
8588
  */
8475
8589
  version?: string;
8476
8590
  /**
8477
- * 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.
8591
+ * Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
8478
8592
  */
8479
8593
  registry?: string;
8480
8594
  } | {
@@ -8611,6 +8725,12 @@ export declare interface Settings {
8611
8725
  description?: string;
8612
8726
  version?: string;
8613
8727
  strict?: boolean;
8728
+ /**
8729
+ * Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
8730
+ */
8731
+ engines?: {
8732
+ [k: string]: unknown;
8733
+ };
8614
8734
  /**
8615
8735
  * HTTP headers sent when downloading this entry's `archive` source.
8616
8736
  */
@@ -8703,7 +8823,7 @@ export declare interface Settings {
8703
8823
  } | {
8704
8824
  source: 'npm';
8705
8825
  /**
8706
- * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). In strictKnownMarketplaces / blockedMarketplaces an entry also governs plugins installed straight from the npm marketplace (`<package>\@npm`): an exact package name matches that package, and "\@acme/*" matches every package under the scope.
8826
+ * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
8707
8827
  */
8708
8828
  package: string;
8709
8829
  /**
@@ -8711,7 +8831,7 @@ export declare interface Settings {
8711
8831
  */
8712
8832
  version?: string;
8713
8833
  /**
8714
- * 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.
8834
+ * Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
8715
8835
  */
8716
8836
  registry?: string;
8717
8837
  } | {
@@ -8848,6 +8968,12 @@ export declare interface Settings {
8848
8968
  description?: string;
8849
8969
  version?: string;
8850
8970
  strict?: boolean;
8971
+ /**
8972
+ * Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
8973
+ */
8974
+ engines?: {
8975
+ [k: string]: unknown;
8976
+ };
8851
8977
  /**
8852
8978
  * HTTP headers sent when downloading this entry's `archive` source.
8853
8979
  */
@@ -8940,7 +9066,7 @@ export declare interface Settings {
8940
9066
  } | {
8941
9067
  source: 'npm';
8942
9068
  /**
8943
- * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). In strictKnownMarketplaces / blockedMarketplaces an entry also governs plugins installed straight from the npm marketplace (`<package>\@npm`): an exact package name matches that package, and "\@acme/*" matches every package under the scope.
9069
+ * npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
8944
9070
  */
8945
9071
  package: string;
8946
9072
  /**
@@ -8948,7 +9074,7 @@ export declare interface Settings {
8948
9074
  */
8949
9075
  version?: string;
8950
9076
  /**
8951
- * 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.
9077
+ * Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
8952
9078
  */
8953
9079
  registry?: string;
8954
9080
  } | {
@@ -9085,6 +9211,12 @@ export declare interface Settings {
9085
9211
  description?: string;
9086
9212
  version?: string;
9087
9213
  strict?: boolean;
9214
+ /**
9215
+ * Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
9216
+ */
9217
+ engines?: {
9218
+ [k: string]: unknown;
9219
+ };
9088
9220
  /**
9089
9221
  * HTTP headers sent when downloading this entry's `archive` source.
9090
9222
  */
@@ -9429,6 +9561,7 @@ export declare interface Settings {
9429
9561
  * Whether to show tips in the spinner
9430
9562
  */
9431
9563
  spinnerTipsEnabled?: boolean;
9564
+
9432
9565
  /**
9433
9566
  * Customize spinner verbs. mode: "append" adds verbs to defaults, "replace" uses only your verbs.
9434
9567
  */
@@ -9563,7 +9696,7 @@ export declare interface Settings {
9563
9696
  */
9564
9697
  showClearContextOnPlanAccept?: boolean;
9565
9698
  /**
9566
- * Idle time before Claude's questions auto-continue with any answers selected so far. Defaults to never — auto-continue only runs when explicitly set to 60s/5m/10m.
9699
+ * Idle time before Claude's questions in the terminal auto-continue with any answers selected so far. When unset, the terminal does not auto-continue. The Claude desktop and web apps show Claude's questions in their own interface and may move on from some unanswered ones after a wait the app sets. Claude is then told that nobody answered and uses its best judgment. In sessions that read this setting, only "never" stops the apps from moving on. Leaving it unset does not. Cloud sessions and Cowork tasks do not read your user settings file (~/.claude/settings.json), and managed settings do not reach all of them. This setting is ignored in a project's settings files.
9567
9700
  */
9568
9701
  askUserQuestionTimeout?: '60s' | '5m' | '10m' | 'never';
9569
9702
  /**
@@ -9781,6 +9914,7 @@ export declare interface Settings {
9781
9914
  * Precompute the compaction summary in the background before it is needed. Only applies when auto-compact is on.
9782
9915
  */
9783
9916
  precomputeCompactionEnabled?: boolean;
9917
+
9784
9918
  /**
9785
9919
  * Set to false to stop Claude Code from compacting a long conversation while the session is idle. Defaults to true.
9786
9920
  */