hyperbrane 0.2.0 → 0.2.1

package/dist/vendor-types/claude/agent-sdk/sdk.d.ts

@@ -73,6 +73,10 @@ export declare type AgentDefinition = {
      * Maximum number of agentic turns (API round-trips) before stopping
      */
     maxTurns?: number;
+    /**
+     * Token count at which this agent compacts its own conversation when it runs as a subagent. It only lowers the window the subagent would otherwise inherit. No effect on the main session agent.
+     */
+    autoCompactWindow?: number;
     /**
      * Run this agent as a background task (non-blocking, fire-and-forget) when invoked
      */
@@ -200,6 +204,17 @@ export declare type BaseOutputFormat = {
     type: OutputFormatType;
 };
 
+/**
+ * Names of built-in tools, as permission rules, hook matchers, `tools` and
+ * `disallowedTools` spell them. A name is listed even where a platform or
+ * setting turns its tool off. The list is not complete: the CLI has tools that
+ * are not on it, so it cannot stand for "every tool". What a session has is
+ * the `tools` field of its `system/init` message.
+ *
+ * @alpha
+ */
+export declare const BUILTIN_TOOL_NAMES: readonly ['Agent', 'Artifact', 'AskUserQuestion', 'Bash', 'ClaudeDesign', 'CronCreate', 'CronDelete', 'CronList', 'Edit', 'EndConversation', 'EnterPlanMode', 'EnterWorktree', 'ExitPlanMode', 'ExitWorktree', 'Glob', 'Grep', 'ListAgents', 'ListMcpResourcesTool', 'LSP', 'Monitor', 'NotebookEdit', 'OfferChromeSetup', 'PowerShell', 'Projects', 'propose_skills', 'ProposeGoal', 'PushNotification', 'Read', 'ReadMcpResourceDirTool', 'ReadMcpResourceTool', 'ReadNotifications', 'RemoteTrigger', 'ReportFindings', 'ScheduleWakeup', 'SendFeedback', 'SendMessage', 'SendUserFile', 'SendUserMessage', 'ShareOnboardingGuide', 'ShowOnboardingRolePicker', 'Skill', 'SubagentHandback', 'TaskCreate', 'TaskGet', 'TaskList', 'TaskStop', 'TaskUpdate', 'TodoWrite', 'ToolSearch', 'WaitForMcpServers', 'WebFetch', 'WebSearch', 'Workflow', 'Write'];
+
 /**
  * Permission callback function for controlling tool usage.
  * Called before each tool execution to determine if it should be allowed.
@@ -244,6 +259,9 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
     };
     /** Explains why this permission request was triggered. */
     decisionReason?: string;
+
+
+
     /**
      * Full permission prompt sentence rendered by the bridge (e.g.
      * "Claude wants to read foo.txt"). Use this as the primary prompt
@@ -277,6 +295,7 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
     toolUseID: string;
     /** If running within the context of a sub-agent, the sub-agent's ID. */
     agentID?: string;
+
     /**
      * The control_request envelope's `request_id`. A control_response sent
      * out-of-band (e.g. a signed HTTP POST instead of the SDK's WS write)
@@ -386,6 +405,7 @@ declare type ControlErrorResponse = {
      */
     error: string;
 
+
     /**
      * can_use_tool requests this CLI process has issued and not yet resolved, so a client joining an already-initialized session learns about in-flight prompts. Always present (possibly empty) on a success `initialize` response from Claude Code v2.1.268 or later; earlier versions could omit it, so treat absence as an older CLI rather than as "nothing pending". A prompt inherited from a previous worker of the same session can remain answerable without appearing here and without a control_cancel_request; session_state "requires_action" on the same reply signals one the CLI is holding, but not every inherited prompt is signalled.
      */
@@ -604,6 +624,11 @@ declare namespace coreTypes {
  * Tool calls are bounded by the MCP tool-call timeout — `options.timeout`
  * (ms) for this server, else the MCP_TOOL_TIMEOUT env var, effectively
  * unbounded by default.
+ *
+ * A tool in `options.tools` whose input schema cannot be converted to JSON
+ * Schema is left out of the server's tool list, with one warning naming it (a
+ * process warning with code CLAUDE_SDK_MCP_TOOL_SCHEMA_UNCONVERTIBLE, or
+ * console.warn where there is no process.emitWarning); its other tools load.
  */
 export declare function createSdkMcpServer(_options: CreateSdkMcpServerOptions): McpSdkServerConfigWithInstance;
 
@@ -679,11 +704,7 @@ export declare type DirectoryAddedHookInput = BaseHookInput & {
 /**
  * Effort level for controlling how much thinking/reasoning Claude applies.
  *
- * - `'low'` — Minimal thinking, fastest responses
- * - `'medium'` — Moderate thinking
- * - `'high'` — Deep reasoning (default)
- * - `'xhigh'` — Deeper than high (Fable 5, Opus 4.7+, Sonnet 5; falls back to `'high'` elsewhere)
- * - `'max'` — Maximum effort (select models only)
+ * @see https://platform.claude.com/docs/en/build-with-claude/effort
  */
 export declare type EffortLevel = 'low' | 'medium' | 'high' | 'xhigh' | 'max';
 
@@ -1072,6 +1093,15 @@ export declare type JsonSchemaOutputFormat = {
     schema: Record<string, unknown>;
 };
 
+/**
+ * Former names that permission rules, hook matchers, `tools` and
+ * `disallowedTools` still accept, each mapped to the tool's current name. An
+ * entry is dropped when its tool is removed.
+ *
+ * @alpha
+ */
+export declare const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;
+
 /**
  * List sessions with metadata.
  *
@@ -1183,7 +1213,7 @@ export declare type McpHttpServerConfig = {
     timeout?: number;
 
     /**
-     * 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.
+     * 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. When false, all tools from this server are deferred behind tool search. Default: tools are deferred when tool search is enabled. As a side effect, true 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.
      */
     alwaysLoad?: boolean;
 
@@ -1196,6 +1226,12 @@ export declare type McpSdkServerConfig = {
      * Per-server tool-call timeout in milliseconds. Overrides the MCP_TOOL_TIMEOUT environment variable for this server. Hard wall-clock limit per call; progress notifications do not extend it. Values below 1000ms are ignored (falls through to MCP_TOOL_TIMEOUT or the default). Applies when the server is first registered; changing it for an already-registered server has no effect until it is removed and re-added.
      */
     timeout?: number;
+
+
+    /**
+     * 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.
+     */
+    tools?: McpServerToolPolicy[];
 };
 
 /**
@@ -1252,6 +1288,9 @@ export declare type McpServerStatus = {
      * Server configuration (includes URL for HTTP/SSE servers)
      */
     config?: McpServerStatusConfig;
+
+
+
     /**
      * Configuration scope (e.g., project, user, local, claudeai, managed)
      */
@@ -1272,7 +1311,7 @@ export declare type McpServerStatus = {
             openWorld?: boolean;
         };
         /**
-         * The MCP Apps (SEP-1865) members of the tool's `_meta`, for a host that renders the tool's `ui://` resource, under the keys the server used: `ui` (an object: `resourceUri`, a `ui://` string; `visibility`, an array of 'model' | 'app'; and any other member the server sent) and the deprecated flat `ui/resourceUri` (a `ui://` string). Validated and size-bounded; every other `_meta` key is withheld. Present only on a tool that declares one, from CLIs that advertise `mcp_tool_ui_meta_v1`.
+         * The MCP Apps (SEP-1865) members of the tool's `_meta`, for a host that renders the tool's `ui://` resource, under the keys the server used: `ui` (an object: `resourceUri`, a `ui://` string; `visibility`, an array of 'model' | 'app'; and any other member the server sent) and the deprecated flat `ui/resourceUri` (a `ui://` string). Each is validated and size-bounded, and withheld if it fails. Of a `ui` that fails, only `visibility` still arrives: the 'model' and 'app' entries the server listed, or `[]` (neither audience) if `ui` is not an object or `visibility` not an array; `null` counts as absent. So a tool with no `visibility` declared none. A CLI that does not advertise `mcp_call_result_not_for_model_v1` may withhold a failed `ui` whole. Every other `_meta` key is withheld. Present only on a tool that declares one, from CLIs that advertise `mcp_tool_ui_meta_v1`.
          */
         _meta?: Record<string, unknown>;
     }[];
@@ -1282,7 +1321,7 @@ export declare type McpServerStatus = {
 export declare type McpServerStatusConfig = McpServerConfigForProcessTransport | McpClaudeAIProxyServerConfig;
 
 /**
- * Per-tool permission policy carried on mcp_set_servers for remote servers.
+ * Per-tool permission policy for an MCP server: carried on mcp_set_servers for remote (http/sse) servers, and on mcp_set_servers or initialize (sdkMcpServerConfigs) for host-registered sdk servers, where only always_ask and always_deny take effect.
  */
 export declare type McpServerToolPolicy = {
     name: string;
@@ -1322,7 +1361,7 @@ export declare type McpSSEServerConfig = {
     timeout?: number;
 
     /**
-     * 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.
+     * 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. When false, all tools from this server are deferred behind tool search. Default: tools are deferred when tool search is enabled. As a side effect, true 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.
      */
     alwaysLoad?: boolean;
 
@@ -1338,7 +1377,7 @@ export declare type McpStdioServerConfig = {
      */
     timeout?: number;
     /**
-     * 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.
+     * 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. When false, all tools from this server are deferred behind tool search. Default: tools are deferred when tool search is enabled. As a side effect, true 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.
      */
     alwaysLoad?: boolean;
 
@@ -1424,6 +1463,7 @@ export declare type ModelInfo = {
     supportsAutoMode?: boolean;
 
 
+
 };
 
 export declare type ModelUsage = {
@@ -1454,7 +1494,7 @@ export declare type ModelUsage = {
 };
 
 export declare type NonNullableUsage = {
-    [K in keyof BetaUsage]: NonNullable<BetaUsage[K]>;
+    [K in keyof BetaUsage]: K extends 'fallback_credit' ? BetaUsage[K] : NonNullable<BetaUsage[K]>;
 };
 
 export declare type NotificationHookInput = BaseHookInput & {
@@ -1625,6 +1665,7 @@ export declare type Options = {
      * ```
      */
     toolAliases?: Record<string, string>;
+
     /**
      * Specify the base set of available built-in tools.
      * - `string[]` - Array of specific tool names (e.g., `['Bash', 'Read', 'Edit']`)
@@ -1905,12 +1946,6 @@ export declare type Options = {
      * Controls how much effort Claude puts into its response.
      * Works with adaptive thinking to guide thinking depth.
      *
-     * - `'low'` — Minimal thinking, fastest responses
-     * - `'medium'` — Moderate thinking
-     * - `'high'` — Deep reasoning (default)
-     * - `'xhigh'` — Deeper than high (Fable 5, Opus 4.7+, Sonnet 5)
-     * - `'max'` — Maximum effort (Fable 5, Opus 4.6+, Sonnet 4.6+)
-     *
      * @see https://platform.claude.com/docs/en/build-with-claude/effort
      */
     effort?: EffortLevel;
@@ -1981,12 +2016,18 @@ export declare type Options = {
      */
     pathToClaudeCodeExecutable?: string;
     /**
-     * Permission mode for the session.
+     * Permission mode for the session. When omitted, Claude Code picks the
+     * starting mode as it does for `claude -p`: a `permissions.defaultMode`
+     * from the settings the session loads, else `'auto'` where that is the
+     * default (and `'default'` where auto mode is unavailable). Pass
+     * `'default'` to keep manual approvals through `canUseTool` (on a cloud
+     * create or attach, `'default'` leaves the session's own mode).
      * - `'default'` - Standard permission behavior, prompts for dangerous operations
      * - `'acceptEdits'` - Auto-accept file edit operations
      * - `'bypassPermissions'` - Bypass all permission checks (requires `allowDangerouslySkipPermissions`)
      * - `'plan'` - Planning mode, no execution of tools
      * - `'dontAsk'` - Don't prompt for permissions, deny if not pre-approved
+     * - `'auto'` - A model classifier approves or denies each call, prompting through `canUseTool` when it cannot decide
      */
     permissionMode?: PermissionMode;
     /**
@@ -2153,19 +2194,33 @@ export declare type Options = {
      * When enabled, commands are executed in a sandboxed environment that restricts
      * filesystem and network access. This provides an additional security layer.
      *
-     * **Important:** Filesystem and network restrictions are configured via permission
-     * rules, not via these sandbox settings:
-     * - Filesystem access: Use `Read` and `Edit` permission rules
-     * - Network access: Use `WebFetch` permission rules
-     *
-     * These sandbox settings control sandbox behavior (enabled, auto-allow, etc.),
-     * while the actual access restrictions come from your permission configuration.
-     *
-     * **Dependency check:** When `enabled: true` is passed via this option,
-     * `failIfUnavailable` defaults to `true` — if sandbox dependencies are missing
-     * (e.g. `bubblewrap` on Linux) or the platform is unsupported, `query()` will
-     * emit an error result and exit rather than silently running commands
-     * unsandboxed. Set `failIfUnavailable: false` to allow graceful degradation.
+     * Access restrictions can be set here (`filesystem`, `network`, `credentials`);
+     * filesystem and network restrictions also come from `Read`, `Edit` and
+     * `WebFetch` permission rules, and Claude Code applies both.
+     *
+     * **Dependency check:** When this option sets `enabled: true`,
+     * `failIfUnavailable` defaults to `true` unless this option or an inline
+     * `settings` sandbox block sets it: if sandbox dependencies are missing (e.g.
+     * `bubblewrap` on Linux) or the platform is unsupported, `query()` emits an
+     * error result and exits rather than silently running commands unsandboxed.
+     * Set `failIfUnavailable: false` to allow graceful degradation.
+     *
+     * **With `settings`:** when `settings` is given inline (an object or JSON string,
+     * not a file path) and has its own `sandbox` block, this option is merged into
+     * it. A value this option sets replaces the value at the same path, and a
+     * value it does not set is kept, with two exceptions: a
+     * `filesystem.disabled: true` is dropped when this option sets `filesystem` or
+     * a `credentials.files` deny entry, since it would switch those off; and a
+     * `network.httpProxyPort` or `network.socksProxyPort` is dropped when this
+     * option sets `network.allowedDomains`, a `network.deniedDomains` entry or
+     * `network.strictAllowlist: true` and does not set that port itself, since
+     * traffic through your own proxy is not checked against those lists. Nested
+     * objects merge key by key, except `ripgrep` and
+     * `network.tlsTerminate`, which this option replaces whole; and the restriction
+     * lists (`filesystem.denyRead`, `filesystem.denyWrite`, `network.deniedDomains`,
+     * `credentials.files`, `credentials.envVars`) from both are combined instead, a
+     * `deny` from either side winning over a `mask` for the same credential path or
+     * variable. A `settings` file path cannot be combined with this option.
      *
      * @example Enable sandboxing with auto-allow
      * ```typescript
@@ -2175,7 +2230,7 @@ export declare type Options = {
      * }
      * ```
      *
-     * @example Configure network options (not restrictions)
+     * @example Configure network options
      * ```typescript
      * sandbox: {
      *   enabled: true,
@@ -2224,6 +2279,18 @@ export declare type Options = {
      * tier present, these apply as the sole policy tier (still filtered
      * restrictive-only — non-allowlisted keys are dropped regardless).
      *
+     * Two hook keys are filtered by value rather than kept as written:
+     * `disableAllHooks: true` binds as `allowManagedHooksOnly: true`, so the
+     * machine administrator's own hooks keep running where the embedder's tier
+     * cannot stop them — and because an enterprise configuration often yields
+     * a boolean as text, any value but `false` and `"false"` binds it the same
+     * way — and `allowedHttpHookUrls` / `httpHookAllowedEnvVars`
+     * bind only as the empty list (admit nothing) — a non-empty one is dropped,
+     * because these lists union across settings sources and would widen an
+     * admin's. For the same reason an empty list binds only where no other
+     * source sets one; pair it with `allowManagedHooksOnly` to stop a project's
+     * HTTP hooks outright.
+     *
      * Intended for embedding applications (e.g. desktop apps) that derive
      * lockdown settings from their own enterprise configuration and need to
      * enforce them on the spawned subprocess without writing root-owned files.
@@ -2668,7 +2735,7 @@ export declare type PostToolUseHookSpecificOutput = {
     hookEventName: 'PostToolUse';
     additionalContext?: string;
     /**
-     * Host-asserted context shown to the auto-mode permission classifier alongside this tool call's result. In the live session the classifier may weigh a user statement relayed here as user intent (it can satisfy a consent bar a user turn would satisfy, never a hard boundary); values restored from saved session state are treated as unverified context only. Relay discipline is the host's obligation: put ONLY genuine user statements in intent-bearing positions — never tool output or model text dressed as one. Capped at 2000 UTF-16 code units, a budget shared across all hooks that contribute to one call (surrogate-pair-safe; emoji and other astral characters count as two). Honored on synchronous hook responses only: an async hook's late response arrives after the result message is frozen and this field in it is silently ignored. Security note: do not copy untrusted tool output or third-party text into it blindly — content placed here reaches the permission classifier with host-application framing. Applies only to calls the classifier transcript shows: read-only lookups the transcript omits (file reads, searches), inner REPL calls, and remote-engine shells produce no per-result line, and context attached to them is silently unused. Not a delivery channel: it is bound to a single call id and sized for a short assertion, not for relaying messages or events. Rewrite integrity: if this assertion describes output you are rewriting, return it in the SAME hook result as the rewrite — it is then dropped automatically if your rewrite is rejected or superseded by a later hook's rewrite; assertions returned without a rewrite are never invalidated by other hooks' rewrites, so a non-rewriting hook should assert only what holds regardless of other hooks' rewrites — hosts that need an assertion bound to exact output bytes should make it in the hook that produces those bytes. (Do NOT return an identity rewrite just to pair an assertion: hooks run in parallel on the ORIGINAL output, so an identity rewrite competes last-write-wins with sibling rewrites and can clobber a real redaction.)
+     * Host-asserted context shown to the auto-mode permission classifier alongside this tool call's result. In the live session the classifier may weigh a user statement relayed here as user intent (it can satisfy a consent bar a user turn would satisfy, never a hard boundary); values restored from saved session state are treated as unverified context only. Relay discipline is the host's obligation: put ONLY genuine user statements in intent-bearing positions — never tool output or model text dressed as one. Capped at 2000 UTF-16 code units, a budget shared across all hooks that contribute to one call (surrogate-pair-safe; emoji and other astral characters count as two). Honored on synchronous hook responses only: an async hook's late response arrives after the result message is frozen and this field in it is silently ignored. Security note: do not copy untrusted tool output or third-party text into it blindly — content placed here reaches the permission classifier with host-application framing. Applies only to calls the classifier transcript shows: read-only lookups the transcript omits (file reads, searches) and remote-engine shells produce no per-result line, and context attached to them is silently unused. Not a delivery channel: it is bound to a single call id and sized for a short assertion, not for relaying messages or events. Rewrite integrity: if this assertion describes output you are rewriting, return it in the SAME hook result as the rewrite — it is then dropped automatically if your rewrite is rejected or superseded by a later hook's rewrite; assertions returned without a rewrite are never invalidated by other hooks' rewrites, so a non-rewriting hook should assert only what holds regardless of other hooks' rewrites — hosts that need an assertion bound to exact output bytes should make it in the hook that produces those bytes. (Do NOT return an identity rewrite just to pair an assertion: hooks run in parallel on the ORIGINAL output, so an identity rewrite competes last-write-wins with sibling rewrites and can clobber a real redaction.)
      */
     classifierContext?: string;
     /**
@@ -2748,6 +2815,7 @@ export declare type PreToolUseHookSpecificOutput = {
     permissionDecisionReason?: string;
     updatedInput?: Record<string, unknown>;
     additionalContext?: string;
+
 };
 
 /**
@@ -2821,6 +2889,10 @@ export declare type PreToolUseHookSpecificOutput = {
  */
 export declare function prewarm(_params?: {
     options?: Options;
+    /**
+     * The most time, in milliseconds, to wait for the spare process to
+     * initialize; it counts throughout. Defaults to 60000.
+     */
     initializeTimeoutMs?: number;
 }): Promise<SpareProcess>;
 
@@ -2913,8 +2985,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
      * / `--thinking-display`) is kept — a session started with thinking
      * disabled has none, so re-enabling without this param gets that default.
      * `'highlights'` (the API's one-line thinking titles) is honored by the API
-     * only for Anthropic-hosted remote sessions; the promise rejects, changing
-     * nothing, when the session cannot send it to the API.
+     * only for Anthropic-hosted remote sessions; when the session cannot send it
+     * to the API the promise rejects and the display stays as it was, while
+     * `maxThinkingTokens` still applies.
      */
     setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | 'highlights' | null): Promise<void>;
     /**
@@ -2933,6 +3006,11 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
      * main-thread agent, and `ultracode` to off with the current effort kept.
      * Only available in streaming input mode.
      *
+     * `ultracode: true` or `false` turns ultracode on or off and leaves the
+     * effort level alone. An `effortLevel` that moves the session to a
+     * different level, sent without an `ultracode` key, also turns ultracode
+     * off; send both keys to change the level and keep it on.
+     *
      * @param settings - A partial settings object to merge into the flag
      * settings. `effortLevel` also accepts `'max'` (never written to settings
      * files, so the persisted {@link Settings.effortLevel} excludes it): it is
@@ -3055,6 +3133,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
 
 
 
+
     /**
      * Read a file from the session's filesystem for the remote sidebar
      * viewer. Path is resolved against cwd and gated by the same
@@ -3081,11 +3160,16 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
      * describing what applying would change; call again without the option
      * to apply anyway.
      *
+     * With `addPlugins`, the reload also loads those plugins, as if each had
+     * been in the `plugins` option at launch; plugins already loaded stay. Each
+     * path must be absolute.
+     *
      * @returns The refreshed session components after plugin reload, or the
      * unchanged ones with `held: true` when the reload was held
      */
     reloadPlugins(options?: {
         holdOnCacheImpact?: boolean;
+        addPlugins?: SdkPluginConfig[];
     }): Promise<SDKControlReloadPluginsResponse>;
     /**
      * Reload skills from disk and return the refreshed skill list.
@@ -3139,6 +3223,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
 
 
 
+
     /**
      * Reconnect an MCP server by name.
      * Throws on failure.
@@ -3373,7 +3458,7 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
         maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
         maskDuplicates: z.ZodOptional<z.ZodBoolean>;
         injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>>>;
+    }, z.core.$strip>, unknown>>>;
     envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
         name: z.ZodString;
         mode: z.ZodEnum<{
@@ -3391,7 +3476,7 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
         }>>;
         maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
         injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    }, z.core.$strip>>>>;
+    }, z.core.$strip>, unknown>>>;
     allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
     awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
         accessKeyIdVar: z.ZodString;
@@ -3505,7 +3590,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
             maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maskDuplicates: z.ZodOptional<z.ZodBoolean>;
             injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>>>;
+        }, z.core.$strip>, unknown>>>;
         envVars: z.ZodOptional<z.ZodArray<z.ZodPreprocess<z.ZodObject<{
             name: z.ZodString;
             mode: z.ZodEnum<{
@@ -3523,7 +3608,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
             }>>;
             maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
             injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$strip>>>>;
+        }, z.core.$strip>, unknown>>>;
         allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
         awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
             accessKeyIdVar: z.ZodString;
@@ -3547,6 +3632,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
     }, z.core.$strip>>;
     ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
+    allowNestedUserNamespaces: z.ZodOptional<z.ZodBoolean>;
     enableWeakerNetworkIsolation: z.ZodOptional<z.ZodBoolean>;
     allowAppleEvents: z.ZodOptional<z.ZodBoolean>;
     excludedCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3554,8 +3640,8 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
         command: z.ZodString;
         args: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
-    bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString>>>;
-    socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString>>>;
+    bwrapPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
+    socatPath: z.ZodCatch<z.ZodOptional<z.ZodPreprocess<z.ZodString, unknown>>>;
 }, z.core.$loose>;
 
 /**
@@ -3611,8 +3697,9 @@ export declare type SDKAssistantMessage = {
 
     session_id: string;
     request_id?: string;
+
     /**
-     * Client uuid of the user message this turn is answering (submitMessage options.uuid), stamped on an assistant message each time that send changes — the turn's FIRST top-level assistant message (which may carry only a thinking block, or be a synthetic API-error message), and then, for a turn started by a synthetic (meta) prompt, the first assistant message after each queued user message folded in mid-turn (the fold takes the echo over); with --include-partial-messages the turn's first non-ping stream event is stamped too, independently (see SDKPartialAssistantMessage), so the same uuid may appear on both — either binds the reply to the send it answers without waiting for the result; the server keeps the first stamp it sees per uuid. A turn started by a typed prompt keeps that uuid for its whole turn, so it stamps once per frame kind. A meta turn's own uuid is stamped only when the host vouches it is the client event's own (on a hosted session, the uuid the session server persisted: delivered content such as a Slack owner ping, a Slack-bot observation or a client-injected synthetic turn), never for a prompt the CLI minted itself — except that the boot-time rescue turn re-running a turn a worker restart interrupted mid-way stamps the interrupted turn's own last user prompt (with resume_reason), the send that re-run answers; either way a user message folded into a meta turn takes the echo over from it (the rescue turn absorbing messages sent while the session was down; a bot-observation turn absorbing a human's post), and the first reply frame of each kind after that fold carries the folded message's uuid — the first reply that message got. Wrapper-level sibling — never inside `message.content` — so it is not replayed to the model. Absent on every other frame of the turn, on subagent frames (parent_tool_use_id set), on turns that neither had a client uuid nor folded a user message in, and from older producers.
+     * Client uuid of the user message this turn is answering (submitMessage options.uuid), stamped on an assistant message each time that send changes — the turn's FIRST top-level assistant message (which may carry only a thinking block, or be a synthetic API-error message), and then, for a turn started by a synthetic (meta) prompt, the first assistant message after each queued user message folded in mid-turn (the fold takes the echo over); with --include-partial-messages the turn's first non-ping stream event is stamped too, independently (see SDKPartialAssistantMessage), so the same uuid may appear on both — either binds the reply to the send it answers without waiting for the result; the server keeps the first stamp it sees per uuid. A turn started by a typed prompt keeps that uuid for its whole turn, so it stamps once per frame kind. A meta turn's own uuid is stamped only when the host vouches it is the client event's own (on a hosted session, the uuid the session server persisted: delivered content such as a Slack owner ping, a Slack-bot observation or a client-injected synthetic turn), never for a prompt the CLI minted itself — except that a turn carrying resume_reason, such as the boot-time rescue turn re-running a turn a worker restart interrupted mid-way, stamps the interrupted turn's own last user prompt, the send it answers, where that can be vouched for (a turn that goes on from a permission answer or from in-flight tool calls may first re-send, unstamped, the assistant message that made those calls); either way a user message folded into a meta turn takes the echo over from it (the rescue turn absorbing messages sent while the session was down; a bot-observation turn absorbing a human's post), and the first reply frame of each kind after that fold carries the folded message's uuid — the first reply that message got. Wrapper-level sibling — never inside `message.content` — so it is not replayed to the model. Absent on every other frame of the turn, on subagent frames (parent_tool_use_id set), on turns that neither had a client uuid nor folded a user message in, and from older producers.
      */
     user_message_uuid?: string;
     /**
@@ -3620,7 +3707,7 @@ export declare type SDKAssistantMessage = {
      */
     user_message_uuids?: string[];
     /**
-     * Why this frame's turn is the automatic re-run of a turn a worker restart interrupted (CLAUDE_CODE_RESUME_INTERRUPTED_TURN): 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 re-run names the interrupted turn's own last user prompt), so a consumer can tell the re-run's first reply from the interrupted attempt's. Absent on every other turn, on thinking_tokens frames, and from older producers.
+     * 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.
      */
     resume_reason?: string;
     /**
@@ -3635,6 +3722,10 @@ export declare type SDKAssistantMessage = {
      * True when this assistant message was truncated by an interrupt/abort before the stream completed: stop_reason was never received and the content may end mid-word. Absent on normally completed messages.
      */
     aborted?: true;
+    /**
+     * ID of the subagent that produced this message: the `task_id` of its task events, unchanged when the subagent is resumed. Absent on main-thread messages.
+     */
+    agent_id?: string;
     /**
      * Subagent type that produced this message.
      */
@@ -3646,6 +3737,8 @@ export declare type SDKAssistantMessage = {
 
 
 
+
+
     /**
      * ISO timestamp of when this content block finished on the originating process. One API assistant turn may produce several assistant messages sharing a message.id, each with its own timestamp. Uses the originating host's clock, so it's for display only; do not order messages by this field. Older emitters omit it; consumers should fall back to receive time.
      */
@@ -3678,6 +3771,7 @@ export declare type SDKAssistantMessage = {
 
 
 
+
 };
 
 export declare type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'verification_required' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';
@@ -3692,7 +3786,7 @@ export declare type SDKAuthStatusMessage = {
 };
 
 /**
- * The full set of live background tasks, emitted whenever membership changes (start, completion, kill, a foreground agent being backgrounded) or an entry's `ambient` flag flips. A level signal, unlike the task_started/task_notification edge bookends: consumers that only need 'is background work running' should replace their set with each payload rather than pairing edges, so a missed bookend cannot wedge a stale running indicator. Ordering relative to the bookends for the same transition is unspecified (in practice the level precedes them) and the payload carries ids only, so do not correlate it with the edge stream. The level is per-process: nothing is emitted at startup, so consumers must reset to the empty set whenever the session's CLI process (re)starts and let the next membership change repopulate it. A host that re-initializes an already-running process (a repeated `initialize` control request, e.g. after reconnecting) is sent a snapshot of the current set right behind the success response to that request, even when it is empty, so it need not wait for a change; CLIs that predate this send nothing there.
+ * The full set of live background tasks, emitted whenever membership changes (start, completion, kill, a foreground agent being backgrounded) or an entry's `ambient` flag or `parent_task_id` changes. A level signal, unlike the task_started/task_notification edge bookends: consumers that only need 'is background work running' should replace their set with each payload rather than pairing edges, so a missed bookend cannot wedge a stale running indicator. Ordering relative to the bookends for the same transition is unspecified (in practice a task that starts in the background joins the level before its task_started, and a finishing task leaves it after its task_updated and task_notification), so do not correlate it with the edge stream. The level is per-process: nothing is emitted at startup, so consumers must reset to the empty set whenever the session's CLI process (re)starts and let the next membership change repopulate it. A host that re-initializes an already-running process (a repeated `initialize` control request, e.g. after reconnecting) is sent a snapshot of the current set right behind the success response to that request, even when it is empty, so it need not wait for a change; CLIs that predate this send nothing there.
  */
 export declare type SDKBackgroundTasksChangedMessage = {
     type: 'system';
@@ -3702,12 +3796,25 @@ export declare type SDKBackgroundTasksChangedMessage = {
      */
     tasks: {
         task_id: string;
+        /**
+         * Id of one run of the task: equal on every task_* event, background_tasks_changed entry and saved notification (its origin.runId) of that run. A resumed task keeps its task_id and gets a new one. The run ids of one task sort, by plain string comparison, in the order the runs opened; a frame that names a run sorting before the one a reader shows is late. Nothing else about the format is promised. Absent for a task this process did not register, and from CLIs that predate it.
+         */
+        run_id?: string;
         task_type: string;
+        /**
+         * Agent type of a local_agent task, such as "general-purpose" or a custom agent's name; "main-session" for a backgrounded main session. Not set on other tasks.
+         */
+        subagent_type?: string;
         description: string;
+        /**
+         * task_id of the subagent (local_agent) task whose agent launched this subagent, shell, monitor or workflow task. Absent when the launcher is the main thread, has no task_id of its own (a teammate, an agent inside a workflow), or is no longer tracked. A resumed subagent keeps its original parent. The parent may be a foreground or already-ended task, so treat an unknown id as no parent.
+         */
+        parent_task_id?: string;
         /**
          * True for tasks that are not activity (every skip_transcript task, plus every live-update watcher, requested or auto-started); hosts should exclude them from activity indicators.
          */
         ambient?: boolean;
+
     }[];
     uuid: UUID;
     session_id: string;
@@ -3739,6 +3846,7 @@ export declare type SDKCompactBoundaryMessage = {
 
 
 
+
         /**
          * 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).
          */
@@ -3863,7 +3971,7 @@ declare type SDKControlBackgroundTasksRequest = {
 };
 
 /**
- * Drops a pending async user message from the command queue by uuid. No-op if already dequeued for execution.
+ * Drops a pending async user message from the command queue by uuid. No-op if already dequeued for execution. Also a no-op, on a worker that recognises held messages, for the queued re-run of an interrupted turn while that re-run also answers for other client messages, which cancelling it would close though nobody withdrew them; see the response.
  */
 declare type SDKControlCancelAsyncMessageRequest = {
     subtype: 'cancel_async_message';
@@ -3892,6 +4000,10 @@ declare type SDKControlElicitationRequest = {
     url?: string;
     elicitation_id?: string;
     requested_schema?: Record<string, unknown>;
+    /**
+     * requested_schema.properties' top-level keys in the order the MCP server listed them; absent for URL mode and when the schema has no properties object. For a host whose transport keeps no JSON object key order (a protobuf Struct, say). Names that look like array indices ("0", "1", …) come first, in JavaScript's object key order.
+     */
+    property_order?: string[];
     /**
      * Permission-display title from the MCP server's _meta['anthropic/permissionDisplay']. Mirrors can_use_tool.title so SDK consumers can render elicitation-driven permission prompts with structured headers instead of parsing `message`.
      */
@@ -3937,6 +4049,10 @@ declare type SDKControlGetContextUsageRequest = {
  */
 export declare type SDKControlGetContextUsageResponse = {
     categories: {
+        /**
+         * Which row this is. Stable where the English name is not: match a particular row on this. Absent from a CLI that predates it. A later CLI may add values: treat an unknown value as absent.
+         */
+        id?: 'system_prompt' | 'system_tools' | 'mcp_tools' | 'mcp_instructions' | 'mcp_tools_deferred' | 'system_tools_deferred' | 'custom_agents' | 'memory_files' | 'skills' | 'messages' | 'autocompact_buffer' | 'compact_buffer' | 'free_space';
         name: string;
         tokens: number;
         color: string;
@@ -3970,6 +4086,16 @@ export declare type SDKControlGetContextUsageResponse = {
         tokens: number;
         isLoaded?: boolean;
     }[];
+    /**
+     * The 'mcp_instructions' row by server. Only the row's total is counted: each server's share of it is estimated from the length of its text. Present only where the CLI answers on its own stdio and no server stores or forwards the reply.
+     */
+    mcpInstructions?: {
+        /**
+         * Server name, as mcp_status reports it and mcp_toggle takes it (not normalized, unlike mcpTools[].serverName).
+         */
+        serverName: string;
+        tokens: number;
+    }[];
     deferredBuiltinTools?: {
         name: string;
         tokens: number;
@@ -3986,6 +4112,14 @@ export declare type SDKControlGetContextUsageResponse = {
     agents: {
         agentType: string;
         source: string;
+        /**
+         * Id of the providing plugin (its name and marketplace), when there is one. Present only where the CLI answers on its own stdio and no server stores or forwards the reply.
+         */
+        pluginId?: string;
+        /**
+         * Absolute path of the agent's file on the machine the CLI runs on, which over SSH or WSL is not the host's. Present only where the CLI answers on its own stdio and no server stores or forwards the reply: absent on cloud, self-hosted runner and Remote Control connections, and for an agent with no file.
+         */
+        path?: string;
         tokens: number;
     }[];
     slashCommands?: {
@@ -4000,6 +4134,18 @@ export declare type SDKControlGetContextUsageResponse = {
         skillFrontmatter: {
             name: string;
             source: string;
+            /**
+             * Name of the providing plugin, when there is one. Not unique across marketplaces: pluginId is.
+             */
+            pluginName?: string;
+            /**
+             * Id of the providing plugin (its name and marketplace), when there is one. Present only where the CLI answers on its own stdio and no server stores or forwards the reply.
+             */
+            pluginId?: string;
+            /**
+             * Absolute path of the skill's file on the machine the CLI runs on, which over SSH or WSL is not the host's. Present only where the CLI answers on its own stdio and no server stores or forwards the reply: absent on cloud, self-hosted runner and Remote Control connections, and for a skill with no file.
+             */
+            path?: string;
             tokens: number;
         }[];
     };
@@ -4194,6 +4340,35 @@ declare type SDKControlGetSettingsRequest = {
     subtype: 'get_settings';
 };
 
+/**
+ * Reads the end of one background shell or Monitor task's output: at most the last 8 KiB the command wrote, the same tail the terminal's /tasks detail view reads. Read-only and no model turn; a host polls it while the task runs, and can read it once more after the task ends. The output is whatever the command printed, escape sequences included: render it as plain text. Refused for a task_id that is neither a shell or Monitor task of this session nor shaped like one (an ended task's id whose file is gone reads as empty), and on a lane that redacts what it persists (a Remote Control bridge worker, a tenant worker).
+ */
+declare type SDKControlGetTaskOutputRequest = {
+    subtype: 'get_task_output';
+    /**
+     * A shell or Monitor task of this session, running or ended: the task_id from task_started or background_tasks_changed.
+     */
+    task_id: string;
+};
+
+/**
+ * Success payload answering get_task_output.
+ */
+declare type SDKControlGetTaskOutputResponse = {
+    /**
+     * The end of the output, decoded as UTF-8; empty when the command has written nothing yet.
+     */
+    output: string;
+    /**
+     * The size of the whole output in bytes.
+     */
+    total_bytes: number;
+    /**
+     * Whether output holds only the end of a longer output (the last 8 KiB).
+     */
+    truncated: boolean;
+};
+
 /**
  * Requests the structured /usage data: session cost/usage totals plus claude.ai plan rate-limit utilization when available. Experimental — the response shape may change.
  */
@@ -4321,7 +4496,7 @@ export declare type SDKControlGetUsageResponse = {
              * Behavioral characteristics of local usage. Categories overlap — this is not a partition, so percentages do not sum to 100.
              */
             behaviors: {
-                key: 'cache_miss' | 'long_context' | 'subagent_heavy' | 'high_parallel' | 'cron';
+                key: 'cache_miss' | 'long_context' | 'subagent_heavy' | 'high_parallel' | 'cron' | 'max_effort' | 'workflow' | 'always_on_context' | 'large_tool_results';
                 /**
                  * Share of the weighted local usage attributed to this behavior, 0-100.
                  */
@@ -4331,6 +4506,40 @@ export declare type SDKControlGetUsageResponse = {
                  */
                 count: number;
             }[];
+            /**
+             * One recommended change per notable behavior or source, largest share first, worded for display.
+             */
+            recommendations?: {
+                /**
+                 * The behavior key, or 'agent', 'skill', 'plugin' or 'mcp_server' for a named source.
+                 */
+                key: string;
+                /**
+                 * Share of the weighted local usage this touches, 0-100.
+                 */
+                pct: number;
+                /**
+                 * What to do, verb first.
+                 */
+                title: string;
+                /**
+                 * A few words: what the scan saw, or the command to run.
+                 */
+                detail?: string;
+            }[];
+            /**
+             * What one "fix" action does. Absent when nothing can be fixed in the session that answered.
+             */
+            fix?: {
+                /**
+                 * The recommendations it covers.
+                 */
+                keys: string[];
+                /**
+                 * User messages to send for the person, one each and in order, at priority 'later' so a running turn cannot reorder them: any /effort commands first, then one prompt for the rest, which goes with client_composed set.
+                 */
+                messages: string[];
+            };
             agents: {
                 name: string;
                 /**
@@ -4376,7 +4585,7 @@ export declare type SDKControlGetUsageResponse = {
              * Behavioral characteristics of local usage. Categories overlap — this is not a partition, so percentages do not sum to 100.
              */
             behaviors: {
-                key: 'cache_miss' | 'long_context' | 'subagent_heavy' | 'high_parallel' | 'cron';
+                key: 'cache_miss' | 'long_context' | 'subagent_heavy' | 'high_parallel' | 'cron' | 'max_effort' | 'workflow' | 'always_on_context' | 'large_tool_results';
                 /**
                  * Share of the weighted local usage attributed to this behavior, 0-100.
                  */
@@ -4386,6 +4595,40 @@ export declare type SDKControlGetUsageResponse = {
                  */
                 count: number;
             }[];
+            /**
+             * One recommended change per notable behavior or source, largest share first, worded for display.
+             */
+            recommendations?: {
+                /**
+                 * The behavior key, or 'agent', 'skill', 'plugin' or 'mcp_server' for a named source.
+                 */
+                key: string;
+                /**
+                 * Share of the weighted local usage this touches, 0-100.
+                 */
+                pct: number;
+                /**
+                 * What to do, verb first.
+                 */
+                title: string;
+                /**
+                 * A few words: what the scan saw, or the command to run.
+                 */
+                detail?: string;
+            }[];
+            /**
+             * What one "fix" action does. Absent when nothing can be fixed in the session that answered.
+             */
+            fix?: {
+                /**
+                 * The recommendations it covers.
+                 */
+                keys: string[];
+                /**
+                 * User messages to send for the person, one each and in order, at priority 'later' so a running turn cannot reorder them: any /effort commands first, then one prompt for the rest, which goes with client_composed set.
+                 */
+                messages: string[];
+            };
             agents: {
                 name: string;
                 /**
@@ -4426,16 +4669,22 @@ declare type SDKControlInitializeRequest = {
     hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
     sdkMcpServers?: string[];
     /**
-     * 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. Applied when the server is first registered.
+     * 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 and connectorId 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.
      */
     sdkMcpServerConfigs?: Record<string, {
         /**
          * Per-server tool-call timeout in milliseconds. Overrides the MCP_TOOL_TIMEOUT environment variable for this server. Hard wall-clock limit per call; progress notifications do not extend it. Values below 1000ms are ignored (falls through to MCP_TOOL_TIMEOUT or the default). Applies when the server is first registered; changing it for an already-registered server has no effect until it is removed and re-added.
          */
         timeout?: number;
+
+
+        /**
+         * 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.
+         */
+        tools?: coreTypes.McpServerToolPolicy[];
     }>;
     /**
-     * Optional, keyed by sdk server name (each key should also appear in sdkMcpServers; other keys are ignored). Unlike sdkMcpServerConfigs — host-declared settings the CLI keeps for the server's lifetime, same shape inline on mcp_set_servers — this is a one-shot cache of the servers' own handshake output: sent on initialize only, consumed by the connect that follows it, never retained. MCP handshake results the host already obtained from its in-process servers by delivering initialize + notifications/initialized (+ tools/list) to them itself before writing this request. For each such server the CLI answers its own MCP client's initialize and first tools/list from these results and skips the notifications/initialized round trip, so registering N in-process servers costs no mcp_message control round trips before the first turn; tools/call and everything after the handshake still flow as mcp_message exactly as before. The host MUST keep answering mcp_message for every server as if this field were absent: a CLI that predates the field ignores it and performs the full per-server handshake over the control channel, and a newer CLI does the same for any server whose entry is missing or malformed, whose initializeResult.protocolVersion differs from the MCP protocol version the CLI's client requests, or that the CLI had already connected. Entries apply only to the connect that follows this initialize; they are never retained for later reconnects. Absent (older hosts, the Python SDK, browser clients): unchanged behaviour.
+     * Optional, keyed by sdk server name (each key should also appear in sdkMcpServers; other keys are ignored). Unlike sdkMcpServerConfigs — host-declared settings the CLI keeps for the server's lifetime, same shape inline on mcp_set_servers — this is a one-shot cache of the servers' own handshake output: sent on initialize only, consumed by the connect that follows it, never retained. MCP handshake results the host already obtained from its in-process servers by delivering initialize + notifications/initialized (+ tools/list) to them itself before writing this request. For each such server the CLI answers its own MCP client's initialize and first tools/list from these results and skips the notifications/initialized round trip, so registering N in-process servers costs no mcp_message control round trips before the first turn; tools/call and everything after the handshake still flow as mcp_message exactly as before. The host MUST keep answering mcp_message for every server as if this field were absent: a CLI that predates the field ignores it and performs the full per-server handshake over the control channel, and a newer CLI does the same for any server whose entry is missing or malformed, whose initializeResult.protocolVersion differs from the MCP protocol version the CLI's client requests, or that the CLI had already connected. Entries apply only to the connect that follows this initialize; they are never retained for later reconnects. Over a remote session transport the CLI uses the field only when sdkMcpServerManifestsOrigin is set (see that field); a host on the CLI's own stream-json stdio transport needs no marker. sdk_mcp_manifests_parked in the response reports what became of each entry. Absent (older hosts, the Python SDK, browser clients): unchanged behaviour.
      */
     sdkMcpServerManifests?: Record<string, {
         /**
@@ -4447,6 +4696,10 @@ declare type SDKControlInitializeRequest = {
          */
         toolsListResult?: Record<string, unknown>;
     }>;
+    /**
+     * 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.
+     */
+    sdkMcpServerManifestsOrigin?: 'host_per_send';
     jsonSchema?: Record<string, unknown>;
     systemPrompt?: string[];
     appendSystemPrompt?: string;
@@ -4463,6 +4716,7 @@ declare type SDKControlInitializeRequest = {
      * Map of tool-name aliases applied before name resolution. When the model emits a tool_use whose name is a key in this map, the tool execution path resolves the mapped name instead. Single-hop (no chains). See Options.toolAliases.
      */
     toolAliases?: Record<string, string>;
+
     /**
      * When true, omit per-user dynamic sections (working directory, auto-memory path) from the cached system prompt and re-inject them as the first user message. Lets cross-user prompt caching hit on a static system prompt prefix. Tradeoff: the model sees this context slightly later in the prompt, so steering on the working directory and memory location is marginally less authoritative. Has no effect when a custom (non-preset) system prompt is in use.
      */
@@ -4484,11 +4738,13 @@ declare type SDKControlInitializeRequest = {
      * Dialog kinds (request_user_dialog `dialog_kind` values) this consumer's onUserDialog can actually render. The CLI treats ABSENCE as 'cannot display' and fails closed: without the kind declared here, a dialog-gated flow degrades to its no-dialog behavior (for 'refusal_fallback_prompt', the classic refusal error) instead of parking a dialog the consumer may mishandle. First-attached-client-wins on multi-client sessions; later initializes do not change it.
      */
     supportedDialogKinds?: string[];
+
     /**
      * Declares that this consumer renders a per-task stop control wired to the `stop_task` control request, so the user can stop an individual background task. When declared, an interrupt on an open-input (interactive stream-json) session spares running background agents/workflows (Stop only aborts the turn). Closed-input exception: a one-shot run (string prompt / -p closes stdin) still kills hold-back tasks at the held-result release regardless of the declaration — with stdin closed, a stop_task control could never be delivered, so the fail-closed kill stands. ABSENCE also fails closed: the interrupt kills background tasks, since the user would otherwise have no way to stop a runaway one. First-attached-client-wins on multi-client sessions; later initializes do not change it.
      */
     perTaskStopAffordance?: boolean;
 
+
     /**
      * Plugins to load for the session, in the same shape as the SDK `plugins` option: the stdin form of one --plugin-dir flag per entry (--plugin-dir-no-mcp when skipMcpDiscovery is set), so the launch command line does not grow with the plugin count. Loaded only by a CLI launched with --await-initialize, which reads this request during startup before any plugin work. Without that flag, on a repeated initialize, or over a remote session transport the field loads nothing; plugins_applied in the response reports whether the listed plugins are in fact loaded.
      */
@@ -4516,18 +4772,29 @@ export declare type SDKControlInitializeResponse = {
 
 
 
+
     /**
      * 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.
      */
     hooks_applied?: boolean;
+
     /**
      * Whether every plugin this initialize listed is loaded: true when each one is among the plugins the process loaded at launch (from `plugins` under --await-initialize, or from --plugin-dir), so a re-sent initialize naming the launch set also reads true; false otherwise. The `plugins` field never loads anything after launch. Absent when the request listed no plugins, and on CLIs that predate the field (those never read `plugins`).
      */
     plugins_applied?: boolean;
 
 
+    /**
+     * 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.
+     */
+    sdk_mcp_manifests_parked?: Record<string, 'parked' | 'already_connected' | 'protocol_version_mismatch' | 'malformed' | 'not_honoured'>;
 
 
+
+    /**
+     * Claude Code version of the process that runs this session's turns (the same value its system/init carries). Absent on CLIs that predate the field, and when the responder is not that process and does not know its version.
+     */
+    claude_code_version?: string;
     fast_mode_state?: coreTypes.FastModeState;
     fast_mode_disabled_reason?: coreTypes.FastModeDisabledReason;
 
@@ -4539,6 +4806,10 @@ export declare type SDKControlInitializeResponse = {
 
 
 
+
+
+
+
 };
 
 /**
@@ -4551,6 +4822,10 @@ declare type SDKControlInterruptRequest = {
      * When true, the interrupt also cancels every uuid-stamped main-thread command still in the queue or already dequeued for the imminent turn but not yet reachable by the abort (the first-command prewait window) — the same set the response would otherwise list under `still_queued`. Each is closed with a terminal 'cancelled' lifecycle and listed on the response's `cancelled` field. `still_queued` is then empty, except that a client driving a hosted session lists there what it can no longer recall (a send already in flight to that session, or the first prompt the session was created with) and, when the session's own sweep then cancels one of those or a send it had already delivered, follows up with a command_lifecycle 'cancelled' frame for it. (The isFoldInFlight guard cancel_async_message uses does not apply here: this request also aborts the running turn, so a fold-in-flight uuid is never delivered and is swept with the rest. A fold-in-flight uuid's queued_command attachment may already appear in the aborted turn's transcript if the abort landed after the fold's attachment yield — pre-existing leave-queued semantics; it never runs as its own turn.) Uuid-less commands (task notifications) still in the queue are also dequeued but cannot be listed; a uuid-less command already in the prewait window is unreachable by either cancel leg — the first-command prewait latch covers it (this request latches exactly like a plain interrupt; see still_queued): its turn starts aborted. When false or absent, queued commands survive the interrupt and are listed under `still_queued` — the interrupt_receipt_v1 contract is unchanged. A Stop-means-stop-everything client (a remote UI's Stop button) sets this true so one round-trip halts the session; a wrapper that wants per-uuid control leaves it false and follows up with cancel_async_message. Advertised by the `interrupt_cancel_queued_v1` capability on system/init; older CLIs ignore the field and behave as if false.
      */
     cancel_queued?: boolean;
+
+
+
+
 };
 
 /**
@@ -4558,11 +4833,14 @@ declare type SDKControlInterruptRequest = {
  */
 export declare type SDKControlInterruptResponse = {
     /**
-     * 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 (today: waiting for the session to take the initial upload from that machine) 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.
+     * 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 (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); 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.
      */
     still_queued: string[];
+
+
+
     /**
-     * Present only when the request set cancel_queued:true — uuids of main-thread commands cancelled by this interrupt: every survivor that would otherwise have appeared under `still_queued`, including any uuid that was mid-fold at the interrupt instant (this request also aborts, so the fold never delivers it). Each listed uuid has been removed (queue-resident) or marked cancel-pending (the first-command prewait window, closed by the drain loop's backstop) and emits a terminal 'cancelled' lifecycle synchronously at the first such interrupt (a repeat interrupt over the same parked batch re-lists the uuid idempotently without re-emitting); none will run. Same coverage caveats as `still_queued` (uuid-stamped main-thread only; internally-enqueued uuids may appear). Advertised by the `interrupt_cancel_queued_v1` capability.
+     * Present only when the request set cancel_queued:true — uuids of main-thread commands cancelled by this interrupt: every survivor that would otherwise have appeared under `still_queued`, including any uuid that was mid-fold at the interrupt instant (this request also aborts, so the fold never delivers it). Each listed uuid has been removed (queue-resident) or marked cancel-pending (the first-command prewait window, closed by the drain loop's backstop) and emits a terminal 'cancelled' lifecycle synchronously at the first such interrupt (a repeat interrupt over the same parked batch re-lists the uuid idempotently without re-emitting); none will run. Where one of them is the re-run of an interrupted turn that also answered for other client messages whose re-sent copies had been set aside for it, those messages' uuids are listed behind the commands' too: they were in no queue and never under `still_queued`, each has its terminal 'cancelled' lifecycle, and a repeat interrupt does not list them again. Same coverage caveats as `still_queued` (uuid-stamped main-thread only; internally-enqueued uuids may appear). Advertised by the `interrupt_cancel_queued_v1` capability.
      */
     cancelled?: string[];
 };
@@ -4592,7 +4870,7 @@ export declare type SDKControlListPermissionRulesResponse = {
 };
 
 /**
- * Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes). 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. 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.
+ * Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes). 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.
  */
 declare type SDKControlMcpCallRequest = {
     subtype: 'mcp_call';
@@ -4612,6 +4890,10 @@ declare type SDKControlMcpCallRequest = {
      * Tool-execution timeout (staging and collection have their own transport timeouts). 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.
      */
     timeout_ms?: number;
+    /**
+     * 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.
+     */
+    result_not_for_model?: boolean;
     /**
      * Declaring input_files or output_files makes this a STAGED call: rows are fetched from the synced-file lane into a private per-request temp dir the WORKER chooses (random, per-UID — the caller never sees or computes paths; it references files via tokens in arguments), the tool runs, and declared outputs are written back as lane rows (durable-at-ack PUT). The response then carries a `staging` result the caller switches on.
      */
@@ -4711,6 +4993,10 @@ declare type SDKControlMcpSetServersRequest = {
  */
 declare type SDKControlMcpStatusRequest = {
     subtype: 'mcp_status';
+    /**
+     * When true and the CLI writes to the session through CCR (a cloud session's worker, or a Remote Control worker), the success reply is published only to the clients attached at that moment, as a control_response marked live_only: true on the session's unsequenced event stream, and is not stored with the session's events; on a cloud session's worker its rows embed each server's configuration (URLs, headers, OAuth settings). Set it only if your client reads control_response frames from that stream; a reply sent while its stream is down is lost and the request must be sent again, and a reply over the live size limit comes back as a live error instead. Error replies other than that size-limit error, and every reply from hosts that do not send live replies (stdio hosts, and CLIs older than this field), are ordinary stored replies, so a client that sets it must accept either.
+     */
+    liveReply?: boolean;
 };
 
 /**
@@ -4741,6 +5027,11 @@ declare type SDKControlPermissionRequest = {
      */
     decision_reason_type?: 'rule' | 'mode' | 'subcommandResults' | 'permissionPromptTool' | 'hook' | 'asyncAgent' | 'sandboxOverride' | 'workingDir' | 'safetyCheck' | 'classifier' | 'other';
 
+
+
+
+
+
     /**
      * Set when a safetyCheck is present anywhere in the decision reason (including nested inside subcommandResults for compound bash). false = at least one safety check requires manual approval (e.g. Windows path bypass, dangerous rm); true = all safety checks MAY be classifier-approved (e.g. sensitive-file paths). Absent when no safetyCheck is involved.
      */
@@ -4765,14 +5056,16 @@ declare type SDKControlPermissionRequest = {
     display_name?: string;
     tool_use_id: string;
     agent_id?: string;
+
     description?: string;
     /**
-     * True when one-tap Approve/Deny must not be offered: the tool's approval card IS the user-interaction surface (Tool.requiresUserInteraction() — the user responds on the card itself), OR the pending ask is localDisplayOnly (its consent disclosure cannot ride this wire and only the local dialog renders it). Either way the user has to open the session to answer.
+     * True when one-tap Approve/Deny must not be offered: the tool's approval card IS the user-interaction surface (Tool.requiresUserInteraction(): the user responds on the card itself), OR the pending ask is localDisplayOnly (its consent disclosure cannot ride this wire and only the local dialog renders it), OR the auto-mode classifier blocked the call and it was handed to a person (decision_reason_type 'classifier' on a person-only ask), which no stored grant or automatic approval may answer, OR the MCP server's name spells a claude.ai connector's key and the server came from neither claude.ai nor whoever launched the session, so a grant keyed on the tool name must not answer it, OR the SDK host worded the ask (title and description are its consent copy, which a push cannot carry whole). In each case the user has to open the session to answer.
      */
     requires_user_interaction?: boolean;
 
 
 
+
 };
 
 /**
@@ -4796,7 +5089,7 @@ export declare type SDKControlPermissionRulesState = {
 };
 
 /**
- * Read a file from the session filesystem for the remote sidebar viewer. Path is resolved against cwd and gated by the same read-permission rules as the Read tool.
+ * Read a file from the session filesystem for the remote sidebar viewer. Path is resolved against cwd by default and gated by the same read-permission rules as the Read tool.
  */
 declare type SDKControlReadFileRequest = {
     subtype: 'read_file';
@@ -4806,6 +5099,7 @@ declare type SDKControlReadFileRequest = {
      * How to encode the bytes in `contents`. Defaults to utf-8 (lossy for binary); pass 'base64' to read images.
      */
     encoding?: 'utf-8' | 'base64';
+
 };
 
 /**
@@ -4819,6 +5113,7 @@ export declare type SDKControlReadFileResponse = {
      * Set when the request asked for base64. Absent means utf-8 — including when an older CLI ignored the request's encoding field.
      */
     encoding?: 'base64';
+
 };
 
 /**
@@ -4855,6 +5150,10 @@ declare type SDKControlReloadPluginsRequest = {
      * When true, the reload is not applied if applying it would change the session's tool list while the conversation's prompt cache depends on that list (the same check the interactive /reload-plugins makes before it asks for --force): the response then carries held: true and cache_impact, and the session keeps its current plugins. Default false: apply unconditionally.
      */
     hold_on_cache_impact?: boolean;
+    /**
+     * Plugins for the reload to load as well, in the same shape as the SDK `plugins` option: each entry joins the session as one more --plugin-dir would (--plugin-dir-no-mcp when skipMcpDiscovery is set). Plugins already loaded stay; nothing is removed. A held or failed reload adds none of them. Refused for a malformed list or a path that is not absolute, when managed settings set disableSideloadFlags, on a connection whose frames persist server-side (any Remote Control or cloud worker), in a cloud-hosted session, and when a running sandbox cannot keep shell commands out of the folders (always on Windows).
+     */
+    add_plugins?: coreTypes.SdkPluginConfig[];
 };
 
 /**
@@ -4932,7 +5231,7 @@ export declare type SDKControlRequest = {
 
 };
 
-declare type SDKControlRequestInner = SDKControlInterruptRequest | SDKControlPermissionRequest | SDKControlInitializeRequest | SDKControlSetPermissionModeRequest | SDKControlSetModelRequest | SDKControlSetMaxThinkingTokensRequest | SDKControlRenameSessionRequest | SDKControlSetColorRequest | SDKControlMcpStatusRequest | SDKControlGetContextUsageRequest | SDKControlGetSessionCostRequest | SDKControlListModelsRequest | SDKControlGetUsageRequest | SDKControlGetBinaryVersionRequest | SDKControlMcpCallRequest | SDKControlFileSuggestionsRequest | SDKHookCallbackRequest | SDKControlMcpMessageRequest | SDKControlRewindFilesRequest | SDKControlCancelAsyncMessageRequest | SDKControlReadFileRequest | SDKControlSeedReadStateRequest | SDKControlMcpSetServersRequest | SDKControlRegisterRepoRootRequest | SDKControlReloadPluginsRequest | SDKControlReloadSkillsRequest | SDKControlReloadOutputStylesRequest | SDKControlMcpReconnectRequest | SDKControlMcpToggleRequest | SDKControlStopTaskRequest | SDKControlBackgroundTasksRequest | SDKControlApplyFlagSettingsRequest | SDKControlGetSettingsRequest | SDKControlGetHooksListingRequest | SDKControlUpdateSettingsRequest | SDKControlElicitationRequest | SDKControlRequestUserDialogRequest | SDKControlListPermissionRulesRequest | SDKControlMcpReadResourceRequest;
+declare type SDKControlRequestInner = SDKControlInterruptRequest | SDKControlPermissionRequest | SDKControlInitializeRequest | SDKControlSetPermissionModeRequest | SDKControlSetModelRequest | SDKControlSetMaxThinkingTokensRequest | SDKControlRenameSessionRequest | SDKControlSetColorRequest | SDKControlMcpStatusRequest | SDKControlGetContextUsageRequest | SDKControlGetSessionCostRequest | SDKControlListModelsRequest | SDKControlGetUsageRequest | SDKControlGetBinaryVersionRequest | SDKControlMcpCallRequest | SDKControlFileSuggestionsRequest | SDKHookCallbackRequest | SDKControlMcpMessageRequest | SDKControlRewindFilesRequest | SDKControlCancelAsyncMessageRequest | SDKControlReadFileRequest | SDKControlSeedReadStateRequest | SDKControlMcpSetServersRequest | SDKControlRegisterRepoRootRequest | SDKControlReloadPluginsRequest | SDKControlReloadSkillsRequest | SDKControlReloadOutputStylesRequest | SDKControlMcpReconnectRequest | SDKControlMcpToggleRequest | SDKControlStopTaskRequest | SDKControlBackgroundTasksRequest | SDKControlGetTaskOutputRequest | SDKControlApplyFlagSettingsRequest | SDKControlGetSettingsRequest | SDKControlGetHooksListingRequest | SDKControlUpdateSettingsRequest | SDKControlElicitationRequest | SDKControlRequestUserDialogRequest | SDKControlListPermissionRulesRequest | SDKControlMcpReadResourceRequest;
 
 /**
  * Progress for a long-running client-originated control_request (currently only side_question), correlated by request_id. status 'started' means the worker accepted the request and launched the work; 'api_retry' carries the same retry counters as SDKAPIRetryMessage and is present only for that status.
@@ -4959,7 +5258,7 @@ export declare type SDKControlRequestProgressMessage = {
 declare type SDKControlRequestUserDialogRequest = {
     subtype: 'request_user_dialog';
     /**
-     * Identifier for the dialog the host should render. Open string union — new kinds may be added without bumping the protocol. A kind is only sent in sessions where some attached client declared it in initialize.supportedDialogKinds (declare exactly the kinds you can render); on multi-client transports the request still reaches every attached client. A host that receives a kind it did not declare must not answer it (an error-subtype response is discarded and the dialog stays pending) — never with {behavior: "cancelled"}, which is a real settlement treated as the user dismissing the dialog. An unanswered dialog is cancelled by the CLI after its dialog deadline.
+     * Identifier for the dialog the host should render. Open string union — new kinds may be added without bumping the protocol. A kind is only sent in sessions where some attached client declared it in initialize.supportedDialogKinds (declare exactly the kinds you can render); on multi-client transports the request still reaches every attached client. A host that receives a kind it did not declare must not answer it (an error-subtype response is discarded and the dialog stays pending) — never with {behavior: "cancelled"}, which is a real settlement treated as the user dismissing the dialog. An unanswered dialog is cancelled by the CLI after its dialog deadline; the CLI may send one that has no deadline, which stays up until it is answered or the CLI withdraws it with a control_cancel_request.
      */
     dialog_kind: string;
     /**
@@ -5007,7 +5306,7 @@ declare type SDKControlSetColorRequest = {
 };
 
 /**
- * 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' fails, and changes neither the budget nor the display, 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).
+ * 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, when experimental betas are off (CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or organization policy), on a Claude 3 model (except on Microsoft Foundry), or on Amazon Bedrock (Mantle included), Google Vertex AI or a Claude apps gateway (API provider "gateway") with a model released before Claude Opus 4.7. 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.
  */
 declare type SDKControlSetMaxThinkingTokensRequest = {
     subtype: 'set_max_thinking_tokens';
@@ -5025,6 +5324,7 @@ declare type SDKControlSetModelRequest = {
      */
     model?: string | null;
 
+
 };
 
 /**
@@ -5037,6 +5337,7 @@ declare type SDKControlSetPermissionModeRequest = {
      */
     mode: coreTypes.PermissionMode;
 
+
 };
 
 /**
@@ -5196,12 +5497,17 @@ export declare type SDKInformationalMessage = {
      * When true, execution stops after this message (e.g. a Stop hook denied continuation).
      */
     prevent_continuation?: boolean;
+    /**
+     * Opaque feature tag on a line a host may treat specially; absent on ordinary lines. Hosts ignore values they do not know.
+     */
+    tag?: string;
+
     uuid: UUID;
     session_id: string;
 };
 
 /**
- * Liveness heartbeat with no payload. Either side may send it at any time (the CLI emits it periodically, for example while a long-running control request is in progress); receivers must ignore it.
+ * Liveness heartbeat. Either side may send it at any time (the CLI emits it periodically, for example while a long-running control request is in progress); receivers must ignore it. It has no payload. One use is not part of this schema: for startup() and prewarm() of the Agent SDK, which set CLAUDE_CODE_SDK_READS_STARTUP_MARKS, the CLI writes lines of this type with a `startup_mark` field, the name of a start-up checkpoint that it has passed, before the initialize response.
  */
 declare type SDKKeepAliveMessage = {
     type: 'keep_alive';
@@ -5308,6 +5614,11 @@ export declare type SDKMessageOrigin = {
      * Kernel-verified pid of the process that connected to this session's cross-session messaging socket, read from the connection (SO_PEERCRED / LOCAL_PEERPID) — never from the payload. This identifies the CONNECTING process, which for relayed traffic (e.g. a daemon forwarding on another session's behalf) is the relay, not the message's author. Key sender identity on this, never on `from`: `from` is sender-authored and kept only for reply routing, so it is forgeable by any same-user process. Absent when unverifiable (Windows, non-UDS ingress) — never a wrong value. Pids are recyclable: provenance, not an authentication token.
      */
     verifiedPeerPid?: number;
+
+
+
+
+
 } | {
     kind: 'task-notification';
     /**
@@ -5318,6 +5629,12 @@ export declare type SDKMessageOrigin = {
      * 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.
      */
     fireReason?: string;
+
+    /**
+     * On a background task's own notification: the run_id its task_* events carried, as of when the notification was queued. Not part of the text the model reads.
+     */
+    runId?: string;
+
 } | {
     kind: 'coordinator';
 } | {
@@ -5430,6 +5747,9 @@ export declare type SDKPartialAssistantMessage = {
     session_id: string;
     ttft_ms?: number;
 
+
+
+
     /**
      * Client uuid of the user message this turn is answering (submitMessage options.uuid), stamped on a non-ping stream event each time that send changes: the turn's FIRST non-ping stream event (normally the frame that triggers the turn's initial ack), and, for a turn started by a synthetic (meta) prompt, the first non-ping stream event after each queued user message folded in mid-turn takes the echo over (see SDKAssistantMessage.user_message_uuid for the rule) — so a consumer can bind the reply stream to the send it answers without waiting for the result. A turn started by a typed prompt stamps only its first non-ping stream event; independently, its first complete assistant message is stamped as well (see SDKAssistantMessage.user_message_uuid), so the same uuid may appear on both. Absent on every other stream event of the turn, on turns that neither had a client uuid nor folded a user message in, and from older producers.
      */
@@ -5439,7 +5759,7 @@ export declare type SDKPartialAssistantMessage = {
      */
     user_message_uuids?: string[];
     /**
-     * Why this frame's turn is the automatic re-run of a turn a worker restart interrupted (CLAUDE_CODE_RESUME_INTERRUPTED_TURN): 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 re-run names the interrupted turn's own last user prompt), so a consumer can tell the re-run's first reply from the interrupted attempt's. Absent on every other turn, on thinking_tokens frames, and from older producers.
+     * 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.
      */
     resume_reason?: string;
 };
@@ -5594,6 +5914,7 @@ export declare type SDKRateLimitInfo = {
     overageDisabledReason?: 'overage_not_provisioned' | 'org_level_disabled' | 'org_level_disabled_until' | 'out_of_credits' | 'seat_tier_level_disabled' | 'member_level_disabled' | 'seat_tier_zero_credit_limit' | 'group_zero_credit_limit' | 'member_zero_credit_limit' | 'org_service_level_disabled' | 'no_limits_configured' | 'fetch_error' | 'unknown';
     isUsingOverage?: boolean;
     overageInUse?: boolean;
+    overageEnabled?: boolean;
     surpassedThreshold?: number;
 
 
@@ -5605,6 +5926,8 @@ export declare type SDKRateLimitInfo = {
     errorCode?: 'credits_required';
     canUserPurchaseCredits?: boolean;
     hasChargeableSavedPaymentMethod?: boolean;
+
+
 };
 
 export declare type SDKResultError = {
@@ -5628,6 +5951,8 @@ export declare type SDKResultError = {
      */
     modelUsage: Record<string, ModelUsage>;
 
+
+
     permission_denials: SDKPermissionDenial[];
     /**
      * User-initiated sends still waiting in the command queue when this result was produced. Greater than 0 means at least one more user turn (and result) follows without further input, barring cancellation; 0 means none is pending, or the session is ending (end_session or a shutdown latched mid-turn discards the backlog). Queued sends may coalesce into fewer turns, so this counts pending sends, not remaining results. System-generated queue entries are not counted. Absent on fatal startup results and on surfaces without a command queue.
@@ -5648,10 +5973,11 @@ export declare type SDKResultError = {
      */
     user_message_uuids?: string[];
     /**
-     * Why this turn was the automatic re-run of a turn a worker restart interrupted (CLAUDE_CODE_RESUME_INTERRUPTED_TURN): the host's CLAUDE_CODE_RESUME_REASON when it set one (host_draining, checkpoint_restore, container_recreated, …), else 'interrupted_turn'. Present on a headless re-run's result, success or error, with or without an echo (a re-run whose opener could not be vouched still carries the reason); absent on every other turn, on the Remote Control bridge's per-turn synthetic results, and from older producers.
+     * Why this turn continued 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'. Present on such a headless turn's result, success or error, with or without an echo (a turn whose opening user prompt could not be vouched for still carries the reason); absent on every other turn (also one that goes on from the answer to any other permission prompt), on the Remote Control bridge's per-turn synthetic results, and from older producers.
      */
     resume_reason?: string;
     terminal_reason?: TerminalReason;
+
     /**
      * 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.
      */
@@ -5676,11 +6002,31 @@ export declare type SDKResultSuccess = {
     ttft_ms?: number;
     ttft_stream_ms?: number;
     time_to_request_ms?: number;
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
     user_message_uuid?: string;
     user_message_uuids?: string[];
     resume_reason?: string;
     local_command?: string;
     request_sent_wall_ms?: number;
+
+
     first_content_frame_ms?: number;
     first_stream_post_ms?: number;
     first_stream_post_ack_ms?: number;
@@ -5691,14 +6037,21 @@ export declare type SDKResultSuccess = {
 
 
 
+
+
     first_text_post_ms?: number;
+    first_text_post_queue_wait_ms?: number;
+    first_text_post_queued_behind?: 'durable_post' | 'ephemeral_post' | 'retry_backoff' | 'hold' | 'none';
     first_text_post_wall_ms?: number;
     time_to_request_from_spawn_ms?: number;
     warm_spare_claimed?: boolean;
+
     time_origin_ms?: number;
     is_error: boolean;
     api_error_status?: number | null;
 
+
+
     num_turns: number;
     result: string;
     stop_reason: string | null;
@@ -5715,6 +6068,8 @@ export declare type SDKResultSuccess = {
      */
     modelUsage: Record<string, ModelUsage>;
 
+
+
     permission_denials: SDKPermissionDenial[];
     /**
      * User-initiated sends still waiting in the command queue when this result was produced. Greater than 0 means at least one more user turn (and result) follows without further input, barring cancellation; 0 means none is pending, or the session is ending (end_session or a shutdown latched mid-turn discards the backlog). Queued sends may coalesce into fewer turns, so this counts pending sends, not remaining results. System-generated queue entries are not counted. Absent on fatal startup results and on surfaces without a command queue.
@@ -5723,6 +6078,7 @@ export declare type SDKResultSuccess = {
     structured_output?: unknown;
     deferred_tool_use?: SDKDeferredToolUse;
     terminal_reason?: TerminalReason;
+
     /**
      * 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.
      */
@@ -5810,9 +6166,9 @@ export declare type SDKSettingsParseError = {
 };
 
 /**
- * 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.
+ * 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.
  */
-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';
+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';
 
 export declare type SDKStatus = 'compacting' | 'requesting' | null;
 
@@ -5824,6 +6180,8 @@ export declare type SDKStatusMessage = {
     compact_result?: 'success' | 'failed';
     compact_error?: string;
 
+
+
     uuid: UUID;
     session_id: string;
 };
@@ -5911,6 +6269,9 @@ export declare type SDKSystemMessage = {
 
 
 
+
+
+
     uuid: UUID;
     session_id: string;
 };
@@ -5919,6 +6280,10 @@ export declare type SDKTaskNotificationMessage = {
     type: 'system';
     subtype: 'task_notification';
     task_id: string;
+    /**
+     * Id of one run of the task: equal on every task_* event, background_tasks_changed entry and saved notification (its origin.runId) of that run. A resumed task keeps its task_id and gets a new one. The run ids of one task sort, by plain string comparison, in the order the runs opened; a frame that names a run sorting before the one a reader shows is late. Nothing else about the format is promised. Absent for a task this process did not register, and from CLIs that predate it.
+     */
+    run_id?: string;
     tool_use_id?: string;
     status: 'completed' | 'failed' | 'stopped';
     /**
@@ -5936,6 +6301,8 @@ export declare type SDKTaskNotificationMessage = {
      * CLI-owned: for a backgrounded MCP task (task_type mcp_task) that completed, the `resource_link` content blocks of its final result — the files it returned by reference — collected from the raw result before the CLI renders it as the text the model reads. A backgrounded task's tool_result is the placeholder text and its real result arrives as this notification, so this is where a host learns which files that tool call produced; join to the originating call via tool_use_id. Same fields and caps as tool_use_result.resourceLinks (at most 50 links, 64 KiB serialized), absent when the result had none or the task is any other type. Never populated from the server's _meta.
      */
     resource_links?: SDKMcpResourceLink[];
+
+
     skip_transcript?: boolean;
     /**
      * True for tasks that are not activity (every skip_transcript task, plus every live-update watcher, requested or auto-started); hosts should exclude them from activity indicators.
@@ -5949,6 +6316,10 @@ export declare type SDKTaskProgressMessage = {
     type: 'system';
     subtype: 'task_progress';
     task_id: string;
+    /**
+     * Id of one run of the task: equal on every task_* event, background_tasks_changed entry and saved notification (its origin.runId) of that run. A resumed task keeps its task_id and gets a new one. The run ids of one task sort, by plain string comparison, in the order the runs opened; a frame that names a run sorting before the one a reader shows is late. Nothing else about the format is promised. Absent for a task this process did not register, and from CLIs that predate it.
+     */
+    run_id?: string;
     tool_use_id?: string;
     description: string;
     /**
@@ -5974,6 +6345,10 @@ export declare type SDKTaskStartedMessage = {
     type: 'system';
     subtype: 'task_started';
     task_id: string;
+    /**
+     * Id of one run of the task: equal on every task_* event, background_tasks_changed entry and saved notification (its origin.runId) of that run. A resumed task keeps its task_id and gets a new one. The run ids of one task sort, by plain string comparison, in the order the runs opened; a frame that names a run sorting before the one a reader shows is late. Nothing else about the format is promised. Absent for a task this process did not register, and from CLIs that predate it.
+     */
+    run_id?: string;
     tool_use_id?: string;
     description: string;
     /**
@@ -5984,10 +6359,15 @@ export declare type SDKTaskStartedMessage = {
      * Whether the task was registered in the background (true) or in the foreground with the spawning tool call blocking on it (false). A resumed subagent is always registered in the background. A later move to the background arrives as task_updated patch.is_backgrounded. Set for local_agent and local_bash tasks.
      */
     is_backgrounded?: boolean;
+
     /**
      * Nesting depth of a spawned subagent (local_agent) task: 1 for a top-level spawn, N+1 when spawned from inside a depth-N agent. Not set on other tasks.
      */
     spawn_depth?: number;
+    /**
+     * task_id of the subagent (local_agent) task whose agent launched this subagent, shell, monitor or workflow task. Absent when the launcher is the main thread, has no task_id of its own (a teammate, an agent inside a workflow), or is no longer tracked. A resumed subagent keeps its original parent. The parent may be a foreground or already-ended task, so treat an unknown id as no parent.
+     */
+    parent_task_id?: string;
     task_type?: string;
     /**
      * meta.name from the workflow script (e.g. 'spec'). Only set when task_type is 'local_workflow'.
@@ -6010,6 +6390,10 @@ export declare type SDKTaskUpdatedMessage = {
     type: 'system';
     subtype: 'task_updated';
     task_id: string;
+    /**
+     * Id of one run of the task: equal on every task_* event, background_tasks_changed entry and saved notification (its origin.runId) of that run. A resumed task keeps its task_id and gets a new one. The run ids of one task sort, by plain string comparison, in the order the runs opened; a frame that names a run sorting before the one a reader shows is late. Nothing else about the format is promised. Absent for a task this process did not register, and from CLIs that predate it.
+     */
+    run_id?: string;
     /**
      * Wire-safe subset of TaskState fields that changed. Excludes abortController, messages, result. Clients merge into their local task map.
      */
@@ -6155,10 +6539,11 @@ export declare type SDKUserMessage = {
     parent_tool_use_id: string | null;
     isSynthetic?: boolean;
     /**
-     * Structured tool output — the tool's full Output object, not the string content sent to the model. The shape is per-tool, keyed by the matching tool_use block's name (see the *Output types in toolTypes); MCP and dynamic tools carry their own shapes, so the field stays unknown-typed. For the Agent/Task tool the completed shape is the subagent's final report without the model-directed agentId/usage trailer, plus run totals — render from it instead of parsing the tool_result text.
+     * Structured tool output — the tool's full Output object, not the string content sent to the model. The shape is per-tool, keyed by the matching tool_use block's name (see the *Output types in toolTypes); MCP and dynamic tools carry their own shapes, so the field stays unknown-typed. For the Agent/Task tool the completed shape is the subagent's final report without the model-directed agentId/usage trailer, plus run totals — render from it instead of parsing the tool_result text. A call that stepped aside for a message the user sent (today a WebFetch or WebSearch call) carries `{ detachedToolCall: true }` in place of its Output: the call is still running, and its result reaches the model in a later turn.
      */
     tool_use_result?: unknown;
     priority?: 'now' | 'next' | 'later';
+
     origin?: SDKMessageOrigin;
 
 
@@ -6184,6 +6569,7 @@ export declare type SDKUserMessage = {
 
 
 
+
 
 
     /**
@@ -6213,16 +6599,23 @@ export declare type SDKUserMessage = {
 
 
 
+
+
+
     uuid?: UUID;
     /**
-     * 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`.
+     * 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.
      */
     pasted_content?: MessageParam['content'][];
     /**
-     * Text the user pasted that is still in `message.content` where they put it: each entry one paste. The prompt is not changed by the host; the CLI may wrap each entry in `<pasted_content>` tags where it still stands in the last text block. For a paste the host took out of `message`, use `pasted_content` instead.
+     * Text the user pasted that is still in `message.content` where they put it: each entry one paste. The prompt is not changed by the host; the CLI may wrap each entry in `<pasted_content>` tags where it still stands in the last text block. It looks for the first 100 entries that are not blank. For a paste the host took out of `message`, use `pasted_content` instead.
      */
     inline_pastes?: string[];
     session_id?: string;
+    /**
+     * ID of the subagent that produced this message: the `task_id` of its task events, unchanged when the subagent is resumed. Absent on main-thread messages.
+     */
+    agent_id?: string;
     /**
      * Subagent type that produced this message.
      */
@@ -6243,10 +6636,11 @@ export declare type SDKUserMessageReplay = {
     parent_tool_use_id: string | null;
     isSynthetic?: boolean;
     /**
-     * Structured tool output — the tool's full Output object, not the string content sent to the model. The shape is per-tool, keyed by the matching tool_use block's name (see the *Output types in toolTypes); MCP and dynamic tools carry their own shapes, so the field stays unknown-typed. For the Agent/Task tool the completed shape is the subagent's final report without the model-directed agentId/usage trailer, plus run totals — render from it instead of parsing the tool_result text.
+     * Structured tool output — the tool's full Output object, not the string content sent to the model. The shape is per-tool, keyed by the matching tool_use block's name (see the *Output types in toolTypes); MCP and dynamic tools carry their own shapes, so the field stays unknown-typed. For the Agent/Task tool the completed shape is the subagent's final report without the model-directed agentId/usage trailer, plus run totals — render from it instead of parsing the tool_result text. A call that stepped aside for a message the user sent (today a WebFetch or WebSearch call) carries `{ detachedToolCall: true }` in place of its Output: the call is still running, and its result reaches the model in a later turn.
      */
     tool_use_result?: unknown;
     priority?: 'now' | 'next' | 'later';
+
     origin?: SDKMessageOrigin;
 
 
@@ -6272,6 +6666,7 @@ export declare type SDKUserMessageReplay = {
 
 
 
+
 
 
     /**
@@ -6301,6 +6696,9 @@ export declare type SDKUserMessageReplay = {
 
 
 
+
+
+
     uuid: UUID;
     session_id: string;
     isReplay: true;
@@ -6657,7 +7055,7 @@ export declare interface Settings {
      */
     desktopSessionCleanupPeriodDays?: number;
     /**
-     * Set to false to turn off syncing of the skills you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced skills (~/.claude/skills/synced) can no longer be run, are hidden from every session started afterwards, and are moved to ~/.claude/skills/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced skills are blocked and hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced skills are available in every session, re-synced every 10 minutes, and removed when you disable them on claude.ai. Only applies when signed in with your Claude account.
+     * Set to false to turn off syncing of the skills you have enabled on claude.ai. In your user settings (or managed settings): nothing more is downloaded, previously synced skills (~/.claude/skills/synced) can no longer be run, are hidden from every session started afterwards, and are moved to ~/.claude/skills/.trash at the next launch (deleted after cleanupPeriodDays; re-downloaded, not restored, if you re-enable). In .claude/settings.local.json or --settings: downloads stop and synced skills are blocked and hidden for sessions in that workspace or invocation only (nothing is moved). Not read from project settings (.claude/settings.json). Only false is honored — the feature is enabled server-side for your account, so setting true does not turn it on early. While it is on, synced skills are available in every session, re-synced about every 10 minutes while a session is in use and a quarter as often otherwise, and removed when you disable them on claude.ai. Only applies when signed in with your Claude account.
      */
     syncClaudeAiSkills?: boolean;
     /**
@@ -6700,6 +7098,19 @@ export declare interface Settings {
         sessionUrl?: boolean;
         [k: string]: unknown;
     };
+    /**
+     * The claude.ai Project this session names for your organization's usage reports: the Project's UUID, or its ID starting with "claude_proj_". An empty string names none and stops lower-precedence files from naming one; the organization default still applies. Sent only when Claude Code uses your claude.ai login, connects directly to the Anthropic API, is not in a cloud session, and CLAUDE_CODE_ATTRIBUTION_HEADER is not 0. CLAUDE_CODE_ATTRIBUTION_PROJECT takes precedence over it. Set in managed settings, it overrides people's own settings files. A project's .claude/settings.json and settings.local.json count only once the folder is trusted; for runs in a folder nobody has trusted, such as CI, use CLAUDE_CODE_ATTRIBUTION_PROJECT.
+     */
+    attributionProject?: string;
+    /**
+     * Your organization's default for attributionProject. Only honored from managed settings (server-managed, MDM / OS policy, or managed-settings.json); ignored in user, project, local and --settings sources.
+     */
+    attributionProjectPolicy?: {
+        /**
+         * The Project used when neither CLAUDE_CODE_ATTRIBUTION_PROJECT nor attributionProject names one: its UUID, or its ID starting with "claude_proj_".
+         */
+        default?: string;
+    };
     /**
      * Deprecated: Use attribution instead. Whether to include Claude's co-authored by attribution in commits and PRs (defaults to true)
      */
@@ -6829,7 +7240,7 @@ export declare interface Settings {
      */
     disabledMcpjsonServers?: string[];
     /**
-     * When true in any settings source, claude.ai MCP cloud connectors are not auto-fetched or connected. Only gates auto-fetched connectors — a claudeai-proxy server passed explicitly (e.g. via --mcp-config or the SDK mcpServers option) still follows the normal MCP config trust flow. Any-source-true wins: a project can opt out, but a project-level false cannot override a user-level true.
+     * When true in any settings source, claude.ai MCP cloud connectors are not auto-fetched or connected, and a claudeai-proxy server passed explicitly (e.g. via --mcp-config or the SDK mcpServers option) does not connect either. Any-source-true wins: a project can opt out, but a project-level false cannot override a user-level true.
      */
     disableClaudeAiConnectors?: boolean;
     /**
@@ -6851,7 +7262,7 @@ export declare interface Settings {
         };
     };
     /**
-     * Enterprise allowlist of the MCP servers users may use. Governs servers users add (user, project and local config, --mcp-config, agent frontmatter, plugins, claude.ai connectors); servers the organization itself delivers (managedMcpServers, and managed-mcp.json entries that use no ${VAR} expansion) are allowed without being listed; a managed-mcp.json entry that uses ${VAR} expansion is still checked against this list. If undefined, all servers are allowed. If empty array, users can use no servers of their own. Denylist takes precedence - if a server is on both lists, it is denied.
+     * Enterprise allowlist of the MCP servers users may use. Governs servers users add (user, project and local config, --mcp-config, agent frontmatter, plugins, claude.ai connectors); servers the organization itself delivers (managedMcpServers, and managed-mcp.json entries with no ${VAR} in their command, args, url or header values) are allowed without being listed; a managed-mcp.json entry with ${VAR} in any of those must match this list. If undefined, all servers are allowed. If empty array, users can use no servers of their own. Denylist takes precedence - if a server is on both lists, it is denied.
      */
     allowedMcpServers?: {
         /**
@@ -6925,6 +7336,10 @@ export declare interface Settings {
                  * Timeout in seconds for this specific command
                  */
                 timeout?: number;
+                /**
+                 * What a failure of this hook does: it could not start (a missing script or plugin directory), timed out, exited with a code other than 0 or 2, or printed JSON that is invalid or fails validation. 'continue' (default): the failure is reported and the action goes ahead. 'block': the failure counts as exit code 2, so the action the event guards (a tool call, a permission request, a prompt) is blocked. Ignored for async hooks and on Stop, SubagentStop, TaskCompleted and TeammateIdle.
+                 */
+                onFailure?: 'continue' | 'block';
                 /**
                  * Custom status message to display in spinner while hook runs
                  */
@@ -7023,6 +7438,10 @@ export declare interface Settings {
                  * Timeout in seconds for this specific request
                  */
                 timeout?: number;
+                /**
+                 * What a failure of this hook does: it could not start (a missing script or plugin directory), timed out, exited with a code other than 0 or 2, or printed JSON that is invalid or fails validation. 'continue' (default): the failure is reported and the action goes ahead. 'block': the failure counts as exit code 2, so the action the event guards (a tool call, a permission request, a prompt) is blocked. Ignored for async hooks and on Stop, SubagentStop, TaskCompleted and TeammateIdle.
+                 */
+                onFailure?: 'continue' | 'block';
                 /**
                  * Additional headers to include in the request. Values may reference environment variables using $VAR_NAME or ${VAR_NAME} syntax (e.g., "Authorization": "Bearer $MY_TOKEN"). Only variables listed in allowedEnvVars will be interpolated.
                  */
@@ -7118,7 +7537,7 @@ export declare interface Settings {
      */
     disableRemoteControl?: boolean;
     /**
-     * Disable the Workflows feature (also via CLAUDE_CODE_DISABLE_WORKFLOWS).
+     * 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.
      */
     disableWorkflows?: boolean;
     /**
@@ -7178,7 +7597,7 @@ export declare interface Settings {
      */
     httpHookAllowedEnvVars?: string[];
     /**
-     * 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 Claude Code adopts from a .claude-plugin manifest inside those skills directories, is ignored too; other plugins and 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.
+     * 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.
      */
     allowManagedPermissionRulesOnly?: boolean;
     /**
@@ -7261,7 +7680,7 @@ export declare interface Settings {
         };
     };
     /**
-     * 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 sec-default\@builtin where it should sit or leave it out. 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.
+     * 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.
      */
     prependPlugins?: string[];
     /**
@@ -7347,7 +7766,7 @@ export declare interface Settings {
                  */
                 version?: string;
                 /**
-                 * 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/").
+                 * 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.
                  */
                 registry?: string;
             } | {
@@ -7391,7 +7810,7 @@ export declare interface Settings {
                      */
                     name: string;
                     /**
-                     * Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
+                     * 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.
                      */
                     source: string | {
                         source: 'npm';
@@ -7442,7 +7861,7 @@ export declare interface Settings {
                          */
                         url: string;
                         /**
-                         * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Cloned sparsely using partial clone (--filter=tree:0) to minimize bandwidth for monorepos.
+                         * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Checked out sparsely — over https or ssh as a partial clone (--filter=tree:0) — to minimize bandwidth for monorepos.
                          */
                         path: string;
                         /**
@@ -7599,7 +8018,7 @@ export declare interface Settings {
                  */
                 version?: string;
                 /**
-                 * 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/").
+                 * 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.
                  */
                 registry?: string;
             } | {
@@ -7643,7 +8062,7 @@ export declare interface Settings {
                      */
                     name: string;
                     /**
-                     * Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
+                     * 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.
                      */
                     source: string | {
                         source: 'npm';
@@ -7694,7 +8113,7 @@ export declare interface Settings {
                          */
                         url: string;
                         /**
-                         * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Cloned sparsely using partial clone (--filter=tree:0) to minimize bandwidth for monorepos.
+                         * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Checked out sparsely — over https or ssh as a partial clone (--filter=tree:0) — to minimize bandwidth for monorepos.
                          */
                         path: string;
                         /**
@@ -7846,7 +8265,7 @@ export declare interface Settings {
          */
         version?: string;
         /**
-         * 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/").
+         * 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.
          */
         registry?: string;
     } | {
@@ -7890,7 +8309,7 @@ export declare interface Settings {
              */
             name: string;
             /**
-             * Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
+             * 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.
              */
             source: string | {
                 source: 'npm';
@@ -7941,7 +8360,7 @@ export declare interface Settings {
                  */
                 url: string;
                 /**
-                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Cloned sparsely using partial clone (--filter=tree:0) to minimize bandwidth for monorepos.
+                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Checked out sparsely — over https or ssh as a partial clone (--filter=tree:0) — to minimize bandwidth for monorepos.
                  */
                 path: string;
                 /**
@@ -8083,7 +8502,7 @@ export declare interface Settings {
          */
         version?: string;
         /**
-         * 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/").
+         * 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.
          */
         registry?: string;
     } | {
@@ -8127,7 +8546,7 @@ export declare interface Settings {
              */
             name: string;
             /**
-             * Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
+             * 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.
              */
             source: string | {
                 source: 'npm';
@@ -8178,7 +8597,7 @@ export declare interface Settings {
                  */
                 url: string;
                 /**
-                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Cloned sparsely using partial clone (--filter=tree:0) to minimize bandwidth for monorepos.
+                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Checked out sparsely — over https or ssh as a partial clone (--filter=tree:0) — to minimize bandwidth for monorepos.
                  */
                 path: string;
                 /**
@@ -8320,7 +8739,7 @@ export declare interface Settings {
          */
         version?: string;
         /**
-         * 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/").
+         * 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.
          */
         registry?: string;
     } | {
@@ -8364,7 +8783,7 @@ export declare interface Settings {
              */
             name: string;
             /**
-             * Where to fetch the plugin from. Must be a remote source — relative paths have no marketplace repository to resolve against.
+             * 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.
              */
             source: string | {
                 source: 'npm';
@@ -8415,7 +8834,7 @@ export declare interface Settings {
                  */
                 url: string;
                 /**
-                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Cloned sparsely using partial clone (--filter=tree:0) to minimize bandwidth for monorepos.
+                 * Subdirectory within the repo containing the plugin (e.g., "tools/claude-plugin"). Checked out sparsely — over https or ssh as a partial clone (--filter=tree:0) — to minimize bandwidth for monorepos.
                  */
                 path: string;
                 /**
@@ -8500,7 +8919,7 @@ export declare interface Settings {
      */
     forceLoginMethod?: 'claudeai' | 'console' | 'gateway';
     /**
-     * Cloud gateway URL to pre-fill and auto-connect to during login, alongside forceLoginMethod: "gateway". Honored only from admin-controlled managed settings (MDM / managed-settings.json / policy helper); ignored in user, project, and remote-delivered settings.
+     * Cloud gateway URL to pre-fill during login, alongside forceLoginMethod: "gateway". Honored from admin-controlled managed settings (MDM / managed-settings.json / policy helper) and, on a machine with none of those, from your own user settings; ignored in project, local, flag, and remote-delivered settings.
      */
     forceLoginGatewayUrl?: string;
     /**
@@ -8512,13 +8931,17 @@ export declare interface Settings {
      */
     parentSettingsBehavior?: 'first-wins' | 'merge';
     /**
-     * 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.
+     * Controls how the managed settings sources compose. "first-wins" (default): the highest-priority source present (server-managed > MDM (managed plist / HKLM) > managed-settings.json) is the managed tier alone. "merge": every present source deep-merges with fixed precedence server-managed > MDM > managed-settings.json — scalars take the highest source's value (a restrictive boolean or enum — the allowManaged*Only locks, the disable* switches, the sandbox lock family — takes the strictest value any source sets) and arrays union, except fallbackModel, the restriction allowlists allowedMcpServers, allowedProviders, availableModels, strictKnownMarketplaces and allowedChannelPlugins, and sandbox.credentials.awsPairs and sandbox.ripgrep (the highest source that sets one owns it whole), modelOverrides (the whole map of the highest source that sets it, dropped when that source sits below the one that sets availableModels), managedMcpServers (server names union; a name set by two sources takes the higher source's whole entry), and the keys taken from the highest source only: the auth pins forceLoginOrgUUID, forceLoginMethod, forceLoginGatewayUrl and gatewayInternalNetworks, the credential helpers apiKeyHelper, awsAuthRefresh, awsCredentialExport, gcpAuthRefresh, otelHeadersHelper and proxyAuthHelper, modelPicker, permissions.defaultMode, parentSettingsBehavior and the policyHelper configuration (env keeps its own per-key union). In both modes, a forceLoginOrgUUID, or a forceLoginMethod of claudeai or console, that this machine's own MDM policy or managed settings file sets applies ahead of server-managed settings. Honored only from the highest-priority source present; enable it only when every lower source is admin-controlled, since lower sources then contribute entries such as permissions.allow. HKCU and --managed-settings never take part in the merge.
      */
     managedSourcesBehavior?: 'first-wins' | 'merge';
     /**
      * 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.
      */
     forceLoginOrgUUID?: string | string[];
+    /**
+     * 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".
+     */
+    allowedProviders?: ('anthropic' | 'customEndpoint' | 'bedrock' | 'vertex' | 'foundry' | 'anthropicAws' | 'mantle' | 'gateway')[];
     /**
      * When set in managed settings, the CLI blocks startup until remote managed settings are freshly fetched, and exits if the fetch fails
      */
@@ -8544,24 +8967,30 @@ export declare interface Settings {
      */
     skipWebFetchPreflight?: boolean;
     sandbox?: {
+        /**
+         * 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).
+         */
         enabled?: boolean;
         /**
-         * 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.
+         * 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).
          */
         failIfUnavailable?: boolean;
         autoAllowBashIfSandboxed?: boolean;
         /**
-         * 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.
+         * 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).
          */
         allowUnsandboxedCommands?: boolean;
         network?: {
+            /**
+             * 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.
+             */
             allowedDomains?: string[];
             /**
              * 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.
              */
             deniedDomains?: string[];
             /**
-             * 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.
+             * 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.
              */
             strictAllowlist?: boolean;
             /**
@@ -8569,19 +8998,28 @@ export declare interface Settings {
              */
             allowManagedDomainsOnly?: boolean;
             /**
-             * macOS only: Unix socket paths to allow. Ignored on Linux (seccomp cannot filter by path).
+             * 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.
              */
             allowUnixSockets?: string[];
             /**
-             * If true, allow all Unix sockets (disables blocking on both platforms).
+             * 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).
              */
             allowAllUnixSockets?: boolean;
+            /**
+             * 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).
+             */
             allowLocalBinding?: boolean;
             /**
-             * 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.
+             * 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.
              */
             allowMachLookup?: string[];
+            /**
+             * 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.
+             */
             httpProxyPort?: number;
+            /**
+             * 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.
+             */
             socksProxyPort?: number;
             /**
              * [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 +9031,7 @@ export declare interface Settings {
         };
         filesystem?: {
             /**
-             * Additional paths to allow writing within the sandbox. Merged with paths from Edit(...) allow permission rules.
+             * 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.
              */
             allowWrite?: string[];
             /**
@@ -8605,7 +9043,7 @@ export declare interface Settings {
              */
             denyRead?: string[];
             /**
-             * Paths to re-allow reading within denyRead regions. Takes precedence over denyRead for matching paths.
+             * 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.
              */
             allowRead?: string[];
             /**
@@ -8727,12 +9165,22 @@ export declare interface Settings {
                 sigv4a?: 'deny' | 'passthrough';
             };
         };
+        /**
+         * 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.
+         */
         ignoreViolations?: {
             [k: string]: string[];
         };
+        /**
+         * 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).
+         */
         enableWeakerNestedSandbox?: boolean;
         /**
-         * 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
+         * Linux/WSL only: Let sandboxed commands create user namespaces of their own, which the sandbox refuses by default. Needed by tools that sandbox themselves that way, such as Chromium's and Electron's sandbox, a nested bubblewrap, and `unshare`. **Removes code-execution isolation** — in any folder a hostile command may write, it can then bypass filesystem.denyWrite, filesystem.denyRead, credentials.files entries and the paths the sandbox always write-protects (such as .claude/settings.json, git hooks and git config), and so plant code that later runs outside the sandbox; while autoAllowBashIfSandboxed is on, the command that plants it needs no approval. Default: false. Only honored from user, managed/policy, or CLI (--settings) settings — true from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (false there still applies).
+         */
+        allowNestedUserNamespaces?: boolean;
+        /**
+         * 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).
          */
         enableWeakerNetworkIsolation?: boolean;
         /**
@@ -8864,11 +9312,15 @@ export declare interface Settings {
              * Maximum effort level for this model. Within one settings file it replaces the top-level maxEffortLevel for the model ("max" exempts it); across settings files the lowest applicable value wins. Keyed like effortLevel: the canonical model name also matches its dated, [1m], Bedrock and Vertex spellings.
              */
             maxEffortLevel?: 'low' | 'medium' | 'high' | 'xhigh' | 'max';
+            /**
+             * Auto-compact window for this model, in tokens (100000 to 1000000), or "auto" for the window tuned for the model. Within one settings file it replaces the top-level autoCompactWindow for the model. /autocompact saves here. The canonical model name as key also matches its dated, [1m], Bedrock and Vertex spellings.
+             */
+            autoCompactWindow?: 'auto' | number;
             [k: string]: unknown;
         };
     };
     /**
-     * Enable ultracode for the session: xhigh effort plus standing dynamic-workflow orchestration. Session-scoped — typically provided via --settings or the apply_flag_settings control request; interactive toggles never persist it. Requires workflows to be enabled and an xhigh-capable model.
+     * 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.
      */
     ultracode?: boolean;
     /**
@@ -9069,6 +9521,10 @@ export declare interface Settings {
          */
         startDirectory?: string;
     }[];
+    /**
+     * SSH connections in Claude Desktop on macOS and Linux whose host comes from a command. A list of entries, each with `id`, `name` and `command`, and optionally `sshIdentityFile` and `startDirectory`. When you ask Desktop to create or replace an entry's host, it runs `command` on this computer: a program name or absolute path, followed by plain arguments. There is no shell, so quotes, pipes, variables and a leading `~` do not work. The command must print only the host on standard output: `host` or `user\@host` on one line, or a JSON object with `sshHost` and, optionally, `sshPort` and `startDirectory`. Desktop reads this key only from user settings and from this computer's managed settings. Claude Code itself does not use it.
+     */
+    sshHostCommands?: unknown[];
     /**
      * CLAUDE.md-style instructions injected as organization-managed memory. Only honored from managed/policy settings.
      */
@@ -9115,6 +9571,10 @@ export declare interface Settings {
      * Precompute the compaction summary in the background before it is needed. Only applies when auto-compact is on.
      */
     precomputeCompactionEnabled?: boolean;
+    /**
+     * Set to false to stop Claude Code from compacting a long conversation while the session is idle. Setting it to true does not turn idle compaction on.
+     */
+    idleCompaction?: boolean;
     /**
      * When safeguards flag a message, automatically switch to a different model to keep chatting. When off, your session will pause instead.
      */
@@ -9238,6 +9698,7 @@ export declare type SlashCommand = {
      * True when the command is Claude Code's own; absent for a command defined by a user, project, plugin or MCP server. Rows can share a name: when a marked row carries it, /name runs that one, and an unmarked row is the one /name runs only when no marked row shares its name. The marker describes the row's name, not its aliases: a typed alias runs a command that has it as its name, when one exists, whatever this marker says.
      */
     builtin?: boolean;
+
 };
 
 /**
@@ -9422,6 +9883,14 @@ export declare interface SpawnOptions {
  */
 export declare function startup(_params?: {
     options?: Options;
+    /**
+     * The most time, in milliseconds, that startup() counts while it waits for
+     * the subprocess to initialize; when that time is used up, the promise
+     * rejects with a timeout error. Defaults to 60000. When no value is passed,
+     * time in which the subprocess reports a SessionStart or Setup hook running
+     * is not counted, for at most 10 minutes in total. A value that is passed
+     * counts throughout.
+     */
     initializeTimeoutMs?: number;
 }): Promise<WarmQuery>;
 
@@ -9698,7 +10167,7 @@ export declare interface Transport {
 /**
  * Messages meaning "a usage limit was genuinely reached" — the error-path
  * outputs of getLimitReachedText (rateLimitMessages.ts) and
- * getFableCreditsRequiredContent (api/errors.ts).
+ * getUsageCreditsOnlyModelRejectionContent (api/errors.ts).
  *
  * @alpha
  */