@anthropic-ai/claude-agent-sdk 0.3.281 → 0.3.283
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 +4 -0
- package/bridge.mjs +67 -64
- package/browser-sdk.js +41 -41
- package/core-3mr1yqt9.mjs +31 -0
- package/core-rg0sgcv0.mjs +38 -0
- package/core.d.ts +20 -0
- package/core.mjs +41 -0
- package/manifest.json +23 -23
- package/manifest.zst.json +27 -27
- package/package.json +19 -11
- package/sdk.d.ts +271 -16
- package/sdk.mjs +82 -82
package/sdk.d.ts
CHANGED
|
@@ -300,6 +300,67 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
|
|
|
300
300
|
|
|
301
301
|
}) => Promise<PermissionResult | null>;
|
|
302
302
|
|
|
303
|
+
/**
|
|
304
|
+
* The per-session half of {@link Options}: what a host only knows once the
|
|
305
|
+
* user has picked a folder and started the session. Everything else (the
|
|
306
|
+
* executable, settings sources, tools, plugins, host-level MCP servers, hooks,
|
|
307
|
+
* canUseTool, environment that the process reads during start-up) is given to
|
|
308
|
+
* {@link prewarm} and is fixed for the life of the spare. A host whose
|
|
309
|
+
* host-level options changed since it prewarmed must discard the spare and
|
|
310
|
+
* start normally.
|
|
311
|
+
* @alpha
|
|
312
|
+
*/
|
|
313
|
+
export declare type ClaimOptions = {
|
|
314
|
+
/**
|
|
315
|
+
* The session's working directory (required). A relative path resolves
|
|
316
|
+
* against this process, as for `query()`; `~/…` is expanded by Claude Code.
|
|
317
|
+
*/
|
|
318
|
+
cwd: string;
|
|
319
|
+
/**
|
|
320
|
+
* Per-session environment additions. Only variables the CLI accepts at
|
|
321
|
+
* claim time (fresh OAuth/session tokens, the host's session id) — anything
|
|
322
|
+
* the process reads during start-up belongs in the prewarm options' env,
|
|
323
|
+
* and the claim is refused if it appears here.
|
|
324
|
+
*/
|
|
325
|
+
env?: Record<string, string>;
|
|
326
|
+
/** As `--add-dir`; relative entries resolve against `cwd`, missing ones are skipped. */
|
|
327
|
+
additionalDirectories?: string[];
|
|
328
|
+
model?: string;
|
|
329
|
+
/**
|
|
330
|
+
* As `Options.permissionMode`, sent as part of the claim itself: a mode
|
|
331
|
+
* the process cannot take (`bypassPermissions` on a spare prewarmed without
|
|
332
|
+
* `allowDangerouslySkipPermissions`, one the folder's settings disable)
|
|
333
|
+
* refuses the claim — `claimed` rejects with `permission_mode_not_claimable`
|
|
334
|
+
* (or `claim_failed`) and the prompt gets the `not_claimed` error result —
|
|
335
|
+
* so a session never runs under a different mode than the one asked for.
|
|
336
|
+
*/
|
|
337
|
+
permissionMode?: PermissionMode;
|
|
338
|
+
maxThinkingTokens?: number | null;
|
|
339
|
+
/**
|
|
340
|
+
* Flag-tier settings overlay (e.g. `{ fastMode: true, effortLevel: 'high' }`),
|
|
341
|
+
* applied as `applyFlagSettings` does. Because an overlay can carry
|
|
342
|
+
* permission rules, a claim that has one holds the prompt until the process
|
|
343
|
+
* has accepted the overlay (one round trip) and does not send it if the
|
|
344
|
+
* overlay is refused: `claimed` then rejects with `settings_not_applied`
|
|
345
|
+
* and the process is closed — start the session with `query()`. One limit
|
|
346
|
+
* in this version: keys that govern hooks (`hooks`, `disableAllHooks`,
|
|
347
|
+
* `allowManagedHooksOnly`, `allowedHttpHookUrls`, `httpHookAllowedEnvVars`)
|
|
348
|
+
* are refused — `claim()` throws before sending anything and the spare stays
|
|
349
|
+
* parked — because the claimed folder's SessionStart hooks start with the
|
|
350
|
+
* claim, before the overlay lands; give those to `prewarm()` in
|
|
351
|
+
* `Options.settings`, where they are in force before any hook as on a cold
|
|
352
|
+
* start. The rest of the overlay is in force before the prompt you pass to
|
|
353
|
+
* `claim()` is read; the claimed folder's own SessionStart hooks, and a
|
|
354
|
+
* first message such a hook hands the session, start with the claim and do
|
|
355
|
+
* not wait for the overlay.
|
|
356
|
+
*/
|
|
357
|
+
settings?: Parameters<Query['applyFlagSettings']>[0];
|
|
358
|
+
appendSystemPrompt?: string;
|
|
359
|
+
title?: string;
|
|
360
|
+
agents?: Record<string, AgentDefinition>;
|
|
361
|
+
|
|
362
|
+
};
|
|
363
|
+
|
|
303
364
|
export declare type ConfigChangeHookInput = BaseHookInput & {
|
|
304
365
|
hook_event_name: 'ConfigChange';
|
|
305
366
|
source: 'user_settings' | 'project_settings' | 'local_settings' | 'policy_settings' | 'skills';
|
|
@@ -2155,10 +2216,13 @@ export declare type Options = {
|
|
|
2155
2216
|
* tab launches merges them by default; `'first-wins'` in the highest-priority
|
|
2156
2217
|
* managed source turns that off). Even when opted in, the value is filtered
|
|
2157
2218
|
* restrictive-only: permissive arrays (`permissions.allow`,
|
|
2158
|
-
* `additionalDirectories`,
|
|
2159
|
-
*
|
|
2160
|
-
*
|
|
2161
|
-
*
|
|
2219
|
+
* `additionalDirectories`, …) that would widen an existing admin lock are
|
|
2220
|
+
* silently dropped; the only-listed-allowed lists (`allowedMcpServers`,
|
|
2221
|
+
* `availableModels`, `strictKnownMarketplaces`) apply only where the admin
|
|
2222
|
+
* tier sets none, while denylists (`deniedMcpServers`,
|
|
2223
|
+
* `blockedMarketplaces`) are kept and union with the admin's. With no admin
|
|
2224
|
+
* tier present, these apply as the sole policy tier (still filtered
|
|
2225
|
+
* restrictive-only — non-allowlisted keys are dropped regardless).
|
|
2162
2226
|
*
|
|
2163
2227
|
* Intended for embedding applications (e.g. desktop apps) that derive
|
|
2164
2228
|
* lockdown settings from their own enterprise configuration and need to
|
|
@@ -2686,6 +2750,80 @@ export declare type PreToolUseHookSpecificOutput = {
|
|
|
2686
2750
|
additionalContext?: string;
|
|
2687
2751
|
};
|
|
2688
2752
|
|
|
2753
|
+
/**
|
|
2754
|
+
* Start a Claude Code process as a parked **spare** before the session it
|
|
2755
|
+
* will serve is known, and bind it later with {@link SpareProcess.claim}.
|
|
2756
|
+
*
|
|
2757
|
+
* What runs now, at `prewarm()`: process start, module load, config, auth,
|
|
2758
|
+
* tools, user-level skills/plugins/commands, the host-level MCP servers in
|
|
2759
|
+
* `options.mcpServers` (including in-process SDK servers and their
|
|
2760
|
+
* handshakes), hooks and `canUseTool` registration, the initialize handshake —
|
|
2761
|
+
* everything `startup()` does, in a private parking directory under the
|
|
2762
|
+
* user's config home (or `options.cwd` if given, which is never the
|
|
2763
|
+
* session's folder). A host whose `spawnClaudeCodeProcess` runs Claude Code on
|
|
2764
|
+
* another machine or in a container must pass `options.cwd`: a directory that
|
|
2765
|
+
* exists there (the default one is created on this machine). What waits
|
|
2766
|
+
* for the claim: the working directory, SessionStart hooks, session
|
|
2767
|
+
* registration, CLAUDE.md and git context, the transcript location. While
|
|
2768
|
+
* parked the process holds roughly 230–260 MB and is otherwise idle.
|
|
2769
|
+
*
|
|
2770
|
+
* What a claim can set ({@link ClaimOptions}): `cwd`, `additionalDirectories`,
|
|
2771
|
+
* `model`, `permissionMode`, `maxThinkingTokens`, a flag-settings overlay
|
|
2772
|
+
* (`settings`, e.g. effort or permission rules — but not hook settings, which
|
|
2773
|
+
* would land after the claimed folder's SessionStart hooks have started; those
|
|
2774
|
+
* go in `Options.settings` here), `appendSystemPrompt`, `title`, `agents`, and
|
|
2775
|
+
* three environment variables (`CLAUDE_CODE_OAUTH_TOKEN`,
|
|
2776
|
+
* `CLAUDE_CODE_SESSION_ACCESS_TOKEN`, `CLAUDE_CODE_HOST_SESSION_ID`). Everything
|
|
2777
|
+
* else — the executable, `settingSources`, `env` the process reads at
|
|
2778
|
+
* start-up, `systemPrompt` presets, `mcpServers`, `hooks`, `canUseTool`,
|
|
2779
|
+
* `skills`, `allowedTools`/`disallowedTools`, a main-thread `agent`, plugins —
|
|
2780
|
+
* is fixed at `prewarm()`: keep one spare per distinct set of those, and when
|
|
2781
|
+
* they change (sign-out, settings that alter them, an updated executable)
|
|
2782
|
+
* `close()` the spare and prewarm again.
|
|
2783
|
+
*
|
|
2784
|
+
* Not every claim can be honoured: the process refuses a folder whose project
|
|
2785
|
+
* settings set `env`, `agent`, `model` (or `permissions.defaultMode` when no
|
|
2786
|
+
* `permissionMode` was given at prewarm), a `permissionMode` it cannot take
|
|
2787
|
+
* (it travels inside the claim so this fails closed), a `settings` overlay it
|
|
2788
|
+
* cannot apply (the prompt is held until the overlay is accepted, so this
|
|
2789
|
+
* fails closed too), an environment key outside the three above, a network
|
|
2790
|
+
* path, or a missing folder; a parked process can also die. In all of those
|
|
2791
|
+
* {@link SpareProcess.claimed} rejects, the process goes away on its own
|
|
2792
|
+
* (`close()` only releases its in-process MCP servers and callbacks sooner),
|
|
2793
|
+
* and this version leaves the fallback to the host: start that session with
|
|
2794
|
+
* `query()` as before. One rejection is different: `option_not_applied`
|
|
2795
|
+
* means only `model` or `maxThinkingTokens` was refused — the prompt was
|
|
2796
|
+
* sent and the session is running, so do not start it again. A CLI too old
|
|
2797
|
+
* to know `--await-claim` makes `prewarm()` itself reject.
|
|
2798
|
+
*
|
|
2799
|
+
* Compared with `startup()`: `startup()` needs the session's folder and
|
|
2800
|
+
* options up front and saves only the spawn; `prewarm()` needs neither and
|
|
2801
|
+
* also keeps tools, plugins and MCP handshakes off the first message.
|
|
2802
|
+
*
|
|
2803
|
+
* After a claim the Query's `initializationResult()`, `supportedAgents()`,
|
|
2804
|
+
* `supportedCommands()` and `accountInfo()` describe the claimed session,
|
|
2805
|
+
* not the parking directory ({@link SpareProcess.claim} names the one limit:
|
|
2806
|
+
* the snapshot predates `model`/`settings`).
|
|
2807
|
+
*
|
|
2808
|
+
* @example
|
|
2809
|
+
* ```typescript
|
|
2810
|
+
* const spare = await prewarm({ options: hostLevelOptions })
|
|
2811
|
+
* // …later, when the user starts a session in `folder`:
|
|
2812
|
+
* const q = spare.claim({ prompt, options: { cwd: folder, model } })
|
|
2813
|
+
* spare.claimed.catch((e: Error) => {
|
|
2814
|
+
* // refused, died or overlay refused: fall back to query(); on
|
|
2815
|
+
* // option_not_applied the session is already running without that option
|
|
2816
|
+
* if (!e.message.startsWith('option_not_applied')) startNormally()
|
|
2817
|
+
* })
|
|
2818
|
+
* for await (const message of q) { … }
|
|
2819
|
+
* ```
|
|
2820
|
+
* @alpha
|
|
2821
|
+
*/
|
|
2822
|
+
export declare function prewarm(_params?: {
|
|
2823
|
+
options?: Options;
|
|
2824
|
+
initializeTimeoutMs?: number;
|
|
2825
|
+
}): Promise<SpareProcess>;
|
|
2826
|
+
|
|
2689
2827
|
/**
|
|
2690
2828
|
* Per-key provenance entry.
|
|
2691
2829
|
* @alpha
|
|
@@ -2774,9 +2912,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2774
2912
|
* and when omitted the display mode from session start (`thinking.display`
|
|
2775
2913
|
* / `--thinking-display`) is kept — a session started with thinking
|
|
2776
2914
|
* disabled has none, so re-enabling without this param gets that default.
|
|
2777
|
-
* `'highlights'` (the API's one-line thinking titles) is honored by the
|
|
2778
|
-
*
|
|
2779
|
-
*
|
|
2915
|
+
* `'highlights'` (the API's one-line thinking titles) is honored by the API
|
|
2916
|
+
* only for Anthropic-hosted remote sessions; the promise rejects, changing
|
|
2917
|
+
* nothing, when the session cannot send it to the API.
|
|
2780
2918
|
*/
|
|
2781
2919
|
setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | 'highlights' | null): Promise<void>;
|
|
2782
2920
|
/**
|
|
@@ -2819,7 +2957,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2819
2957
|
updateSettings(source: 'localSettings' | 'userSettings', settings: Record<string, unknown>): Promise<void>;
|
|
2820
2958
|
/**
|
|
2821
2959
|
* Get the full initialization result, including supported commands, models,
|
|
2822
|
-
* account info, and output style configuration
|
|
2960
|
+
* account info, and output style configuration: the first-connect answer,
|
|
2961
|
+
* or, on a Query returned by a pre-warmed spare's `claim()`, the claimed
|
|
2962
|
+
* session's.
|
|
2823
2963
|
*
|
|
2824
2964
|
* @returns The complete initialization response
|
|
2825
2965
|
*/
|
|
@@ -2845,7 +2985,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2845
2985
|
* re-send if the call races an unanswered hook.
|
|
2846
2986
|
*
|
|
2847
2987
|
* Unlike {@link Query.initializationResult}, this always sends a fresh request
|
|
2848
|
-
* rather than returning the cached
|
|
2988
|
+
* rather than returning the cached result.
|
|
2849
2989
|
*
|
|
2850
2990
|
* @returns A fresh initialization response
|
|
2851
2991
|
*/
|
|
@@ -4541,7 +4681,7 @@ export declare type SDKControlMcpReadResourceResponse = {
|
|
|
4541
4681
|
*/
|
|
4542
4682
|
blob?: string;
|
|
4543
4683
|
/**
|
|
4544
|
-
* The content item's own `_meta
|
|
4684
|
+
* The content item's own `_meta` as the server sent it (MCP Apps puts the resource's `ui.csp` and `ui.permissions` here), minus keys under the CLI-reserved `com.anthropic/` prefix.
|
|
4545
4685
|
*/
|
|
4546
4686
|
_meta?: Record<string, unknown>;
|
|
4547
4687
|
}[];
|
|
@@ -4867,7 +5007,7 @@ declare type SDKControlSetColorRequest = {
|
|
|
4867
5007
|
};
|
|
4868
5008
|
|
|
4869
5009
|
/**
|
|
4870
|
-
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is
|
|
5010
|
+
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is null, thinking resets to the session default: any mid-session budget override is cleared (back to the spawn-time budget, if one was set), and thinking stays off for sessions that have it disabled. When max_thinking_tokens is omitted, the budget is left as it is, so a request that only changes thinking_display can leave the field out. thinking_display optionally sets the thinking display mode for the rest of the session: a value replaces the session display mode, null clears that override so Claude Code's default display handling applies again, and when omitted the display mode from session start (--thinking-display) is kept. 'highlights' returns one short title per stretch of thinking instead of a prose summary. The API accepts it only from Claude Code sessions that Anthropic hosts; if the API rejects it, the session sends 'omitted' (no thinking text) in its place from then on. A request for 'highlights' fails, and changes neither the budget nor the display, after such a rejection, on Amazon Bedrock, Google Vertex AI or another provider without Anthropic's first-party beta features, when experimental betas are off (CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS or organization policy), or on a Claude 3 model (except on Microsoft Foundry).
|
|
4871
5011
|
*/
|
|
4872
5012
|
declare type SDKControlSetMaxThinkingTokensRequest = {
|
|
4873
5013
|
subtype: 'set_max_thinking_tokens';
|
|
@@ -5173,7 +5313,7 @@ export declare type SDKMessageOrigin = {
|
|
|
5173
5313
|
/**
|
|
5174
5314
|
* Present when the delivery is the fired stored prompt of a scheduled task/routine ('scheduled-trigger', stamped from server-asserted provenance, or declared by a local host for its own scheduled runs; the schedule attests storage, not authorship) or a coordinator co-member SendMessage delivery ('peer-send-message': model-authored text from another of the same user's sessions, verified by the server-stamped receiver co-membership — task-notification for prompt authority, but distinguishable so the receive-side crossSessionInbound setting can apply to it). The harness frames a scheduled-trigger delivery as the session's assigned task instead of the generic background-notification frame. Absent on webhook, PR-steward, plugin, and background-event deliveries.
|
|
5175
5315
|
*/
|
|
5176
|
-
subkind?: 'scheduled-trigger' | 'peer-send-message' | 'projects-relay';
|
|
5316
|
+
subkind?: 'scheduled-trigger' | 'peer-send-message' | 'projects-relay' | 'session-inbox';
|
|
5177
5317
|
/**
|
|
5178
5318
|
* On a 'scheduled-trigger' delivery, why it fired: a short lowercase token such as 'scheduled', 'manual', 'retry', 'catch_up' or 'api'. Set by the server for cloud routines, or declared by a local host for its own scheduled runs, which is honored only in a process the host started with CLAUDE_CODE_HOST_SCHEDULED_RUN=1 (a local host's value is kept only if it is 1 to 32 lowercase letters or underscores); absent when neither sent one.
|
|
5179
5319
|
*/
|
|
@@ -5289,6 +5429,7 @@ export declare type SDKPartialAssistantMessage = {
|
|
|
5289
5429
|
uuid: UUID;
|
|
5290
5430
|
session_id: string;
|
|
5291
5431
|
ttft_ms?: number;
|
|
5432
|
+
|
|
5292
5433
|
/**
|
|
5293
5434
|
* Client uuid of the user message this turn is answering (submitMessage options.uuid), stamped on a non-ping stream event each time that send changes: the turn's FIRST non-ping stream event (normally the frame that triggers the turn's initial ack), and, for a turn started by a synthetic (meta) prompt, the first non-ping stream event after each queued user message folded in mid-turn takes the echo over (see SDKAssistantMessage.user_message_uuid for the rule) — so a consumer can bind the reply stream to the send it answers without waiting for the result. A turn started by a typed prompt stamps only its first non-ping stream event; independently, its first complete assistant message is stamped as well (see SDKAssistantMessage.user_message_uuid), so the same uuid may appear on both. Absent on every other stream event of the turn, on turns that neither had a client uuid nor folded a user message in, and from older producers.
|
|
5294
5435
|
*/
|
|
@@ -5549,6 +5690,7 @@ export declare type SDKResultSuccess = {
|
|
|
5549
5690
|
|
|
5550
5691
|
|
|
5551
5692
|
|
|
5693
|
+
|
|
5552
5694
|
first_text_post_ms?: number;
|
|
5553
5695
|
first_text_post_wall_ms?: number;
|
|
5554
5696
|
time_to_request_from_spawn_ms?: number;
|
|
@@ -5668,7 +5810,7 @@ export declare type SDKSettingsParseError = {
|
|
|
5668
5810
|
};
|
|
5669
5811
|
|
|
5670
5812
|
/**
|
|
5671
|
-
* 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. 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,
|
|
5813
|
+
* 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. 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.
|
|
5672
5814
|
*/
|
|
5673
5815
|
export declare type SDKStartupFailureReason = 'org_pin_api_key_conflict' | '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';
|
|
5674
5816
|
|
|
@@ -5731,7 +5873,18 @@ export declare type SDKSystemMessage = {
|
|
|
5731
5873
|
*/
|
|
5732
5874
|
version?: string;
|
|
5733
5875
|
}[];
|
|
5734
|
-
|
|
5876
|
+
/**
|
|
5877
|
+
* 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`. A session whose frames are persisted server-side (a Remote Control worker) always omits this key — plugin diagnostics stay in the local log there, so an omitted key does not assert a clean load.
|
|
5878
|
+
*/
|
|
5879
|
+
plugin_errors?: {
|
|
5880
|
+
plugin: string;
|
|
5881
|
+
type: string;
|
|
5882
|
+
message: string;
|
|
5883
|
+
/**
|
|
5884
|
+
* 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.
|
|
5885
|
+
*/
|
|
5886
|
+
path?: string;
|
|
5887
|
+
}[];
|
|
5735
5888
|
|
|
5736
5889
|
|
|
5737
5890
|
fast_mode_state?: FastModeState;
|
|
@@ -6598,13 +6751,21 @@ export declare interface Settings {
|
|
|
6598
6751
|
*/
|
|
6599
6752
|
fallbackModel?: string[];
|
|
6600
6753
|
/**
|
|
6601
|
-
* Allowlist of models that users can select. Accepts family aliases ("opus" allows any opus version), version prefixes ("opus-4-5" allows
|
|
6754
|
+
* Allowlist of models that users can select. Accepts family aliases ("opus" allows any opus version), version prefixes ("opus-4-5" allows that version and any model ID that extends it, so "claude-opus-5" also allows "claude-opus-5-5"), and full model IDs. If undefined, all models are available. If empty array, only the default model is available. Typically set in managed settings by enterprise administrators.
|
|
6602
6755
|
*/
|
|
6603
6756
|
availableModels?: string[];
|
|
6604
6757
|
/**
|
|
6605
6758
|
* When true and availableModels is a non-empty array, the Default model selection is also constrained: if the default model for the user tier is not in availableModels, Default resolves to the first allowed availableModels entry instead. Has no effect when availableModels is unset or an empty array. Typically set in managed settings by enterprise administrators.
|
|
6606
6759
|
*/
|
|
6607
6760
|
enforceAvailableModels?: boolean;
|
|
6761
|
+
/**
|
|
6762
|
+
* How availableModels entries match model IDs. "prefix" (the default) lets an entry also allow any model ID that extends it, so "claude-opus-5" allows "claude-opus-5-5". "exact" keeps that matching but stops a model ID entry from allowing other versions: "claude-opus-5" allows Opus 5 and its dated and -fast IDs, but not Opus 5.5 or a later release until it is listed, and a -latest ID needs a -latest entry. Family aliases ("opus") still allow the whole family; aliases whose model depends on the release or settings (best, opusplan, default) are ignored. With "exact" and a list that names at least one model, the Default option also uses only a listed model; if none can be used, Claude Code will not start. Haiku background models, and hooks and other helper requests that pick their own model, are not restricted (deniedModels covers them; allowManagedHooksOnly limits hooks). Read from managed settings only.
|
|
6763
|
+
*/
|
|
6764
|
+
availableModelsMatch?: 'prefix' | 'exact';
|
|
6765
|
+
/**
|
|
6766
|
+
* Models users cannot select, even when availableModels allows them. A family alias ("opus") blocks that family. A model ID blocks that version in every spelling: dates, -fast and provider prefixes are ignored, so "claude-opus-5-5" blocks every Opus 5.5 ID but not Opus 5. An ID with no minor version ("claude-opus-5") also blocks later minor versions, as it allows them in availableModels. Aliases whose model depends on the release or settings (best, opusplan, default) are ignored. The Default option steps down past a blocked model; if the Default has no allowed model to step down to, Claude Code will not start. Read from managed settings only.
|
|
6767
|
+
*/
|
|
6768
|
+
deniedModels?: string[];
|
|
6608
6769
|
/**
|
|
6609
6770
|
* Override mapping from Anthropic model ID (e.g. "claude-opus-4-6") to provider-specific model ID (e.g. a Bedrock inference profile ARN). Typically set in managed settings by enterprise administrators.
|
|
6610
6771
|
*/
|
|
@@ -7017,7 +7178,7 @@ export declare interface Settings {
|
|
|
7017
7178
|
*/
|
|
7018
7179
|
httpHookAllowedEnvVars?: string[];
|
|
7019
7180
|
/**
|
|
7020
|
-
* 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. --disallowedTools and other deny and ask rules from the command line or the current session still apply.
|
|
7181
|
+
* 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 Claude Code adopts from a .claude-plugin manifest inside those skills directories, is ignored too; other plugins and 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.
|
|
7021
7182
|
*/
|
|
7022
7183
|
allowManagedPermissionRulesOnly?: boolean;
|
|
7023
7184
|
/**
|
|
@@ -7028,6 +7189,10 @@ export declare interface Settings {
|
|
|
7028
7189
|
* When true (and set in managed settings), claude.ai cloud MCP connectors load alongside managed-mcp.json instead of being suppressed by its exclusive-control lockdown. Default off preserves the lockdown. Read from managed settings only.
|
|
7029
7190
|
*/
|
|
7030
7191
|
allowAllClaudeAiMcps?: boolean;
|
|
7192
|
+
/**
|
|
7193
|
+
* When true (and set in device managed settings: MDM, the managed-settings.json file, or a policy helper those configure), the built-in Claude in Chrome MCP server can run alongside managed-mcp.json instead of being blocked by its exclusive-control lockdown. deniedMcpServers and the organization's Claude in Chrome setting still block it. Default off preserves the lockdown.
|
|
7194
|
+
*/
|
|
7195
|
+
allowClaudeInChromeWithManagedMcp?: boolean;
|
|
7031
7196
|
/**
|
|
7032
7197
|
* When set in managed settings, blocks non-plugin customization sources for the listed surfaces. Array form locks specific surfaces (e.g. ["skills", "hooks"]); `true` locks all four; `false` is an explicit no-op. Blocked: ~/.claude/{surface}/, .claude/{surface}/ (project), settings.json hooks, .mcp.json. NOT blocked: managed (policySettings) sources, plugin-provided customizations. Composes with strictKnownMarketplaces for end-to-end admin control — plugins gated by marketplace allowlist, everything else blocked here.
|
|
7033
7198
|
*/
|
|
@@ -8574,6 +8739,9 @@ export declare interface Settings {
|
|
|
8574
8739
|
* macOS only: Allow sandboxed commands to send Apple Events (and look up the appleeventsd Mach service). Needed for `open`, `osascript`, and browser-based auth flows that open URLs. **Removes code-execution isolation** — sandboxed commands can launch other applications unsandboxed with no user prompt, and can script running apps (e.g. Terminal) subject to the user's per-app TCC automation consent. Only honored from user, managed/policy, or CLI (--settings) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored. Default: false
|
|
8575
8740
|
*/
|
|
8576
8741
|
allowAppleEvents?: boolean;
|
|
8742
|
+
/**
|
|
8743
|
+
* Command patterns (Bash permission-rule syntax) that always run outside the sandbox. A convenience, not a security boundary: excluded commands still go through the permission flow. Merged across settings sources. When managed settings or a --settings file set allowUnsandboxedCommands: false, or managed settings set network.allowManagedDomainsOnly: true, values from project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
|
|
8744
|
+
*/
|
|
8577
8745
|
excludedCommands?: string[];
|
|
8578
8746
|
/**
|
|
8579
8747
|
* Custom ripgrep configuration for bundled ripgrep support. Only honored from user, managed/policy, or CLI (--settings) settings — project settings (.claude/settings.json and .claude/settings.local.json) are ignored.
|
|
@@ -8633,6 +8801,10 @@ export declare interface Settings {
|
|
|
8633
8801
|
* Whether to disable syntax highlighting in diffs
|
|
8634
8802
|
*/
|
|
8635
8803
|
syntaxHighlightingDisabled?: boolean;
|
|
8804
|
+
/**
|
|
8805
|
+
* Maximum width, in terminal columns, of the prose in Claude's responses (paragraphs, headings, lists, blockquotes). In a wider terminal the prose wraps at this width while tables and code blocks keep the full width; only the display wraps, the response text itself gains no line breaks. Minimum 40. Unset (the default) uses the full terminal width.
|
|
8806
|
+
*/
|
|
8807
|
+
maxProseWidth?: number;
|
|
8636
8808
|
/**
|
|
8637
8809
|
* Underline misspelled words in the prompt input as you type, using an installed aspell, hunspell or ispell (off unless "enabled" is true; does nothing if none is installed). Read from user, flag and managed settings only (the whole block from the highest-precedence of those applies); ignored in project .claude/settings.json and .claude/settings.local.json.
|
|
8638
8810
|
*/
|
|
@@ -9068,6 +9240,89 @@ export declare type SlashCommand = {
|
|
|
9068
9240
|
builtin?: boolean;
|
|
9069
9241
|
};
|
|
9070
9242
|
|
|
9243
|
+
/**
|
|
9244
|
+
* A parked, fully started Claude Code process that is not yet any session
|
|
9245
|
+
* (see {@link prewarm}). `claim()` binds it to a session and sends the first
|
|
9246
|
+
* message; `close()` discards it. Single use.
|
|
9247
|
+
* @alpha
|
|
9248
|
+
*/
|
|
9249
|
+
export declare interface SpareProcess extends AsyncDisposable {
|
|
9250
|
+
/**
|
|
9251
|
+
* Bind the spare to a session and send its first message. Synchronous, like
|
|
9252
|
+
* `query()`: it writes the claim, the per-session settings and the prompt
|
|
9253
|
+
* to the waiting process and returns the Query; consume the Query's messages
|
|
9254
|
+
* as usual (a claim with a `settings` overlay sends the prompt one round
|
|
9255
|
+
* trip later, once the overlay is accepted — see {@link ClaimOptions}). Can
|
|
9256
|
+
* only be called once.
|
|
9257
|
+
*
|
|
9258
|
+
* If the process cannot honour the claim (see {@link ClaimOptions}),
|
|
9259
|
+
* {@link SpareProcess.claimed} rejects with the reason, a prompt already
|
|
9260
|
+
* sent is answered with an error result whose text starts with
|
|
9261
|
+
* `not_claimed` (the Query then ends as any query with an error result
|
|
9262
|
+
* does), and the process is let go: it exits once it has answered. Start
|
|
9263
|
+
* the session with `query()` instead. `close()` is not needed for the
|
|
9264
|
+
* process to go away, but it releases what the spare holds in this process
|
|
9265
|
+
* — in-process (`type: 'sdk'`) MCP server instances, hook and tool
|
|
9266
|
+
* callbacks — at once rather than at exit, so call it first if the
|
|
9267
|
+
* fallback `query()` reuses those same objects.
|
|
9268
|
+
*
|
|
9269
|
+
* The returned Query's `initializationResult()`, `supportedCommands()`,
|
|
9270
|
+
* `supportedAgents()`, `supportedModels()` and `accountInfo()` wait for the
|
|
9271
|
+
* claim's answer and then describe the claimed session — the folder's
|
|
9272
|
+
* agents, commands and output styles, the claimed permission mode — as they
|
|
9273
|
+
* would after a cold `query()` in that folder (the folder's `availableModels`
|
|
9274
|
+
* narrows the model list as it does there). One limit: that snapshot is
|
|
9275
|
+
* taken as part of the claim, before `model` and `settings` are applied, so
|
|
9276
|
+
* fields the model or the settings overlay decide (for example
|
|
9277
|
+
* `fast_mode_state`, `output_style`, the remote-control defaults, an
|
|
9278
|
+
* `availableModels` in the overlay) may not reflect them yet. After a refused claim the reads
|
|
9279
|
+
* keep describing the parked process; after `option_not_applied` or
|
|
9280
|
+
* `settings_not_applied` (the claim itself took) they describe the claimed
|
|
9281
|
+
* session.
|
|
9282
|
+
*
|
|
9283
|
+
* @throws when called a second time, when the spare was closed or has
|
|
9284
|
+
* exited, or when `options.settings` carries a key that governs hooks (see
|
|
9285
|
+
* {@link ClaimOptions}) — in that last case nothing has been sent and the
|
|
9286
|
+
* spare stays parked, so it can still be claimed.
|
|
9287
|
+
*/
|
|
9288
|
+
claim(params: {
|
|
9289
|
+
prompt: string | AsyncIterable<SDKUserMessage>;
|
|
9290
|
+
options: ClaimOptions;
|
|
9291
|
+
}): Query;
|
|
9292
|
+
/**
|
|
9293
|
+
* Settles once the process has answered the claim AND the per-session
|
|
9294
|
+
* settings sent with it: resolves with the canonical working directory, the
|
|
9295
|
+
* session id and how long the spare was parked. Rejects — and the host
|
|
9296
|
+
* should start the session with `query()` instead — when the claim is
|
|
9297
|
+
* refused (`not_a_spare`, `env_key_not_claimable`, `cwd_not_found`,
|
|
9298
|
+
* `project_settings_not_claimable`, `permission_mode_not_claimable`, …; a
|
|
9299
|
+
* prompt already sent gets the `not_claimed` error result and the process
|
|
9300
|
+
* exits), when the claim broke after it began (`claim_failed`; likewise),
|
|
9301
|
+
* when the spare exited or was closed before a claim (`spare_exited` /
|
|
9302
|
+
* `spare_closed`), or when the `settings` overlay was refused
|
|
9303
|
+
* (`settings_not_applied: …`; the prompt was never sent and the process
|
|
9304
|
+
* was closed). In all of those your prompt has not run. The one rejection
|
|
9305
|
+
* after which it does run is `option_not_applied: …`: `model` or
|
|
9306
|
+
* `maxThinkingTokens` was not accepted and the session runs without it.
|
|
9307
|
+
* Both `…_not_applied` errors carry `.claim` with the claim info.
|
|
9308
|
+
* `permissionMode` is part of the claim itself and fails closed: see
|
|
9309
|
+
* {@link ClaimOptions}.
|
|
9310
|
+
*/
|
|
9311
|
+
readonly claimed: Promise<{
|
|
9312
|
+
cwd: string;
|
|
9313
|
+
sessionId: string;
|
|
9314
|
+
parkedMs?: number;
|
|
9315
|
+
sdkMcpSettled: boolean;
|
|
9316
|
+
}>;
|
|
9317
|
+
/** Settles when the spare's process exits, claimed or not — a parked spare that dies should be replaced. */
|
|
9318
|
+
readonly exited: Promise<void>;
|
|
9319
|
+
/**
|
|
9320
|
+
* Terminate the process. Before a claim this discards the spare (and
|
|
9321
|
+
* rejects `claimed`); after one it is the same as closing the Query.
|
|
9322
|
+
*/
|
|
9323
|
+
close(): void;
|
|
9324
|
+
}
|
|
9325
|
+
|
|
9071
9326
|
/**
|
|
9072
9327
|
* Represents a spawned process with stdin/stdout streams and lifecycle management.
|
|
9073
9328
|
* Implementers provide this interface to abstract the process spawning mechanism.
|