@anthropic-ai/claude-agent-sdk 0.2.112 → 0.2.114

package/sdk.d.ts

@@ -351,6 +351,7 @@ declare namespace coreTypes {
         SDKMemoryRecallMessage,
         SDKMessageOrigin,
         SDKMessage,
+        SDKMirrorErrorMessage,
         SDKNotificationMessage,
         SDKPartialAssistantMessage,
         SDKPermissionDenial,
@@ -431,6 +432,22 @@ export declare type CwdChangedHookSpecificOutput = {
     watchPaths?: string[];
 };
 
+/**
+ * Delete a session.
+ *
+ * With `sessionStore`: calls `sessionStore.delete()` if implemented; no-op
+ * otherwise (per the SessionStore contract — appropriate for WORM/append-only
+ * backends).
+ *
+ * Without `sessionStore`: removes `{sessionId}.jsonl` and the `{sessionId}/`
+ * subagent-transcript subdirectory from the local projects dir. Throws if the
+ * session is not found.
+ *
+ * @param sessionId - UUID of the session
+ * @param options - `{ dir?, sessionStore? }`
+ */
+export declare function deleteSession(_sessionId: string, _options?: SessionMutationOptions): Promise<void>;
+
 /**
  * Effort level for controlling how much thinking/reasoning Claude applies.
  *
@@ -589,7 +606,12 @@ export declare type GetSessionInfoOptions = {
      * When omitted, all project directories are searched for the session file.
      */
     dir?: string;
-
+    /**
+     * When provided, load session info from this store instead of the local
+     * filesystem.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 /**
@@ -621,7 +643,12 @@ export declare type GetSessionMessagesOptions = {
      * Defaults to false for backwards compatibility.
      */
     includeSystemMessages?: boolean;
-
+    /**
+     * When provided, load session messages from this store instead of the
+     * local filesystem.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 /**
@@ -647,7 +674,12 @@ export declare type GetSubagentMessagesOptions = {
     limit?: number;
     /** Number of messages to skip from the start. */
     offset?: number;
-
+    /**
+     * When provided, load subagent messages from this store instead of the
+     * local filesystem.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 export declare const HOOK_EVENTS: readonly ["PreToolUse", "PostToolUse", "PostToolUseFailure", "Notification", "UserPromptSubmit", "SessionStart", "SessionEnd", "Stop", "StopFailure", "SubagentStart", "SubagentStop", "PreCompact", "PostCompact", "PermissionRequest", "PermissionDenied", "Setup", "TeammateIdle", "TaskCreated", "TaskCompleted", "Elicitation", "ElicitationResult", "ConfigChange", "WorktreeCreate", "WorktreeRemove", "InstructionsLoaded", "CwdChanged", "FileChanged"];
@@ -677,6 +709,45 @@ export declare type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
 
 export declare type HookPermissionDecision = 'allow' | 'deny' | 'ask' | 'defer';
 
+/**
+ * Copy a local JSONL session into a SessionStore.
+ *
+ * Reads the session file (and optionally subagent transcripts) from disk
+ * and calls `store.append()` for each. Entries are appended in batches of
+ * `batchSize` to avoid backend payload limits; the store's `append()` is
+ * called multiple times per session. Useful for migrating existing local
+ * sessions to a remote backend.
+ *
+ * @alpha
+ * @param sessionId - UUID of the local session to import
+ * @param store - Destination SessionStore
+ * @param options - `{ dir?, includeSubagents?, batchSize? }`
+ */
+export declare function importSessionToStore(_sessionId: string, _store: SessionStore, _options?: ImportSessionToStoreOptions): Promise<void>;
+
+/**
+ * Options for importing a local JSONL session into a SessionStore.
+ * @alpha
+ */
+export declare type ImportSessionToStoreOptions = {
+    /**
+     * Project directory path (same semantics as `listSessions({ dir })`).
+     * When omitted, all project directories are searched for the session file
+     * and the destination projectKey is derived from the resolved cwd.
+     */
+    dir?: string;
+    /**
+     * If true, also import subagent transcripts. Default: true.
+     */
+    includeSubagents?: boolean;
+    /**
+     * Maximum entries per `store.append()` call. Entries are appended in
+     * batches of this size to avoid backend payload limits; the store's
+     * `append()` is called multiple times per session. Default: 500.
+     */
+    batchSize?: number;
+};
+
 /**
  * A user message typed on claude.ai, extracted from the bridge WS.
  * @alpha
@@ -692,6 +763,35 @@ export declare type InferShape<T extends AnyZodRawShape> = {
     } ? O : never;
 } & {};
 
+/**
+ * In-memory SessionStore implementation for testing and development.
+ * Stores entries in a Map keyed by a composite string.
+ * Not suitable for production -- data is lost when the process exits.
+ * @alpha
+ */
+export declare class InMemorySessionStore implements SessionStore {
+    private store;
+    private mtimes;
+    private keyToString;
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    listSessions(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    delete(key: SessionKey): Promise<void>;
+    listSubkeys(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+    /** Test helper -- get all entries for a key */
+    getEntries(key: SessionKey): SessionStoreEntry[];
+    /** Test helper -- number of stored sessions (main transcripts only) */
+    get size(): number;
+    /** Test helper -- clear all stored data */
+    clear(): void;
+}
+
 export declare type InstructionsLoadedHookInput = BaseHookInput & {
     hook_event_name: 'InstructionsLoaded';
     file_path: string;
@@ -752,7 +852,12 @@ export declare type ListSessionsOptions = {
      * Only applies when reading from the local filesystem.
      */
     includeWorktrees?: boolean;
-
+    /**
+     * When provided, list sessions from this store instead of the local
+     * filesystem. Requires `store.listSessions` to be defined.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 /**
@@ -773,7 +878,12 @@ export declare function listSubagents(_sessionId: string, _options?: ListSubagen
 export declare type ListSubagentsOptions = {
     /** Project directory to find the session in. If omitted, searches all projects. */
     dir?: string;
-
+    /**
+     * When provided, list subagents from this store instead of the local
+     * filesystem. Requires `store.listSubkeys` to be defined.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 export declare type McpClaudeAIProxyServerConfig = {
@@ -1058,11 +1168,7 @@ export declare type Options = {
     };
     /**
      * Environment variables to pass to the Claude Code process.
-     * Merged on top of `process.env` — entries here override the parent
-     * process's variables, and anything not set here is inherited.
-     * Set a key to `undefined` to remove an inherited variable. Note:
-     * `GITHUB_ACTIONS` and a few SDK-managed vars are stripped and are
-     * not inherited unless set explicitly here.
+     * Defaults to `process.env`.
      *
      * SDK consumers can identify their app/library to include in the User-Agent header by setting:
      * - `CLAUDE_AGENT_SDK_CLIENT_APP` - Your app/library identifier (e.g., "my-app/1.0.0", "my-library/2.1")
@@ -1169,8 +1275,28 @@ export declare type Options = {
      * @default true
      */
     persistSession?: boolean;
-
-
+    /**
+     * Mirror session transcripts to an external store. When set, the subprocess
+     * still writes to CLAUDE_CONFIG_DIR (set it to /tmp for ephemeral local copy)
+     * AND emits entries to this adapter via dual-write.
+     *
+     * Cannot be used with persistSession: false -- local writes are required
+     * for the mirror to function (the mirror hook fires after local write success).
+     *
+     * Default: undefined (no mirroring, today's behavior).
+     * @alpha
+     */
+    sessionStore?: SessionStore;
+    /**
+     * Timeout for each `sessionStore.load()` / `sessionStore.listSubkeys()` call
+     * during resume materialization. If the adapter doesn't settle within this
+     * window the query fails with a clear error instead of hanging the iterator
+     * forever (the deferred-spawn path otherwise has no upper bound).
+     *
+     * @default 60_000
+     * @alpha
+     */
+    loadTimeoutMs?: number;
     /**
      * Include hook lifecycle events in the output stream.
      * When true, `hook_started`, `hook_progress`, and `hook_response` system
@@ -1510,6 +1636,15 @@ export declare type Options = {
         append?: string;
         excludeDynamicSections?: boolean;
     };
+    /**
+     * Custom title for a new session. When provided, the session uses this title
+     * instead of auto-generating one from the first user message.
+     *
+     * When resuming via `resume` or `continue`, the resumed session's persisted
+     * title takes precedence — use `renameSession()` to retitle an existing
+     * session.
+     */
+    title?: string;
 
     /**
      * Custom function to spawn the Claude Code process.
@@ -1970,6 +2105,7 @@ export declare type SandboxNetworkConfig = NonNullable<z.infer<ReturnType<typeof
  */
 declare const SandboxNetworkConfigSchema: () => z.ZodOptional<z.ZodObject<{
     allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    deniedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
     allowManagedDomainsOnly: z.ZodOptional<z.ZodBoolean>;
     allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
     allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
@@ -1991,6 +2127,7 @@ declare const SandboxSettingsSchema: () => z.ZodObject<{
     allowUnsandboxedCommands: z.ZodOptional<z.ZodBoolean>;
     network: z.ZodOptional<z.ZodObject<{
         allowedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        deniedDomains: z.ZodOptional<z.ZodArray<z.ZodString>>;
         allowManagedDomainsOnly: z.ZodOptional<z.ZodBoolean>;
         allowUnixSockets: z.ZodOptional<z.ZodArray<z.ZodString>>;
         allowAllUnixSockets: z.ZodOptional<z.ZodBoolean>;
@@ -2123,6 +2260,14 @@ declare type SDKControlElicitationRequest = {
     description?: string;
 };
 
+/**
+ * Requests at-mention file autocomplete suggestions for a partial path prefix. Returns the same fuzzy-matched results the TUI shows.
+ */
+declare type SDKControlFileSuggestionsRequest = {
+    subtype: 'file_suggestions';
+    query: string;
+};
+
 /**
  * Requests a breakdown of current context window usage by category.
  */
@@ -2248,6 +2393,10 @@ declare type SDKControlInitializeRequest = {
      */
     excludeDynamicSections?: boolean;
     agents?: Record<string, coreTypes.AgentDefinition>;
+    /**
+     * Custom session title. When provided, the session uses this title and skips automatic title generation. Has no effect on the persisted title when resuming an existing session.
+     */
+    title?: string;
     promptSuggestions?: boolean;
     agentProgressSummaries?: boolean;
 };
@@ -2370,7 +2519,7 @@ export declare type SDKControlRequest = {
     request: SDKControlRequestInner;
 };
 
-declare type SDKControlRequestInner = SDKControlInterruptRequest | SDKControlPermissionRequest | SDKControlInitializeRequest | SDKControlSetPermissionModeRequest | SDKControlSetModelRequest | SDKControlSetMaxThinkingTokensRequest | SDKControlRenameSessionRequest | SDKControlMcpStatusRequest | SDKControlGetContextUsageRequest | SDKHookCallbackRequest | SDKControlMcpMessageRequest | SDKControlRewindFilesRequest | SDKControlCancelAsyncMessageRequest | SDKControlSeedReadStateRequest | SDKControlMcpSetServersRequest | SDKControlReloadPluginsRequest | SDKControlMcpReconnectRequest | SDKControlMcpToggleRequest | SDKControlChannelEnableRequest | SDKControlEndSessionRequest | SDKControlMcpAuthenticateRequest | SDKControlMcpClearAuthRequest | SDKControlMcpOAuthCallbackUrlRequest | SDKControlClaudeAuthenticateRequest | SDKControlClaudeOAuthCallbackRequest | SDKControlClaudeOAuthWaitForCompletionRequest | SDKControlRemoteControlRequest | SDKControlGenerateSessionTitleRequest | SDKControlSideQuestionRequest | SDKControlUltrareviewLaunchRequest | SDKControlOAuthTokenRefreshRequest | SDKControlStopTaskRequest | SDKControlApplyFlagSettingsRequest | SDKControlGetSettingsRequest | SDKControlElicitationRequest | SDKControlRequestUserDialogRequest;
+declare type SDKControlRequestInner = SDKControlInterruptRequest | SDKControlPermissionRequest | SDKControlInitializeRequest | SDKControlSetPermissionModeRequest | SDKControlSetModelRequest | SDKControlSetMaxThinkingTokensRequest | SDKControlRenameSessionRequest | SDKControlMcpStatusRequest | SDKControlGetContextUsageRequest | SDKControlFileSuggestionsRequest | SDKHookCallbackRequest | SDKControlMcpMessageRequest | SDKControlRewindFilesRequest | SDKControlCancelAsyncMessageRequest | SDKControlSeedReadStateRequest | SDKControlMcpSetServersRequest | SDKControlReloadPluginsRequest | SDKControlMcpReconnectRequest | SDKControlMcpToggleRequest | SDKControlChannelEnableRequest | SDKControlEndSessionRequest | SDKControlMcpAuthenticateRequest | SDKControlMcpClearAuthRequest | SDKControlMcpOAuthCallbackUrlRequest | SDKControlClaudeAuthenticateRequest | SDKControlClaudeOAuthCallbackRequest | SDKControlClaudeOAuthWaitForCompletionRequest | SDKControlRemoteControlRequest | SDKControlGenerateSessionTitleRequest | SDKControlSideQuestionRequest | SDKControlUltrareviewLaunchRequest | SDKControlOAuthTokenRefreshRequest | SDKControlStopTaskRequest | SDKControlApplyFlagSettingsRequest | SDKControlGetSettingsRequest | SDKControlElicitationRequest | SDKControlRequestUserDialogRequest;
 
 /**
  * Requests the SDK consumer to render a tool-driven blocking dialog and return the user choice. Used by tools that previously rendered Ink JSX via setToolJSX with an onDone callback.
@@ -2595,7 +2744,7 @@ export declare type SDKMemoryRecallMessage = {
     session_id: string;
 };
 
-export declare type SDKMessage = SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKAPIRetryMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskUpdatedMessage | SDKTaskProgressMessage | SDKSessionStateChangedMessage | SDKNotificationMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKMemoryRecallMessage | SDKRateLimitEvent | SDKElicitationCompleteMessage | SDKPromptSuggestionMessage;
+export declare type SDKMessage = SDKAssistantMessage | SDKUserMessage | SDKUserMessageReplay | SDKResultMessage | SDKSystemMessage | SDKPartialAssistantMessage | SDKCompactBoundaryMessage | SDKStatusMessage | SDKAPIRetryMessage | SDKLocalCommandOutputMessage | SDKHookStartedMessage | SDKHookProgressMessage | SDKHookResponseMessage | SDKPluginInstallMessage | SDKToolProgressMessage | SDKAuthStatusMessage | SDKTaskNotificationMessage | SDKTaskStartedMessage | SDKTaskUpdatedMessage | SDKTaskProgressMessage | SDKSessionStateChangedMessage | SDKNotificationMessage | SDKFilesPersistedEvent | SDKToolUseSummaryMessage | SDKMemoryRecallMessage | SDKRateLimitEvent | SDKElicitationCompleteMessage | SDKPromptSuggestionMessage | SDKMirrorErrorMessage;
 
 /**
  * Provenance of a user-role message (peer session, team lead, channel). Absent or `human` means keyboard input from the user.
@@ -2615,6 +2764,22 @@ export declare type SDKMessageOrigin = {
     kind: 'coordinator';
 };
 
+/**
+ * Emitted when SessionStore.append() rejects or times out for a transcript-mirror batch. The batch is dropped (at-most-once delivery); this surfaces the failure so consumers are not silent on data loss.
+ */
+export declare type SDKMirrorErrorMessage = {
+    type: 'system';
+    subtype: 'mirror_error';
+    error: string;
+    key: {
+        projectKey: string;
+        sessionId: string;
+        subpath?: string;
+    };
+    uuid: UUID;
+    session_id: string;
+};
+
 /**
  * Loop-side text notification. Mirrors the interactive REPL notification queue (key/priority/timeout). JSX notifications are not emitted on this channel.
  */
@@ -2838,11 +3003,7 @@ export declare type SDKSessionOptions = {
     executableArgs?: string[];
     /**
      * Environment variables to pass to the Claude Code process.
-     * Merged on top of `process.env` — entries here override the parent
-     * process's variables, and anything not set here is inherited.
-     * Set a key to `undefined` to remove an inherited variable. Note:
-     * `GITHUB_ACTIONS` and a few SDK-managed vars are stripped and are
-     * not inherited unless set explicitly here.
+     * Defaults to `process.env`.
      *
      * SDK consumers can identify their app/library to include in the User-Agent header by setting:
      * - `CLAUDE_AGENT_SDK_CLIENT_APP` - Your app/library identifier (e.g., "my-app/1.0.0", "my-library/2.1")
@@ -3111,6 +3272,25 @@ export declare type SessionEndHookInput = BaseHookInput & {
     reason: ExitReason;
 };
 
+/**
+ * Identifies a session transcript or subagent transcript in the store.
+ * Main transcripts have no subpath; subagent transcripts include a subpath
+ * like 'subagents/agent-{id}' that mirrors the on-disk directory structure.
+ * @alpha
+ */
+export declare type SessionKey = {
+    /** Caller-defined scope. Default: sanitized cwd. Multi-tenant deployments
+     *  should set this to a tenant ID or project name. Paths longer than 200
+     *  characters are truncated and suffixed with a portable djb2 hash so the
+     *  same path yields the same key under both Bun and Node.js. */
+    projectKey: string;
+    sessionId: string;
+    /** Undefined = main transcript. Set for subagent files.
+     *  Empty string is invalid — omit the field for the main transcript.
+     *  Opaque to the adapter — just use it as a storage key suffix. */
+    subpath?: string;
+};
+
 /**
  * A message from a session transcript.
  * Returned by `getSessionMessages` for reading historical session data.
@@ -3133,7 +3313,12 @@ export declare type SessionMutationOptions = {
      * When omitted, all project directories are searched for the session file.
      */
     dir?: string;
-
+    /**
+     * When provided, read/write session data via this store instead of the
+     * local filesystem.
+     * @alpha
+     */
+    sessionStore?: SessionStore;
 };
 
 export declare type SessionStartHookInput = BaseHookInput & {
@@ -3150,6 +3335,94 @@ export declare type SessionStartHookSpecificOutput = {
     watchPaths?: string[];
 };
 
+/**
+ * Adapter for mirroring session transcripts to external storage.
+ * The subprocess still writes to local disk (set CLAUDE_CONFIG_DIR=/tmp
+ * for ephemeral local copy); the adapter receives a secondary copy.
+ *
+ * The SDK never deletes from your store unless you call deleteSession()
+ * with delete? implemented. Retention is the adapter's responsibility —
+ * implement TTL, S3 lifecycle policies, or scheduled cleanup according
+ * to your compliance requirements (e.g., ZDR/HIPAA retention windows).
+ * Local-disk transcripts under CLAUDE_CONFIG_DIR are swept by the
+ * existing cleanupPeriodDays setting independently of this adapter.
+ * @alpha
+ */
+export declare type SessionStore = {
+    /**
+     * Mirror a batch of transcript entries. Called AFTER the subprocess's
+     * local write succeeds — durability is already guaranteed locally.
+     *
+     * Batches arrive at ~100ms cadence during active turns. Entries are
+     * JSON-safe POJOs — one per line in the local JSONL file.
+     *
+     * Within a single process, persist entries in append-call order; across
+     * concurrent processes, order is by storage commit time, not call time.
+     *
+     * Rejection is logged; the subprocess continues unaffected.
+     * At-most-once delivery — failed batches are not retried.
+     */
+    append(key: SessionKey, entries: SessionStoreEntry[]): Promise<void>;
+    /**
+     * Load a full session for resume. Called once, in the SDK parent, before
+     * subprocess spawn. The result is materialized to a temporary JSONL file;
+     * the subprocess resumes from that file using its existing resume code.
+     *
+     * Return `null` for a key that was never written; adapters that cannot
+     * distinguish "never written" from "emptied" (e.g. Redis LRANGE) may
+     * return `null` for both. Returned entries must be deep-equal to what was
+     * appended — byte-equal serialization is NOT required (e.g. Postgres
+     * JSONB may reorder object keys); the SDK never hashes or byte-compares
+     * entries.
+     */
+    load(key: SessionKey): Promise<SessionStoreEntry[] | null>;
+    /**
+     * List sessions for a projectKey. Returns IDs + modification times.
+     * `mtime` is Unix epoch milliseconds; adapters without native modification
+     * time (e.g. Redis) must maintain their own index. Result order is
+     * unspecified — the SDK sorts by mtime descending.
+     * Optional — if undefined, listSessions() with a sessionStore throws.
+     */
+    listSessions?(projectKey: string): Promise<Array<{
+        sessionId: string;
+        mtime: number;
+    }>>;
+    /**
+     * Delete a session. Optional — if undefined, deletion is a no-op
+     * (appropriate for WORM/append-only backends like S3).
+     */
+    delete?(key: SessionKey): Promise<void>;
+    /**
+     * List all subpath keys under a session (e.g., subagent transcripts).
+     * Used during resume to discover and materialize all subagent data.
+     * If undefined, resume only materializes the main transcript.
+     */
+    listSubkeys?(key: {
+        projectKey: string;
+        sessionId: string;
+    }): Promise<string[]>;
+};
+
+/**
+ * One JSONL transcript line as observed by a {@link SessionStore} adapter.
+ *
+ * The concrete entry shape is the on-disk transcript format (a large
+ * discriminated union over `type` covering user/assistant messages, summaries,
+ * titles, tags, mode changes, etc.). That union is CLI-internal and not part
+ * of the SDK API surface, so this is exposed as a minimal structural supertype
+ * — every entry has a string `type` discriminant, most carry a `uuid` and ISO
+ * `timestamp`, and the rest of the payload is opaque JSON. Adapters should
+ * treat entries as pass-through blobs; round-tripping `JSON.stringify` /
+ * `JSON.parse` is the only required invariant.
+ * @alpha
+ */
+export declare type SessionStoreEntry = {
+    type: string;
+    uuid?: string;
+    timestamp?: string;
+    [k: string]: unknown;
+};
+
 /**
  * AUTO-GENERATED - DO NOT EDIT
  *
@@ -4192,6 +4465,10 @@ export declare interface Settings {
         allowUnsandboxedCommands?: boolean;
         network?: {
             allowedDomains?: string[];
+            /**
+             * Domains that are always blocked, even if matched by allowedDomains. Supports the same wildcard syntax as allowedDomains. Merged from all settings sources regardless of allowManagedDomainsOnly.
+             */
+            deniedDomains?: string[];
             /**
              * When true (and set in managed settings), only allowedDomains and WebFetch(domain:...) allow rules from managed settings are respected. User, project, local, and flag settings domains are ignored. Denied domains are still respected from all sources.
              */
@@ -4356,7 +4633,7 @@ export declare interface Settings {
     /**
      * Release channel for auto-updates (latest or stable)
      */
-    autoUpdatesChannel?: 'latest' | 'stable';
+    autoUpdatesChannel?: 'latest' | 'stable' | 'rc';
     /**
      * Minimum version to stay on - prevents downgrades when switching to stable channel
      */