@anthropic-ai/claude-agent-sdk 0.3.280 → 0.3.282
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.d.ts +11 -1
- package/bridge.mjs +96 -157
- package/browser-sdk.js +56 -96
- package/core-276encc2.mjs +38 -0
- package/core-5drmq1nt.mjs +31 -0
- package/core.d.ts +20 -0
- package/core.mjs +41 -0
- package/manifest.json +24 -24
- package/manifest.zst.json +28 -28
- package/package.json +19 -11
- package/sdk-tools.d.ts +6 -6
- package/sdk.d.ts +280 -18
- package/sdk.mjs +85 -161
package/sdk-tools.d.ts
CHANGED
|
@@ -2964,7 +2964,7 @@ export interface ProposeSkillsInput {
|
|
|
2964
2964
|
| [
|
|
2965
2965
|
{
|
|
2966
2966
|
/**
|
|
2967
|
-
* kebab-case skill slug
|
|
2967
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
2968
2968
|
*/
|
|
2969
2969
|
name: string;
|
|
2970
2970
|
kind: "new" | "improvement";
|
|
@@ -2989,7 +2989,7 @@ export interface ProposeSkillsInput {
|
|
|
2989
2989
|
| [
|
|
2990
2990
|
{
|
|
2991
2991
|
/**
|
|
2992
|
-
* kebab-case skill slug
|
|
2992
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
2993
2993
|
*/
|
|
2994
2994
|
name: string;
|
|
2995
2995
|
kind: "new" | "improvement";
|
|
@@ -3012,7 +3012,7 @@ export interface ProposeSkillsInput {
|
|
|
3012
3012
|
},
|
|
3013
3013
|
{
|
|
3014
3014
|
/**
|
|
3015
|
-
* kebab-case skill slug
|
|
3015
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
3016
3016
|
*/
|
|
3017
3017
|
name: string;
|
|
3018
3018
|
kind: "new" | "improvement";
|
|
@@ -3037,7 +3037,7 @@ export interface ProposeSkillsInput {
|
|
|
3037
3037
|
| [
|
|
3038
3038
|
{
|
|
3039
3039
|
/**
|
|
3040
|
-
* kebab-case skill slug
|
|
3040
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
3041
3041
|
*/
|
|
3042
3042
|
name: string;
|
|
3043
3043
|
kind: "new" | "improvement";
|
|
@@ -3060,7 +3060,7 @@ export interface ProposeSkillsInput {
|
|
|
3060
3060
|
},
|
|
3061
3061
|
{
|
|
3062
3062
|
/**
|
|
3063
|
-
* kebab-case skill slug
|
|
3063
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
3064
3064
|
*/
|
|
3065
3065
|
name: string;
|
|
3066
3066
|
kind: "new" | "improvement";
|
|
@@ -3083,7 +3083,7 @@ export interface ProposeSkillsInput {
|
|
|
3083
3083
|
},
|
|
3084
3084
|
{
|
|
3085
3085
|
/**
|
|
3086
|
-
* kebab-case skill slug
|
|
3086
|
+
* kebab-case skill slug; must not contain "claude" or "anthropic"; at most 64 characters for a new skill
|
|
3087
3087
|
*/
|
|
3088
3088
|
name: string;
|
|
3089
3089
|
kind: "new" | "improvement";
|
package/sdk.d.ts
CHANGED
|
@@ -295,8 +295,72 @@ export declare type CanUseTool = (toolName: string, input: Record<string, unknow
|
|
|
295
295
|
toolName: string;
|
|
296
296
|
ruleContent?: string;
|
|
297
297
|
};
|
|
298
|
+
|
|
299
|
+
|
|
300
|
+
|
|
298
301
|
}) => Promise<PermissionResult | null>;
|
|
299
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
|
+
|
|
300
364
|
export declare type ConfigChangeHookInput = BaseHookInput & {
|
|
301
365
|
hook_event_name: 'ConfigChange';
|
|
302
366
|
source: 'user_settings' | 'project_settings' | 'local_settings' | 'policy_settings' | 'skills';
|
|
@@ -321,6 +385,7 @@ declare type ControlErrorResponse = {
|
|
|
321
385
|
* Human-readable failure description.
|
|
322
386
|
*/
|
|
323
387
|
error: string;
|
|
388
|
+
|
|
324
389
|
/**
|
|
325
390
|
* can_use_tool requests this CLI process has issued and not yet resolved, so a client joining an already-initialized session learns about in-flight prompts. Always present (possibly empty) on a success `initialize` response from Claude Code v2.1.268 or later; earlier versions could omit it, so treat absence as an older CLI rather than as "nothing pending". A prompt inherited from a previous worker of the same session can remain answerable without appearing here and without a control_cancel_request; session_state "requires_action" on the same reply signals one the CLI is holding, but not every inherited prompt is signalled.
|
|
326
391
|
*/
|
|
@@ -2147,12 +2212,17 @@ export declare type Options = {
|
|
|
2147
2212
|
* IT-controlled managed-settings tier (server / MDM / managed-settings.json)
|
|
2148
2213
|
* exists on the user's machine, these are **dropped by default** — they only
|
|
2149
2214
|
* layer in if that admin opts in via `parentSettingsBehavior: 'merge'` in
|
|
2150
|
-
* their managed settings
|
|
2215
|
+
* their managed settings (a gateway-mode session that Claude Desktop's Code
|
|
2216
|
+
* tab launches merges them by default; `'first-wins'` in the highest-priority
|
|
2217
|
+
* managed source turns that off). Even when opted in, the value is filtered
|
|
2151
2218
|
* restrictive-only: permissive arrays (`permissions.allow`,
|
|
2152
|
-
* `additionalDirectories`,
|
|
2153
|
-
*
|
|
2154
|
-
*
|
|
2155
|
-
*
|
|
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).
|
|
2156
2226
|
*
|
|
2157
2227
|
* Intended for embedding applications (e.g. desktop apps) that derive
|
|
2158
2228
|
* lockdown settings from their own enterprise configuration and need to
|
|
@@ -2680,6 +2750,80 @@ export declare type PreToolUseHookSpecificOutput = {
|
|
|
2680
2750
|
additionalContext?: string;
|
|
2681
2751
|
};
|
|
2682
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
|
+
|
|
2683
2827
|
/**
|
|
2684
2828
|
* Per-key provenance entry.
|
|
2685
2829
|
* @alpha
|
|
@@ -2768,9 +2912,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2768
2912
|
* and when omitted the display mode from session start (`thinking.display`
|
|
2769
2913
|
* / `--thinking-display`) is kept — a session started with thinking
|
|
2770
2914
|
* disabled has none, so re-enabling without this param gets that default.
|
|
2771
|
-
* `'highlights'` (the API's one-line thinking titles) is honored by the
|
|
2772
|
-
*
|
|
2773
|
-
*
|
|
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.
|
|
2774
2918
|
*/
|
|
2775
2919
|
setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | 'highlights' | null): Promise<void>;
|
|
2776
2920
|
/**
|
|
@@ -2813,7 +2957,9 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2813
2957
|
updateSettings(source: 'localSettings' | 'userSettings', settings: Record<string, unknown>): Promise<void>;
|
|
2814
2958
|
/**
|
|
2815
2959
|
* Get the full initialization result, including supported commands, models,
|
|
2816
|
-
* 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.
|
|
2817
2963
|
*
|
|
2818
2964
|
* @returns The complete initialization response
|
|
2819
2965
|
*/
|
|
@@ -2839,7 +2985,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2839
2985
|
* re-send if the call races an unanswered hook.
|
|
2840
2986
|
*
|
|
2841
2987
|
* Unlike {@link Query.initializationResult}, this always sends a fresh request
|
|
2842
|
-
* rather than returning the cached
|
|
2988
|
+
* rather than returning the cached result.
|
|
2843
2989
|
*
|
|
2844
2990
|
* @returns A fresh initialization response
|
|
2845
2991
|
*/
|
|
@@ -2992,6 +3138,7 @@ export declare interface Query extends AsyncGenerator<SDKMessage, void> {
|
|
|
2992
3138
|
|
|
2993
3139
|
|
|
2994
3140
|
|
|
3141
|
+
|
|
2995
3142
|
/**
|
|
2996
3143
|
* Reconnect an MCP server by name.
|
|
2997
3144
|
* Throws on failure.
|
|
@@ -3530,6 +3677,7 @@ export declare type SDKAssistantMessage = {
|
|
|
3530
3677
|
|
|
3531
3678
|
|
|
3532
3679
|
|
|
3680
|
+
|
|
3533
3681
|
};
|
|
3534
3682
|
|
|
3535
3683
|
export declare type SDKAssistantMessageError = 'authentication_failed' | 'oauth_org_not_allowed' | 'account_on_hold' | 'verification_required' | 'billing_error' | 'rate_limit' | 'overloaded' | 'invalid_request' | 'model_not_found' | 'server_error' | 'unknown' | 'max_output_tokens' | 'cloud_credential_error';
|
|
@@ -4533,7 +4681,7 @@ export declare type SDKControlMcpReadResourceResponse = {
|
|
|
4533
4681
|
*/
|
|
4534
4682
|
blob?: string;
|
|
4535
4683
|
/**
|
|
4536
|
-
* 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.
|
|
4537
4685
|
*/
|
|
4538
4686
|
_meta?: Record<string, unknown>;
|
|
4539
4687
|
}[];
|
|
@@ -4623,6 +4771,8 @@ declare type SDKControlPermissionRequest = {
|
|
|
4623
4771
|
*/
|
|
4624
4772
|
requires_user_interaction?: boolean;
|
|
4625
4773
|
|
|
4774
|
+
|
|
4775
|
+
|
|
4626
4776
|
};
|
|
4627
4777
|
|
|
4628
4778
|
/**
|
|
@@ -4857,7 +5007,7 @@ declare type SDKControlSetColorRequest = {
|
|
|
4857
5007
|
};
|
|
4858
5008
|
|
|
4859
5009
|
/**
|
|
4860
|
-
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is omitted or 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. 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
|
|
5010
|
+
* Sets the maximum number of thinking tokens for extended thinking. When max_thinking_tokens is omitted or 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. 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).
|
|
4861
5011
|
*/
|
|
4862
5012
|
declare type SDKControlSetMaxThinkingTokensRequest = {
|
|
4863
5013
|
subtype: 'set_max_thinking_tokens';
|
|
@@ -4910,13 +5060,25 @@ declare type SDKControlUpdateSettingsRequest = {
|
|
|
4910
5060
|
};
|
|
4911
5061
|
|
|
4912
5062
|
/**
|
|
4913
|
-
* Emitted by /clear, plan-mode exit,
|
|
5063
|
+
* Emitted by /clear, plan-mode exit, fresh-session, and onboarding flows. The surface should mount a fresh transcript under new_conversation_id and reset any cached session title. From internal QueryEvent 'conversation_reset'.
|
|
4914
5064
|
*/
|
|
4915
5065
|
export declare type SDKConversationResetMessage = {
|
|
4916
5066
|
type: 'conversation_reset';
|
|
4917
5067
|
new_conversation_id: UUID;
|
|
4918
5068
|
uuid: UUID;
|
|
4919
5069
|
session_id: string;
|
|
5070
|
+
/**
|
|
5071
|
+
* What discarded the conversation: 'clear' is the /clear command (or its /reset and /new aliases), 'plan_mode_exit' is leaving plan mode with the clear-context option, 'fresh_session' is a flow that starts a fresh session to implement an approved plan, 'onboarding' is an onboarding flow re-run inside an existing session. Informational: a consumer should reset on every conversation_reset frame whatever this says, and treat an absent (older emitter) or unrecognized value as an unspecified reset.
|
|
5072
|
+
*/
|
|
5073
|
+
trigger?: 'clear' | 'plan_mode_exit' | 'fresh_session' | 'onboarding';
|
|
5074
|
+
/**
|
|
5075
|
+
* Only with trigger 'clear': the uuid of the user message whose /clear was executed (the client's own uuid for that message when it came from a Remote Control or stream-json client, otherwise the uuid the CLI assigned to the typed command). Lets a consumer match this frame to a /clear message it has already seen, wiping once whichever arrives first, instead of relying on arrival order. Absent for the other triggers, when that uuid is not a canonical UUID, and from older emitters.
|
|
5076
|
+
*/
|
|
5077
|
+
user_message_uuid?: string;
|
|
5078
|
+
/**
|
|
5079
|
+
* When the reset happened, as an ISO 8601 string in UTC read from the clock of the process that performed it. Meant for display, such as the time on a "conversation cleared" row, not for ordering frames. Absent from older emitters; a consumer can fall back to the time it received the frame.
|
|
5080
|
+
*/
|
|
5081
|
+
timestamp?: string;
|
|
4920
5082
|
};
|
|
4921
5083
|
|
|
4922
5084
|
export declare type SDKDeferredToolUse = {
|
|
@@ -5151,7 +5313,7 @@ export declare type SDKMessageOrigin = {
|
|
|
5151
5313
|
/**
|
|
5152
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.
|
|
5153
5315
|
*/
|
|
5154
|
-
subkind?: 'scheduled-trigger' | 'peer-send-message' | 'projects-relay';
|
|
5316
|
+
subkind?: 'scheduled-trigger' | 'peer-send-message' | 'projects-relay' | 'session-inbox';
|
|
5155
5317
|
/**
|
|
5156
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.
|
|
5157
5319
|
*/
|
|
@@ -5527,6 +5689,7 @@ export declare type SDKResultSuccess = {
|
|
|
5527
5689
|
|
|
5528
5690
|
|
|
5529
5691
|
|
|
5692
|
+
|
|
5530
5693
|
first_text_post_ms?: number;
|
|
5531
5694
|
first_text_post_wall_ms?: number;
|
|
5532
5695
|
time_to_request_from_spawn_ms?: number;
|
|
@@ -5719,6 +5882,11 @@ export declare type SDKSystemMessage = {
|
|
|
5719
5882
|
* The effort level the session will send on its next request — after env overrides, session state, org caps and model-support downgrades; the same value get_settings reports as applied.effort. null when no effort parameter will be sent (a model without effort, CLAUDE_CODE_EFFORT_LEVEL=unset, or an internal numeric budget). Present on Remote Control bridge init frames (terminal- and Desktop/VS Code-hosted sessions); absent on hosts that do not publish it and on CLIs that predate the field. Re-emitted inits carry the current value — the newest frame wins.
|
|
5720
5883
|
*/
|
|
5721
5884
|
effort?: ('low' | 'medium' | 'high' | 'xhigh' | 'max') | null;
|
|
5885
|
+
|
|
5886
|
+
/**
|
|
5887
|
+
* Whether the session's transcript is in focus view ('focus': the model is told the user sees only its final message per turn, so clients may collapse each turn to the prompt and the final response; 'default' otherwise). Toggled by /focus, including over Remote Control. Present on Remote Control bridge init frames and on the per-turn init of headless stream-json runs (`claude rc` workers, -p, the SDK's subprocess transport); absent on hosts that do not publish it (the in-process engine) and on CLIs that predate the field. Re-emitted inits carry the current value — the newest frame wins.
|
|
5888
|
+
*/
|
|
5889
|
+
view_mode?: 'focus' | 'default';
|
|
5722
5890
|
/**
|
|
5723
5891
|
* 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). Absent on older CLIs.
|
|
5724
5892
|
*/
|
|
@@ -6503,9 +6671,9 @@ export declare interface Settings {
|
|
|
6503
6671
|
[k: string]: string;
|
|
6504
6672
|
};
|
|
6505
6673
|
/**
|
|
6506
|
-
* Customize attribution text for commits and PRs. Each field defaults to the standard Claude Code attribution if not set.
|
|
6674
|
+
* Customize attribution text for commits and PRs. Each field defaults to the standard Claude Code attribution if not set. Set to false to hide all attribution, the same as { "commit": "", "pr": "", "sessionUrl": false }. Setting it to true is the same as leaving it out. Older Claude Code versions reject true or false here, so use the object form in settings files shared across versions.
|
|
6507
6675
|
*/
|
|
6508
|
-
attribution?: {
|
|
6676
|
+
attribution?: boolean | {
|
|
6509
6677
|
/**
|
|
6510
6678
|
* Attribution text for git commits, including any trailers. Empty string hides attribution.
|
|
6511
6679
|
*/
|
|
@@ -6990,7 +7158,7 @@ export declare interface Settings {
|
|
|
6990
7158
|
*/
|
|
6991
7159
|
httpHookAllowedEnvVars?: string[];
|
|
6992
7160
|
/**
|
|
6993
|
-
* 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.
|
|
7161
|
+
* 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.
|
|
6994
7162
|
*/
|
|
6995
7163
|
allowManagedPermissionRulesOnly?: boolean;
|
|
6996
7164
|
/**
|
|
@@ -7001,6 +7169,10 @@ export declare interface Settings {
|
|
|
7001
7169
|
* 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.
|
|
7002
7170
|
*/
|
|
7003
7171
|
allowAllClaudeAiMcps?: boolean;
|
|
7172
|
+
/**
|
|
7173
|
+
* 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.
|
|
7174
|
+
*/
|
|
7175
|
+
allowClaudeInChromeWithManagedMcp?: boolean;
|
|
7004
7176
|
/**
|
|
7005
7177
|
* 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.
|
|
7006
7178
|
*/
|
|
@@ -8316,7 +8488,7 @@ export declare interface Settings {
|
|
|
8316
8488
|
*/
|
|
8317
8489
|
gatewayInternalNetworks?: string[];
|
|
8318
8490
|
/**
|
|
8319
|
-
* Controls whether the SDK parent tier (Options.managedSettings / --managed-settings) layers under this admin tier. "first-wins" (default): parent is dropped — admin tiers are the only policy source. "merge": parent's restrictive-only-filtered settings union under the admin winner. Has no effect when no admin tier exists (parent applies as the sole policy tier, still filtered restrictive-only).
|
|
8491
|
+
* Controls whether the SDK parent tier (Options.managedSettings / --managed-settings) layers under this admin tier. "first-wins" (the default, except in a gateway session Claude Desktop's Code tab launched, where "merge" is): parent is dropped — admin tiers are the only policy source. "merge": parent's restrictive-only-filtered settings union under the admin winner. Has no effect when no admin tier exists (parent applies as the sole policy tier, still filtered restrictive-only).
|
|
8320
8492
|
*/
|
|
8321
8493
|
parentSettingsBehavior?: 'first-wins' | 'merge';
|
|
8322
8494
|
/**
|
|
@@ -8547,6 +8719,9 @@ export declare interface Settings {
|
|
|
8547
8719
|
* 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
|
|
8548
8720
|
*/
|
|
8549
8721
|
allowAppleEvents?: boolean;
|
|
8722
|
+
/**
|
|
8723
|
+
* 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.
|
|
8724
|
+
*/
|
|
8550
8725
|
excludedCommands?: string[];
|
|
8551
8726
|
/**
|
|
8552
8727
|
* 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.
|
|
@@ -8606,6 +8781,10 @@ export declare interface Settings {
|
|
|
8606
8781
|
* Whether to disable syntax highlighting in diffs
|
|
8607
8782
|
*/
|
|
8608
8783
|
syntaxHighlightingDisabled?: boolean;
|
|
8784
|
+
/**
|
|
8785
|
+
* 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.
|
|
8786
|
+
*/
|
|
8787
|
+
maxProseWidth?: number;
|
|
8609
8788
|
/**
|
|
8610
8789
|
* 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.
|
|
8611
8790
|
*/
|
|
@@ -9041,6 +9220,89 @@ export declare type SlashCommand = {
|
|
|
9041
9220
|
builtin?: boolean;
|
|
9042
9221
|
};
|
|
9043
9222
|
|
|
9223
|
+
/**
|
|
9224
|
+
* A parked, fully started Claude Code process that is not yet any session
|
|
9225
|
+
* (see {@link prewarm}). `claim()` binds it to a session and sends the first
|
|
9226
|
+
* message; `close()` discards it. Single use.
|
|
9227
|
+
* @alpha
|
|
9228
|
+
*/
|
|
9229
|
+
export declare interface SpareProcess extends AsyncDisposable {
|
|
9230
|
+
/**
|
|
9231
|
+
* Bind the spare to a session and send its first message. Synchronous, like
|
|
9232
|
+
* `query()`: it writes the claim, the per-session settings and the prompt
|
|
9233
|
+
* to the waiting process and returns the Query; consume the Query's messages
|
|
9234
|
+
* as usual (a claim with a `settings` overlay sends the prompt one round
|
|
9235
|
+
* trip later, once the overlay is accepted — see {@link ClaimOptions}). Can
|
|
9236
|
+
* only be called once.
|
|
9237
|
+
*
|
|
9238
|
+
* If the process cannot honour the claim (see {@link ClaimOptions}),
|
|
9239
|
+
* {@link SpareProcess.claimed} rejects with the reason, a prompt already
|
|
9240
|
+
* sent is answered with an error result whose text starts with
|
|
9241
|
+
* `not_claimed` (the Query then ends as any query with an error result
|
|
9242
|
+
* does), and the process is let go: it exits once it has answered. Start
|
|
9243
|
+
* the session with `query()` instead. `close()` is not needed for the
|
|
9244
|
+
* process to go away, but it releases what the spare holds in this process
|
|
9245
|
+
* — in-process (`type: 'sdk'`) MCP server instances, hook and tool
|
|
9246
|
+
* callbacks — at once rather than at exit, so call it first if the
|
|
9247
|
+
* fallback `query()` reuses those same objects.
|
|
9248
|
+
*
|
|
9249
|
+
* The returned Query's `initializationResult()`, `supportedCommands()`,
|
|
9250
|
+
* `supportedAgents()`, `supportedModels()` and `accountInfo()` wait for the
|
|
9251
|
+
* claim's answer and then describe the claimed session — the folder's
|
|
9252
|
+
* agents, commands and output styles, the claimed permission mode — as they
|
|
9253
|
+
* would after a cold `query()` in that folder (the folder's `availableModels`
|
|
9254
|
+
* narrows the model list as it does there). One limit: that snapshot is
|
|
9255
|
+
* taken as part of the claim, before `model` and `settings` are applied, so
|
|
9256
|
+
* fields the model or the settings overlay decide (for example
|
|
9257
|
+
* `fast_mode_state`, `output_style`, the remote-control defaults, an
|
|
9258
|
+
* `availableModels` in the overlay) may not reflect them yet. After a refused claim the reads
|
|
9259
|
+
* keep describing the parked process; after `option_not_applied` or
|
|
9260
|
+
* `settings_not_applied` (the claim itself took) they describe the claimed
|
|
9261
|
+
* session.
|
|
9262
|
+
*
|
|
9263
|
+
* @throws when called a second time, when the spare was closed or has
|
|
9264
|
+
* exited, or when `options.settings` carries a key that governs hooks (see
|
|
9265
|
+
* {@link ClaimOptions}) — in that last case nothing has been sent and the
|
|
9266
|
+
* spare stays parked, so it can still be claimed.
|
|
9267
|
+
*/
|
|
9268
|
+
claim(params: {
|
|
9269
|
+
prompt: string | AsyncIterable<SDKUserMessage>;
|
|
9270
|
+
options: ClaimOptions;
|
|
9271
|
+
}): Query;
|
|
9272
|
+
/**
|
|
9273
|
+
* Settles once the process has answered the claim AND the per-session
|
|
9274
|
+
* settings sent with it: resolves with the canonical working directory, the
|
|
9275
|
+
* session id and how long the spare was parked. Rejects — and the host
|
|
9276
|
+
* should start the session with `query()` instead — when the claim is
|
|
9277
|
+
* refused (`not_a_spare`, `env_key_not_claimable`, `cwd_not_found`,
|
|
9278
|
+
* `project_settings_not_claimable`, `permission_mode_not_claimable`, …; a
|
|
9279
|
+
* prompt already sent gets the `not_claimed` error result and the process
|
|
9280
|
+
* exits), when the claim broke after it began (`claim_failed`; likewise),
|
|
9281
|
+
* when the spare exited or was closed before a claim (`spare_exited` /
|
|
9282
|
+
* `spare_closed`), or when the `settings` overlay was refused
|
|
9283
|
+
* (`settings_not_applied: …`; the prompt was never sent and the process
|
|
9284
|
+
* was closed). In all of those your prompt has not run. The one rejection
|
|
9285
|
+
* after which it does run is `option_not_applied: …`: `model` or
|
|
9286
|
+
* `maxThinkingTokens` was not accepted and the session runs without it.
|
|
9287
|
+
* Both `…_not_applied` errors carry `.claim` with the claim info.
|
|
9288
|
+
* `permissionMode` is part of the claim itself and fails closed: see
|
|
9289
|
+
* {@link ClaimOptions}.
|
|
9290
|
+
*/
|
|
9291
|
+
readonly claimed: Promise<{
|
|
9292
|
+
cwd: string;
|
|
9293
|
+
sessionId: string;
|
|
9294
|
+
parkedMs?: number;
|
|
9295
|
+
sdkMcpSettled: boolean;
|
|
9296
|
+
}>;
|
|
9297
|
+
/** Settles when the spare's process exits, claimed or not — a parked spare that dies should be replaced. */
|
|
9298
|
+
readonly exited: Promise<void>;
|
|
9299
|
+
/**
|
|
9300
|
+
* Terminate the process. Before a claim this discards the spare (and
|
|
9301
|
+
* rejects `claimed`); after one it is the same as closing the Query.
|
|
9302
|
+
*/
|
|
9303
|
+
close(): void;
|
|
9304
|
+
}
|
|
9305
|
+
|
|
9044
9306
|
/**
|
|
9045
9307
|
* Represents a spawned process with stdin/stdout streams and lifecycle management.
|
|
9046
9308
|
* Implementers provide this interface to abstract the process spawning mechanism.
|