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

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
@@ -134,6 +134,19 @@ export declare type AnyZodRawShape = ZodRawShape | ZodRawShape_2;
134
134
  */
135
135
  export declare type ApiKeySource = 'ANTHROPIC_API_KEY' | 'apiKeyHelper' | '/login managed key' | 'none' | 'user' | 'project' | 'org' | 'temporary' | 'oauth';
136
136
 
137
+ /**
138
+ * Archive a session. It stays on disk, and `listSessions` still returns it,
139
+ * with `archived: true`. A prompt sent in the session later unarchives it.
140
+ * Does not change the transcript or stop a process that runs the session.
141
+ *
142
+ * Throws if the session is not found, or if `sessionStore` is passed: the mark
143
+ * is kept in a file beside the local transcript, which a store does not hold.
144
+ *
145
+ * @param sessionId - UUID of the session
146
+ * @param options - `{ dir?: string }` project path; omit to search all projects
147
+ */
148
+ export declare function archiveSession(_sessionId: string, _options?: SessionMutationOptions): Promise<void>;
149
+
137
150
  export declare type AsyncHookJSONOutput = {
138
151
  async: true;
139
152
  asyncTimeout?: number;
@@ -3101,6 +3114,12 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3101
3114
  * main-thread agent, and `ultracode` to off with the current effort kept.
3102
3115
  * Only available in streaming input mode.
3103
3116
  *
3117
+ * Rejects if a value would make Claude Code discard the flag settings layer:
3118
+ * nothing in that call applies, including its valid keys, and settings from
3119
+ * earlier calls stay in force. Catch the rejection. A value Claude Code ignores
3120
+ * on its own does not reject, and its key still replaces the earlier value: a
3121
+ * `permissions` object whose only deny rule is malformed leaves no deny rules.
3122
+ *
3104
3123
  * `ultracode: true` or `false` turns ultracode on or off and leaves the
3105
3124
  * effort level alone. An `effortLevel` that moves the session to a
3106
3125
  * different level, sent without an `ultracode` key, also turns ultracode
@@ -3260,12 +3279,24 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
3260
3279
  * been in the `plugins` option at launch; plugins already loaded stay. Each
3261
3280
  * path must be absolute.
3262
3281
  *
3282
+ * With `refuseIfBusy`, a request that finds the session busy reloads nothing:
3283
+ * the promise rejects with an error whose `errorCode` is
3284
+ * 'reload_plugins_busy', and the caller asks again once the session is idle.
3285
+ * Busy: a turn is running or queued, a permission prompt taken over from an
3286
+ * earlier process is unanswered, or background work such as an agent or a
3287
+ * workflow, or an in-process teammate, is still at work; a background shell
3288
+ * command alone is not busy.
3289
+ * For a host whose request can arrive late. Only a CLI whose `system/init`
3290
+ * lists the capability `reload_plugins_refuse_if_busy_v1` is sure to honor
3291
+ * the option: any other may serve the request, in a turn too.
3292
+ *
3263
3293
  * @returns The refreshed session components after plugin reload, or the
3264
3294
  * unchanged ones with `held: true` when the reload was held
3265
3295
  */
3266
3296
  reloadPlugins(options?: {
3267
3297
  holdOnCacheImpact?: boolean;
3268
3298
  addPlugins?: SdkPluginConfig[];
3299
+ refuseIfBusy?: boolean;
3269
3300
  }): Promise<SDKControlReloadPluginsResponse>;
3270
3301
  /**
3271
3302
  * Reload skills from disk and return the refreshed skill list.
@@ -3904,6 +3935,7 @@ export declare type SDKAssistantMessage = {
3904
3935
 
3905
3936
 
3906
3937
 
3938
+
3907
3939
 
3908
3940
  };
3909
3941
 
@@ -5000,7 +5032,7 @@ declare type SDKControlListModelsRequest = {
5000
5032
  };
5001
5033
 
5002
5034
  /**
5003
- * Requests the session's live permission rules and workspace directories — the same data /permissions lists in the terminal: rules from settings files plus session-only approvals, slash-command grants, and --allowedTools flag rules, each with its source.
5035
+ * Requests the session's live permission rules and workspace directories — the same data /permissions lists in the terminal: rules from settings files plus session-only approvals, slash-command grants, and --allowedTools flag rules, each with its source. A connection that stores its answers cuts these: see `withheld` on the state.
5004
5036
  */
5005
5037
  declare type SDKControlListPermissionRulesRequest = {
5006
5038
  subtype: 'list_permission_rules';
@@ -5011,7 +5043,7 @@ declare type SDKControlListPermissionRulesRequest = {
5011
5043
  */
5012
5044
  export declare type SDKControlListPermissionRulesResponse = {
5013
5045
  /**
5014
- * The session's live permission rules state, as list_permission_rules reports it.
5046
+ * The session's live permission rules state, as list_permission_rules reports it. Cut when `withheld` is true.
5015
5047
  */
5016
5048
  state: SDKControlPermissionRulesState;
5017
5049
  };
@@ -5043,7 +5075,7 @@ declare type SDKControlMcpCallRequest = {
5043
5075
  */
5044
5076
  result_not_for_model?: boolean;
5045
5077
  /**
5046
- * The call is someone else's (a page a host renders), so it is decided as the model's own call to this tool is: permission rules under every spelling, the permission mode, requiresUserInteraction, managed settings, and PreToolUse and PostToolUse hooks, which see the arguments and the result. An ask reaches the host as a can_use_tool control request; where no host can answer, and in dontAsk or plan mode, it is refused. A refused call never reaches the server: on a plain call the error subtype, on a staged call staging error_code=tool_error, each with text starting 'The tool did not run: '. The other refusals of mcp_call come first and keep their own words. A PostToolUse hook's rewrite replaces content and drops structuredContent and _meta. The result stays out of the model's context. Only a CLI that says mcp_call_check_permissions_v1 honours this member: an older one ignores it and runs the tool with no check. Honoured only on the pipes of the host that spawned the process; elsewhere the call is refused. A value that is not a boolean is refused.
5078
+ * The call is someone else's (a page a host renders), so it is decided as the model's own call to this tool is, except that a slash command's allowed-tools and connector card answers never allow it, even during a turn: permission rules under every spelling, the permission mode, requiresUserInteraction, managed settings, and PreToolUse and PostToolUse hooks, which see the arguments and the result. An ask reaches the host as a can_use_tool control request; where no host can answer, and in dontAsk or plan mode, it is refused. A refused call never reaches the server: on a plain call the error subtype, on a staged call staging error_code=tool_error, each with text starting 'The tool did not run: '. The other refusals of mcp_call come first and keep their own words. A PostToolUse hook's rewrite replaces content and drops structuredContent and _meta. The result stays out of the model's context. Only a CLI that says mcp_call_check_permissions_v1 honours this member: an older one ignores it and runs the tool with no check. Honoured only on the pipes of the host that spawned the process; elsewhere the call is refused. A value that is not a boolean is refused.
5047
5079
  */
5048
5080
  check_permissions?: boolean;
5049
5081
  /**
@@ -5223,7 +5255,7 @@ declare type SDKControlPermissionRequest = {
5223
5255
  };
5224
5256
 
5225
5257
  /**
5226
- * The session's live permission rules state, as list_permission_rules reports it.
5258
+ * The session's live permission rules state, as list_permission_rules reports it. Cut when `withheld` is true.
5227
5259
  */
5228
5260
  export declare type SDKControlPermissionRulesState = {
5229
5261
  rules: SDKPermissionRuleEntry[];
@@ -5241,6 +5273,10 @@ export declare type SDKControlPermissionRulesState = {
5241
5273
  * 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.
5242
5274
  */
5243
5275
  errors?: coreTypes.SDKSettingsParseError[];
5276
+ /**
5277
+ * True when this answer was cut because the connection stores its answers (a cloud or self-hosted session): `rules` holds only rows from settings sources and `mcpServerPolicy`, `workspaceDirectories` only folders from settings sources, each entry of `errors` only a fixed `message` and an empty `path`, and `parentSettingsIncluded` is absent. Where session folders are withheld, `workspaceDirectories` is empty, `originalCwd` is an empty string, and each rule other than a bare tool name the session can send loses its `description` and goes as `Tool(withheld)`, or as `(withheld)` where its tool name cannot be sent. An `ask` or `deny` rule of that last kind goes as `*(withheld)`, so a client that matches rules by tool name treats it as covering every tool. Absent from an answer that was not cut.
5278
+ */
5279
+ withheld?: boolean;
5244
5280
  };
5245
5281
 
5246
5282
  /**
@@ -5322,6 +5358,10 @@ declare type SDKControlReloadPluginsRequest = {
5322
5358
  * Plugins for the reload to load as well, in the same shape as the SDK `plugins` option: each entry joins the session as one more --plugin-dir would (--plugin-dir-no-mcp when skipMcpDiscovery is set). Plugins already loaded stay; nothing is removed. A held or failed reload adds none of them. Refused for a malformed list or a path that is not absolute, when managed settings set disableSideloadFlags, on a connection whose frames persist server-side (any Remote Control or cloud worker), in a cloud-hosted session, and when a running sandbox cannot keep shell commands out of the folders (always on Windows).
5323
5359
  */
5324
5360
  add_plugins?: coreTypes.SdkPluginConfig[];
5361
+ /**
5362
+ * When true, a request that finds the session busy reloads nothing and gets an error whose error_code is reload_plugins_busy; ask again once the session is idle. Busy: a turn is running or still ending, a message is queued for one, a permission prompt taken over from an earlier process is unanswered, background work that keeps the session at running (an agent, a workflow and the like) is live, or an in-process teammate is at work; a session that only waits for a background shell command is not busy. For a host whose request can arrive late, such as one that reaches the session over SSH: a reload changes the commands, agents, hooks and servers under a running turn, agent or teammate. Default false: the request is served in a turn too. Only `claude -p` reads it, and says so in system/init.capabilities (reload_plugins_refuse_if_busy_v1) to a host on its pipes; a CLI that does not say so may ignore the field.
5363
+ */
5364
+ refuse_if_busy?: boolean;
5325
5365
  };
5326
5366
 
5327
5367
  /**
@@ -5687,6 +5727,7 @@ export declare type SDKInformationalMessage = {
5687
5727
  tag?: string;
5688
5728
 
5689
5729
 
5730
+
5690
5731
  uuid: UUID;
5691
5732
  session_id: string;
5692
5733
  };
@@ -6005,7 +6046,7 @@ export declare type SDKPermissionRuleEntry = {
6005
6046
  */
6006
6047
  source: 'userSettings' | 'projectSettings' | 'localSettings' | 'flagSettings' | 'policySettings' | 'cliArg' | 'command' | 'session' | 'mcpMount' | 'toolsNarrowing' | 'mcpServerPolicy' | 'hostCredential';
6007
6048
  /**
6008
- * The stored rule string VERBATIM, exactly as the session holds it. Two stored spellings that parse identically each get their own entry. Can carry invisible or control characters by design — escape at display.
6049
+ * The stored rule string VERBATIM, exactly as the session holds it; where the state's `withheld` is true, the text may be cut. Two stored spellings that parse identically each get their own entry. Can carry invisible or control characters by design — escape at display.
6009
6050
  */
6010
6051
  rule: string;
6011
6052
  /**
@@ -6152,6 +6193,27 @@ export declare type SDKResultError = {
6152
6193
  * 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.
6153
6194
  */
6154
6195
  startup_failure_reason?: SDKStartupFailureReason;
6196
+ /**
6197
+ * Set when startup_failure_reason is config_file_invalid: the config file that did not parse and its backup, as separate fields. Read paths from here, never from the text of errors. Each path is in the form that the machine running Claude Code uses, which can differ from the host's. Absent on every other result and from older producers.
6198
+ */
6199
+ invalid_config_file?: {
6200
+ /**
6201
+ * The file that is not valid JSON.
6202
+ */
6203
+ path: string;
6204
+ /**
6205
+ * Whether this is Claude Code's global config file. Only that file has backups, and only its message says how to repair it.
6206
+ */
6207
+ is_global: boolean;
6208
+ /**
6209
+ * Whether Claude Code knows the result of its search for a backup of the file. True with no backup_path: it found none. False: the result is not known, or this is not the global config file.
6210
+ */
6211
+ backup_searched: boolean;
6212
+ /**
6213
+ * The backup that the message in errors names. Usually it parses and shows use. Where the search finds none that does, it is the newest that it found with an account, then the newest that holds anything, or at last the newest that does not parse or could not be read, which a person may be able to mend. So show it to a person, or check that it parses before you copy it over the file at path.
6214
+ */
6215
+ backup_path?: string;
6216
+ };
6155
6217
  /**
6156
6218
  * Client uuid of the user message that triggered this turn (submitMessage options.uuid), echoed back so a consumer can link this error result to the send it answers — the same join key the success variant echoes, carried alone (error turns have no request_sent_wall_ms to report). A delivery-failure result from the remote-session client echoes the failed send's queue key, which is client-minted when the host sent no uuid of its own. A synthetic/scheduled (meta) turn's own uuid is echoed only when the host vouches it is the client event's own (delivered content such as a Slack owner ping or a Slack-bot observation); a meta turn that folded queued user messages in mid-turn, vouched or not, echoes the LAST of them. Absent on turns that neither had a client uuid nor folded a user message in, on session-scoped failures with no single triggering send (a crashed worker's zeroed result), and from older producers.
6157
6219
  */
@@ -6274,6 +6336,7 @@ export declare type SDKResultSuccess = {
6274
6336
 
6275
6337
 
6276
6338
 
6339
+
6277
6340
  num_turns: number;
6278
6341
  result: string;
6279
6342
  stop_reason: string | null;
@@ -6302,6 +6365,7 @@ export declare type SDKResultSuccess = {
6302
6365
  terminal_reason?: TerminalReason;
6303
6366
 
6304
6367
 
6368
+
6305
6369
  /**
6306
6370
  * 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.
6307
6371
  */
@@ -6361,6 +6425,10 @@ export declare type SDKSessionInfo = {
6361
6425
  * Creation time in integer milliseconds since epoch, extracted from the first entry's timestamp.
6362
6426
  */
6363
6427
  createdAt?: number;
6428
+ /**
6429
+ * Whether the session is archived: false if it was and has been unarchived, or a prompt was sent in it since. Absent if it never was, and with a sessionStore.
6430
+ */
6431
+ archived?: boolean;
6364
6432
  };
6365
6433
 
6366
6434
  /**
@@ -6415,7 +6483,7 @@ export declare type SDKSettingsParseError = {
6415
6483
  };
6416
6484
 
6417
6485
  /**
6418
- * Why Claude Code refused to start, so a host can offer the fix instead of a retry. org_pin_api_key_conflict: managed settings pin a first-party or Cloud gateway sign-in, and an Anthropic API key or auth token is configured instead. provider_not_allowed: managed settings list the API providers this machine may use (allowedProviders), and the session is set up for one that is not listed. org_verify_failed: the sign-in's organization could not be verified against the pin (network, or a revoked token). org_pin_mismatch: the sign-in belongs to an organization the pin does not allow. managed_settings_invalid: managed policy settings could not be read, the pin names no organization, or managed model settings (deniedModels, or an availableModels list matched exactly) block the default model and leave no allowed model to use instead. remote_settings_required_unavailable: managed settings the organization requires could not be loaded. gateway_signin_required: the Cloud gateway ended this sign-in. gateway_access_denied: the Cloud gateway refused managed settings for this account. proxy_invalid: a proxy setting is not a complete URL. temp_dir_unusable: the per-user temp directory is unsafe or could not be created. cwd_unavailable: the working directory was deleted, moved or cannot be read. shell_tool_missing: Windows has no shell tool: Git Bash is missing, and PowerShell is missing or turned off by CLAUDE_CODE_USE_POWERSHELL_TOOL. session_held_by_background: the conversation to resume or continue is running as a background session. worktree_resume_refused: the resume was refused because the session's worktree failed its safety checks or the resume was launched from inside it; errors says whether a re-run continues without the worktree. worktree_unverified: the session's worktree could not be verified right now; retrying may succeed. cli_version_too_old: this Claude Code version is below the minimum Anthropic requires. bypass_root: bypass permissions mode was requested while running as root. org_config_required_unavailable: the organization requires its policy limits and managed settings before a session starts, and they could not be loaded (network, proxy, or an Anthropic error); retrying may succeed. org_config_refused: the organization requires its policy limits and managed settings, and Anthropic refused them for this sign-in (expired or revoked session, or the organization does not allow Claude Code for this account); signing in again or an admin's change is the fix, not a retry. sandbox_required_unavailable: a working sandbox is required and it cannot run in this session, for example because bubblewrap is missing or the platform is not supported; make the sandbox available or have the requirement changed. initialize_not_first: Claude Code was started with --await-initialize, and its first stdin line was not the initialize control request (another message, or not valid JSON). Either the host wrote something else first, or a wrapper script between the host and Claude Code read or changed that line; the fix is in the host or the wrapper script, not a retry. config_file_invalid: a configuration file read at start-up is not valid JSON; errors names the file and, for the global configuration file, how to restore or repair it. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help. managed_settings_not_delivered: Claude Code was started with --managed-settings-in-initialize and could not use the managed settings in the initialize control request. Stdin ended or failed first, or its first line was too long; the request has no managedSettings object, that object could not be used, or the request's plugins field is malformed; or the launch does not read that request at start-up or also passes --managed-settings. errors says which. Claude Code starts no session without them; the fix is in the host or in a wrapper script between it and Claude Code, not a retry.
6486
+ * 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, and invalid_config_file has the paths as fields. The file is left unchanged, and every start without a terminal is refused until it is repaired, so a retry alone does not help. managed_settings_not_delivered: Claude Code was started with --managed-settings-in-initialize and could not use the managed settings in the initialize control request. Stdin ended or failed first, or its first line was too long; the request has no managedSettings object, that object could not be used, or the request's plugins field is malformed; or the launch does not read that request at start-up or also passes --managed-settings. errors says which. Claude Code starts no session without them; the fix is in the host or in a wrapper script between it and Claude Code, not a retry.
6419
6487
  */
6420
6488
  export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | 'provider_not_allowed' | 'org_verify_failed' | 'org_pin_mismatch' | 'managed_settings_invalid' | 'remote_settings_required_unavailable' | 'gateway_signin_required' | 'gateway_access_denied' | 'proxy_invalid' | 'temp_dir_unusable' | 'cwd_unavailable' | 'shell_tool_missing' | 'session_held_by_background' | 'worktree_resume_refused' | 'worktree_unverified' | 'cli_version_too_old' | 'bypass_root' | 'org_config_required_unavailable' | 'org_config_refused' | 'sandbox_required_unavailable' | 'initialize_not_first' | 'config_file_invalid' | 'managed_settings_not_delivered';
6421
6489
 
@@ -6492,6 +6560,14 @@ export declare type SDKSystemMessage = {
6492
6560
  * Present only when a --plugin-dir, SDK `plugins` or synced directory entry did not load at all: the path of that entry, resolved against the cwd (for a directory, the value its `plugins[]` row would have carried; for a .zip, the archive; a --plugin-url entry carries none). `plugin` is then the positional `inline[N]` / `synced[N]` tag, so a host that mounts several directories pairs the error to its own by this path.
6493
6561
  */
6494
6562
  path?: string;
6563
+ /**
6564
+ * Present only when a managed-settings `enabledPlugins` entry dropped this --plugin-dir, SDK `plugins`, skills-directory or synced copy: the two halves of that entry, `name` and `marketplace`, and its value. `plugin_enabled` true: the entry turns that plugin on, and Claude Code does not accept this copy as that plugin. `plugin_enabled` false: the entry turns it off, and no directory copy of the name may load. Neither stops an install of the same name from another marketplace, which can load beside this row. `name` and `marketplace` are byte-exact, like `plugin`: control and bidi characters are not removed and the length is not bounded, so clean and bound them before showing them. `name` is as the entry spells it, which can differ from the copy (case, Unicode form, an earlier name of a built-in). `marketplace` is absent where the entry names no marketplace that an install could come from.
6565
+ */
6566
+ managed_lock?: {
6567
+ plugin_enabled: boolean;
6568
+ name: string;
6569
+ marketplace?: string;
6570
+ };
6495
6571
  }[];
6496
6572
 
6497
6573
 
@@ -6510,7 +6586,7 @@ export declare type SDKSystemMessage = {
6510
6586
  */
6511
6587
  view_mode?: 'focus' | 'default';
6512
6588
  /**
6513
- * Protocol capabilities this CLI supports, so SDK consumers can feature-detect instead of version-sniffing. Open set — ignore unknown values; check each capability for exactly the behavior you use. 'interrupt_receipt_v1' = the interrupt control_response success payload carries still_queued (uuids of async user messages that survive the interrupt). 'interrupt_cancel_queued_v1' = the interrupt control_request honors cancel_queued:true (queued and pending-dispatch commands are cancelled alongside the abort, listed on the response's cancelled field; still_queued is then empty — including any uuid that was mid-fold at the interrupt instant, since this request also aborts and the fold never delivers it — except that a client driving a hosted session lists there what it can no longer recall: a send already in flight to that session, or the first prompt the session was created with). 'queued_notifications' = the CLI accepts inbound queued_notification stream messages and drains them via ReadNotifications (the cloud session backend reads this from the persisted init event to decide whether it may send them). 'ask_user_question_unanswered_v1' = an AskUserQuestion answer may set annotations[question].unanswered ('skipped' | 'replied_in_chat' | 'dismissed'), which the tool result echoes; send it only to a session that advertises this, since an older CLI on a strict host refuses the whole answer. A strict host also refuses an answer with a value outside these three; a new value will come with a new capability. Absent on older CLIs.
6589
+ * Protocol capabilities this CLI supports, so SDK consumers can feature-detect instead of version-sniffing. Open set — ignore unknown values; check each capability for exactly the behavior you use. 'interrupt_receipt_v1' = the interrupt control_response success payload carries still_queued (uuids of async user messages that survive the interrupt). 'interrupt_cancel_queued_v1' = the interrupt control_request honors cancel_queued:true (queued and pending-dispatch commands are cancelled alongside the abort, listed on the response's cancelled field; still_queued is then empty — including any uuid that was mid-fold at the interrupt instant, since this request also aborts and the fold never delivers it — except that a client driving a hosted session lists there what it can no longer recall: a send already in flight to that session, or the first prompt the session was created with). 'queued_notifications' = the CLI accepts inbound queued_notification stream messages and drains them via ReadNotifications (the cloud session backend reads this from the persisted init event to decide whether it may send them). 'ask_user_question_unanswered_v1' = an AskUserQuestion answer may set annotations[question].unanswered ('skipped' | 'replied_in_chat' | 'dismissed'), which the tool result echoes; send it only to a session that advertises this, since an older CLI on a strict host refuses the whole answer. A strict host also refuses an answer with a value outside these three; a new value will come with a new capability. 'reload_plugins_refuse_if_busy_v1' = the reload_plugins control request honors refuse_if_busy; a CLI that does not advertise this may ignore the field and serve the request in a turn too. Absent on older CLIs.
6514
6590
  */
6515
6591
  capabilities?: string[];
6516
6592
 
@@ -7050,7 +7126,7 @@ export declare type SessionMessage = {
7050
7126
 
7051
7127
  /**
7052
7128
  * Options shared by session mutation functions (renameSession, tagSession,
7053
- * deleteSession, forkSession).
7129
+ * archiveSession, unarchiveSession, deleteSession, forkSession).
7054
7130
  */
7055
7131
  export declare type SessionMutationOptions = {
7056
7132
  /**
@@ -7060,7 +7136,7 @@ export declare type SessionMutationOptions = {
7060
7136
  dir?: string;
7061
7137
  /**
7062
7138
  * When provided, read/write session data via this store instead of the
7063
- * local filesystem.
7139
+ * local filesystem. archiveSession and unarchiveSession reject it.
7064
7140
  * @alpha
7065
7141
  */
7066
7142
  sessionStore?: SessionStore;
@@ -7531,7 +7607,7 @@ export declare interface Settings {
7531
7607
  */
7532
7608
  disabledMcpjsonServers?: string[];
7533
7609
  /**
7534
- * When true in any settings source, claude.ai MCP cloud connectors are not auto-fetched or connected, and a claudeai-proxy server passed explicitly (e.g. via --mcp-config or the SDK mcpServers option) does not connect either. Any-source-true wins: a project can opt out, but a project-level false cannot override a user-level true.
7610
+ * When true in any settings source, claude.ai MCP cloud connectors are not auto-fetched or connected, and a claudeai-proxy server passed explicitly (e.g. via --mcp-config or the SDK mcpServers option) does not connect either. Where a managed or served source sets it, the connectors that the desktop app's Code tab hands to a session do not connect either, from the app version that shows them as turned off. Any-source-true wins: a project can opt out, but a project-level false cannot override a user-level true.
7535
7611
  */
7536
7612
  disableClaudeAiConnectors?: boolean;
7537
7613
  /**
@@ -7979,7 +8055,7 @@ export declare interface Settings {
7979
8055
  };
7980
8056
  };
7981
8057
  /**
7982
- * Managed plugins (plugin\@marketplace ids that managed enabledPlugins sets true) whose hooks run first, outermost, in the listed order: the first id listed sees every event before any other plugin and every result after it. Managed plugins not listed here or in appendPlugins follow the listed ones; user, project and marketplace plugins come after those; then appendPlugins; then the built-in plugins. The bundled cc-plugin-sec-default\@builtin seats itself outermost (on a machine with managed settings and for Team and Enterprise organizations) unless this list is set, in which case list it where it should sit or leave it out. Name it there as sec-default\@builtin, the id every release reads, for as long as any machine in the organization may run a release from before its rename; a release that knows the new id reads either. Any other id that is not an enabled managed plugin is skipped; an id listed in both keys is prepended. Only honored from managed settings (or, on a machine with none, from user settings for your own plugins); ignored in project, local and --settings sources.
8058
+ * Managed plugins (plugin\@marketplace ids that managed enabledPlugins sets true) whose hooks run first, outermost, in the listed order: the first id listed sees every event before any other plugin and every result after it. Managed plugins read in place from a local folder managed settings name, and not listed here or in appendPlugins, follow the listed ones; user, project and marketplace plugins come after those, with a managed plugin from a remote marketplace that neither key lists; then appendPlugins; then the built-in plugins. The bundled cc-plugin-sec-default\@builtin seats itself outermost (on a machine with managed settings and for Team and Enterprise organizations) unless this list is set, in which case list it where it should sit or leave it out. Name it there as sec-default\@builtin, the id every release reads, for as long as any machine in the organization may run a release from before its rename; a release that knows the new id reads either. Any other id that is not an enabled managed plugin is skipped; an id listed in both keys is prepended. Only honored from managed settings (or, on a machine with none, from user settings for your own plugins); ignored in project, local and --settings sources.
7983
8059
  */
7984
8060
  prependPlugins?: string[];
7985
8061
  /**
@@ -8017,7 +8093,7 @@ export declare interface Settings {
8017
8093
  */
8018
8094
  repo: string;
8019
8095
  /**
8020
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8096
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8021
8097
  */
8022
8098
  ref?: string;
8023
8099
  /**
@@ -8039,7 +8115,7 @@ export declare interface Settings {
8039
8115
  */
8040
8116
  url: string;
8041
8117
  /**
8042
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8118
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8043
8119
  */
8044
8120
  ref?: string;
8045
8121
  /**
@@ -8243,7 +8319,7 @@ export declare interface Settings {
8243
8319
  */
8244
8320
  autoUpdate?: boolean;
8245
8321
  /**
8246
- * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link, .claude-directory-proof.json and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8322
+ * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it, declare its marketplace with a remote source and list it in prependPlugins or appendPlugins.
8247
8323
  */
8248
8324
  pluginDigests?: {
8249
8325
  [k: string]: string[];
@@ -8281,7 +8357,7 @@ export declare interface Settings {
8281
8357
  */
8282
8358
  repo: string;
8283
8359
  /**
8284
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8360
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8285
8361
  */
8286
8362
  ref?: string;
8287
8363
  /**
@@ -8303,7 +8379,7 @@ export declare interface Settings {
8303
8379
  */
8304
8380
  url: string;
8305
8381
  /**
8306
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8382
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8307
8383
  */
8308
8384
  ref?: string;
8309
8385
  /**
@@ -8507,7 +8583,7 @@ export declare interface Settings {
8507
8583
  */
8508
8584
  autoUpdate?: boolean;
8509
8585
  /**
8510
- * Managed settings only: the plugins of this marketplace that an organization delivers with its own tier, by plugin name, each with the digests of its releases. A plugin also enabled and listed in prependPlugins or appendPlugins by managed settings the session vouches for loads its hooks module only from a folder that proves one of them, and is then seated in that tier; any other copy does not load. A digest is sha256- and the base64 SHA-256 of, for every regular file in the folder in UTF-16 code unit order of its path, not normalized, "f PATH" NUL BYTE-LENGTH NUL BYTES, with / in paths; .git, .in_use, .orphaned_at, .claude-plugin-link, .claude-directory-proof.json and .links_materialized at the root are left out. The plugin keeps its manifest at .claude-plugin/plugin.json and names one module in hooks/hooks.json. A string of any other form, or a list that is empty or of any other shape, matches no folder. A symbolic link, or a surface module, proves nothing. A proved plugin ships bundled with no install step: the digest covers the whole folder, node_modules included. A checkout whose line endings were converted proves nothing.
8586
+ * Deprecated and ignored: settings that hold it still load. A plugin takes the organization tier when managed settings enable it, declare its marketplace with a remote source and list it in prependPlugins or appendPlugins.
8511
8587
  */
8512
8588
  pluginDigests?: {
8513
8589
  [k: string]: string[];
@@ -8540,7 +8616,7 @@ export declare interface Settings {
8540
8616
  */
8541
8617
  repo: string;
8542
8618
  /**
8543
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8619
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8544
8620
  */
8545
8621
  ref?: string;
8546
8622
  /**
@@ -8562,7 +8638,7 @@ export declare interface Settings {
8562
8638
  */
8563
8639
  url: string;
8564
8640
  /**
8565
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8641
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8566
8642
  */
8567
8643
  ref?: string;
8568
8644
  /**
@@ -8783,7 +8859,7 @@ export declare interface Settings {
8783
8859
  */
8784
8860
  repo: string;
8785
8861
  /**
8786
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8862
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8787
8863
  */
8788
8864
  ref?: string;
8789
8865
  /**
@@ -8805,7 +8881,7 @@ export declare interface Settings {
8805
8881
  */
8806
8882
  url: string;
8807
8883
  /**
8808
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
8884
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
8809
8885
  */
8810
8886
  ref?: string;
8811
8887
  /**
@@ -9001,7 +9077,7 @@ export declare interface Settings {
9001
9077
  };
9002
9078
  })[];
9003
9079
  /**
9004
- * 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.
9080
+ * 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, and an entry naming a branch or tag in `ref` also blocks every full commit id in that repository. The check happens BEFORE downloading, so blocked sources never touch the filesystem.
9005
9081
  */
9006
9082
  blockedMarketplaces?: ({
9007
9083
  source: 'url';
@@ -9026,7 +9102,7 @@ export declare interface Settings {
9026
9102
  */
9027
9103
  repo: string;
9028
9104
  /**
9029
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
9105
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
9030
9106
  */
9031
9107
  ref?: string;
9032
9108
  /**
@@ -9048,7 +9124,7 @@ export declare interface Settings {
9048
9124
  */
9049
9125
  url: string;
9050
9126
  /**
9051
- * Git branch or tag to use (e.g., "main", "v1.0.0"). Defaults to repository default branch.
9127
+ * Git branch, tag or full commit id to use (e.g., "main", "v1.0.0"). Defaults to repository default branch. A full commit id (40 or 64 lowercase hex digits) holds the marketplace at that commit: refreshes and auto-updates do not move it. A branch or tag of the repository must hold the commit. Plugins listed with a remote source follow that source unless they name a `sha`. Reserved Anthropic marketplace names do not accept a commit id.
9052
9128
  */
9053
9129
  ref?: string;
9054
9130
  /**
@@ -9313,9 +9389,12 @@ export declare interface Settings {
9313
9389
  */
9314
9390
  enabled?: boolean;
9315
9391
  /**
9316
- * Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed-settings deployments that require sandboxing as a hard gate. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, and managed, --settings or user settings set true, false from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (true there still applies).
9392
+ * Exit with an error at startup if sandbox.enabled is true but the sandbox cannot start (missing dependencies or unsupported platform). When false (default), a warning is shown and commands run unsandboxed. Intended for managed-settings deployments that require sandboxing as a hard gate. A Claude Code on the web, scheduled-task or Cowork cloud session (Anthropic's cloud container, which has no command sandbox) starts anyway with a warning: the container isolates it, and the sandbox.filesystem and sandbox.network rules in settings are not enforced there. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, and managed, --settings or user settings set true, false from project settings (.claude/settings.json and .claude/settings.local.json) is ignored (true there still applies).
9317
9393
  */
9318
9394
  failIfUnavailable?: boolean;
9395
+ /**
9396
+ * macOS and Linux/WSL only: approve a Bash command that will run inside the sandbox without a permission prompt, unless a deny rule, a command-specific ask rule or a safety check stops it. Default: false, so sandboxed commands go through the same permission flow as any other command. Has no effect on native Windows.
9397
+ */
9319
9398
  autoAllowBashIfSandboxed?: boolean;
9320
9399
  /**
9321
9400
  * Allow commands to run outside the sandbox via the dangerouslyDisableSandbox parameter. When false, the dangerouslyDisableSandbox parameter is completely ignored and all commands must run sandboxed. Default: true. A false in managed, --settings or user settings holds whatever project settings (.claude/settings.json and .claude/settings.local.json) say (false there still applies).
@@ -9392,7 +9471,7 @@ export declare interface Settings {
9392
9471
  */
9393
9472
  allowManagedReadPathsOnly?: boolean;
9394
9473
  /**
9395
- * macOS and Linux/WSL only: skip filesystem isolation entirely while keeping network and seccomp isolation. Ignored on native Windows, where the sandboxed process runs as a separate user with no inherent rights, so skipping the filesystem rules would withhold every access grant rather than loosen them — filesystem isolation stays on there. Sandboxed commands get unrestricted read/write access to the host filesystem; network egress is still confined to network.allowedDomains. Intended for deployments whose goal is egress control rather than filesystem containment. Does not change Bash prompting: sandbox.autoAllowBashIfSandboxed is independent and still defaults to true, so set it to false to keep prompting for sandboxed commands. Drops the read protection from filesystem.denyRead and credentials.files deny entries for sandboxed commands, since both are enforced by the filesystem layer this turns off; credentials.files mask entries (sentinel binds) and credentials.envVars deny/mask are unaffected. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored. If managed settings configure sandbox.filesystem at all, or list any sandbox.credentials.files deny entry, only managed settings can set this: an admin who deployed filesystem restrictions must not have them switched off by a user-writable file. (sandbox.credentials.envVars and credentials.files mask entries do not pin it — env scrubbing and sentinel binds are independent of the filesystem layer and survive this setting.) When unset, filesystem isolation stays on.
9474
+ * macOS and Linux/WSL only: skip filesystem isolation entirely while keeping network and seccomp isolation. Ignored on native Windows, where the sandboxed process runs as a separate user with no inherent rights, so skipping the filesystem rules would withhold every access grant rather than loosen them — filesystem isolation stays on there. Sandboxed commands get unrestricted read/write access to the host filesystem; network egress is still confined to network.allowedDomains. Intended for deployments whose goal is egress control rather than filesystem containment. Does not change Bash prompting: sandbox.autoAllowBashIfSandboxed is independent and still defaults to false, so sandboxed commands keep going through the permission flow unless it is set to true. Drops the read protection from filesystem.denyRead and credentials.files deny entries for sandboxed commands, since both are enforced by the filesystem layer this turns off; credentials.files mask entries (sentinel binds) and credentials.envVars deny/mask are unaffected. Only honored from user, managed/policy, or CLI (`--settings`) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored. If managed settings configure sandbox.filesystem at all, or list any sandbox.credentials.files deny entry, only managed settings can set this: an admin who deployed filesystem restrictions must not have them switched off by a user-writable file. (sandbox.credentials.envVars and credentials.files mask entries do not pin it — env scrubbing and sentinel binds are independent of the filesystem layer and survive this setting.) When unset, filesystem isolation stays on.
9396
9475
  */
9397
9476
  disabled?: boolean;
9398
9477
  };
@@ -10543,6 +10622,18 @@ export declare interface Transport {
10543
10622
  [Symbol.dispose]?(): void;
10544
10623
  }
10545
10624
 
10625
+ /**
10626
+ * Unarchive a session, so that `listSessions` returns it with
10627
+ * `archived: false`.
10628
+ *
10629
+ * Throws if the session is not found, or if `sessionStore` is passed (see
10630
+ * {@link archiveSession}).
10631
+ *
10632
+ * @param sessionId - UUID of the session
10633
+ * @param options - `{ dir?: string }` project path; omit to search all projects
10634
+ */
10635
+ export declare function unarchiveSession(_sessionId: string, _options?: SessionMutationOptions): Promise<void>;
10636
+
10546
10637
  /**
10547
10638
  * Messages meaning "a usage limit was genuinely reached" — the error-path
10548
10639
  * outputs of getLimitReachedText (rateLimitMessages.ts) and