@anthropic-ai/claude-agent-sdk 0.3.267 → 0.3.269

package/sdk.d.ts

@@ -241,6 +241,16 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
      * read and write access to files in ~/Downloads").
      */
     description?: string;
+    /**
+     * The ask must not be approvable by a single stray keystroke: open the
+     * prompt on its decline option and offer no one-key approve shortcut.
+     */
+    defaultToNo?: boolean;
+    /**
+     * The ask must not offer a persistent "don't ask again" choice: the
+     * rule it would write grants more than this ask's own action.
+     */
+    suppressAlwaysAllowRule?: boolean;
     /**
      * Unique identifier for this specific tool call within the assistant message.
      * Multiple tool calls in the same assistant message will have different toolUseIDs.
@@ -293,11 +303,11 @@ declare type ControlErrorResponse = {
      */
     error: string;
     /**
-     * Permission requests still awaiting a response. Sent on the `initialize` response so a client joining an already-initialized session learns about in-flight prompts.
+     * 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.
      */
     pending_permission_requests?: SDKControlRequest[];
     /**
-     * request_user_dialog requests still awaiting a response. Sent on the `initialize` response (sibling of pending_permission_requests) so a client joining an already-initialized session can re-arm in-flight dialogs. Receivers must tolerate the same request_id also arriving as a live or replayed control_request frame and render it once.
+     * request_user_dialog requests this CLI process has issued and not yet resolved (sibling of pending_permission_requests, with the same inherited-prompt caveat), so a client joining an already-initialized session can re-arm in-flight dialogs. 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". Receivers must tolerate the same request_id also arriving as a live or replayed control_request frame and render it once.
      */
     pending_user_dialog_requests?: SDKControlRequest[];
 };
@@ -316,11 +326,11 @@ declare type ControlResponse = {
      */
     response?: Record<string, unknown>;
     /**
-     * Permission requests still awaiting a response. Sent on the `initialize` response so a client joining an already-initialized session learns about in-flight prompts.
+     * 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.
      */
     pending_permission_requests?: SDKControlRequest[];
     /**
-     * request_user_dialog requests still awaiting a response. Sent on the `initialize` response (sibling of pending_permission_requests) so a client joining an already-initialized session can re-arm in-flight dialogs. Receivers must tolerate the same request_id also arriving as a live or replayed control_request frame and render it once.
+     * request_user_dialog requests this CLI process has issued and not yet resolved (sibling of pending_permission_requests, with the same inherited-prompt caveat), so a client joining an already-initialized session can re-arm in-flight dialogs. 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". Receivers must tolerate the same request_id also arriving as a live or replayed control_request frame and render it once.
      */
     pending_user_dialog_requests?: SDKControlRequest[];
 };
