@anthropic-ai/claude-agent-sdk 0.3.222 → 0.3.224

package/sdk.d.ts

@@ -10,7 +10,7 @@ import type { Readable } from 'stream';
 import type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
 import type { UUID } from 'crypto';
 import type { Writable } from 'stream';
-import { z } from 'zod/v4';
+import * as z from 'zod/v4';
 import type { ZodRawShape } from 'zod';
 import type { ZodRawShape as ZodRawShape_2 } from 'zod/v4';
 
@@ -1810,9 +1810,62 @@ export declare type Options = {
     /**
      * When resuming, only resume messages up to and including the message with this UUID.
      * Use with `resume`. This allows you to resume from a specific point in the conversation.
-     * The message ID should be from `SDKAssistantMessage.uuid`.
+     * Accepts any chain-entry UUID — typically `SDKAssistantMessage.uuid`, but
+     * end-turn tool sessions and transcript-only appends need a later entry's
+     * UUID (see `resumeDropsTurn` for the fork-point guidance).
      */
     resumeSessionAt?: string;
+    /**
+     * With `resumeSessionAt`: declares the prompt UUID of the turn this
+     * truncating resume intends to discard. The CLI validates at fork time
+     * that every entry past the `resumeSessionAt` point is attributable to
+     * that turn, and refuses the resume (an `error_during_execution` result
+     * whose message starts with `Resume rejected by --resume-drops-turn:`)
+     * when the discarded range contains anything else — e.g. a queued user
+     * message or task notification the session absorbed mid-turn that the
+     * caller's view of the conversation had not yet observed. Omit to keep
+     * the unvalidated truncation behavior.
+     *
+     * Consumers MUST map a refusal (match on the message prefix above) to
+     * their rewind-recovery path — clear the pending fork target and resume
+     * plainly, keeping the evidence — not retry: the refusal is
+     * deterministic, so re-sending the same fork request fails forever.
+     *
+     * End-turn tool sessions (`outputFormat: {type: 'json_schema'}`, or any
+     * MCP tool using `_meta['claude/endTurn']`): a completed turn there ends
+     * on a successful tool_result carrier — with no trailing assistant
+     * message — followed by a `structured_output` attachment holding the
+     * turn's actual output (the carrier's data is a placeholder). Fork at
+     * the LAST entry of the turn being kept — the `structured_output`
+     * attachment when present, else the carrier — not the last assistant
+     * UUID; `resumeSessionAt` accepts any chain UUID. Forking earlier
+     * leaves the carrier or attachment in the discarded range, and the
+     * validator deliberately refuses: both are the kept turn's own payload,
+     * and dropping either would discard kept-turn output (the attachment is
+     * its sole persisted copy) or leave its tool_use dangling.
+     *
+     * The same fork-past-your-appends rule applies to plain (non-synthetic)
+     * `shouldQuery: false` transcript appends (e.g. CCD bash mode): they
+     * persist as bare user entries, so a fork point that leaves one in the
+     * discarded range refuses. Fork at or after your own last append.
+     *
+     * PRINT/HEADLESS LANE ONLY: the pair is consumed exclusively by the
+     * headless boot path (print-mode CLI, Agent SDK, ProcessTransport). An
+     * interactive `claude --resume` boot and background-job worker boots
+     * ignore both options — the resume loads the full chain with no
+     * truncation, no guard, and no error — so callers must not pass the
+     * pair outside print mode and expect an armed guard (rejecting it on
+     * those lanes is tracked follow-up work).
+     *
+     * General rule subsuming all of the above: fork at the KEPT turn's last
+     * chain entry, whatever it is — `resumeSessionAt` accepts any chain
+     * UUID. This also covers interrupted turns that completed one or more
+     * tools before Esc: the completed (non-error) tool_result in the tail
+     * is kept-turn payload and deliberately refuses at an assistant-UUID
+     * fork point, while the marker / cancel-batch entries after it are
+     * skippable — so fork at the last entry and the refusal never fires.
+     */
+    resumeDropsTurn?: string;
     /**
      * Sandbox settings for command execution isolation.
      *
@@ -2717,6 +2770,10 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
             error: "error";
             warn: "warn";
         }>>;
+        decode: z.ZodOptional<z.ZodEnum<{
+            jwt: "jwt";
+        }>>;
+        maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
         maskDuplicates: z.ZodOptional<z.ZodBoolean>;
         injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>>;
@@ -2726,9 +2783,38 @@ declare const SandboxCredentialsConfigSchema: () => z.ZodOptional<z.ZodObject<{
             deny: "deny";
             mask: "mask";
         }>;
+        extract: z.ZodOptional<z.ZodString>;
+        onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
+            deny: "deny";
+            error: "error";
+            warn: "warn";
+        }>>;
+        decode: z.ZodOptional<z.ZodEnum<{
+            jwt: "jwt";
+        }>>;
+        maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
         injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>>>;
     allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
+    awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        accessKeyIdVar: z.ZodString;
+        secretAccessKeyVar: z.ZodString;
+        sessionTokenVar: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    sigv4: z.ZodOptional<z.ZodObject<{
+        streaming: z.ZodOptional<z.ZodEnum<{
+            deny: "deny";
+            passthrough: "passthrough";
+        }>>;
+        presigned: z.ZodOptional<z.ZodEnum<{
+            deny: "deny";
+            passthrough: "passthrough";
+        }>>;
+        sigv4a: z.ZodOptional<z.ZodEnum<{
+            deny: "deny";
+            passthrough: "passthrough";
+        }>>;
+    }, z.core.$strip>>;
 }, z.core.$strip>>;
 
 export declare type SandboxFilesystemConfig = NonNullable<z.infer<ReturnType<typeof SandboxFilesystemConfigSchema>>>;
@@ -2816,6 +2902,10 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
                 error: "error";
                 warn: "warn";
             }>>;
+            decode: z.ZodOptional<z.ZodEnum<{
+                jwt: "jwt";
+            }>>;
+            maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
             maskDuplicates: z.ZodOptional<z.ZodBoolean>;
             injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>>;
@@ -2825,9 +2915,38 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
                 deny: "deny";
                 mask: "mask";
             }>;
+            extract: z.ZodOptional<z.ZodString>;
+            onExtractNoMatch: z.ZodOptional<z.ZodEnum<{
+                deny: "deny";
+                error: "error";
+                warn: "warn";
+            }>>;
+            decode: z.ZodOptional<z.ZodEnum<{
+                jwt: "jwt";
+            }>>;
+            maskClaims: z.ZodOptional<z.ZodArray<z.ZodString>>;
             injectHosts: z.ZodOptional<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>>>;
         allowPlaintextInject: z.ZodOptional<z.ZodBoolean>;
+        awsPairs: z.ZodOptional<z.ZodArray<z.ZodObject<{
+            accessKeyIdVar: z.ZodString;
+            secretAccessKeyVar: z.ZodString;
+            sessionTokenVar: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
+        sigv4: z.ZodOptional<z.ZodObject<{
+            streaming: z.ZodOptional<z.ZodEnum<{
+                deny: "deny";
+                passthrough: "passthrough";
+            }>>;
+            presigned: z.ZodOptional<z.ZodEnum<{
+                deny: "deny";
+                passthrough: "passthrough";
+            }>>;
+            sigv4a: z.ZodOptional<z.ZodEnum<{
+                deny: "deny";
+                passthrough: "passthrough";
+            }>>;
+        }, z.core.$strip>>;
     }, z.core.$strip>>;
     ignoreViolations: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
     enableWeakerNestedSandbox: z.ZodOptional<z.ZodBoolean>;
@@ -4075,11 +4194,13 @@ export declare type SDKMessageOrigin = {
 } | {
     kind: 'task-notification';
     /**
-     * Present when the delivery is the fired stored prompt of a scheduled task/routine (stamped from server-asserted provenance; the schedule attests storage, not authorship). The harness frames it as the session's assigned task instead of the generic background-notification frame. Absent on webhook, PR-steward, plugin, and background-event deliveries.
+     * Present when the delivery is the fired stored prompt of a scheduled task/routine ('scheduled-trigger', stamped from server-asserted provenance; the schedule attests storage, not authorship), or a coordinator co-member SendMessage delivery ('peer-send-message': model-authored text from another of the same user's sessions, verified by the server-stamped receiver co-membership — task-notification for prompt authority, but distinguishable so the receive-side crossSessionInbound setting can apply to it). The harness frames a scheduled-trigger delivery as the session's assigned task instead of the generic background-notification frame. Absent on webhook, PR-steward, plugin, and background-event deliveries.
      */
-    subkind?: 'scheduled-trigger';
+    subkind?: 'scheduled-trigger' | 'peer-send-message';
 } | {
     kind: 'coordinator';
+} | {
+    kind: 'unclassified';
 } | {
     kind: 'observer';
     from: string;
@@ -4189,7 +4310,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). The 'ask' path surfaces via a can_use_tool control_request; this event covers the 'deny' short-circuit in canUseTool so SDK hosts can render the denial instead of only seeing an is_error tool_result. PreToolUse hook denies bypass canUseTool and are not covered here.
+ * 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).
  */
 export declare type SDKPermissionDeniedMessage = {
     type: 'system';
@@ -4300,8 +4421,17 @@ export declare type SDKResultError = {
     is_error: boolean;
     num_turns: number;
     stop_reason: string | null;
+    /**
+     * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, resumed sessions start fresh, and a mid-session /clear resets the running total. An estimate, not a billing statement.
+     */
     total_cost_usd: number;
+    /**
+     * MAIN AGENT LOOP ONLY — excludes Task subagent, sidechain, and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer modelUsage for token/cost accounting.
+     */
     usage: NonNullableUsage;
+    /**
+     * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, resumed sessions start fresh, and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
+     */
     modelUsage: Record<string, ModelUsage>;
     permission_denials: SDKPermissionDenial[];
     errors: string[];
@@ -4333,8 +4463,17 @@ export declare type SDKResultSuccess = {
     num_turns: number;
     result: string;
     stop_reason: string | null;
+    /**
+     * Cumulative estimated cost in USD for this query() call, covering the same query-pipeline calls as modelUsage and sharing its lifecycle: cumulative across turns in streaming-input sessions — each result carries the running total so far, so read the latest result rather than summing across results. Crash/startup-error results may carry zeroed values, resumed sessions start fresh, and a mid-session /clear resets the running total. An estimate, not a billing statement.
+     */
     total_cost_usd: number;
+    /**
+     * MAIN AGENT LOOP ONLY — excludes Task subagent, sidechain, and auxiliary model calls, and is per-turn in streaming-input sessions. Prefer modelUsage for token/cost accounting.
+     */
     usage: NonNullableUsage;
+    /**
+     * Per-model totals for every model call made through the query pipeline during this query() call — main loop, Task subagents, sidechains, and internal calls such as compaction and Workflow agents. Cumulative across turns in streaming-input sessions: each result carries the running total so far, so read the latest result rather than summing across results. Internal helper calls outside the query pipeline (e.g. the permission classifier, token-count probes) are excluded; crash/startup-error results may carry zeroed usage, resumed sessions start fresh, and a mid-session /clear resets the running total. The correct field for token/cost accounting; treat it as an estimate, not a billing statement.
+     */
     modelUsage: Record<string, ModelUsage>;
     permission_denials: SDKPermissionDenial[];
     structured_output?: unknown;
@@ -5552,7 +5691,7 @@ export declare interface Settings {
             } | {
                 source: 'github';
                 /**
-                 * GitHub repository in owner/repo format
+                 * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
                  */
                 repo: string;
                 /**
@@ -5702,8 +5841,19 @@ export declare interface Settings {
                          * Specific commit SHA to use
                          */
                         sha?: string;
+                    } | {
+                        source: 'archive';
+                        /**
+                         * HTTPS URL of a zip archive containing the plugin. The plugin root (the directory holding .claude-plugin/) may be at the top of the archive or nested one directory deep — a single wrapping directory is stripped.
+                         */
+                        url: string;
+                        /**
+                         * SHA-256 digest of the archive. When set, every download is verified against it and the install is refused on mismatch. It also serves as the version identity when neither plugin.json nor the marketplace entry declares a `version`. Recommended. Note the update signal is the version string (plugin.json version, else the entry version, else this digest) — changing only the digest while a version is declared does not trigger an update.
+                         */
+                        sha256?: string;
                     } | {
                         source: 'unsupported';
+                        error?: string;
                     };
                     description?: string;
                     version?: string;
@@ -5735,7 +5885,7 @@ export declare interface Settings {
         };
     };
     /**
-     * Enterprise strict list of allowed marketplace sources. When set in managed settings, ONLY these exact sources can be added as marketplaces. The check happens BEFORE downloading, so blocked sources never touch the filesystem. Note: this is a policy gate only — it does NOT register marketplaces. To pre-register allowed marketplaces for users, also set extraKnownMarketplaces.
+     * Enterprise strict list of allowed marketplace sources. When set in managed settings, ONLY these sources can be added as marketplaces. Entries match exactly, except that a github entry may use the owner-wildcard form {"source":"github","repo":"owner/*"} to allow every repository under that owner. The check happens BEFORE downloading, so blocked sources never touch the filesystem. Note: this is a policy gate only — it does NOT register marketplaces. To pre-register allowed marketplaces for users, also set extraKnownMarketplaces.
      */
     strictKnownMarketplaces?: ({
         source: 'url';
@@ -5752,7 +5902,7 @@ export declare interface Settings {
     } | {
         source: 'github';
         /**
-         * GitHub repository in owner/repo format
+         * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
          */
         repo: string;
         /**
@@ -5902,8 +6052,19 @@ export declare interface Settings {
                  * Specific commit SHA to use
                  */
                 sha?: string;
+            } | {
+                source: 'archive';
+                /**
+                 * HTTPS URL of a zip archive containing the plugin. The plugin root (the directory holding .claude-plugin/) may be at the top of the archive or nested one directory deep — a single wrapping directory is stripped.
+                 */
+                url: string;
+                /**
+                 * SHA-256 digest of the archive. When set, every download is verified against it and the install is refused on mismatch. It also serves as the version identity when neither plugin.json nor the marketplace entry declares a `version`. Recommended. Note the update signal is the version string (plugin.json version, else the entry version, else this digest) — changing only the digest while a version is declared does not trigger an update.
+                 */
+                sha256?: string;
             } | {
                 source: 'unsupported';
+                error?: string;
             };
             description?: string;
             version?: string;
@@ -5925,7 +6086,7 @@ export declare interface Settings {
         };
     })[];
     /**
-     * Enterprise blocklist of marketplace sources. When set in managed settings, these exact sources are blocked from being added as marketplaces. The check happens BEFORE downloading, so blocked sources never touch the filesystem.
+     * Enterprise blocklist of marketplace sources. When set in managed settings, these sources are blocked from being added as marketplaces. Entries match exactly, except that a github entry may use the owner-wildcard form {"source":"github","repo":"owner/*"} to block every repository under that owner. The check happens BEFORE downloading, so blocked sources never touch the filesystem.
      */
     blockedMarketplaces?: ({
         source: 'url';
@@ -5942,7 +6103,7 @@ export declare interface Settings {
     } | {
         source: 'github';
         /**
-         * GitHub repository in owner/repo format
+         * GitHub repository in owner/repo format. ONLY in the managed-settings policy lists (strictKnownMarketplaces / blockedMarketplaces) the owner-wildcard form "owner/*" matches every repository under exactly that owner. Everywhere else (marketplace add, extraKnownMarketplaces, known_marketplaces.json) the value must name a single repository — a wildcard is taken literally and fails to clone.
          */
         repo: string;
         /**
@@ -6092,8 +6253,19 @@ export declare interface Settings {
                  * Specific commit SHA to use
                  */
                 sha?: string;
+            } | {
+                source: 'archive';
+                /**
+                 * HTTPS URL of a zip archive containing the plugin. The plugin root (the directory holding .claude-plugin/) may be at the top of the archive or nested one directory deep — a single wrapping directory is stripped.
+                 */
+                url: string;
+                /**
+                 * SHA-256 digest of the archive. When set, every download is verified against it and the install is refused on mismatch. It also serves as the version identity when neither plugin.json nor the marketplace entry declares a `version`. Recommended. Note the update signal is the version string (plugin.json version, else the entry version, else this digest) — changing only the digest while a version is declared does not trigger an update.
+                 */
+                sha256?: string;
             } | {
                 source: 'unsupported';
+                error?: string;
             };
             description?: string;
             version?: string;
@@ -6251,11 +6423,19 @@ export declare interface Settings {
                  */
                 extract?: string;
                 /**
-                 * What to do when `extract` matches nothing in the file. `warn` (default) emits a stderr warning and leaves the file readable as-is inside the sandbox (fail-open, for credentials that may be legitimately absent); `deny` degrades the entry to mode `deny` so the file is unreadable (fail-closed) — under `sandbox.filesystem.disabled` it is treated as `error`, since read-denies are dropped in that mode; `error` aborts at sandbox setup so nothing runs until the config is fixed. Only meaningful when mode is `mask` and `extract` is set; accepted but ignored otherwise.
+                 * What to do when `extract` matches nothing in the file — or, with `decode`, when no candidate survives verification. `warn` (default) emits a stderr warning and leaves the file readable as-is inside the sandbox (fail-open, for credentials that may be legitimately absent); `deny` degrades the entry to mode `deny` so the file is unreadable (fail-closed) — under `sandbox.filesystem.disabled` it is treated as `error`, since read-denies are dropped in that mode; `error` aborts at sandbox setup so nothing runs until the config is fixed. Only meaningful when mode is `mask` and `extract` or `decode` is set; accepted but ignored otherwise.
                  */
                 onExtractNoMatch?: 'warn' | 'deny' | 'error';
                 /**
-                 * If true, verbatim occurrences of each captured credential value outside the regex-matched spans are also replaced with the corresponding sentinel — for a secret repeated where the regex does not reach (e.g. pasted into a comment). Matches raw substrings, so short or common values may corrupt unrelated content; intended for long, high-entropy secrets. Defaults to false. Only meaningful when mode is `mask` and `extract` is set; accepted but ignored otherwise.
+                 * Optional encoded-credential format for `mask` mode. `jwt`: candidates are located with a built-in JWT regex (or the explicit `extract` pattern, if set), verified to actually be JWTs before masking, and replaced with a structurally valid fake JWT so client-side token parsing inside the sandbox keeps working. If no candidate verifies, behavior is governed by `onExtractNoMatch` (default `warn`). Accepted but ignored for `deny`.
+                 */
+                decode?: 'jwt';
+                /**
+                 * Names of top-level payload claims to mask inside each decoded value, instead of replacing the whole token. Each named claim present with a string value gets its own sentinel and the token is rebuilt around the modified payload; all other claims are preserved so a tool that decodes the token and reads a non-secret claim keeps working. Requires `decode`. If no named claim matches in any verified token, behavior is governed by `onExtractNoMatch` (default `warn`). Only meaningful when mode is `mask`; accepted but ignored for `deny`.
+                 */
+                maskClaims?: string[];
+                /**
+                 * If true, verbatim occurrences of each captured credential value outside the regex-matched spans are also replaced with the corresponding sentinel — for a secret repeated where the regex does not reach (e.g. pasted into a comment). Matches raw substrings, so short or common values may corrupt unrelated content; intended for long, high-entropy secrets. Defaults to false. Only meaningful when mode is `mask` and `extract` or `decode` is set; accepted but ignored otherwise.
                  */
                 maskDuplicates?: boolean;
                 /**
@@ -6275,6 +6455,22 @@ export declare interface Settings {
                  * Access mode for this environment variable. `deny` unsets the variable for sandboxed commands; `mask` shows sandboxed commands a sentinel value and the host proxy swaps sentinel→real on egress to `injectHosts`.
                  */
                 mode: 'deny' | 'mask';
+                /**
+                 * Optional regex for structured masking when mode is `mask`. Applied globally to the value; capture group 1 of each match is a credential value, and only those captured spans are replaced with sentinels — the rest of the value is preserved so a tool that parses it (a `DATABASE_URL` connection string, a composite `KEY:SECRET` pair) still succeeds inside the sandbox. Without `extract`, the entire value is replaced with one sentinel (whole-value masking, suited to bare tokens). If the regex matches nothing, behavior is governed by `onExtractNoMatch` (default `warn`). Cannot be combined with `decode` (the decode path never consults it). Accepted but ignored for `deny`.
+                 */
+                extract?: string;
+                /**
+                 * What to do when `extract` matches nothing in the value. `warn` (default) emits a stderr warning and lets the variable pass through unmasked (fail-open, for credentials that may be legitimately absent); `deny` unsets the variable inside the sandbox (fail-closed); `error` aborts at sandbox setup so nothing runs until the config is fixed. Only meaningful when mode is `mask` and `extract` is set without `decode`. On a mask entry with `decode`, the runtime takes the decode path and never consults this field, so a fail-closed setting cannot be honored — `deny` and `error` are rejected there; only `warn` is accepted. In all other shapes the field is accepted but ignored.
+                 */
+                onExtractNoMatch?: 'warn' | 'deny' | 'error';
+                /**
+                 * Optional encoded-credential format for `mask` mode. `jwt`: the variable's whole value is verified to actually be a JWT and replaced with a structurally valid fake JWT so client-side token parsing inside the sandbox keeps working; the proxy swaps the whole fake token on egress. If the value does not verify, the variable is left unmasked with a stderr warning (fail-open). Cannot be combined with `extract` — the decode path never consults it. Accepted but ignored for `deny`.
+                 */
+                decode?: 'jwt';
+                /**
+                 * Names of top-level payload claims to mask inside the decoded value, instead of replacing the whole token. Each named claim present with a string value gets its own sentinel and the token is rebuilt around the modified payload; all other claims are preserved so claim-reading clients keep working. Requires `decode`. If no named claim matches, the variable is left unmasked with a stderr warning (fail-open). Only meaningful when mode is `mask`; accepted but ignored for `deny`.
+                 */
+                maskClaims?: string[];
                 /**
                  * Optional narrowing of where the proxy substitutes this credential. Only meaningful when mode is `mask`; accepted but ignored for `deny`. If unset, defaults to `network.allowedDomains` — the credential is injected at every reachable host. Each entry must be reachable via `network.allowedDomains` (sandbox-runtime validates this).
                  */
@@ -6284,6 +6480,40 @@ export declare interface Settings {
              * Allow sentinel→real substitution on the plain-HTTP proxy path. Defaults to false: without TLS termination the upstream identity is unverified and the credential travels in cleartext. Set only for trusted-network test fixtures. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
              */
             allowPlaintextInject?: boolean;
+            /**
+             * Explicit groupings of masked env vars into AWS credential pairs for SigV4 re-signing, for non-standard variable names. The conventional AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_SESSION_TOKEN trio is paired automatically when masked. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored. A member is only usable when its env var is forwarded as a whole-value `mask` entry (an entry carrying `extract` or `decode` does not qualify — re-signing needs the whole real value). A pair whose key id or secret member is unusable never re-signs: it is dropped, unless it names a conventional AWS variable, in which case it is forwarded as an inert suppressor so implicit auto-pairing stays overridden. A pair whose ONLY unusable member is the session token still re-signs, without an x-amz-security-token (temporary-credential requests fail upstream until the entry is fixed).
+             */
+            awsPairs?: {
+                /**
+                 * Name of the masked env var holding the AWS access key id.
+                 */
+                accessKeyIdVar: string;
+                /**
+                 * Name of the masked env var holding the AWS secret access key.
+                 */
+                secretAccessKeyVar: string;
+                /**
+                 * Optional name of the masked env var holding the AWS session token (temporary credentials). When set, the proxy sends the real token as x-amz-security-token on re-signed requests and adds it to the signed header set if the client did not.
+                 */
+                sessionTokenVar?: string;
+            }[];
+            /**
+             * Policies for AWS SigV4 request shapes the proxy cannot re-sign (streaming, presigned, sigv4a) when they reference a masked credential pair: `deny` (default) or `passthrough`. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
+             */
+            sigv4?: {
+                /**
+                 * Policy for aws-chunked streaming uploads (x-amz-content-sha256: STREAMING-*): per-chunk signatures chain off the seed signature, so re-signing would require rewriting the body. `deny` (default) fails closed with a 403; `passthrough` forwards the request unre-signed (the upstream will reject its signature).
+                 */
+                streaming?: 'deny' | 'passthrough';
+                /**
+                 * Policy for presigned URLs (X-Amz-Algorithm/X-Amz-Signature in the query, no Authorization header): the signature lives in the URL itself. `deny` (default) or `passthrough`.
+                 */
+                presigned?: 'deny' | 'passthrough';
+                /**
+                 * Policy for SigV4A (AWS4-ECDSA-P256-SHA256) asymmetric signatures: there is no shared-key HMAC to recompute. `deny` (default) or `passthrough`.
+                 */
+                sigv4a?: 'deny' | 'passthrough';
+            };
         };
         ignoreViolations?: {
             [k: string]: string[];
@@ -6394,6 +6624,10 @@ export declare interface Settings {
      * Idle time before Claude's questions auto-continue with any answers selected so far. Defaults to never — auto-continue only runs when explicitly set to 60s/5m/10m.
      */
     askUserQuestionTimeout?: '60s' | '5m' | '10m' | 'never';
+    /**
+     * Max time a permission/user dialog forwarded to a remote client stays parked awaiting an answer, and how long a HELD cross-session message awaits approval, before either resolves to its safe no-action default (cancelled / dropped-with-denial). Defaults to 5m to match the long-standing remote-dialog deadline; "never" disables the deadline. Local-only permission prompts (no remote client) are unaffected. The CLAUDE_CODE_USER_DIALOG_TIMEOUT_MS env var, when set, overrides this. Read from trusted sources only (never a checked-in repo settings file).
+     */
+    dialogExpiry?: '60s' | '5m' | '10m' | 'never';
     /**
      * Name of an agent (built-in or custom) to use for the main thread. Applies the agent's system prompt, tool restrictions, and model.
      */
@@ -6635,6 +6869,10 @@ export declare interface Settings {
      * When no background service is running: 'transient' spawns one for this login session; 'ask' offers to install it persistently
      */
     daemonColdStart?: 'transient' | 'ask';
+    /**
+     * Inbound cross-session peer messages (SendMessage from your other sessions): 'accept' delivers them, 'hold' parks them for your review without letting Claude act, 'refuse' opts this session out. An explicit value always wins. Unset (mode parity): a message auto-delivers only when the sending session's permission-mode class matches yours (bypass↔bypass or prompting↔prompting); a mismatched sender's message is held for your approval; a sender that asserts no class is held only while this session bypasses permission prompts.
+     */
+    crossSessionInbound?: 'accept' | 'hold' | 'refuse';
     /**
      * Mirror local sessions to claude.ai as view-only (no remote control)
      */