@anthropic-ai/claude-agent-sdk 0.3.316 → 0.3.318

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/sdk.d.ts CHANGED
@@ -284,8 +284,8 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
284
284
  */
285
285
  defaultToNo?: boolean;
286
286
  /**
287
- * The ask must not offer a persistent "don't ask again" choice: the
288
- * rule it would write grants more than this ask's own action.
287
+ * The ask must not offer a persistent "don't ask again" choice: its rule
288
+ * grants more than this ask's action, or a plugin started this call.
289
289
  */
290
290
  suppressAlwaysAllowRule?: boolean;
291
291
  /**
@@ -579,6 +579,7 @@ declare namespace coreTypes {
579
579
  SDKResultSuccess,
580
580
  SDKSessionInfo,
581
581
  SDKSessionStateChangedMessage,
582
+ SDKSessionWritesLostMessage,
582
583
  SDKSettingsParseError,
583
584
  SDKStartupFailureReason,
584
585
  SDKStatusMessage,
@@ -688,7 +689,8 @@ export declare type CwdChangedHookSpecificOutput = {
688
689
  };
689
690
 
690
691
  /**
691
- * Delete a session.
692
+ * Delete a session. Deletes data only on this computer, or only in
693
+ * `sessionStore` when one is passed, not anything stored by Anthropic.
692
694
  *
693
695
  * With `sessionStore`: calls `sessionStore.delete()` if implemented; no-op
694
696
  * otherwise (per the SessionStore contract — appropriate for WORM/append-only
@@ -1005,6 +1007,17 @@ export declare interface HookCallbackMatcher {
1005
1007
  hooks: HookCallback[];
1006
1008
  /** Timeout in seconds for all hooks in this matcher */
1007
1009
  timeout?: number;
1010
+ /**
1011
+ * What a failure of these hooks does: one throws, or returns output that
1012
+ * fails validation. `'continue'` (default): the failure is reported in a
1013
+ * warning message and the action goes ahead. `'block'`: the action the event
1014
+ * guards (a tool call, a permission request, a prompt) is blocked. Ignored on
1015
+ * Stop, SubagentStop, TaskCompleted and TeammateIdle. With `'block'`, the
1016
+ * query fails at startup on a Claude Code that does not support the option
1017
+ * and on a session already running that did not register these hooks, and
1018
+ * the first prompt is sent only once those checks have passed.
1019
+ */
1020
+ onFailure?: 'continue' | 'block';
1008
1021
  }
1009
1022
 
1010
1023
  export declare type HookEvent = 'PreToolUse' | 'PostToolUse' | 'PostToolUseFailure' | 'PostToolBatch' | 'Notification' | 'UserPromptSubmit' | 'UserPromptExpansion' | 'SessionStart' | 'SessionEnd' | 'Stop' | 'StopFailure' | 'SubagentStart' | 'SubagentStop' | 'PreCompact' | 'PostCompact' | 'PreModelSwitch' | 'PostModelSwitch' | 'PermissionRequest' | 'PermissionDenied' | 'Setup' | 'TeammateIdle' | 'TaskCreated' | 'TaskCompleted' | 'Elicitation' | 'ElicitationResult' | 'ConfigChange' | 'WorktreeCreate' | 'WorktreeRemove' | 'InstructionsLoaded' | 'CwdChanged' | 'FileChanged' | 'DirectoryAdded' | 'MessageDisplay';
@@ -1226,6 +1239,7 @@ export declare type McpHttpServerConfig = {
1226
1239
  */
1227
1240
  timeout?: number;
1228
1241
 
1242
+
1229
1243
  /**
1230
1244
  * 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.
1231
1245
  */
@@ -1331,6 +1345,7 @@ export declare type McpServerStatus = {
1331
1345
  _meta?: Record<string, unknown>;
1332
1346
  }[];
1333
1347
 
1348
+
1334
1349
  };
1335
1350
 
1336
1351
  export declare type McpServerStatusConfig = McpServerConfigForProcessTransport | McpClaudeAIProxyServerConfig;
