@anthropic-ai/claude-agent-sdk 0.3.322 → 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/README.md +1 -1
- package/bridge.mjs +104 -84
- package/browser-sdk.js +78 -67
- package/core-4tdxk2rb.mjs +16 -0
- package/core-7sc5aw3j.mjs +17 -0
- package/core-de9edyhn.mjs +19 -0
- package/core-dtdat34e.mjs +45 -0
- package/core-hjrk2537.mjs +16 -0
- package/core-mjr5v0tc.mjs +17 -0
- package/core-nbx2rjdx.mjs +18 -0
- package/core-qe0dk8na.mjs +16 -0
- package/core-qkncpzfw.mjs +42 -0
- package/core-s4as5f4b.mjs +18 -0
- package/core-ttsjec9g.mjs +17 -0
- package/core.d.ts +3 -0
- package/core.mjs +11 -11
- package/manifest.json +22 -22
- package/manifest.zst.json +26 -26
- package/package.json +21 -14
- package/sdk-tools.d.ts +182 -12
- package/sdk.d.ts +298 -73
- package/sdk.mjs +96 -85
- package/core-8zdh6hy9.mjs +0 -45
- package/core-b5da77cd.mjs +0 -34
- package/core-f2yzhw4m.mjs +0 -18
- package/core-j29a9c1a.mjs +0 -17
package/sdk.d.ts
CHANGED
|
@@ -98,7 +98,7 @@ export declare type AgentDefinition = {
|
|
|
98
98
|
*/
|
|
99
99
|
permissionMode?: PermissionMode;
|
|
100
100
|
/**
|
|
101
|
-
* Agent type auto-spawned as a background observer whenever this agent runs.
|
|
101
|
+
* Agent type auto-spawned as a background observer whenever this agent runs, or a comma-separated list of up to four, none of whose names has a comma. An observer receives read-only activity digests and reports via the ObserverReport tool; it never participates in the task.
|
|
102
102
|
*/
|
|
103
103
|
observer?: string;
|
|
104
104
|
/**
|
|
@@ -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;
|
|
@@ -710,6 +723,18 @@ export declare type CwdChangedHookSpecificOutput = {
|
|
|
710
723
|
*/
|
|
711
724
|
export declare function deleteSession(_sessionId: string, _options?: SessionMutationOptions): Promise<void>;
|
|
712
725
|
|
|
726
|
+
/**
|
|
727
|
+
* What {@link matchDeniedModels} answers.
|
|
728
|
+
*
|
|
729
|
+
* @alpha
|
|
730
|
+
*/
|
|
731
|
+
export declare type DeniedModelsMatch = {
|
|
732
|
+
/** For each model asked about, in order: whether an entry blocks it. */
|
|
733
|
+
denied: boolean[];
|
|
734
|
+
/** The CLI's notes on entries: why one was ignored, or what one blocks where that may surprise. And a note on what was asked about but is no model name. */
|
|
735
|
+
warnings: string[];
|
|
736
|
+
};
|
|
737
|
+
|
|
713
738
|
export declare type DirectoryAddedHookInput = BaseHookInput & {
|
|
714
739
|
hook_event_name: 'DirectoryAdded';
|
|
715
740
|
/**
|
|
@@ -884,7 +909,13 @@ export declare type ForkSessionOptions = SessionMutationOptions & {
|
|
|
884
909
|
* Slice transcript up to the message whose `uuid` field equals this value
|
|
885
910
|
* (inclusive). If omitted, full copy. Obtain the value from
|
|
886
911
|
* {@link SessionMessage.uuid} via `getSessionMessages()`, or from the
|
|
887
|
-
* `uuid` you supplied on a streamed {@link SDKUserMessage}.
|
|
912
|
+
* `uuid` you supplied on a streamed {@link SDKUserMessage}. With a compaction
|
|
913
|
+
* summary's id, the fork leaves out the messages kept after that summary.
|
|
914
|
+
* With the id of a `compact_boundary` message that a compaction wrote, or of a
|
|
915
|
+
* queued prompt or other non-message entry stored between that boundary and
|
|
916
|
+
* its summary, the fork ends before the boundary, and has no messages if none
|
|
917
|
+
* came before it. With the id of a boundary written by rewinding behind a
|
|
918
|
+
* compaction, the fork keeps that boundary and the messages it kept.
|
|
888
919
|
*/
|
|
889
920
|
upToMessageId?: string;
|
|
890
921
|
/** Custom title for the fork. If omitted, derives from original title + " (fork)". */
|
|
@@ -1224,6 +1255,22 @@ export declare type ListSubagentsOptions = {
|
|
|
1224
1255
|
sessionStore?: SessionStore;
|
|
1225
1256
|
};
|
|
1226
1257
|
|
|
1258
|
+
/**
|
|
1259
|
+
* Say which of `models` a managed `deniedModels` list blocks, without spawning
|
|
1260
|
+
* the Claude CLI. Pass `effective.deniedModels` from {@link resolveSettings}.
|
|
1261
|
+
* Nothing throws: a bad list or entry is ignored, a bad model is `false`, and
|
|
1262
|
+
* `models` that isn't a list gets an empty `denied`; `warnings` notes each.
|
|
1263
|
+
*
|
|
1264
|
+
* @remarks
|
|
1265
|
+
* **Not the CLI's enforcement: grant nothing by it.** It compares model IDs
|
|
1266
|
+
* with entries alone. `true` means that this version's CLI refuses the model
|
|
1267
|
+
* too; `false` promises nothing: the CLI also judges what an alias or a custom
|
|
1268
|
+
* name stands for, a model's other names, path tails and `modelOverrides`.
|
|
1269
|
+
*
|
|
1270
|
+
* @alpha
|
|
1271
|
+
*/
|
|
1272
|
+
export declare function matchDeniedModels(_models: readonly string[], _deniedModels: readonly string[] | undefined): Promise<DeniedModelsMatch>;
|
|
1273
|
+
|
|
1227
1274
|
export declare type McpClaudeAIProxyServerConfig = {
|
|
1228
1275
|
type: 'claudeai-proxy';
|
|
1229
1276
|
url: string;
|
|
@@ -1262,6 +1309,7 @@ export declare type McpSdkServerConfig = {
|
|
|
1262
1309
|
|
|
1263
1310
|
|
|
1264
1311
|
|
|
1312
|
+
|
|
1265
1313
|
/**
|
|
1266
1314
|
* Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
|
|
1267
1315
|
*/
|
|
@@ -2158,7 +2206,7 @@ export declare type Options = {
|
|
|
2158
2206
|
* true, the subagent's conversation is forked every ~30s to produce a short
|
|
2159
2207
|
* present-tense description (e.g. "Analyzing authentication module"), emitted
|
|
2160
2208
|
* on `task_progress` events via the `summary` field. The fork reuses the
|
|
2161
|
-
* subagent's model and prompt cache
|
|
2209
|
+
* subagent's model and prompt cache.
|
|
2162
2210
|
*
|
|
2163
2211
|
* Summaries are not a heartbeat. None is made while the conversation is
|
|
2164
2212
|
* unchanged. A summary can also be delayed by up to 5 minutes while the
|
|
@@ -2167,6 +2215,8 @@ export declare type Options = {
|
|
|
2167
2215
|
* finishes first, that summary is not sent.
|
|
2168
2216
|
*
|
|
2169
2217
|
* Applies to both foreground and background subagents. Defaults to false.
|
|
2218
|
+
* The `CLAUDE_CODE_DISABLE_AGENT_PROGRESS_SUMMARIES=1` env var turns
|
|
2219
|
+
* summaries off even when this option is true.
|
|
2170
2220
|
*/
|
|
2171
2221
|
agentProgressSummaries?: boolean;
|
|
2172
2222
|
|
|
@@ -2256,6 +2306,10 @@ export declare type Options = {
|
|
|
2256
2306
|
* error result and exits rather than silently running commands unsandboxed.
|
|
2257
2307
|
* Set `failIfUnavailable: false` to allow graceful degradation.
|
|
2258
2308
|
*
|
|
2309
|
+
* **Invalid settings:** one value that fails validation rejects all of
|
|
2310
|
+
* `settings`, this option included. With `enabled: true`, `query()` then emits
|
|
2311
|
+
* the same error result and exits, unless `failIfUnavailable` is `false`.
|
|
2312
|
+
*
|
|
2259
2313
|
* **With `settings`:** when `settings` is given inline (an object or JSON string,
|
|
2260
2314
|
* not a file path) and has its own `sandbox` block, this option is merged into
|
|
2261
2315
|
* it. A value this option sets replaces the value at the same path, and a
|
|
@@ -2354,6 +2408,7 @@ export declare type Options = {
|
|
|
2354
2408
|
* ```
|
|
2355
2409
|
*/
|
|
2356
2410
|
managedSettings?: Settings;
|
|
2411
|
+
|
|
2357
2412
|
/**
|
|
2358
2413
|
* Control which filesystem settings to load.
|
|
2359
2414
|
* - `'user'` - Global user settings (`~/.claude/settings.json`)
|
|
@@ -2604,6 +2659,8 @@ export declare type PermissionRequestHookInput = BaseHookInput & {
|
|
|
2604
2659
|
tool_input: unknown;
|
|
2605
2660
|
permission_suggestions?: PermissionUpdate[];
|
|
2606
2661
|
mcp_server?: McpServerProvenance;
|
|
2662
|
+
|
|
2663
|
+
|
|
2607
2664
|
};
|
|
2608
2665
|
|
|
2609
2666
|
export declare type PermissionRequestHookSpecificOutput = {
|
|
@@ -3057,6 +3114,12 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
3057
3114
|
* main-thread agent, and `ultracode` to off with the current effort kept.
|
|
3058
3115
|
* Only available in streaming input mode.
|
|
3059
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
|
+
*
|
|
3060
3123
|
* `ultracode: true` or `false` turns ultracode on or off and leaves the
|
|
3061
3124
|
* effort level alone. An `effortLevel` that moves the session to a
|
|
3062
3125
|
* different level, sent without an `ultracode` key, also turns ultracode
|
|
@@ -3119,6 +3182,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
3119
3182
|
* @returns A fresh initialization response
|
|
3120
3183
|
*/
|
|
3121
3184
|
reinitialize(): Promise<SDKControlInitializeResponse>;
|
|
3185
|
+
|
|
3122
3186
|
/**
|
|
3123
3187
|
* Get the list of available skills for the current session.
|
|
3124
3188
|
*
|
|
@@ -3215,12 +3279,24 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
3215
3279
|
* been in the `plugins` option at launch; plugins already loaded stay. Each
|
|
3216
3280
|
* path must be absolute.
|
|
3217
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
|
+
*
|
|
3218
3293
|
* @returns The refreshed session components after plugin reload, or the
|
|
3219
3294
|
* unchanged ones with `held: true` when the reload was held
|
|
3220
3295
|
*/
|
|
3221
3296
|
reloadPlugins(options?: {
|
|
3222
3297
|
holdOnCacheImpact?: boolean;
|
|
3223
3298
|
addPlugins?: SdkPluginConfig[];
|
|
3299
|
+
refuseIfBusy?: boolean;
|
|
3224
3300
|
}): Promise<SDKControlReloadPluginsResponse>;
|
|
3225
3301
|
/**
|
|
3226
3302
|
* Reload skills from disk and return the refreshed skill list.
|
|
@@ -3311,28 +3387,33 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
3311
3387
|
|
|
3312
3388
|
/**
|
|
3313
3389
|
* Dynamically set the MCP servers for this session.
|
|
3314
|
-
* This replaces the
|
|
3315
|
-
*
|
|
3390
|
+
* This replaces the servers added by earlier calls to this method, and all
|
|
3391
|
+
* in-process SDK servers (including any passed in the `mcpServers` option),
|
|
3392
|
+
* with the provided set. Servers that are removed will be disconnected, and
|
|
3393
|
+
* new servers will be connected.
|
|
3316
3394
|
*
|
|
3317
3395
|
* Supports both process-based servers (stdio, sse, http) and SDK servers (in-process).
|
|
3318
3396
|
* SDK servers are handled locally in the SDK process, while process-based servers
|
|
3319
3397
|
* are managed by the CLI subprocess.
|
|
3320
3398
|
*
|
|
3321
|
-
* Note:
|
|
3399
|
+
* Note: Outside a cloud session, a call that leaves out a stdio, sse or http
|
|
3400
|
+
* server passed in the `mcpServers` option does not disconnect it or list it
|
|
3401
|
+
* in the result's `removed` list, unless an earlier call to this method named
|
|
3402
|
+
* that server. To be able to remove a server later, add it with this method
|
|
3403
|
+
* instead of in `mcpServers`.
|
|
3404
|
+
*
|
|
3322
3405
|
* Servers configured via settings files are not affected. A `.mcp.json` or
|
|
3323
3406
|
* local-scope server of the session's current folder stays up when omitted,
|
|
3324
|
-
* unless enterprise policy denies it; once a
|
|
3325
|
-
*
|
|
3326
|
-
*
|
|
3327
|
-
*
|
|
3328
|
-
*
|
|
3329
|
-
*
|
|
3330
|
-
*
|
|
3331
|
-
*
|
|
3332
|
-
*
|
|
3333
|
-
*
|
|
3334
|
-
*
|
|
3335
|
-
* @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).
|
|
3407
|
+
* unless enterprise policy denies it; once a call has named such a server, a
|
|
3408
|
+
* later call that omits it removes it. Servers introduced by plugins are also
|
|
3409
|
+
* exempt: they are managed by the plugin system, so omitting them from a call
|
|
3410
|
+
* does NOT remove them — they keep running (unless enterprise policy denies
|
|
3411
|
+
* the server) and are simply absent from the result's `removed` list. Naming a
|
|
3412
|
+
* plugin server explicitly in a call still replaces it. Because of these
|
|
3413
|
+
* exceptions, `setMcpServers({})` does not guarantee that a session has no MCP
|
|
3414
|
+
* servers left.
|
|
3415
|
+
*
|
|
3416
|
+
* @param servers - Record of server name to configuration. Pass an empty object to remove the servers this method replaces.
|
|
3336
3417
|
* @returns Information about which servers were added, removed, and any connection errors
|
|
3337
3418
|
*/
|
|
3338
3419
|
setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
|
|
@@ -3406,6 +3487,33 @@ export declare type ResolvedSettings = {
|
|
|
3406
3487
|
path?: string;
|
|
3407
3488
|
policyOrigin?: PolicySettingsOrigin;
|
|
3408
3489
|
}>;
|
|
3490
|
+
/**
|
|
3491
|
+
* What became of this machine's own policy sources, in the host's own read
|
|
3492
|
+
* (not a Claude Code session's). `effective`, `provenance` and `sources` show
|
|
3493
|
+
* a source that was not read as absent, so a host that enforces managed
|
|
3494
|
+
* settings reads this first. An SDK that predates the member leaves it out,
|
|
3495
|
+
* which says nothing either way.
|
|
3496
|
+
*/
|
|
3497
|
+
machinePolicy?: {
|
|
3498
|
+
/**
|
|
3499
|
+
* `false`, or the kinds of source that may be there and did not load:
|
|
3500
|
+
* `'profile'` (a macOS MDM profile), `'registry'` (the Windows HKLM policy
|
|
3501
|
+
* value; under WSL also the Windows folder's managed-settings files while
|
|
3502
|
+
* WSL does not inherit them), `'file'` (the managed-settings file or a
|
|
3503
|
+
* drop-in). Call again to try again: the file is read at every call, the
|
|
3504
|
+
* other two once their last read is 30 minutes old, or sooner after one
|
|
3505
|
+
* that gave no answer or was set aside; once one read has answered, a later
|
|
3506
|
+
* read that fails leaves this as it was. A source that the 30-minute
|
|
3507
|
+
* read finds gone counts so once a second read agrees, which the first call
|
|
3508
|
+
* 30 seconds or more later makes; outside WSL, a profile, or a value that
|
|
3509
|
+
* reg.exe handed over, that fails to load where neither of the two, nor a
|
|
3510
|
+
* per-user value (HKCU), held policy is named. `false` is no proof: a
|
|
3511
|
+
* registry query that fails for good shows as an absent value, and under
|
|
3512
|
+
* WSL a `wslInheritsWindowsSettings` that is neither true nor false is not
|
|
3513
|
+
* named.
|
|
3514
|
+
*/
|
|
3515
|
+
didNotLoad: false | Array<'profile' | 'registry' | 'file'>;
|
|
3516
|
+
};
|
|
3409
3517
|
};
|
|
3410
3518
|
|
|
3411
3519
|
/**
|
|
@@ -3431,8 +3539,9 @@ export declare type ResolvedSettingSource = SettingSource | 'managed' | 'flag';
|
|
|
3431
3539
|
* HKLM/HKCU, and `managedSettings`) **except** the admin-configured
|
|
3432
3540
|
* `policyHelper` subprocess is not executed. MDM resolution may invoke
|
|
3433
3541
|
* `plutil` (macOS, when an MDM plist exists) or `reg.exe` (Windows/WSL)
|
|
3434
|
-
* on the first call per process. If your
|
|
3435
|
-
* policyHelper to inject managed settings, results will
|
|
3542
|
+
* on the first call per process, and again at later calls. If your
|
|
3543
|
+
* deployment relies on policyHelper to inject managed settings, results will
|
|
3544
|
+
* differ.
|
|
3436
3545
|
* - **`permissions.defaultMode` is reported as-is across all tiers**
|
|
3437
3546
|
* including project. The CLI applies a separate trust filter before
|
|
3438
3547
|
* honoring escalating modes (`bypassPermissions`, `auto`, `acceptEdits`)
|
|
@@ -3770,7 +3879,7 @@ export declare type SDKAssistantMessage = {
|
|
|
3770
3879
|
*/
|
|
3771
3880
|
resumed_from_incomplete_thinking?: true;
|
|
3772
3881
|
/**
|
|
3773
|
-
*
|
|
3882
|
+
* Uuids of earlier messages that this message replaces: after a refusal fallback, or after a response whose tool call could not be parsed. It can name user messages too, such as a refused attempt's tool results. Remove the named messages when this one arrives. After a refusal fallback it is idempotent with the end-of-turn model_refusal_fallback notice.
|
|
3774
3883
|
*/
|
|
3775
3884
|
supersedes?: UUID[];
|
|
3776
3885
|
/**
|
|
@@ -3826,6 +3935,7 @@ export declare type SDKAssistantMessage = {
|
|
|
3826
3935
|
|
|
3827
3936
|
|
|
3828
3937
|
|
|
3938
|
+
|
|
3829
3939
|
|
|
3830
3940
|
};
|
|
3831
3941
|
|
|
@@ -3870,6 +3980,7 @@ export declare type SDKBackgroundTasksChangedMessage = {
|
|
|
3870
3980
|
*/
|
|
3871
3981
|
ambient?: boolean;
|
|
3872
3982
|
|
|
3983
|
+
|
|
3873
3984
|
}[];
|
|
3874
3985
|
uuid: UUID;
|
|
3875
3986
|
session_id: string;
|
|
@@ -4725,7 +4836,7 @@ declare type SDKControlInitializeRequest = {
|
|
|
4725
4836
|
hooks?: Partial<Record<coreTypes.HookEvent, SDKHookCallbackMatcher[]>>;
|
|
4726
4837
|
sdkMcpServers?: string[];
|
|
4727
4838
|
/**
|
|
4728
|
-
* Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout, disableAutoBackground, connectorId and
|
|
4839
|
+
* Settings for the SDK-hosted MCP servers named in sdkMcpServers, keyed by server name. Sent as a separate field so a CLI that predates it ignores it; entries whose name is not in sdkMcpServers, and values that do not match this shape, are ignored rather than rejected. timeout, disableAutoBackground, connectorId, autoModeVerdictTools and dataFlowServer apply when the server is first registered; tools (the per-tool permission policy) adds its ask and deny rules on every initialize that names the server. An initialize never removes a rule; mcp_set_servers replaces them.
|
|
4729
4840
|
*/
|
|
4730
4841
|
sdkMcpServerConfigs?: Record<string, {
|
|
4731
4842
|
/**
|
|
@@ -4735,6 +4846,7 @@ declare type SDKControlInitializeRequest = {
|
|
|
4735
4846
|
|
|
4736
4847
|
|
|
4737
4848
|
|
|
4849
|
+
|
|
4738
4850
|
/**
|
|
4739
4851
|
* Per-tool permission policy the host declares for this server's tools (not the tool definitions passed to createSdkMcpServer). always_ask: the CLI asks the host (canUseTool or the permission prompt tool) before each call, even where an allow rule or allowedTools covers the tool, and under bypassPermissions outside a hosted remote session (CLAUDE_CODE_REMOTE); under dontAsk the call is denied; in auto mode the classifier decides, except that by default a tool annotated destructiveHint still asks. always_deny: calls are denied. always_allow and org_max_permission are ignored on sdk servers; grant allows with allowedTools or canUseTool. Read from initialize (sdkMcpServerConfigs) and from each mcp_set_servers entry that names the server. On the wire an entry without tools states no policy: on initialize the stored list and the rules stand; on mcp_set_servers the rules are replaced without them. The Agent SDK always re-sends the registered list. An entry whose policy is not one of the three asks; an entry without a string name is dropped and the rest apply; a value that is not a list reads as absent.
|
|
4740
4852
|
*/
|
|
@@ -4754,7 +4866,7 @@ declare type SDKControlInitializeRequest = {
|
|
|
4754
4866
|
toolsListResult?: Record<string, unknown>;
|
|
4755
4867
|
}>;
|
|
4756
4868
|
/**
|
|
4757
|
-
* The host's statement that it composed this request's sdkMcpServerManifests for this very send, from its servers' current state. Needed only by a host that reaches the CLI over a remote session transport, where an unmarked sdkMcpServerManifests is not used (a recorded registration could be handed to a later worker). The CLI also refuses a marked manifest whose session-stream frame is more than five minutes old, so capture the manifests when writing the request, not earlier
|
|
4869
|
+
* The host's statement that it composed this request's sdkMcpServerManifests for this very send, from its servers' current state. Needed only by a host that reaches the CLI over a remote session transport, where an unmarked sdkMcpServerManifests is not used (a recorded registration could be handed to a later worker). The CLI also refuses a marked manifest whose session-stream frame is more than five minutes old, so capture the manifests when writing the request, not earlier. It declines them too when manifests are switched off in that CLI. Over a remote session it also declines them in three more cases: in any session other than an interactive Cowork chat started from claude.ai; until Anthropic has served that CLI its manifests switch on (so not before its feature flags load); and where the session service has not recently told the CLI that only the account owning the session can send events to it. sdk_mcp_manifests_parked in the response says what became of each entry. A value this CLI does not know counts as no marker. A host on the CLI's own stream-json stdio transport may omit this field; a host writing to the stdin of a remote-session worker cannot use manifests at all.
|
|
4758
4870
|
*/
|
|
4759
4871
|
sdkMcpServerManifestsOrigin?: 'host_per_send';
|
|
4760
4872
|
jsonSchema?: Record<string, unknown>;
|
|
@@ -4809,6 +4921,7 @@ declare type SDKControlInitializeRequest = {
|
|
|
4809
4921
|
|
|
4810
4922
|
|
|
4811
4923
|
|
|
4924
|
+
|
|
4812
4925
|
};
|
|
4813
4926
|
|
|
4814
4927
|
/**
|
|
@@ -4847,8 +4960,9 @@ export declare type SDKControlInitializeResponse = {
|
|
|
4847
4960
|
plugins_applied?: boolean;
|
|
4848
4961
|
|
|
4849
4962
|
|
|
4963
|
+
|
|
4850
4964
|
/**
|
|
4851
|
-
* What became of each entry of this initialize's sdkMcpServerManifests, keyed by sdk server name, for the entries whose name is in sdkMcpServers. 'parked': kept for the connect that follows this reply, which answers the server's MCP initialize and first tools/list from it (a later failure to replay shows up as live mcp_message frames, as when no entry was sent). 'already_connected': this CLI already had a live client for the server. 'protocol_version_mismatch': initializeResult.protocolVersion is not the version this CLI's client requests. 'malformed': the entry is not of the documented shape, reported whether or not manifests were honoured (every name in sdkMcpServers gets this when the field itself is not an object); or an honoured entry is past the limits this CLI sets on a live answer. 'not_honoured': the CLI did not use the entry: manifests
|
|
4965
|
+
* What became of each entry of this initialize's sdkMcpServerManifests, keyed by sdk server name, for the entries whose name is in sdkMcpServers. 'parked': kept for the connect that follows this reply, which answers the server's MCP initialize and first tools/list from it (a later failure to replay shows up as live mcp_message frames, as when no entry was sent). 'already_connected': this CLI already had a live client for the server. 'protocol_version_mismatch': initializeResult.protocolVersion is not the version this CLI's client requests. 'malformed': the entry is not of the documented shape, reported whether or not manifests were honoured (every name in sdkMcpServers gets this when the field itself is not an object); or an honoured entry is past the limits this CLI sets on a live answer. 'not_honoured': the CLI did not use the entry: manifests are switched off in this CLI, this remote session is not an interactive Cowork chat started from claude.ai, the session service has not recently told this remote-session worker that only the account owning the session can send events to it, or the request reached such a worker other than over its session stream (nothing for the host to change in any of these cases); or this CLI had read as many tool lists as it allows in a minute (send it again later); or it came over the session stream without sdkMcpServerManifestsOrigin or on a frame too old to trust (the host's to fix). Absent when the request carried no sdkMcpServerManifests or named no sdkMcpServers, and on CLIs that predate the field.
|
|
4852
4966
|
*/
|
|
4853
4967
|
sdk_mcp_manifests_parked?: Record<string, 'parked' | 'already_connected' | 'protocol_version_mismatch' | 'malformed' | 'not_honoured'>;
|
|
4854
4968
|
|
|
@@ -4898,7 +5012,7 @@ declare type SDKControlInterruptRequest = {
|
|
|
4898
5012
|
*/
|
|
4899
5013
|
export declare type SDKControlInterruptResponse = {
|
|
4900
5014
|
/**
|
|
4901
|
-
* 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.
|
|
5015
|
+
* 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. A worker of a cloud session may treat a plain interrupt from a person differently. If it reads the interrupt before its first turn, while it holds a prompt from the worker before it, the interrupt stops the turn of that prompt, and listed messages that no turn has started then run. 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.
|
|
4902
5016
|
*/
|
|
4903
5017
|
still_queued: string[];
|
|
4904
5018
|
|
|
@@ -4918,7 +5032,7 @@ declare type SDKControlListModelsRequest = {
|
|
|
4918
5032
|
};
|
|
4919
5033
|
|
|
4920
5034
|
/**
|
|
4921
|
-
* 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.
|
|
4922
5036
|
*/
|
|
4923
5037
|
declare type SDKControlListPermissionRulesRequest = {
|
|
4924
5038
|
subtype: 'list_permission_rules';
|
|
@@ -4929,13 +5043,13 @@ declare type SDKControlListPermissionRulesRequest = {
|
|
|
4929
5043
|
*/
|
|
4930
5044
|
export declare type SDKControlListPermissionRulesResponse = {
|
|
4931
5045
|
/**
|
|
4932
|
-
* 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.
|
|
4933
5047
|
*/
|
|
4934
5048
|
state: SDKControlPermissionRulesState;
|
|
4935
5049
|
};
|
|
4936
5050
|
|
|
4937
5051
|
/**
|
|
4938
|
-
* Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes) unless check_permissions is set. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can invoke them directly without the subprocess round-trip. Result content passes through the same processing as model-turn MCP calls, unless result_not_for_model is set. Session expiry is not retried automatically; callers can mcp_reconnect and retry. UrlElicitationRequired (-32042) tries Elicitation hooks; if no hook resolves, the call errors with the URL in the message — open it out-of-band, then retry mcp_call. STAGED calls (input_files/output_files declared) additionally stage lane rows in/out around the call — see the input_files describe. Staged failures come back as a success-subtype response whose staging field carries a typed error_code; subtype:error is emitted only when the call could not be attempted at all (server not connected, kill switch, dispatch failure) and means nothing ran. A target server that is not yet connected is brought up on demand: dispatch runs the deferred plugin/MCP startup resolution (the work a first model turn would have done) and waits up to 30s — shortened by expires_at when that is sooner — for the server to connect before answering "MCP server not connected", so a dispatch that races plugin startup (e.g. after an idle-wake reattach) succeeds instead of failing until a turn runs. Standard RPC semantics: a redelivered request_id supersedes the in-flight run (it is aborted and its response suppressed — exactly one response per request_id); conversion is idempotent, so re-running is safe. Cancellable via control_cancel_request.
|
|
5052
|
+
* Invokes an MCP tool via the subprocess MCP client without a model turn. No permission check (control channel is trusted, same as other subtypes) unless check_permissions is set. In a cloud session, tools on the user's own computer or browser are rejected. SDK-type MCP servers (config.type === "sdk") are rejected — they are caller-provided, so the caller can invoke them directly without the subprocess round-trip. Result content passes through the same processing as model-turn MCP calls, unless result_not_for_model is set. Session expiry is not retried automatically; callers can mcp_reconnect and retry. UrlElicitationRequired (-32042) tries Elicitation hooks; if no hook resolves, the call errors with the URL in the message — open it out-of-band, then retry mcp_call. STAGED calls (input_files/output_files declared) additionally stage lane rows in/out around the call — see the input_files describe. Staged failures come back as a success-subtype response whose staging field carries a typed error_code; subtype:error is emitted only when the call could not be attempted at all (server not connected, kill switch, dispatch failure) and means nothing ran. A target server that is not yet connected is brought up on demand: dispatch runs the deferred plugin/MCP startup resolution (the work a first model turn would have done) and waits up to 30s — shortened by expires_at when that is sooner — for the server to connect before answering "MCP server not connected", so a dispatch that races plugin startup (e.g. after an idle-wake reattach) succeeds instead of failing until a turn runs. Standard RPC semantics: a redelivered request_id supersedes the in-flight run (it is aborted and its response suppressed — exactly one response per request_id); conversion is idempotent, so re-running is safe. Cancellable via control_cancel_request.
|
|
4939
5053
|
*/
|
|
4940
5054
|
declare type SDKControlMcpCallRequest = {
|
|
4941
5055
|
subtype: 'mcp_call';
|
|
@@ -4955,12 +5069,13 @@ declare type SDKControlMcpCallRequest = {
|
|
|
4955
5069
|
* Tool-execution timeout (staging and collection have their own transport timeouts); with check_permissions it also bounds hooks and the wait for an answer. Clamped to [1000, 600000]; default 120000. Sending timeout_ms routes the call through the staging engine — so it is always enforced when present and the response carries a staging result; omit it for a plain call. Staged calls are POSIX-worker-only: on a Windows worker any staged-field call fails with a typed staging refusal.
|
|
4956
5070
|
*/
|
|
4957
5071
|
timeout_ms?: number;
|
|
5072
|
+
|
|
4958
5073
|
/**
|
|
4959
5074
|
* The caller hands the result to a program (a host that renders it, a script), not to a model, and bounds it itself. content is then the server's own content blocks as MCP defines them (the MCP SDK drops members it does not define), not what a model turn would be handed: no image is resized or put in the Messages API's shape, nothing is saved under tool-results, no embedded resource is flattened, and text blocks beside structuredContent stay. They are untrusted third-party data: any mimeType, images neither re-encoded nor bounded in pixels, each block's annotations and _meta unfiltered. The size check that protects a model's context is skipped too: no count_tokens request (which uploads the result), no truncation, no note in place of the content. Instead a result over 10485760 characters (content with its base64, structuredContent and _meta together) fails though the tool ran: a plain call answers the error subtype, a staged call staging.error_code tool_error with the text in detail, before its outputs are collected. A legacy toolResult still comes back as a string. Does not route the call through the staging engine. Absent or false: as before. Honoured only for a host on this process's own pipes, not over a remote transport nor on a lane that redacts what it persists. Feature-detected as `mcp_call_result_not_for_model_v1` in system/init.capabilities and in the initialize response's capabilities; where it is not said, and by a CLI without it, the member is ignored.
|
|
4960
5075
|
*/
|
|
4961
5076
|
result_not_for_model?: boolean;
|
|
4962
5077
|
/**
|
|
4963
|
-
* 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.
|
|
4964
5079
|
*/
|
|
4965
5080
|
check_permissions?: boolean;
|
|
4966
5081
|
/**
|
|
@@ -5005,7 +5120,7 @@ declare type SDKControlMcpMessageRequest = {
|
|
|
5005
5120
|
};
|
|
5006
5121
|
|
|
5007
5122
|
/**
|
|
5008
|
-
* 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.
|
|
5123
|
+
* 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, in a cloud session a server on the user's own computer or browser, 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.
|
|
5009
5124
|
*/
|
|
5010
5125
|
declare type SDKControlMcpReadResourceRequest = {
|
|
5011
5126
|
subtype: 'mcp_read_resource';
|
|
@@ -5140,7 +5255,7 @@ declare type SDKControlPermissionRequest = {
|
|
|
5140
5255
|
};
|
|
5141
5256
|
|
|
5142
5257
|
/**
|
|
5143
|
-
* 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.
|
|
5144
5259
|
*/
|
|
5145
5260
|
export declare type SDKControlPermissionRulesState = {
|
|
5146
5261
|
rules: SDKPermissionRuleEntry[];
|
|
@@ -5158,6 +5273,10 @@ export declare type SDKControlPermissionRulesState = {
|
|
|
5158
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.
|
|
5159
5274
|
*/
|
|
5160
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;
|
|
5161
5280
|
};
|
|
5162
5281
|
|
|
5163
5282
|
/**
|
|
@@ -5172,6 +5291,9 @@ declare type SDKControlReadFileRequest = {
|
|
|
5172
5291
|
*/
|
|
5173
5292
|
encoding?: 'utf-8' | 'base64';
|
|
5174
5293
|
|
|
5294
|
+
|
|
5295
|
+
|
|
5296
|
+
|
|
5175
5297
|
};
|
|
5176
5298
|
|
|
5177
5299
|
/**
|
|
@@ -5186,10 +5308,16 @@ export declare type SDKControlReadFileResponse = {
|
|
|
5186
5308
|
*/
|
|
5187
5309
|
encoding?: 'base64';
|
|
5188
5310
|
/**
|
|
5189
|
-
* 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.
|
|
5311
|
+
* 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, at its end when `truncated` is set, or at its start when `offset` 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.
|
|
5190
5312
|
*/
|
|
5191
5313
|
lossy?: boolean;
|
|
5192
5314
|
|
|
5315
|
+
|
|
5316
|
+
|
|
5317
|
+
|
|
5318
|
+
|
|
5319
|
+
|
|
5320
|
+
|
|
5193
5321
|
};
|
|
5194
5322
|
|
|
5195
5323
|
/**
|
|
@@ -5230,6 +5358,10 @@ declare type SDKControlReloadPluginsRequest = {
|
|
|
5230
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).
|
|
5231
5359
|
*/
|
|
5232
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;
|
|
5233
5365
|
};
|
|
5234
5366
|
|
|
5235
5367
|
/**
|
|
@@ -5595,6 +5727,7 @@ export declare type SDKInformationalMessage = {
|
|
|
5595
5727
|
tag?: string;
|
|
5596
5728
|
|
|
5597
5729
|
|
|
5730
|
+
|
|
5598
5731
|
uuid: UUID;
|
|
5599
5732
|
session_id: string;
|
|
5600
5733
|
};
|
|
@@ -5856,6 +5989,7 @@ export declare type SDKPartialAssistantMessage = {
|
|
|
5856
5989
|
* Why this frame's turn continues one that a worker restart interrupted. Such a turn is the automatic re-run of the interrupted turn (CLAUDE_CODE_RESUME_INTERRUPTED_TURN), or one that goes on from the answer to the permission prompt the new worker took over, or from that turn's tool calls still in flight. The value is the host's CLAUDE_CODE_RESUME_REASON when it set one (host_draining, checkpoint_restore, container_recreated, …), else 'interrupted_turn'. Stamped on the same reply frames as user_message_uuid (which on such a turn names the interrupted turn's own last user prompt), so a consumer can tell its first reply from the interrupted attempt's. Absent on every other turn (also one that goes on from the answer to any other permission prompt), on thinking_tokens frames, and from older producers.
|
|
5857
5990
|
*/
|
|
5858
5991
|
resume_reason?: string;
|
|
5992
|
+
|
|
5859
5993
|
};
|
|
5860
5994
|
|
|
5861
5995
|
export declare type SDKPermissionDenial = {
|
|
@@ -5912,7 +6046,7 @@ export declare type SDKPermissionRuleEntry = {
|
|
|
5912
6046
|
*/
|
|
5913
6047
|
source: 'userSettings' | 'projectSettings' | 'localSettings' | 'flagSettings' | 'policySettings' | 'cliArg' | 'command' | 'session' | 'mcpMount' | 'toolsNarrowing' | 'mcpServerPolicy' | 'hostCredential';
|
|
5914
6048
|
/**
|
|
5915
|
-
* 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.
|
|
5916
6050
|
*/
|
|
5917
6051
|
rule: string;
|
|
5918
6052
|
/**
|
|
@@ -5959,7 +6093,7 @@ export declare type SdkPluginConfig = {
|
|
|
5959
6093
|
};
|
|
5960
6094
|
|
|
5961
6095
|
/**
|
|
5962
|
-
* Headless plugin installation progress
|
|
6096
|
+
* Headless plugin installation progress. installed/failed carry a per-marketplace name. Under CLAUDE_CODE_SYNC_PLUGIN_INSTALL started/completed bracket the whole install, ahead of init; without it the install runs in the background, so there is no bracket and a frame can come at any time, before or after init, or not at all if the process ends first. In the background case only the Claude desktop app gets them, once it asks for them, on a local transport (stdout). `error` comes without URL secrets; it is otherwise raw text: treat it as untrusted.
|
|
5963
6097
|
*/
|
|
5964
6098
|
export declare type SDKPluginInstallMessage = {
|
|
5965
6099
|
type: 'system';
|
|
@@ -6059,6 +6193,27 @@ export declare type SDKResultError = {
|
|
|
6059
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.
|
|
6060
6194
|
*/
|
|
6061
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
|
+
};
|
|
6062
6217
|
/**
|
|
6063
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.
|
|
6064
6219
|
*/
|
|
@@ -6077,6 +6232,8 @@ export declare type SDKResultError = {
|
|
|
6077
6232
|
terminal_reason?: TerminalReason;
|
|
6078
6233
|
|
|
6079
6234
|
|
|
6235
|
+
|
|
6236
|
+
|
|
6080
6237
|
/**
|
|
6081
6238
|
* 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.
|
|
6082
6239
|
*/
|
|
@@ -6133,6 +6290,9 @@ export declare type SDKResultSuccess = {
|
|
|
6133
6290
|
|
|
6134
6291
|
|
|
6135
6292
|
|
|
6293
|
+
|
|
6294
|
+
|
|
6295
|
+
|
|
6136
6296
|
|
|
6137
6297
|
|
|
6138
6298
|
|
|
@@ -6176,6 +6336,7 @@ export declare type SDKResultSuccess = {
|
|
|
6176
6336
|
|
|
6177
6337
|
|
|
6178
6338
|
|
|
6339
|
+
|
|
6179
6340
|
num_turns: number;
|
|
6180
6341
|
result: string;
|
|
6181
6342
|
stop_reason: string | null;
|
|
@@ -6204,6 +6365,7 @@ export declare type SDKResultSuccess = {
|
|
|
6204
6365
|
terminal_reason?: TerminalReason;
|
|
6205
6366
|
|
|
6206
6367
|
|
|
6368
|
+
|
|
6207
6369
|
/**
|
|
6208
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.
|
|
6209
6371
|
*/
|
|
@@ -6263,6 +6425,10 @@ export declare type SDKSessionInfo = {
|
|
|
6263
6425
|
* Creation time in integer milliseconds since epoch, extracted from the first entry's timestamp.
|
|
6264
6426
|
*/
|
|
6265
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;
|
|
6266
6432
|
};
|
|
6267
6433
|
|
|
6268
6434
|
/**
|
|
@@ -6317,9 +6483,9 @@ export declare type SDKSettingsParseError = {
|
|
|
6317
6483
|
};
|
|
6318
6484
|
|
|
6319
6485
|
/**
|
|
6320
|
-
* 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.
|
|
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.
|
|
6321
6487
|
*/
|
|
6322
|
-
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';
|
|
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';
|
|
6323
6489
|
|
|
6324
6490
|
export declare type SDKStatus = 'compacting' | 'requesting' | null;
|
|
6325
6491
|
|
|
@@ -6384,7 +6550,7 @@ export declare type SDKSystemMessage = {
|
|
|
6384
6550
|
version?: string;
|
|
6385
6551
|
}[];
|
|
6386
6552
|
/**
|
|
6387
|
-
* Plugin load-time errors. A plugin that did not load (an unmet dependency, a --plugin-dir entry that failed) is absent from `plugins[]`; a plugin that loaded without one of its components keeps its row and gets an entry here too. `plugin` is `name@marketplace`, or the positional `inline[N]` / `synced[N]` tag for a directory entry that failed before it had a name; `type` is a category from an open set (path-not-found, generic-error, manifest-validation-error, dependency-unsatisfied, hook-load-failed, …) — treat a value you do not recognize as a generic failure; `message` is display text. The key is omitted when there are no errors; CI can fail on `(plugin_errors?.length ?? 0) > 0`.
|
|
6553
|
+
* Plugin load-time errors. A plugin that did not load (an unmet dependency, a --plugin-dir entry that failed, a plugin enabled by managed settings that the loader could not load) is absent from `plugins[]`; a plugin that loaded without one of its components keeps its row and gets an entry here too. `plugin` is `name@marketplace`, or the positional `inline[N]` / `synced[N]` tag for a directory entry that failed before it had a name; `type` is a category from an open set (path-not-found, generic-error, manifest-validation-error, dependency-unsatisfied, hook-load-failed, …) — treat a value you do not recognize as a generic failure; `message` is display text; over a transport that may store its frames (a cloud worker or a self-hosted runner), an entry that is here only because managed settings enable the plugin carries one fixed sentence in its place, with no path or URL. The key is omitted when there are no errors; CI can fail on `(plugin_errors?.length ?? 0) > 0`. That check also trips on a machine that has no copy yet of a plugin enabled by managed settings, which is every run on a throwaway CI runner; CLAUDE_CODE_SYNC_PLUGIN_INSTALL=1 makes the first turn wait for the install. A Remote Control worker and the hosted worker always omit this key — plugin diagnostics stay in the local log there, so an omitted key does not assert a clean load.
|
|
6388
6554
|
*/
|
|
6389
6555
|
plugin_errors?: {
|
|
6390
6556
|
plugin: string;
|
|
@@ -6394,6 +6560,14 @@ export declare type SDKSystemMessage = {
|
|
|
6394
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.
|
|
6395
6561
|
*/
|
|
6396
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
|
+
};
|
|
6397
6571
|
}[];
|
|
6398
6572
|
|
|
6399
6573
|
|
|
@@ -6412,7 +6586,7 @@ export declare type SDKSystemMessage = {
|
|
|
6412
6586
|
*/
|
|
6413
6587
|
view_mode?: 'focus' | 'default';
|
|
6414
6588
|
/**
|
|
6415
|
-
* 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.
|
|
6416
6590
|
*/
|
|
6417
6591
|
capabilities?: string[];
|
|
6418
6592
|
|
|
@@ -6498,6 +6672,7 @@ export declare type SDKTaskProgressMessage = {
|
|
|
6498
6672
|
summary?: string;
|
|
6499
6673
|
|
|
6500
6674
|
|
|
6675
|
+
|
|
6501
6676
|
uuid: UUID;
|
|
6502
6677
|
session_id: string;
|
|
6503
6678
|
};
|
|
@@ -6766,6 +6941,7 @@ export declare type SDKUserMessage = {
|
|
|
6766
6941
|
|
|
6767
6942
|
|
|
6768
6943
|
|
|
6944
|
+
|
|
6769
6945
|
uuid?: UUID;
|
|
6770
6946
|
/**
|
|
6771
6947
|
* 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.
|
|
@@ -6868,6 +7044,7 @@ export declare type SDKUserMessageReplay = {
|
|
|
6868
7044
|
|
|
6869
7045
|
|
|
6870
7046
|
|
|
7047
|
+
|
|
6871
7048
|
uuid: UUID;
|
|
6872
7049
|
session_id: string;
|
|
6873
7050
|
isReplay: true;
|
|
@@ -6949,7 +7126,7 @@ export declare type SessionMessage = {
|
|
|
6949
7126
|
|
|
6950
7127
|
/**
|
|
6951
7128
|
* Options shared by session mutation functions (renameSession, tagSession,
|
|
6952
|
-
* deleteSession, forkSession).
|
|
7129
|
+
* archiveSession, unarchiveSession, deleteSession, forkSession).
|
|
6953
7130
|
*/
|
|
6954
7131
|
export declare type SessionMutationOptions = {
|
|
6955
7132
|
/**
|
|
@@ -6959,7 +7136,7 @@ export declare type SessionMutationOptions = {
|
|
|
6959
7136
|
dir?: string;
|
|
6960
7137
|
/**
|
|
6961
7138
|
* When provided, read/write session data via this store instead of the
|
|
6962
|
-
* local filesystem.
|
|
7139
|
+
* local filesystem. archiveSession and unarchiveSession reject it.
|
|
6963
7140
|
* @alpha
|
|
6964
7141
|
*/
|
|
6965
7142
|
sessionStore?: SessionStore;
|
|
@@ -7313,11 +7490,12 @@ export declare interface Settings {
|
|
|
7313
7490
|
*/
|
|
7314
7491
|
disableBypassPermissionsMode?: 'disable';
|
|
7315
7492
|
/**
|
|
7316
|
-
* Refuse file-tool reads (Read, Grep, Glob, LSP) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Also set when the user picks "block" on the one-time auto-mode prompt for a read outside the working directories.
|
|
7493
|
+
* Refuse file-tool reads (Read, Grep, Glob, LSP) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Also binds shell commands: one that names a path outside them is asked about in every mode, and the sandbox, where it is on, denies such reads. Also set when the user picks "block" on the one-time auto-mode prompt for a read outside the working directories.
|
|
7317
7494
|
*/
|
|
7318
7495
|
blockReadsOutsideWorkingDirectories?: boolean;
|
|
7496
|
+
|
|
7319
7497
|
/**
|
|
7320
|
-
* Refuse file-tool writes (Write, Edit, NotebookEdit) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Files that Claude Code keeps for the session are not refused: its plan files, scratchpad and background job folder, and the auto-memory of this project, unless a repository settings file points it elsewhere. Nothing runs them unless the model asks. Also refuses file-tool writes to Claude Code settings files, inside the working directories too, and takes EnterWorktree and ExitWorktree, which move the working directory, out of the tools on offer. Does not limit shell commands, MCP tools, the programs that hooks run, or the memory tools. Cloud sessions (Claude Code on the web), whose file tools run in a container that is itself the boundary, may not apply it.
|
|
7498
|
+
* Refuse file-tool writes (Write, Edit, NotebookEdit) outside the working directories in every permission mode; true in any settings source wins. No allow rule lifts it. Files that Claude Code keeps for the session are not refused: its plan files, scratchpad and background job folder, and the auto-memory of this project, unless a repository settings file points it elsewhere (a setting of the program that starts Claude Code can narrow this and the working directories). Nothing runs them unless the model asks. Also refuses file-tool writes to Claude Code settings files, inside the working directories too, and takes EnterWorktree and ExitWorktree, which move the working directory, out of the tools on offer (a setting of the program that starts Claude Code can keep them). Does not limit shell commands, MCP tools, the programs that hooks run, or the memory tools. Cloud sessions (Claude Code on the web), whose file tools run in a container that is itself the boundary, may not apply it.
|
|
7321
7499
|
*/
|
|
7322
7500
|
blockWritesOutsideWorkingDirectories?: boolean;
|
|
7323
7501
|
/**
|
|
@@ -7429,7 +7607,7 @@ export declare interface Settings {
|
|
|
7429
7607
|
*/
|
|
7430
7608
|
disabledMcpjsonServers?: string[];
|
|
7431
7609
|
/**
|
|
7432
|
-
* 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.
|
|
7433
7611
|
*/
|
|
7434
7612
|
disableClaudeAiConnectors?: boolean;
|
|
7435
7613
|
/**
|
|
@@ -7794,7 +7972,7 @@ export declare interface Settings {
|
|
|
7794
7972
|
*/
|
|
7795
7973
|
httpHookAllowedEnvVars?: string[];
|
|
7796
7974
|
/**
|
|
7797
|
-
* When true (and set in managed settings), permission rules from user, project, local, and --settings files and allow rules from --allowedTools are ignored; only managed settings can add allow rules through settings. The allowed-tools frontmatter of skills and custom commands from user, project, and --add-dir sources, and of plugins no managed setting vouches for, is ignored too. Plugins keep theirs only on an admin-backed channel: host-delivered --plugin-dir plugins (in Claude Desktop, only while this is not set by the organization's own managed settings), the official marketplace registered from its unpinned anthropics source, claude.ai-synced plugins Anthropic attests, the saved login organization's claude.ai-hosted marketplaces, marketplaces whose registered source managed extraKnownMarketplaces declares or an exact or owner-pinned (owner/*) strictKnownMarketplaces entry names at the path it pins (an npm marketplace source only when the registration and the declared entry pin the same registry, and a settings marketplace source only when every nested npm plugin entry pins one on a bare package name — unpinned, the package resolves through the member's own npm config, and a non-bare spelling packs as an exotic spec the pin does not bind, so nothing an entry names is what was fetched)
|
|
7975
|
+
* When true (and set in managed settings), permission rules from user, project, local, and --settings files and allow rules from --allowedTools are ignored; only managed settings can add allow rules through settings. The allowed-tools frontmatter of skills and custom commands from user, project, and --add-dir sources, and of plugins no managed setting vouches for, is ignored too. Plugins keep theirs only on an admin-backed channel: host-delivered --plugin-dir plugins (in Claude Desktop, only while this is not set by the organization's own managed settings), the official marketplace registered from its unpinned anthropics source, claude.ai-synced plugins Anthropic attests, the saved login organization's claude.ai-hosted marketplaces, marketplaces whose registered source managed extraKnownMarketplaces declares or an exact or owner-pinned (owner/*) strictKnownMarketplaces entry names at the path it pins (an npm marketplace source only when the registration and the declared entry pin the same registry, and a settings marketplace source only when every nested npm plugin entry pins one on a bare package name — unpinned, the package resolves through the member's own npm config, and a non-bare spelling packs as an exotic spec the pin does not bind, so nothing an entry names is what was fetched) (host and path patterns and enabledPlugins ids do not vouch); managed and bundled skills keep theirs. --disallowedTools, skill disallowed-tools, and other deny and ask rules from the command line or the current session still apply.
|
|
7798
7976
|
*/
|
|
7799
7977
|
allowManagedPermissionRulesOnly?: boolean;
|
|
7800
7978
|
/**
|
|
@@ -7862,14 +8040,14 @@ export declare interface Settings {
|
|
|
7862
8040
|
[k: string]: unknown;
|
|
7863
8041
|
})[];
|
|
7864
8042
|
/**
|
|
7865
|
-
*
|
|
8043
|
+
* Deprecated: no longer has any effect. Subagent rows always use the default look.
|
|
7866
8044
|
*/
|
|
7867
8045
|
subagentStatusLine?: {
|
|
7868
8046
|
type: 'command';
|
|
7869
8047
|
command: string;
|
|
7870
8048
|
};
|
|
7871
8049
|
/**
|
|
7872
|
-
* Enabled plugins using plugin-id\@marketplace-id format. Example: { "formatter\@anthropic-tools": true }.
|
|
8050
|
+
* Enabled plugins using plugin-id\@marketplace-id format. Example: { "formatter\@anthropic-tools": true }. Only true turns on a marketplace plugin: a list of versions is accepted but leaves it off. Settings precedence is user < project < local < flag < policy, so to disable a plugin that project settings enable, set it to false in .claude/settings.local.json — setting false in ~/.claude/settings.json is overridden by the project.
|
|
7873
8051
|
*/
|
|
7874
8052
|
enabledPlugins?: {
|
|
7875
8053
|
[k: string]: string[] | boolean | {
|
|
@@ -7877,7 +8055,7 @@ export declare interface Settings {
|
|
|
7877
8055
|
};
|
|
7878
8056
|
};
|
|
7879
8057
|
/**
|
|
7880
|
-
* 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.
|
|
7881
8059
|
*/
|
|
7882
8060
|
prependPlugins?: string[];
|
|
7883
8061
|
/**
|
|
@@ -7915,7 +8093,7 @@ export declare interface Settings {
|
|
|
7915
8093
|
*/
|
|
7916
8094
|
repo: string;
|
|
7917
8095
|
/**
|
|
7918
|
-
* Git branch or
|
|
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.
|
|
7919
8097
|
*/
|
|
7920
8098
|
ref?: string;
|
|
7921
8099
|
/**
|
|
@@ -7937,7 +8115,7 @@ export declare interface Settings {
|
|
|
7937
8115
|
*/
|
|
7938
8116
|
url: string;
|
|
7939
8117
|
/**
|
|
7940
|
-
* Git branch or
|
|
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.
|
|
7941
8119
|
*/
|
|
7942
8120
|
ref?: string;
|
|
7943
8121
|
/**
|
|
@@ -7955,7 +8133,7 @@ export declare interface Settings {
|
|
|
7955
8133
|
} | {
|
|
7956
8134
|
source: 'npm';
|
|
7957
8135
|
/**
|
|
7958
|
-
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace").
|
|
8136
|
+
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
|
|
7959
8137
|
*/
|
|
7960
8138
|
package: string;
|
|
7961
8139
|
/**
|
|
@@ -7963,7 +8141,7 @@ export declare interface Settings {
|
|
|
7963
8141
|
*/
|
|
7964
8142
|
version?: string;
|
|
7965
8143
|
/**
|
|
7966
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides).
|
|
8144
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
7967
8145
|
*/
|
|
7968
8146
|
registry?: string;
|
|
7969
8147
|
} | {
|
|
@@ -8100,6 +8278,12 @@ export declare interface Settings {
|
|
|
8100
8278
|
description?: string;
|
|
8101
8279
|
version?: string;
|
|
8102
8280
|
strict?: boolean;
|
|
8281
|
+
/**
|
|
8282
|
+
* Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
|
|
8283
|
+
*/
|
|
8284
|
+
engines?: {
|
|
8285
|
+
[k: string]: unknown;
|
|
8286
|
+
};
|
|
8103
8287
|
/**
|
|
8104
8288
|
* HTTP headers sent when downloading this entry's `archive` source.
|
|
8105
8289
|
*/
|
|
@@ -8135,7 +8319,7 @@ export declare interface Settings {
|
|
|
8135
8319
|
*/
|
|
8136
8320
|
autoUpdate?: boolean;
|
|
8137
8321
|
/**
|
|
8138
|
-
*
|
|
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.
|
|
8139
8323
|
*/
|
|
8140
8324
|
pluginDigests?: {
|
|
8141
8325
|
[k: string]: string[];
|
|
@@ -8173,7 +8357,7 @@ export declare interface Settings {
|
|
|
8173
8357
|
*/
|
|
8174
8358
|
repo: string;
|
|
8175
8359
|
/**
|
|
8176
|
-
* Git branch or
|
|
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.
|
|
8177
8361
|
*/
|
|
8178
8362
|
ref?: string;
|
|
8179
8363
|
/**
|
|
@@ -8195,7 +8379,7 @@ export declare interface Settings {
|
|
|
8195
8379
|
*/
|
|
8196
8380
|
url: string;
|
|
8197
8381
|
/**
|
|
8198
|
-
* Git branch or
|
|
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.
|
|
8199
8383
|
*/
|
|
8200
8384
|
ref?: string;
|
|
8201
8385
|
/**
|
|
@@ -8213,7 +8397,7 @@ export declare interface Settings {
|
|
|
8213
8397
|
} | {
|
|
8214
8398
|
source: 'npm';
|
|
8215
8399
|
/**
|
|
8216
|
-
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace").
|
|
8400
|
+
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
|
|
8217
8401
|
*/
|
|
8218
8402
|
package: string;
|
|
8219
8403
|
/**
|
|
@@ -8221,7 +8405,7 @@ export declare interface Settings {
|
|
|
8221
8405
|
*/
|
|
8222
8406
|
version?: string;
|
|
8223
8407
|
/**
|
|
8224
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides).
|
|
8408
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8225
8409
|
*/
|
|
8226
8410
|
registry?: string;
|
|
8227
8411
|
} | {
|
|
@@ -8358,6 +8542,12 @@ export declare interface Settings {
|
|
|
8358
8542
|
description?: string;
|
|
8359
8543
|
version?: string;
|
|
8360
8544
|
strict?: boolean;
|
|
8545
|
+
/**
|
|
8546
|
+
* Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
|
|
8547
|
+
*/
|
|
8548
|
+
engines?: {
|
|
8549
|
+
[k: string]: unknown;
|
|
8550
|
+
};
|
|
8361
8551
|
/**
|
|
8362
8552
|
* HTTP headers sent when downloading this entry's `archive` source.
|
|
8363
8553
|
*/
|
|
@@ -8393,7 +8583,7 @@ export declare interface Settings {
|
|
|
8393
8583
|
*/
|
|
8394
8584
|
autoUpdate?: boolean;
|
|
8395
8585
|
/**
|
|
8396
|
-
*
|
|
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.
|
|
8397
8587
|
*/
|
|
8398
8588
|
pluginDigests?: {
|
|
8399
8589
|
[k: string]: string[];
|
|
@@ -8426,7 +8616,7 @@ export declare interface Settings {
|
|
|
8426
8616
|
*/
|
|
8427
8617
|
repo: string;
|
|
8428
8618
|
/**
|
|
8429
|
-
* Git branch or
|
|
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.
|
|
8430
8620
|
*/
|
|
8431
8621
|
ref?: string;
|
|
8432
8622
|
/**
|
|
@@ -8448,7 +8638,7 @@ export declare interface Settings {
|
|
|
8448
8638
|
*/
|
|
8449
8639
|
url: string;
|
|
8450
8640
|
/**
|
|
8451
|
-
* Git branch or
|
|
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.
|
|
8452
8642
|
*/
|
|
8453
8643
|
ref?: string;
|
|
8454
8644
|
/**
|
|
@@ -8466,7 +8656,7 @@ export declare interface Settings {
|
|
|
8466
8656
|
} | {
|
|
8467
8657
|
source: 'npm';
|
|
8468
8658
|
/**
|
|
8469
|
-
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace").
|
|
8659
|
+
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
|
|
8470
8660
|
*/
|
|
8471
8661
|
package: string;
|
|
8472
8662
|
/**
|
|
@@ -8474,7 +8664,7 @@ export declare interface Settings {
|
|
|
8474
8664
|
*/
|
|
8475
8665
|
version?: string;
|
|
8476
8666
|
/**
|
|
8477
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides).
|
|
8667
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8478
8668
|
*/
|
|
8479
8669
|
registry?: string;
|
|
8480
8670
|
} | {
|
|
@@ -8611,6 +8801,12 @@ export declare interface Settings {
|
|
|
8611
8801
|
description?: string;
|
|
8612
8802
|
version?: string;
|
|
8613
8803
|
strict?: boolean;
|
|
8804
|
+
/**
|
|
8805
|
+
* Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
|
|
8806
|
+
*/
|
|
8807
|
+
engines?: {
|
|
8808
|
+
[k: string]: unknown;
|
|
8809
|
+
};
|
|
8614
8810
|
/**
|
|
8615
8811
|
* HTTP headers sent when downloading this entry's `archive` source.
|
|
8616
8812
|
*/
|
|
@@ -8663,7 +8859,7 @@ export declare interface Settings {
|
|
|
8663
8859
|
*/
|
|
8664
8860
|
repo: string;
|
|
8665
8861
|
/**
|
|
8666
|
-
* Git branch or
|
|
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.
|
|
8667
8863
|
*/
|
|
8668
8864
|
ref?: string;
|
|
8669
8865
|
/**
|
|
@@ -8685,7 +8881,7 @@ export declare interface Settings {
|
|
|
8685
8881
|
*/
|
|
8686
8882
|
url: string;
|
|
8687
8883
|
/**
|
|
8688
|
-
* Git branch or
|
|
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.
|
|
8689
8885
|
*/
|
|
8690
8886
|
ref?: string;
|
|
8691
8887
|
/**
|
|
@@ -8703,7 +8899,7 @@ export declare interface Settings {
|
|
|
8703
8899
|
} | {
|
|
8704
8900
|
source: 'npm';
|
|
8705
8901
|
/**
|
|
8706
|
-
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace").
|
|
8902
|
+
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
|
|
8707
8903
|
*/
|
|
8708
8904
|
package: string;
|
|
8709
8905
|
/**
|
|
@@ -8711,7 +8907,7 @@ export declare interface Settings {
|
|
|
8711
8907
|
*/
|
|
8712
8908
|
version?: string;
|
|
8713
8909
|
/**
|
|
8714
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides).
|
|
8910
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8715
8911
|
*/
|
|
8716
8912
|
registry?: string;
|
|
8717
8913
|
} | {
|
|
@@ -8848,6 +9044,12 @@ export declare interface Settings {
|
|
|
8848
9044
|
description?: string;
|
|
8849
9045
|
version?: string;
|
|
8850
9046
|
strict?: boolean;
|
|
9047
|
+
/**
|
|
9048
|
+
* Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
|
|
9049
|
+
*/
|
|
9050
|
+
engines?: {
|
|
9051
|
+
[k: string]: unknown;
|
|
9052
|
+
};
|
|
8851
9053
|
/**
|
|
8852
9054
|
* HTTP headers sent when downloading this entry's `archive` source.
|
|
8853
9055
|
*/
|
|
@@ -8875,7 +9077,7 @@ export declare interface Settings {
|
|
|
8875
9077
|
};
|
|
8876
9078
|
})[];
|
|
8877
9079
|
/**
|
|
8878
|
-
* 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.
|
|
8879
9081
|
*/
|
|
8880
9082
|
blockedMarketplaces?: ({
|
|
8881
9083
|
source: 'url';
|
|
@@ -8900,7 +9102,7 @@ export declare interface Settings {
|
|
|
8900
9102
|
*/
|
|
8901
9103
|
repo: string;
|
|
8902
9104
|
/**
|
|
8903
|
-
* Git branch or
|
|
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.
|
|
8904
9106
|
*/
|
|
8905
9107
|
ref?: string;
|
|
8906
9108
|
/**
|
|
@@ -8922,7 +9124,7 @@ export declare interface Settings {
|
|
|
8922
9124
|
*/
|
|
8923
9125
|
url: string;
|
|
8924
9126
|
/**
|
|
8925
|
-
* Git branch or
|
|
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.
|
|
8926
9128
|
*/
|
|
8927
9129
|
ref?: string;
|
|
8928
9130
|
/**
|
|
@@ -8940,7 +9142,7 @@ export declare interface Settings {
|
|
|
8940
9142
|
} | {
|
|
8941
9143
|
source: 'npm';
|
|
8942
9144
|
/**
|
|
8943
|
-
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace").
|
|
9145
|
+
* npm package containing marketplace.json (e.g. "\@acme/claude-marketplace"). A scope wildcard such as "\@acme/*" still parses in a managed list, so a list that holds one stays valid, but it matches no marketplace package.
|
|
8944
9146
|
*/
|
|
8945
9147
|
package: string;
|
|
8946
9148
|
/**
|
|
@@ -8948,7 +9150,7 @@ export declare interface Settings {
|
|
|
8948
9150
|
*/
|
|
8949
9151
|
version?: string;
|
|
8950
9152
|
/**
|
|
8951
|
-
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides).
|
|
9153
|
+
* Registry URL. When adding a marketplace: a one-off registry override (otherwise your npm configuration decides). Under allowManagedPermissionRulesOnly, an npm marketplace keeps plugin allowed-tools only when both the entry and the registration pin this same registry.
|
|
8952
9154
|
*/
|
|
8953
9155
|
registry?: string;
|
|
8954
9156
|
} | {
|
|
@@ -9085,6 +9287,12 @@ export declare interface Settings {
|
|
|
9085
9287
|
description?: string;
|
|
9086
9288
|
version?: string;
|
|
9087
9289
|
strict?: boolean;
|
|
9290
|
+
/**
|
|
9291
|
+
* Versions of its hosts this plugin runs on. "claude-code" is a semver range (e.g. ">=2.1.320"): outside it, the plugin is not installed, updated or loaded. Other keys are ignored.
|
|
9292
|
+
*/
|
|
9293
|
+
engines?: {
|
|
9294
|
+
[k: string]: unknown;
|
|
9295
|
+
};
|
|
9088
9296
|
/**
|
|
9089
9297
|
* HTTP headers sent when downloading this entry's `archive` source.
|
|
9090
9298
|
*/
|
|
@@ -9181,9 +9389,12 @@ export declare interface Settings {
|
|
|
9181
9389
|
*/
|
|
9182
9390
|
enabled?: boolean;
|
|
9183
9391
|
/**
|
|
9184
|
-
* 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).
|
|
9185
9393
|
*/
|
|
9186
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
|
+
*/
|
|
9187
9398
|
autoAllowBashIfSandboxed?: boolean;
|
|
9188
9399
|
/**
|
|
9189
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).
|
|
@@ -9260,7 +9471,7 @@ export declare interface Settings {
|
|
|
9260
9471
|
*/
|
|
9261
9472
|
allowManagedReadPathsOnly?: boolean;
|
|
9262
9473
|
/**
|
|
9263
|
-
* 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
|
|
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.
|
|
9264
9475
|
*/
|
|
9265
9476
|
disabled?: boolean;
|
|
9266
9477
|
};
|
|
@@ -9429,6 +9640,7 @@ export declare interface Settings {
|
|
|
9429
9640
|
* Whether to show tips in the spinner
|
|
9430
9641
|
*/
|
|
9431
9642
|
spinnerTipsEnabled?: boolean;
|
|
9643
|
+
|
|
9432
9644
|
/**
|
|
9433
9645
|
* Customize spinner verbs. mode: "append" adds verbs to defaults, "replace" uses only your verbs.
|
|
9434
9646
|
*/
|
|
@@ -9563,7 +9775,7 @@ export declare interface Settings {
|
|
|
9563
9775
|
*/
|
|
9564
9776
|
showClearContextOnPlanAccept?: boolean;
|
|
9565
9777
|
/**
|
|
9566
|
-
* Idle time before Claude's questions auto-continue with any answers selected so far.
|
|
9778
|
+
* Idle time before Claude's questions in the terminal auto-continue with any answers selected so far. When unset, the terminal does not auto-continue. The Claude desktop and web apps show Claude's questions in their own interface and may move on from some unanswered ones after a wait the app sets. Claude is then told that nobody answered and uses its best judgment. In sessions that read this setting, only "never" stops the apps from moving on. Leaving it unset does not. Cloud sessions and Cowork tasks do not read your user settings file (~/.claude/settings.json), and managed settings do not reach all of them. This setting is ignored in a project's settings files.
|
|
9567
9779
|
*/
|
|
9568
9780
|
askUserQuestionTimeout?: '60s' | '5m' | '10m' | 'never';
|
|
9569
9781
|
/**
|
|
@@ -9781,6 +9993,7 @@ export declare interface Settings {
|
|
|
9781
9993
|
* Precompute the compaction summary in the background before it is needed. Only applies when auto-compact is on.
|
|
9782
9994
|
*/
|
|
9783
9995
|
precomputeCompactionEnabled?: boolean;
|
|
9996
|
+
|
|
9784
9997
|
/**
|
|
9785
9998
|
* Set to false to stop Claude Code from compacting a long conversation while the session is idle. Defaults to true.
|
|
9786
9999
|
*/
|
|
@@ -10409,6 +10622,18 @@ export declare interface Transport {
|
|
|
10409
10622
|
[Symbol.dispose]?(): void;
|
|
10410
10623
|
}
|
|
10411
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
|
+
|
|
10412
10637
|
/**
|
|
10413
10638
|
* Messages meaning "a usage limit was genuinely reached" — the error-path
|
|
10414
10639
|
* outputs of getLimitReachedText (rateLimitMessages.ts) and
|