@@ -2671,26 +2681,26 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
      */
     setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | null): Promise<void>;
     /**
-     * Merge the provided settings into the flag settings layer, dynamically
-     * updating the active configuration. Equivalent to the inline `settings`
-     * option of `query()`, but applies mid-session. Flag settings sit above
-     * user/project/local settings and below managed policy settings in the
-     * precedence order.
+     * Merge settings into the flag settings layer. This is the inline `settings`
+     * option of `query()`, applied mid-session. Flag settings sit above
+     * user/project/local and below managed policy settings in precedence order.
      *
      * Successive calls shallow-merge top-level keys — a second call with
      * `{permissions: {...}}` replaces the entire `permissions` object from a
      * prior call. Pass `null` for a key to clear it from the flag layer and
      * fall back to lower-precedence sources (`undefined` is dropped by JSON
-     * serialization and has no effect).
-     *
+     * serialization and has no effect). Four keys instead reset session state
+     * and restore neither a `query()` option nor a settings-file value.
+     * `effortLevel` goes to the model's default effort, `model` to Claude Code's
+     * default model (not `ANTHROPIC_MODEL` or `settings.model`), `agent` to no
+     * main-thread agent, and `ultracode` to off with the current effort kept.
      * Only available in streaming input mode.
      *
-     * @param settings - A partial settings object to merge into the flag settings.
-     * Each top-level key also accepts `null` to clear it from the flag layer.
-     * `effortLevel` additionally accepts `'max'`, which is session-scoped: it
-     * applies for the rest of the session on models that support it and is
-     * never persisted to settings files (the persisted
-     * {@link Settings.effortLevel} excludes it for that reason).
+     * @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
+     * session-only, runs as `'high'` on a model without `'max'` support, and
+     * runs no higher than the organization's effort limit for the model.
      */
     applyFlagSettings(settings: {
         [K in keyof Settings]?: K extends 'effortLevel' ? EffortLevel | null : Settings[K] | null;
@@ -2796,6 +2806,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
     usage_EXPERIMENTAL_MAY_CHANGE_DO_NOT_RELY_ON_THIS_API_YET(opts?: {
         skipBehaviors?: boolean;
     }): Promise<SDKControlGetUsageResponse>;
+
     /**
      * Read a file from the session's filesystem for the remote sidebar
      * viewer. Path is resolved against cwd and gated by the same
@@ -2814,9 +2825,19 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
      * Reload plugins from disk and return the refreshed commands, agents,
      * plugins, and MCP server status.
      *
-     * @returns The refreshed session components after plugin reload
+     * With `holdOnCacheImpact`, the CLI first runs the check the interactive
+     * /reload-plugins makes: when applying would change the session's tool
+     * list while the conversation's prompt cache depends on it, nothing is
+     * applied and the response carries `held: true` with `cache_impact`
+     * describing what applying would change; call again without the option
+     * to apply anyway.
+     *
+     * @returns The refreshed session components after plugin reload, or the
+     * unchanged ones with `held: true` when the reload was held
      */
-    reloadPlugins(): Promise<SDKControlReloadPluginsResponse>;
+    reloadPlugins(options?: {
+        holdOnCacheImpact?: boolean;
+    }): Promise<SDKControlReloadPluginsResponse>;
     /**
      * Reload skills from disk and return the refreshed skill list.
      *
@@ -3328,13 +3349,17 @@ 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 a reply frame each time that send changes — the turn's FIRST reply frame, and then, for a turn started by a synthetic (meta) prompt, the first reply frame after each queued user message folded in mid-turn takes the echo over. In complete-message mode the frame is the first assistant message; with --include-partial-messages the stamp normally rides the first non-ping stream event instead (see SDKPartialAssistantMessage), and a turn that produces no stream events still stamps its first assistant message — so a consumer can bind 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 its first reply frame only. 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 such as the boot-time rescue turn; 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 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 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.
      */
     user_message_uuid?: string;
     /**
      * Client uuids of every user message whose prompt this turn has consumed so far, in consumption order — all members of a prompt batch the host merged into this one turn (several messages sent close together run as one turn whose user_message_uuid is the LAST member's), then any user message folded into the turn before this frame — so a consumer that sent any of them can bind this reply to its own send by finding its uuid anywhere in the list. Always contains user_message_uuid; at most 64 entries. Present exactly when user_message_uuid is, on the same frames; absent from older producers (fall back to user_message_uuid).
      */
     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.
+     */
+    resume_reason?: string;
     /**
      * This turn continued the preceding truncated assistant turn inside its trailing signed thinking block (max-output-tokens recovery). Its thinking signatures are cumulative over that preceding thinking-only turn, so a history replayed through the bridge must carry this flag back for the normalizer to keep the run's prefix on the wire. Wrapper-level sibling — never inside `message.content` — so it is not replayed to the model.
      */
@@ -3383,7 +3408,7 @@ export declare type SDKAssistantMessage = {
 
 };
 
-export declare type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';
+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';
 
 export declare type SDKAuthStatusMessage = {
     type: 'auth_status';
@@ -3644,6 +3669,10 @@ export declare type SDKControlGetContextUsageResponse = {
         tokens: number;
         color: string;
         isDeferred?: boolean;
+        /**
+         * What the row is, the same classification the /context result's context_usage rows carry: 'used' content occupies the window; 'free' is the remaining window; 'buffer' is the compaction reserve; 'deferred' rows are out-of-window tool schemas. Classify on this, never on the English name.
+         */
+        kind: 'used' | 'free' | 'buffer' | 'deferred';
     }[];
     totalTokens: number;
     maxTokens: number;
@@ -3730,6 +3759,151 @@ export declare type SDKControlGetContextUsageResponse = {
     } | null;
 };
 
+/**
+ * Returns the hooks listing the CLI's read-only /hooks menu renders: settings-file, session, and plugin hooks grouped by event and matcher, with display-ready strings (control characters revealed) and the policy and safe-mode state the menu banners on. A snapshot at request time; hosts re-request when their surface opens.
+ */
+declare type SDKControlGetHooksListingRequest = {
+    subtype: 'get_hooks_listing';
+};
+
+/**
+ * The hooks listing the CLI's /hooks menu renders, with display-ready strings.
+ */
+declare type SDKControlGetHooksListingResponse = {
+    /**
+     * Events that have at least one listed hook, in the /hooks menu’s lifecycle order.
+     */
+    events: {
+        /**
+         * Hook event name.
+         */
+        name: string;
+        /**
+         * One-line summary, as the /hooks event list shows.
+         */
+        summary: string;
+        /**
+         * Whether hooks on this event can carry a matcher.
+         */
+        supportsMatcher: boolean;
+        /**
+         * Number of listed hooks.
+         */
+        hookCount: number;
+    }[];
+    /**
+     * One row per listed hook: events in lifecycle order, matchers in the menu’s priority order.
+     */
+    hooks: {
+        event: string;
+        /**
+         * Matcher with control characters revealed; '' when the entry has none.
+         */
+        matcher: string;
+        /**
+         * Raw source name (userSettings, sessionHook, pluginHook, …).
+         */
+        source: string;
+        /**
+         * User-facing source description.
+         */
+        sourceLabel: string;
+        pluginName?: string;
+        /**
+         * Hook type (command, prompt, agent, http, mcp_tool, …).
+         */
+        type: string;
+        /**
+         * List-row label: statusMessage when set, else the identity text; one line, control characters revealed.
+         */
+        displayText: string;
+        /**
+         * Identity text — the literal command/prompt/URL that runs, control characters revealed.
+         */
+        commandText: string;
+        /**
+         * Label for commandText (Command, Prompt, URL, …).
+         */
+        contentLabel: string;
+        /**
+         * If-condition, revealed, when set.
+         */
+        condition?: string;
+        /**
+         * Timeout in seconds.
+         */
+        timeout?: number;
+        statusMessage?: string;
+        runsOnce?: boolean;
+        runsInBackground?: boolean;
+        /**
+         * True when the session's mode or policy keeps this hook from running (the policy block and safeMode/bareMode say why); absent on rows that run.
+         */
+        disabled?: true;
+        /**
+         * The entry as stored (raw matcher, '' when none, and raw hook object; no display escaping) for a host's edit form and as the target it names to `claude edit-hook`. Only on rows from a settings file this session reads and may write. HTTP header values are blanked (headersRedacted); a replace that sends no headers keeps the stored ones.
+         */
+        editable?: {
+            matcher: string;
+            config: Record<string, unknown>;
+            headersRedacted?: true;
+        };
+    }[];
+    /**
+     * Every hook event in lifecycle order (name, the /hooks summary, whether its hooks take a matcher), for an add-hook form.
+     */
+    eventCatalog: {
+        name: string;
+        summary: string;
+        supportsMatcher: boolean;
+    }[];
+    policy: {
+        /**
+         * Managed disableAllHooks — nothing runs at all.
+         */
+        disabledByPolicy: boolean;
+        /**
+         * Managed allowManagedHooksOnly — non-managed hooks are blocked and managed hooks are intentionally not listed.
+         */
+        managedOnly: boolean;
+        /**
+         * Managed strictPluginOnlyCustomization locks the hooks surface.
+         */
+        pluginOnly: boolean;
+        /**
+         * Effective disableAllHooks, whatever source set it.
+         */
+        allDisabled: boolean;
+        /**
+         * Hooks configured in managed settings (they run even under a non-managed disableAllHooks).
+         */
+        policyHookCount: number;
+    };
+    /**
+     * Present only when the session runs under --safe-mode.
+     */
+    safeMode?: {
+        managedHooksStillApply: boolean;
+        /**
+         * How to leave safe mode, per its activation source.
+         */
+        exitHint: string;
+    };
+    /**
+     * Present only under --bare / CLAUDE_CODE_SIMPLE with the hooks surface gated off: settings-file, flag, policy, and plugin hooks never fire there; session hooks still run.
+     */
+    bareMode?: {
+        /**
+         * How to leave bare mode, per its activation source.
+         */
+        exitHint: string;
+    };
+    /**
+     * Settings files skipped by the merge — their hooks are neither listed nor running.
+     */
+    errors?: coreTypes.SDKSettingsParseError[];
+};
+
 /**
  * Requests the formatted session cost summary (the same text /usage prints in non-interactive mode). Used by the thin-client /usage dialog to show the remote container cost instead of the local $0.00.
  */
@@ -3833,7 +4007,7 @@ export declare type SDKControlGetUsageResponse = {
             resets_at: string | null;
         } | null;
         /**
-         * Per-model weekly windows from the server limits[] array, filtered by the overage-included-models allowlist. Additive — present only when the server emits them.
+         * Per-model weekly windows from the server limits[] array, filtered by the overage-included-models allowlist. Additive: absent when nothing is known about them (an answer served from cached data, or rows the allowlist hides); an empty array means the endpoint itself answered and listed no per-model weekly window at all for this account, before the allowlist was applied.
          */
         model_scoped?: {
             /**
@@ -4054,6 +4228,7 @@ export declare type SDKControlInitializeResponse = {
     agents: coreTypes.AgentInfo[];
     output_style: string;
     available_output_styles: string[];
+
     models: coreTypes.ModelInfo[];
 
     /**
@@ -4085,6 +4260,7 @@ export declare type SDKControlInitializeResponse = {
 
 
 
+
 };
 
 /**
@@ -4120,6 +4296,23 @@ declare type SDKControlListModelsRequest = {
     subtype: 'list_models';
 };
 
+/**
+ * Requests the session's live permission rules and workspace directories — the same data /permissions lists in the terminal: rules from settings files plus session-only approvals, slash-command grants, and --allowedTools flag rules, each with its source.
+ */
+declare type SDKControlListPermissionRulesRequest = {
+    subtype: 'list_permission_rules';
+};
+
+/**
+ * Success payload of list_permission_rules.
+ */
+export declare type SDKControlListPermissionRulesResponse = {
+    /**
+     * The session's live permission rules state, as list_permission_rules reports it.
+     */
+    state: SDKControlPermissionRulesState;
+};
+
 /**
  * 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.
  */
@@ -4263,6 +4456,27 @@ declare type SDKControlPermissionRequest = {
      * 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.
      */
     requires_user_interaction?: boolean;
+
+};
+
+/**
+ * The session's live permission rules state, as list_permission_rules reports it.
+ */
+export declare type SDKControlPermissionRulesState = {
+    rules: SDKPermissionRuleEntry[];
+    workspaceDirectories: SDKPermissionWorkspaceDirectory[];
+    /**
+     * The session's original working directory.
+     */
+    originalCwd: string;
+    /**
+     * True when enterprise managed settings pin allowManagedPermissionRulesOnly: the session applies policy rules only, and rules from other settings files appear with notInEffect set.
+     */
+    managedOnly: boolean;
+    /**
+     * Settings parse and validation errors, as get_settings reports them. When non-empty, the listed files were skipped — their rules are not in the session and not listed above.
+     */
+    errors?: coreTypes.SDKSettingsParseError[];
 };
 
 /**
@@ -4321,6 +4535,10 @@ export declare type SDKControlReloadOutputStylesResponse = {
  */
 declare type SDKControlReloadPluginsRequest = {
     subtype: 'reload_plugins';
+    /**
+     * 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;
 };
 
 /**
@@ -4340,6 +4558,18 @@ export declare type SDKControlReloadPluginsResponse = {
     }[];
     mcpServers: coreTypes.McpServerStatus[];
     error_count: number;
+    /**
+     * Present only when the request asked to hold on cache impact and this CLI ran the check. True: the reload was not applied, the lists above describe the session as it still is, and cache_impact says what applying would change. False: the check found no impact and the reload was applied. Absent: the request did not ask, or the CLI predates the option and applied the reload unchecked.
+     */
+    held?: boolean;
+    /**
+     * What applying the held reload would change in the session's tool list: plugin MCP servers it would register or drop (scoped plugin:<plugin>:<server> names, plugin-authored — validate before showing) and whether it would add or remove the LSP tool (the may- forms mean the preview could not fully see the pending plugin set). Present only with held: true.
+     */
+    cache_impact?: {
+        mcp_servers_added: string[];
+        mcp_servers_removed: string[];
+        lsp_tool_change: ('adds' | 'may-add' | 'removes' | 'may-remove') | null;
+    };
 };
 
 /**
@@ -4362,6 +4592,14 @@ export declare type SDKControlReloadSkillsResponse = {
 declare type SDKControlRenameSessionRequest = {
     subtype: 'rename_session';
     title: string;
+    /**
+     * Who chose the title: 'remote' (the default) for a rename made on claude.ai and relayed to this process, 'host' for one the user made in the hosting application (an IDE), which the CLI counts as a user rename.
+     */
+    source?: 'remote' | 'host';
+    /**
+     * The session the title is for. When given and this process has since moved to another session (/clear, an in-session resume), the request is refused instead of naming the new session.
+     */
+    session_id?: string;
 };
 
 /**
@@ -4378,7 +4616,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 | SDKControlUpdateSettingsRequest | SDKControlElicitationRequest | SDKControlRequestUserDialogRequest;
+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;
 
 /**
  * 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.
@@ -4860,13 +5098,17 @@ 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 its first non-ping stream event only. 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.
+     * 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.
      */
     user_message_uuid?: string;
     /**
      * Client uuids of every user message whose prompt this turn has consumed so far, in consumption order — all members of a prompt batch the host merged into this one turn (several messages sent close together run as one turn whose user_message_uuid is the LAST member's), then any user message folded into the turn before this frame — so a consumer that sent any of them can bind this reply to its own send by finding its uuid anywhere in the list. Always contains user_message_uuid; at most 64 entries. Present exactly when user_message_uuid is, on the same frames; absent from older producers (fall back to user_message_uuid).
      */
     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.
+     */
+    resume_reason?: string;
 };
 
 export declare type SDKPermissionDenial = {
@@ -4876,7 +5118,7 @@ export declare type SDKPermissionDenial = {
 };
 
 /**
- * Emitted when a tool call is auto-denied without an interactive permission prompt (e.g. auto-mode classifier, dontAsk mode, headless-agent auto-deny, or a deny rule). With a permission prompt surface (stdio/SDK canUseTool), the 'ask' path surfaces via a can_use_tool control_request and this event covers the 'deny' short-circuit. Without one (bare -p / SDK query() with no canUseTool), 'ask' decisions are terminal, so this event also covers those implicit denials. Best-effort advisory: in rare races a denial can book without a frame or a frame can lack a booking twin — result.permission_denials is the authoritative record. Denials that resolve before canUseTool runs — PreToolUse hook denies, and deny-rule overrides of hook allow/ask decisions — are not covered here, and neither is the MCP --permission-prompt-tool surface (the prompt tool is the host there).
+ * Emitted when a tool call is auto-denied without an interactive permission prompt (e.g. auto-mode classifier, dontAsk mode, headless-agent auto-deny, or a deny rule). With a permission prompt surface (stdio/SDK canUseTool), the 'ask' path surfaces via a can_use_tool control_request and this event covers the 'deny' short-circuit. Without one (bare -p / SDK query() with no canUseTool), 'ask' decisions are terminal, so this event also covers those implicit denials. Best-effort advisory: in rare races a denial can book without a frame or a frame can lack a booking twin — result.permission_denials is the authoritative record. Denials that resolve before canUseTool runs — PreToolUse hook denies, deny-rule overrides of hook allow/ask decisions, and file-tool calls (Read, Edit, Write) refused by a path-scoped deny rule — are not covered here, and neither is the MCP --permission-prompt-tool surface (the prompt tool is the host there).
  */
 export declare type SDKPermissionDeniedMessage = {
     type: 'system';
@@ -4903,6 +5145,53 @@ export declare type SDKPermissionDeniedMessage = {
     session_id: string;
 };
 
+/**
+ * The CLI's plain-language reading of a rule (e.g. "Any Bash command starting with npm run"), split into parts so hosts can render the rule-derived fragment the way the terminal does (bold). prefix and suffix are fixed words; emphasis is rule content — apply display hygiene (invisible-character escaping) before rendering it.
+ */
+export declare type SDKPermissionRuleDescription = {
+    prefix: string;
+    emphasis?: string;
+    suffix?: string;
+};
+
+/**
+ * One permission rule with its provenance and where it lives.
+ */
+export declare type SDKPermissionRuleEntry = {
+    behavior: 'allow' | 'deny' | 'ask';
+    /**
+     * Where the rule comes from. Mirrors PermissionRuleSource (permissionRuleLookup.ts PERMISSION_RULE_SOURCES); the parity test in test/cli/headlessControl/listPermissionRules.test.ts keeps the two aligned.
+     */
+    source: 'userSettings' | 'projectSettings' | 'localSettings' | 'flagSettings' | 'policySettings' | 'cliArg' | 'command' | 'session' | 'toolsNarrowing' | 'mcpServerPolicy' | 'hostCredential';
+    /**
+     * The stored rule string VERBATIM, exactly as the session holds it. Two stored spellings that parse identically each get their own entry. Can carry invisible or control characters by design — escape at display.
+     */
+    rule: string;
+    /**
+     * Plain-language reading of the rule; absent where the terminal shows no subtitle either.
+     */
+    description?: SDKPermissionRuleDescription;
+    /**
+     * Where the rule lives: 'persistent' (userSettings/projectSettings/localSettings — saved in a settings file), 'session' (cliArg/session — in memory only, for the rest of this session), or 'readonly' (policySettings/flagSettings/command and every other source — the set the terminal's /permissions treats as read-only). Informational for hosts; this request never changes rules.
+     */
+    editability: 'persistent' | 'session' | 'readonly';
+    /**
+     * Present (true) when enterprise managed settings pin allowManagedPermissionRulesOnly and this rule, read from a non-policy settings file, is ignored by the session. Such rows are readonly.
+     */
+    notInEffect?: boolean;
+};
+
+/**
+ * One additional working directory in the permission scope.
+ */
+export declare type SDKPermissionWorkspaceDirectory = {
+    path: string;
+    /**
+     * Where the directory grant came from: a settings source (e.g. 'localSettings'), 'cliArg' (--add-dir), or 'session' (/add-dir, IDE workspace folders).
+     */
+    source: string;
+};
+
 /**
  * Configuration for loading a plugin.
  */
@@ -4975,6 +5264,10 @@ export declare type SDKRateLimitInfo = {
 
 
 
+    /**
+     * Which spend limit blocked the request when it is not the member's own cap: 'group_pool' means a pooled group budget shared by the member's team is used up (the denial otherwise looks like the member's own monthly cap). Absent on a plain member denial and from older CLIs.
+     */
+    limitScope?: 'service' | 'channel' | 'group_pool';
     errorCode?: 'credits_required';
     canUserPurchaseCredits?: boolean;
     hasChargeableSavedPaymentMethod?: boolean;
@@ -5016,7 +5309,15 @@ export declare type SDKResultError = {
      * Client uuids of every user message whose prompt this turn consumed, in consumption order — all members of a prompt batch the host merged into this one turn (several messages sent close together run as one turn whose user_message_uuid is the LAST member's), then any queued user message folded into the running turn between tool rounds, once taken off the queue — so a consumer that sent any of them can bind this result to its own send by finding its uuid anywhere in the list. Always contains user_message_uuid; at most 64 entries; can be longer than the list on the turn's first reply frame. Present when a headless turn that ran echoes user_message_uuid; absent on delivery-failure and zeroed results and from older producers (fall back to user_message_uuid).
      */
     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.
+     */
+    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.
+     */
+    result_index?: number;
     fast_mode_state?: FastModeState;
     fast_mode_disabled_reason?: FastModeDisabledReason;
     origin?: SDKMessageOrigin;
@@ -5039,6 +5340,8 @@ export declare type SDKResultSuccess = {
     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;
@@ -5073,6 +5376,10 @@ 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.
+     */
+    result_index?: number;
     fast_mode_state?: FastModeState;
     fast_mode_disabled_reason?: FastModeDisabledReason;
     origin?: SDKMessageOrigin;
@@ -6369,6 +6676,10 @@ export declare interface Settings {
      * Default shell for input-box ! commands. Defaults to 'bash' on all platforms (no Windows auto-flip).
      */
     defaultShell?: 'bash' | 'powershell';
+    /**
+     * Whether the Bash tool shows a diff of the files a Bash command changed (PostToolUse Bash hooks get the changed-file list in tool_response). Set to false to turn that off. Default: on when the Bash tool handles file edits. Only user, flag or policy settings can turn it on outside auto and bypassPermissions modes.
+     */
+    bashEditDiffEnabled?: boolean;
     /**
      * How many characters of a successful Bash or PowerShell command's output Claude receives inline (default 30000; values clamp to 4000-128000). Output past this is saved to a file and Claude receives a short preview plus the path. When set, this also replaces BASH_MAX_OUTPUT_LENGTH, which on its own only sizes the read-back window.
      */
@@ -6472,7 +6783,14 @@ export declare interface Settings {
             [k: string]: unknown;
         };
     };
-
+    /**
+     * 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.
+     */
+    prependPlugins?: string[];
+    /**
+     * Managed plugins (plugin\@marketplace ids that managed enabledPlugins sets true) whose hooks run last among plugins, innermost, in the listed order: the last id listed sits just above the built-in plugins and sees each event as every other plugin left it. 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.
+     */
+    appendPlugins?: string[];
     /**
      * Additional marketplaces to make available for this repository. Typically used in repository .claude/settings.json to ensure team members have required plugin sources.
      */
@@ -7668,12 +7986,16 @@ export declare interface Settings {
      * 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.
      */
     forceLoginGatewayUrl?: string;
+    /**
+     * IPv4 CIDR blocks (at most 4, each /8 to /32, not overlapping) your Cloud gateway sits in: the public block your organization numbers its internal network from, which lets /login reach a gateway there. A block must lie entirely outside private space, where /login accepts a gateway without this key. /login accepts a gateway inside a listed block over a direct connection only, and only when this machine's own address on that connection is inside the same block, so /login must happen from a machine whose own address is inside the block (not through a proxy, VPN pool, container or NAT segment outside it). A bar against copied settings files, not proof of location. Honored only from admin-controlled managed settings (MDM / managed-settings.json / policy helper); ignored in user, project, and remote-delivered settings.
+     */
+    gatewayInternalNetworks?: string[];
     /**
      * Controls whether the SDK parent tier (Options.managedSettings / --managed-settings) layers under this admin tier. "first-wins" (default): parent is dropped — admin tiers are the only policy source. "merge": parent's restrictive-only-filtered settings union under the admin winner. Has no effect when no admin tier exists (parent applies as the sole policy tier, still filtered restrictive-only).
      */
     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 and forceLoginGatewayUrl, 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, 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.
      */
     managedSourcesBehavior?: 'first-wins' | 'merge';
     /**
@@ -8697,6 +9019,7 @@ export declare type ToolConfig = {
          */
         previewFormat?: 'markdown' | 'html';
 
+
     };
 };