@@ -1375,6 +1390,7 @@ export declare type McpSSEServerConfig = {
1375
1390
  */
1376
1391
  timeout?: number;
1377
1392
 
1393
+
1378
1394
  /**
1379
1395
  * 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.
1380
1396
  */
@@ -2138,6 +2154,12 @@ export declare type Options = {
2138
2154
  * on `task_progress` events via the `summary` field. The fork reuses the
2139
2155
  * subagent's model and prompt cache, so cost is typically minimal.
2140
2156
  *
2157
+ * Summaries are not a heartbeat. None is made while the conversation is
2158
+ * unchanged. A summary can also be delayed by up to 5 minutes while the
2159
+ * subagent is waiting for a model response and its prompt cache is likely cold
2160
+ * (no response yet, or none begun in the last 4.5 minutes). If the subagent
2161
+ * finishes first, that summary is not sent.
2162
+ *
2141
2163
  * Applies to both foreground and background subagents. Defaults to false.
2142
2164
  */
2143
2165
  agentProgressSummaries?: boolean;
@@ -3291,16 +3313,20 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3291
3313
  * are managed by the CLI subprocess.
3292
3314
  *
3293
3315
  * Note: This only affects servers added dynamically via this method or the SDK.
3294
- * Servers configured via settings files are not affected. Servers introduced
3295
- * by plugins are also exempt: they are managed by the plugin system, so
3296
- * omitting them from the payload does NOT remove them — they keep running
3297
- * (unless enterprise policy denies the server) and are simply absent from
3298
- * the result's `removed` list. In particular, `setMcpServers({})` no longer
3299
- * guarantees a session has zero dynamic MCP surface when plugins are
3300
- * loaded. Naming a plugin server explicitly in the payload still replaces
3301
- * it (ownership is preserved CLI-side).
3302
- *
3303
- * @param servers - Record of server name to configuration. Pass an empty object to remove all dynamic servers (except plugin-owned ones, which are retained).
3316
+ * Servers configured via settings files are not affected. A `.mcp.json` or
3317
+ * local-scope server of the session's current folder stays up when omitted,
3318
+ * unless enterprise policy denies it; once a payload has named such a server
3319
+ * it is the host's, and a later payload that omits it removes it. Servers
3320
+ * introduced by plugins are also exempt: they are managed by the plugin
3321
+ * system, so omitting them from the payload does NOT remove them — they keep
3322
+ * running (unless enterprise policy denies the server) and are simply absent
3323
+ * from the result's `removed` list. In particular, `setMcpServers({})` no
3324
+ * longer guarantees a session has zero dynamic MCP surface when plugins are
3325
+ * loaded or its current folder has such servers. Naming a plugin server
3326
+ * explicitly in the payload still replaces it (ownership is preserved
3327
+ * CLI-side).
3328
+ *
3329
+ * @param servers - Record of server name to configuration. Pass an empty object to remove all dynamic servers (except plugin-owned ones and those of the session's current folder, which are retained as above).
3304
3330
  * @returns Information about which servers were added, removed, and any connection errors
3305
3331
  */
3306
3332
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
@@ -4800,6 +4826,10 @@ export declare type SDKControlInitializeResponse = {
4800
4826
  * 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.
4801
4827
  */
4802
4828
  hooks_applied?: boolean;
4829
+ /**
4830
+ * True on every initialize reply from a CLI that honors `onFailure` on hook matchers. Absent on CLIs that predate the option, which ignore it (a failed callback set to "block" lets the action run), and from responders that do not run the host's hooks. A host that sets "block" must not go on without it; the TypeScript SDK refuses the session. It says nothing of this request's hooks: `hooks_applied` does, and the TypeScript SDK also refuses a first initialize that reads `hooks_applied: false` when a matcher sets "block".
4831
+ */
4832
+ hook_on_failure_supported?: boolean;
4803
4833
 
4804
4834
  /**
4805
4835
  * 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`).
@@ -4857,14 +4887,14 @@ declare type SDKControlInterruptRequest = {
4857
4887
  */
4858
4888
  export declare type SDKControlInterruptResponse = {
4859
4889
  /**
4860
- * 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.
4890
+ * Uuids of async user messages that survive this interrupt: commands still in the queue, plus any batch already dequeued for the imminent turn but not yet reachable by the abort, plus any user message this process has read but not yet queued, from its own input stream (held, for instance, while a model change is still being checked or behind start-up work; a message a Remote Control client sent that is still being ingested is not listed). An interrupt — plain or cancel_queued:true — that lands during the FIRST-command prewait window (before the first turn of the session has armed a controller) is additionally LATCHED, scoped to the user-intent work pending at that instant — the batch already dequeued and parked for the imminent turn, plus the user-intent main-thread commands then in the queue or held ahead of it (the work this list enumerates): the first turn to arm that carries any of that doomed work starts already aborted, exactly once, so the listed prewait batch is delivered into an immediately-aborted turn, its frames and result flowing through the normal abort path, instead of running to completion. A turn carrying none of it arms live and leaves the latch waiting: a system delivery turn (for example a replayed host event), or a prompt enqueued after the interrupt — post-interrupt work is never coalesced with the doomed work and never dies to the latch, so the Stop kills exactly what this receipt listed. The latch is released when the doomed work is retired without arming: if a parked prewait batch is entirely cancelled, the latch is released even when other queued commands remain (those arm and run normally); with nothing parked, it is released once none of the doomed commands remains queued or held — work enqueued after the interrupt neither holds it up nor is aborted by it. Survivors that ride any later turn run normally. These WILL run (subject to that latch) unless cancelled first (or unless the request set cancel_queued:true, in which case every uuid-stamped survivor this process holds is removed, emitted a terminal `cancelled` synchronously, and listed under `cancelled` instead — leaving here only what a client driving a hosted session can no longer recall: a send already in flight to that session, or the first prompt the session was created with; a send that client still holds on its own machine behind a send gate (it waits there until that session is ready to take it) has not gone out, so it is withdrawn and listed under `cancelled` like a queued one, and cancel_async_message can withdraw it too, while a plain interrupt leaves it held and lists it here). Cancellation granularity: uuids still in the queue are individually cancellable via cancel_async_message (the re-run of an interrupted turn that also answers for other client messages only if this interrupt was for it; see the response to that request); a listed uuid whose message the process running the session (never a client driving a hosted session) still keeps out of its queue, behind a model change or start-up work, is not yet cancellable that way: cancel_async_message answers cancelled:false for it and plants a cancel-pending mark, which the drain honours once the message is queued and the mid-turn fold of a running turn does not; once a batch is dequeued and coalesced into one turn, cancelling a NON-representative member uuid is a no-op (its content still runs), while cancelling the batch-representative uuid drops the WHOLE coalesced batch — in both cases the cancel response reports cancelled:false because the message was no longer in the queue. Coverage caveats: only uuid-STAMPED messages appear (a message enqueued without a uuid still runs but is never listed, so [] does not mean "nothing will run"); only main-thread messages are listed (subagent-addressed messages are out of scope); and the list may include internally-enqueued uuids the client never sent (cron triggers, auto-resume continuations) — ignore unknown uuids rather than treating them as an error. Ordering: on a clean interrupt this receipt is written before the interrupted turn result; a turn that crashes during interrupt handling emits its error result on a direct-write path that may precede the receipt. Snapshot is taken synchronously with abort processing — probing the queue after the interrupted result instead always loses the race against the drain loop, which starts the next queued turn immediately.
4861
4891
  */
4862
4892
  still_queued: string[];
4863
4893
 
4864
4894
 
4865
4895
 
4866
4896
  /**
4867
- * 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.
4897
+ * 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), dropped before it was queued (a message this process had read and was still holding), 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.
4868
4898
  */
4869
4899
  cancelled?: string[];
4870
4900
  };
@@ -4960,7 +4990,7 @@ declare type SDKControlMcpMessageRequest = {
4960
4990
  };
4961
4991
 
4962
4992
  /**
4963
- * Reads one MCP Apps (SEP-1865) UI resource — a `ui://` URI, typically the `_meta.ui.resourceUri` a tool declares — from a connected MCP server the CLI itself dialed, with `resources/read`, for a host that renders it. Read-only and no model turn. The reply is untrusted third-party content (HTML): render it sandboxed. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can read them directly. Errors name the cause: a non-ui:// URI, an unknown server, a server that managed policy blocks, that is disabled or that the project has not approved (the refusals mcp_reconnect gives), a server that is not connected (failed, pending or needs-auth: send mcp_reconnect; a connected server, or one still listed from the discovery cache, is read through the same connect path a tool call takes), a response over the size limit, or the server's own resources/read error. Refused on a lane that redacts what it persists (a Remote Control bridge worker, a tenant worker) and by the client of a cloud-hosted session. Advertised as `mcp_read_resource_v1` in system/init.capabilities.
4993
+ * Reads one MCP Apps (SEP-1865) UI resource — a `ui://` URI, typically the `_meta.ui.resourceUri` a tool declares — from a connected MCP server the CLI itself dialed, with `resources/read`, for a host that renders it. Read-only and no model turn. The reply is untrusted third-party content (HTML): render it sandboxed. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can read them directly. Errors name the cause: a non-ui:// URI, an unknown server, a server that managed policy blocks, that is disabled or that the project has not approved (the refusals mcp_reconnect gives), a server that is not connected (failed, pending or needs-auth: send mcp_reconnect; a connected server, or one still listed from the discovery cache, is read through the same connect path a tool call takes), a response over the size limit, or the server's own resources/read error (over a transport that stores frames, one fixed sentence in its place). Refused on a lane that redacts what it persists (a Remote Control bridge worker, a tenant worker) and by the client of a cloud-hosted session. Advertised as `mcp_read_resource_v1` in system/init.capabilities.
4964
4994
  */
4965
4995
  declare type SDKControlMcpReadResourceRequest = {
4966
4996
  subtype: 'mcp_read_resource';
@@ -5018,7 +5048,7 @@ declare type SDKControlMcpSetServersRequest = {
5018
5048
  declare type SDKControlMcpStatusRequest = {
5019
5049
  subtype: 'mcp_status';
5020
5050
  /**
5021
- * 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.
5051
+ * 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; a cloud session's worker that does not advertise `mcp_status_no_config_v1` embeds each server's configuration (URLs, headers, OAuth settings) in its rows. 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; a reply too large to send in full leaves out each server's `tools`, `serverInfo` and `capabilities` and sends only how many tools it has, and one still 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.
5022
5052
  */
5023
5053
  liveReply?: boolean;
5024
5054
  };
@@ -5061,7 +5091,7 @@ declare type SDKControlPermissionRequest = {
5061
5091
  */
5062
5092
  classifier_approvable?: boolean;
5063
5093
  /**
5064
- * True when the dialog must not offer the persistent "don't ask again" row for this ask: accepting it would write a whole-tool allow rule broader than the ask's own verb (PermissionAskDecision.suppressAlwaysAllowRule). Hosts rendering approve options should omit any persistent-rule affordance when set.
5094
+ * True when the dialog must not offer the persistent "don't ask again" row for this ask: accepting it would write a whole-tool allow rule broader than the ask's own verb (PermissionAskDecision.suppressAlwaysAllowRule), or the ask comes from a run a plugin started, where Claude Code saves no rule from the answer, not even for the session. Hosts rendering approve options should omit any persistent-rule affordance when set.
5065
5095
  */
5066
5096
  suppress_always_allow_rule?: boolean;
5067
5097
  /**
@@ -5083,7 +5113,7 @@ declare type SDKControlPermissionRequest = {
5083
5113
 
5084
5114
  description?: string;
5085
5115
  /**
5086
- * 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), OR the ask is the one made before the first upload by file reference to a connector, which no stored grant or automatic approval may answer. In each case the user has to open the session to answer.
5116
+ * 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 a grant keyed on the tool name must not answer it: 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, or, while Claude Code enforces grants, two tools of the server get that name, OR the SDK host worded the ask (title and description are its consent copy, which a push cannot carry whole), OR the ask is the one made before the first upload by file reference to a connector, which no stored grant or automatic approval may answer. In each case the user has to open the session to answer.
5087
5117
  */
5088
5118
  requires_user_interaction?: boolean;
5089
5119
 
@@ -5107,6 +5137,7 @@ export declare type SDKControlPermissionRulesState = {
5107
5137
  * True when enterprise managed settings pin allowManagedPermissionRulesOnly: the session applies policy rules only, and rules from other settings files appear with notInEffect set.
5108
5138
  */
5109
5139
  managedOnly: boolean;
5140
+
5110
5141
  /**
5111
5142
  * 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.
5112
5143
  */
@@ -5138,6 +5169,10 @@ export declare type SDKControlReadFileResponse = {
5138
5169
  * Set when the request asked for base64. Absent means utf-8 — including when an older CLI ignored the request's encoding field.
5139
5170
  */
5140
5171
  encoding?: 'base64';
5172
+ /**
5173
+ * Present on every utf-8 answer. True when the bytes read were not all valid UTF-8, so `contents` has U+FFFD where bytes were replaced and is not the file's own text: a binary file, text in another encoding, or a read cut inside a character when `truncated` is set. False when `contents` is exactly the bytes read, decoded, even if the file itself contains U+FFFD. Absent on a base64 answer, which is exact, and from an older CLI or tool container: a client that sees neither this nor `encoding: 'base64'` cannot tell whether `contents` is exact.
5174
+ */
5175
+ lossy?: boolean;
5141
5176
 
5142
5177
  };
5143
5178
 
@@ -5451,6 +5486,10 @@ declare type SDKHookCallbackMatcher = {
5451
5486
  */
5452
5487
  hookCallbackIds: string[];
5453
5488
  timeout?: number;
5489
+ /**
5490
+ * What a failure of these callbacks does: the client answered the hook_callback request with an error, or with an answer that fails validation. 'continue' (default): the failure is reported and the action goes ahead. 'block': the failure counts as a block, as it does for a command hook, so the action the event guards (a tool call, a permission request, a prompt) is blocked. Ignored on Stop, SubagentStop, TaskCompleted and TeammateIdle.
5491
+ */
5492
+ onFailure?: 'continue' | 'block';
5454
5493
  };
5455
5494
 
5456
5495
  /**
@@ -5527,6 +5566,7 @@ export declare type SDKInformationalMessage = {
5527
5566
  */
5528
5567
  tag?: string;
5529
5568
 
5569
+
5530
5570
  uuid: UUID;
5531
5571
  session_id: string;
5532
5572
  };
@@ -5601,7 +5641,7 @@ export declare type SDKMemoryRecallMessage = {
5601
5641
  /**
5602
5642
  * Every conversational and informational message the CLI emits on its output stream, discriminated by type (and subtype for system/result messages). Consumers should ignore types and subtypes they do not recognize: the set grows over time.
5603
5643
  */
5604
- export declare type SDKMessage = SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKAPIRetryMessage | SDKControlRequestProgressMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskUpdatedMessage | SDKTaskProgressMessage | SDKBackgroundTasksChangedMessage | SDKThinkingTokensMessage | SDKSessionStateChangedMessage | SDKWorkerShuttingDownMessage | SDKCommandsChangedMessage | SDKNotificationMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKMemoryRecallMessage | SDKRateLimitEvent | SDKElicitationCompleteMessage | SDKPermissionDeniedMessage | SDKPromptSuggestionMessage | SDKMirrorErrorMessage | SDKInformationalMessage | SDKConversationResetMessage;
5644
+ export declare type SDKMessage = SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKAPIRetryMessage | SDKControlRequestProgressMessage | SDKModelRefusalFallbackMessage | SDKModelRefusalNoFallbackMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskUpdatedMessage | SDKTaskProgressMessage | SDKBackgroundTasksChangedMessage | SDKThinkingTokensMessage | SDKSessionStateChangedMessage | SDKWorkerShuttingDownMessage | SDKCommandsChangedMessage | SDKNotificationMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKMemoryRecallMessage | SDKRateLimitEvent | SDKElicitationCompleteMessage | SDKPermissionDeniedMessage | SDKPromptSuggestionMessage | SDKMirrorErrorMessage | SDKInformationalMessage | SDKConversationResetMessage | SDKSessionWritesLostMessage;
5605
5645
 
5606
5646
  /**
5607
5647
  * Provenance of a user-role message (peer session, team lead, channel). A host wrapping keyboard input must stamp {kind:'human'} explicitly — absent origin is treated as unattributed and fails closed at strict isHuman() trust gates.
@@ -5632,7 +5672,7 @@ export declare type SDKMessageOrigin = {
5632
5672
  */
5633
5673
  senderTaskId?: string;
5634
5674
  /**
5635
- * Decoded message body with the peer envelope stripped — byte-exact with what the model sees. Present only when the turn is exactly one harness-formed envelope (or an in-process agent message); render this instead of re-parsing the message text.
5675
+ * Decoded message body with the peer envelope stripped — byte-exact with what the model sees. Present only when the turn is exactly one harness-formed envelope (or an in-process agent message), or when Claude Desktop declares it and the message text holds those exact bytes; render this instead of re-parsing the message text.
5636
5676
  */
5637
5677
  body?: string;
5638
5678
  /**
@@ -5714,6 +5754,7 @@ export declare type SDKModelRefusalFallbackMessage = {
5714
5754
  * stop_details.explanation from the refused API response (client lane only — the server-lane trigger carries no explanation). Unstable human prose — display only, never parse. null/absent when the response carried none, and always null on server-lane banners.
5715
5755
  */
5716
5756
  api_refusal_explanation?: string | null;
5757
+
5717
5758
  /**
5718
5759
  * Wire uuids of the messages this fallback retracted — the refused partial as the consumer received it (one uuid per normalized SDK message; multi-block messages carry per-block derived uuids) plus any tombstoned tool_results. Emitted AFTER the retraction, so this is a resolution-time eviction signal: remove these messages from transcript state on receipt. Eviction is idempotent — unknown or already-removed uuids are a no-op. Absent when emitted by an older CLI.
5719
5760
  */
@@ -5986,7 +6027,7 @@ export declare type SDKResultError = {
5986
6027
  errors: string[];
5987
6028
 
5988
6029
  /**
5989
- * Set on the zeroed error_during_execution result a stream-json run writes before exiting on a known startup failure; errors carries the failure message. Failures that otherwise end with stderr alone write that result only when the host sets CLAUDE_CODE_STARTUP_FAILURE_RESULTS. Absent on every other result, on startup failures without a known cause, and from older producers.
6030
+ * Set on the zeroed error_during_execution result a stream-json run writes before exiting on a known startup failure; errors carries the failure message. Failures that otherwise end with stderr alone write that result only when the host sets CLAUDE_CODE_STARTUP_FAILURE_RESULTS, except org_config_required_unavailable, org_config_refused and config_file_invalid, which every stream-json run writes. Absent on every other result, on startup failures without a known cause, and from older producers.
5990
6031
  */
5991
6032
  startup_failure_reason?: SDKStartupFailureReason;
5992
6033
  /**
@@ -6010,6 +6051,10 @@ export declare type SDKResultError = {
6010
6051
  * 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.
6011
6052
  */
6012
6053
  result_index?: number;
6054
+ /**
6055
+ * When the claude.ai credential this process's requests send ends for good, as an ISO 8601 instant, read as the result is written. For a stored claude.ai login it is the end of the login's refresh chain as stored at sign-in, which renewing the access token does not move. That date is the server's when it sent one and otherwise a 30-day estimate, and the real end can be up to 3 days earlier. The server is not asked, so a login revoked early still shows its date, and a date in the past means the login has probably ended, not that it has. Absent when no date is known, for every other credential (an API key, a token from the environment, another provider), on results this process did not number, and from older producers.
6056
+ */
6057
+ credential_expires_at?: string;
6013
6058
  fast_mode_state?: FastModeState;
6014
6059
  fast_mode_disabled_reason?: FastModeDisabledReason;
6015
6060
  origin?: SDKMessageOrigin;
@@ -6051,6 +6096,10 @@ export declare type SDKResultSuccess = {
6051
6096
 
6052
6097
 
6053
6098
 
6099
+
6100
+
6101
+
6102
+
6054
6103
 
6055
6104
 
6056
6105
 
@@ -6125,6 +6174,10 @@ export declare type SDKResultSuccess = {
6125
6174
  * 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.
6126
6175
  */
6127
6176
  result_index?: number;
6177
+ /**
6178
+ * When the claude.ai credential this process's requests send ends for good, as an ISO 8601 instant, read as the result is written. For a stored claude.ai login it is the end of the login's refresh chain as stored at sign-in, which renewing the access token does not move. That date is the server's when it sent one and otherwise a 30-day estimate, and the real end can be up to 3 days earlier. The server is not asked, so a login revoked early still shows its date, and a date in the past means the login has probably ended, not that it has. Absent when no date is known, for every other credential (an API key, a token from the environment, another provider), on results this process did not number, and from older producers.
6179
+ */
6180
+ credential_expires_at?: string;
6128
6181
  fast_mode_state?: FastModeState;
6129
6182
  fast_mode_disabled_reason?: FastModeDisabledReason;
6130
6183
  origin?: SDKMessageOrigin;
@@ -6189,6 +6242,28 @@ export declare type SDKSessionStateChangedMessage = {
6189
6242
  session_id: string;
6190
6243
  };
6191
6244
 
6245
+ /**
6246
+ * The CLI could not save lines of a session transcript, changes to ~/.claude.json, or both, because the disk was full or its quota was used up. Sent at most once, as the CLI exits, after the last result if there was one. The results already received stand, and this message does not change the exit status. As on every message, session_id is the session the CLI is in; transcript_session_ids says whose transcript lost lines. Sent only with stream-json output on stdout, never under --sdk-url or a Claude Desktop entrypoint. Safe to ignore.
6247
+ */
6248
+ export declare type SDKSessionWritesLostMessage = {
6249
+ type: 'system';
6250
+ subtype: 'session_writes_lost';
6251
+ /**
6252
+ * Why the writes failed. 'ENOSPC': the disk was full. 'EDQUOT': the disk quota was used up. When both kinds of write were lost for different reasons, the transcript's. More codes may be added.
6253
+ */
6254
+ error_code: 'ENOSPC' | 'EDQUOT';
6255
+ /**
6256
+ * What was not saved. 'transcript': lines of a session transcript, so resuming a session in transcript_session_ids may miss part of its conversation. 'global_config': changes this run made to ~/.claude.json. Never empty. More values may be added.
6257
+ */
6258
+ lost: ('transcript' | 'global_config')[];
6259
+ /**
6260
+ * The sessions whose transcripts lost lines, in the order each first lost one. Present only when 'transcript' is listed; never empty. Usually session_id alone. A CLI that started a new session after the loss, as /clear does, lists the earlier session, and lists session_id only if that session lost lines too.
6261
+ */
6262
+ transcript_session_ids?: string[];
6263
+ uuid: UUID;
6264
+ session_id: string;
6265
+ };
6266
+
6192
6267
  /**
6193
6268
  * A settings file parse or validation error. When a settings.json file fails to parse (invalid JSON, JSON comments, schema mismatch), the file is skipped and any rules it contained — including permission allow/deny lists — are not applied.
6194
6269
  */
@@ -6208,9 +6283,9 @@ export declare type SDKSettingsParseError = {
6208
6283
  };
6209
6284
 
6210
6285
  /**
6211
- * Why Claude Code refused to start, so a host can offer the fix instead of a retry. org_pin_api_key_conflict: managed settings pin a first-party or Cloud gateway sign-in, and an Anthropic API key or auth token is configured instead. provider_not_allowed: managed settings list the API providers this machine may use (allowedProviders), and the session is set up for one that is not listed. org_verify_failed: the sign-in's organization could not be verified against the pin (network, or a revoked token). org_pin_mismatch: the sign-in belongs to an organization the pin does not allow. managed_settings_invalid: managed policy settings could not be read, the pin names no organization, or managed model settings (deniedModels, or an availableModels list matched exactly) block the default model and leave no allowed model to use instead. remote_settings_required_unavailable: managed settings the organization requires could not be loaded. gateway_signin_required: the Cloud gateway ended this sign-in. gateway_access_denied: the Cloud gateway refused managed settings for this account. proxy_invalid: a proxy setting is not a complete URL. temp_dir_unusable: the per-user temp directory is unsafe or could not be created. cwd_unavailable: the working directory was deleted, moved or cannot be read. shell_tool_missing: Windows has no shell tool: Git Bash is missing, and PowerShell is missing or turned off by CLAUDE_CODE_USE_POWERSHELL_TOOL. session_held_by_background: the conversation to resume or continue is running as a background session. worktree_resume_refused: the resume was refused because the session's worktree failed its safety checks or the resume was launched from inside it; errors says whether a re-run continues without the worktree. worktree_unverified: the session's worktree could not be verified right now; retrying may succeed. cli_version_too_old: this Claude Code version is below the minimum Anthropic requires. bypass_root: bypass permissions mode was requested while running as root. org_config_required_unavailable: the organization requires its policy limits and managed settings before a session starts, and they could not be loaded (network, proxy, or an Anthropic error); retrying may succeed. org_config_refused: the organization requires its policy limits and managed settings, and Anthropic refused them for this sign-in (expired or revoked session, or the organization does not allow Claude Code for this account); signing in again or an admin's change is the fix, not a retry. sandbox_required_unavailable: a working sandbox is required and it cannot run in this session, for example because bubblewrap is missing or the platform is not supported; make the sandbox available or have the requirement changed.
6286
+ * Why Claude Code refused to start, so a host can offer the fix instead of a retry. org_pin_api_key_conflict: managed settings pin a first-party or Cloud gateway sign-in, and an Anthropic API key or auth token is configured instead. provider_not_allowed: managed settings list the API providers this machine may use (allowedProviders), and the session is set up for one that is not listed. org_verify_failed: the sign-in's organization could not be verified against the pin (network, or a revoked token). org_pin_mismatch: the sign-in belongs to an organization the pin does not allow. managed_settings_invalid: managed policy settings could not be read, the pin names no organization, or managed model settings (deniedModels, or an availableModels list matched exactly) block the default model and leave no allowed model to use instead. remote_settings_required_unavailable: managed settings the organization requires could not be loaded. gateway_signin_required: the Cloud gateway ended this sign-in. gateway_access_denied: the Cloud gateway refused managed settings for this account. proxy_invalid: a proxy setting is not a complete URL. temp_dir_unusable: the per-user temp directory is unsafe or could not be created. cwd_unavailable: the working directory was deleted, moved or cannot be read. shell_tool_missing: Windows has no shell tool: Git Bash is missing, and PowerShell is missing or turned off by CLAUDE_CODE_USE_POWERSHELL_TOOL. session_held_by_background: the conversation to resume or continue is running as a background session. worktree_resume_refused: the resume was refused because the session's worktree failed its safety checks or the resume was launched from inside it; errors says whether a re-run continues without the worktree. worktree_unverified: the session's worktree could not be verified right now; retrying may succeed. cli_version_too_old: this Claude Code version is below the minimum Anthropic requires. bypass_root: bypass permissions mode was requested while running as root. org_config_required_unavailable: the organization requires its policy limits and managed settings before a session starts, and they could not be loaded (network, proxy, or an Anthropic error); retrying may succeed. org_config_refused: the organization requires its policy limits and managed settings, and Anthropic refused them for this sign-in (expired or revoked session, or the organization does not allow Claude Code for this account); signing in again or an admin's change is the fix, not a retry. sandbox_required_unavailable: a working sandbox is required and it cannot run in this session, for example because bubblewrap is missing or the platform is not supported; make the sandbox available or have the requirement changed. initialize_not_first: Claude Code was started with --await-initialize, and its first stdin line was not the initialize control request (another message, or not valid JSON). Either the host wrote something else first, or a wrapper script between the host and Claude Code read or changed that line; the fix is in the host or the wrapper script, not a retry. config_file_invalid: a configuration file read at start-up is not valid JSON; errors names the file and, for the global configuration file, how to restore or repair it. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help.
6212
6287
  */
6213
- export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | 'provider_not_allowed' | 'org_verify_failed' | 'org_pin_mismatch' | 'managed_settings_invalid' | 'remote_settings_required_unavailable' | 'gateway_signin_required' | 'gateway_access_denied' | 'proxy_invalid' | 'temp_dir_unusable' | 'cwd_unavailable' | 'shell_tool_missing' | 'session_held_by_background' | 'worktree_resume_refused' | 'worktree_unverified' | 'cli_version_too_old' | 'bypass_root' | 'org_config_required_unavailable' | 'org_config_refused' | 'sandbox_required_unavailable';
6288
+ export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | 'provider_not_allowed' | 'org_verify_failed' | 'org_pin_mismatch' | 'managed_settings_invalid' | 'remote_settings_required_unavailable' | 'gateway_signin_required' | 'gateway_access_denied' | 'proxy_invalid' | 'temp_dir_unusable' | 'cwd_unavailable' | 'shell_tool_missing' | 'session_held_by_background' | 'worktree_resume_refused' | 'worktree_unverified' | 'cli_version_too_old' | 'bypass_root' | 'org_config_required_unavailable' | 'org_config_refused' | 'sandbox_required_unavailable' | 'initialize_not_first' | 'config_file_invalid';
6214
6289
 
6215
6290
  export declare type SDKStatus = 'compacting' | 'requesting' | null;
6216
6291
 
@@ -6296,6 +6371,7 @@ export declare type SDKSystemMessage = {
6296
6371
  effort?: ('low' | 'medium' | 'high' | 'xhigh' | 'max') | null;
6297
6372
 
6298
6373
 
6374
+
6299
6375
  /**
6300
6376
  * Whether the session's transcript is in focus view ('focus': the model is told the user sees only its final message per turn, so clients may collapse each turn to the prompt and the final response; 'default' otherwise). Toggled by /focus, including over Remote Control. Present on Remote Control bridge init frames and on the per-turn init of headless stream-json runs (`claude rc` workers, -p, the SDK's subprocess transport); absent on hosts that do not publish it (the in-process engine) and on CLIs that predate the field. Re-emitted inits carry the current value — the newest frame wins.
6301
6377
  */
@@ -6315,6 +6391,9 @@ export declare type SDKSystemMessage = {
6315
6391
 
6316
6392
 
6317
6393
 
6394
+
6395
+
6396
+
6318
6397
  uuid: UUID;
6319
6398
  session_id: string;
6320
6399
  };
@@ -6612,6 +6691,8 @@ export declare type SDKUserMessage = {
6612
6691
 
6613
6692
 
6614
6693
 
6694
+
6695
+
6615
6696
 
6616
6697
 
6617
6698
 
@@ -6645,6 +6726,7 @@ export declare type SDKUserMessage = {
6645
6726
 
6646
6727
 
6647
6728
 
6729
+
6648
6730
  uuid?: UUID;
6649
6731
  /**
6650
6732
  * 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.
@@ -6654,6 +6736,7 @@ export declare type SDKUserMessage = {
6654
6736
  * 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.
6655
6737
  */
6656
6738
  inline_pastes?: string[];
6739
+
6657
6740
  session_id?: string;
6658
6741
  /**
6659
6742
  * 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.
@@ -6668,6 +6751,7 @@ export declare type SDKUserMessage = {
6668
6751
  */
6669
6752
  task_description?: string;
6670
6753
 
6754
+
6671
6755
  };
6672
6756
 
6673
6757
  export declare type SDKUserMessageReplay = {
@@ -6709,6 +6793,8 @@ export declare type SDKUserMessageReplay = {
6709
6793
 
6710
6794
 
6711
6795
 
6796
+
6797
+
6712
6798
 
6713
6799
 
6714
6800
 
@@ -6742,6 +6828,7 @@ export declare type SDKUserMessageReplay = {
6742
6828
 
6743
6829
 
6744
6830
 
6831
+
6745
6832
  uuid: UUID;
6746
6833
  session_id: string;
6747
6834
  isReplay: true;
@@ -7090,11 +7177,11 @@ export declare interface Settings {
7090
7177
 
7091
7178
 
7092
7179
  /**
7093
- * Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely.
7180
+ * Number of days to retain chat transcripts before automatic cleanup (default: 30). Minimum 1. Use a large value for long retention; use --no-session-persistence to disable transcript writes entirely. Cleanup deletes data only on this computer, not anything stored by Anthropic.
7094
7181
  */
7095
7182
  cleanupPeriodDays?: number;
7096
7183
  /**
7097
- * Retention ceiling in days for session transcripts created or last written by a desktop-host surface (Claude Desktop, Cowork), which are otherwise exempt from the cleanupPeriodDays sweep. 0 (the default) means no ceiling: such transcripts are kept until deleted another way. Unlike cleanupPeriodDays, 0 is allowed because this setting never disables writes — it only bounds an exemption from deletion. The ceiling is a hard cap: it also bounds an active archive grace, so the grace window of a release marker never keeps files past the ceiling. Ignored when cleanupPeriodDays is managed by org policy. A ceiling at or below cleanupPeriodDays effectively disables the exemption: those transcripts age out on the regular cleanupPeriodDays schedule, so the effective retention is whichever of the two periods is longer.
7184
+ * Retention ceiling in days for session transcripts created or last written by a desktop-host surface (Claude Desktop, Cowork), which are otherwise exempt from the cleanupPeriodDays sweep. 0 (the default) means no ceiling: such transcripts are kept until deleted another way. Unlike cleanupPeriodDays, 0 is allowed because this setting never disables writes — it only bounds an exemption from deletion. The ceiling is a hard cap: it also bounds an active archive grace, so the grace window of a release marker never keeps files past the ceiling. Ignored when cleanupPeriodDays is managed by org policy. A ceiling at or below cleanupPeriodDays effectively disables the exemption: those transcripts age out on the regular cleanupPeriodDays schedule, so the effective retention is whichever of the two periods is longer. Cleanup deletes data only on this computer, not anything stored by Anthropic.
7098
7185
  */
7099
7186
  desktopSessionCleanupPeriodDays?: number;
7100
7187
  /**
@@ -7142,7 +7229,7 @@ export declare interface Settings {
7142
7229
  [k: string]: unknown;
7143
7230
  };
7144
7231
  /**
7145
- * 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.
7232
+ * The claude.ai Project this session names for your organization's usage reports: the Project's ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project. 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.
7146
7233
  */
7147
7234
  attributionProject?: string;
7148
7235
  /**
@@ -7150,7 +7237,7 @@ export declare interface Settings {
7150
7237
  */
7151
7238
  attributionProjectPolicy?: {
7152
7239
  /**
7153
- * The Project used when neither CLAUDE_CODE_ATTRIBUTION_PROJECT nor attributionProject names one: its UUID, or its ID starting with "claude_proj_".
7240
+ * The Project used when neither CLAUDE_CODE_ATTRIBUTION_PROJECT nor attributionProject names one: its ID, starting with "claude_proj_" or "chan_", or the UUID of a "claude_proj_" Project.
7154
7241
  */
7155
7242
  default?: string;
7156
7243
  };
@@ -7198,6 +7285,10 @@ export declare interface Settings {
7198
7285
  * For the program that starts Claude Code: read only from --settings and from settings that program sends while the session runs; ignored in user, project, local and managed settings. Absolute paths, each a folder with all below it or one file, that blockReadsOutsideWorkingDirectories lets through beside the working directories. It allows nothing: an allow rule, the permission mode or the user still decides each read, as with that setting off, and a shell command that hands such a path to a program is still asked about unless a Read allow rule covers it. The paths do not become working directories, so blockWritesOutsideWorkingDirectories refuses writes to them, and they are not told to MCP servers or to the model. Each path counts as written: a link in it is not followed and a pattern is not expanded, so list every spelling that a read may arrive by. Ignored: an entry that starts with ~, has a ".." segment or has white space at either end (as written or once normalized), a relative or network path, and the root of a filesystem. Does not change what sandboxed commands may read (sandbox.filesystem.allowRead does).
7199
7286
  */
7200
7287
  blockReadsExemptPaths?: string[];
7288
+ /**
7289
+ * For the program that starts Claude Code: read only from --settings and from settings that program sends while the session runs; ignored in user, project, local and managed settings. Absolute paths of working directories, each spelled exactly as it is passed, letter case included (the session folder, --add-dir, permissions.additionalDirectories). To decide what lies inside a listed working directory, Claude Code takes it as written and follows no link at it, so a link that later stands in its place gives the file tools no access to where the link leads. List real paths: the files of a listed path that runs through a link count as outside the working directories, because where they really are lies outside it. List a mapped network drive by its drive-letter path: Claude Code still derives the UNC form of that path by itself and adds it, as for any mapped drive. A file path that is itself spelled as a UNC path is judged as written, so a link on the share is not seen by that spelling. It adds no working directory and allows nothing. Once listed, a path stays so until the process ends, also if later settings leave it out. Ignored: an entry that is not already normalized (a relative path, one that starts with ~, a ".." segment, a separator at its end unless it is a filesystem root, forward slashes on Windows, white space at either end). Does not change what sandboxed commands may write.
7290
+ */
7291
+ workingDirectoriesAsGiven?: string[];
7201
7292
  /**
7202
7293
  * Disable auto mode
7203
7294
  */
@@ -7583,6 +7674,10 @@ export declare interface Settings {
7583
7674
  * Disable all hooks and statusLine execution: the hooks defined in settings files and by installed plugins. Features built into Claude Code are not hooks in this sense and keep working; each has its own switch.
7584
7675
  */
7585
7676
  disableAllHooks?: boolean;
7677
+ /**
7678
+ * Disable the reply check in Claude Tag sessions on a self-hosted runner. The check re-prompts Claude, at most four times a turn, when a turn ends without a call to one of Claude Tag's reply tools. It is not a hook, so disableAllHooks does not affect it. Disabling it also stops two messages to Claude that Anthropic's service can request for such a session: a nudge after a long stretch of work with no visible update, and a reminder added to prompts. Claude Code's built-in reminder to give progress updates, on models that have it, is then no longer held back. Set it in managed settings; false there keeps the check on. Everywhere else it is ignored and the check stays on. Has no effect on sessions that Anthropic hosts.
7679
+ */
7680
+ disableReplyCheck?: boolean;
7586
7681
  /**
7587
7682
  * Disable agent view (`claude agents`, `--bg`, /background, the on-demand daemon). Typically set in managed settings. Equivalent to CLAUDE_CODE_DISABLE_AGENT_VIEW=1.
7588
7683
  */
@@ -8978,7 +9073,7 @@ export declare interface Settings {
8978
9073
  */
8979
9074
  disableSideloadFlags?: boolean;
8980
9075
  /**
8981
- * Marketplace names whose plugins may surface as contextual install suggestions (relevance-based tips). No marketplace-declared suggestions surface without this allowlist; the built-in first-party frontend-design tip is unaffected. Only honored when set in managed settings (policy scope); the key is ignored in user, project, and local settings. A name only takes effect when the marketplace is registered on the machine AND its registered source is also declared in managed settings, either as the extraKnownMarketplaces entry for that name or as an entry of strictKnownMarketplaces. A marketplace registered from a different source under an allowlisted name is ignored. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source.
9076
+ * Marketplace names whose plugins may surface as contextual install suggestions (relevance-based tips). No marketplace-declared suggestions surface without this allowlist; the built-in tips for Anthropic's own plugins are unaffected. Only honored when set in managed settings (policy scope); the key is ignored in user, project, and local settings. A name only takes effect when the marketplace is registered on the machine AND its registered source is also declared in managed settings, either as the extraKnownMarketplaces entry for that name or as an entry of strictKnownMarketplaces. A marketplace registered from a different source under an allowlisted name is ignored. The official marketplace is exempt from the source requirement: allowlisting its name alone suffices, since that name can only register from the official Anthropic source.
8982
9077
  */
8983
9078
  pluginSuggestionMarketplaces?: string[];
8984
9079
  /**
@@ -10253,7 +10348,7 @@ export declare interface Transport {
10253
10348
  /**
10254
10349
  * Await the underlying subprocess's exit. Only meaningful for
10255
10350
  * subprocess-backed transports (ProcessTransport); WebSocket / SSE /
10256
- * in-process transports leave this undefined. Query.performCleanup()
10351
+ * Bun Worker transports leave this undefined. Query.performCleanup()
10257
10352
  * awaits it (bounded) so .return() / asyncDispose don't resolve while
10258
10353
  * the child is still draining the stdin EOF that close() just sent.
10259
10354
  */