ai-sdk-provider-claude-code 3.4.3 → 3.5.0

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { LanguageModelV3, ProviderV3, APICallError, LoadAPIKeyError } from '@ai-sdk/provider';
-import { ThinkingConfig, PermissionMode, SdkBeta, SdkPluginConfig, SandboxSettings, Options, McpServerConfig, CanUseTool, AgentMcpServerSpec, SpawnOptions, SpawnedProcess, Query, SdkMcpToolDefinition, McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
-export { AgentMcpServerSpec, CanUseTool, HookCallback, HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, McpSdkServerConfigWithInstance, McpServerConfig, OutputFormat, PermissionBehavior, PermissionResult, PermissionRuleValue, PermissionUpdate, PostToolUseHookInput, PreToolUseHookInput, Query, SessionEndHookInput, SessionStartHookInput, SpawnOptions, SpawnedProcess, TaskCompletedHookInput, TeammateIdleHookInput, ThinkingAdaptive, ThinkingConfig, ThinkingDisabled, ThinkingEnabled, UserPromptSubmitHookInput, createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
+import { Options, ThinkingConfig, EffortLevel, PermissionMode, SdkBeta, SdkPluginConfig, SandboxSettings, Settings, ToolConfig, McpServerConfig, CanUseTool, OnUserDialog, AgentDefinition, SessionStore, SessionStoreFlush, SpawnOptions, SpawnedProcess, Query, SdkMcpToolDefinition, McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
+export { AbortError, AccountInfo, AgentDefinition, AgentInfo, AgentMcpServerSpec, AsyncHookJSONOutput, CanUseTool, ConfigChangeHookInput, CwdChangedHookInput, CwdChangedHookSpecificOutput, EffortLevel, ElicitationHookInput, ElicitationHookSpecificOutput, ElicitationResultHookInput, ElicitationResultHookSpecificOutput, FileChangedHookInput, FileChangedHookSpecificOutput, ForkSessionOptions, ForkSessionResult, GetSessionInfoOptions, GetSessionMessagesOptions, GetSubagentMessagesOptions, HOOK_EVENTS, HookCallback, HookCallbackMatcher, HookEvent, HookInput, HookJSONOutput, HookPermissionDecision, ImportSessionToStoreOptions, InMemorySessionStore, InstructionsLoadedHookInput, ListSessionsOptions, ListSubagentsOptions, McpHttpServerConfig, McpSSEServerConfig, McpSdkServerConfig, McpSdkServerConfigWithInstance, McpServerConfig, McpServerConfigForProcessTransport, McpServerStatus, McpSetServersResult, McpStdioServerConfig, MessageDisplayHookInput, MessageDisplayHookSpecificOutput, ModelInfo, NotificationHookInput, NotificationHookSpecificOutput, OnUserDialog, Options, OutputFormat, PermissionBehavior, PermissionDecisionClassification, PermissionDeniedHookInput, PermissionDeniedHookSpecificOutput, PermissionMode, PermissionRequestHookInput, PermissionRequestHookSpecificOutput, PermissionResult, PermissionRuleValue, PermissionUpdate, PermissionUpdateDestination, PostCompactHookInput, PostToolBatchHookInput, PostToolBatchHookSpecificOutput, PostToolUseFailureHookInput, PostToolUseFailureHookSpecificOutput, PostToolUseHookInput, PostToolUseHookSpecificOutput, PreCompactHookInput, PreToolUseHookInput, PreToolUseHookSpecificOutput, Query, RewindFilesResult, SDKMessage, SDKMessageOrigin, SDKSessionInfo, SDKUserMessage, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, SandboxFilesystemConfig, SandboxIgnoreViolations, SandboxNetworkConfig, SandboxSettings, SdkBeta, SdkPluginConfig, SessionCronSummary, SessionEndHookInput, SessionKey, SessionMessage, SessionMutationOptions, SessionStartHookInput, SessionStartHookSpecificOutput, SessionStore, SessionStoreEntry, SessionStoreFlush, SessionSummaryEntry, Settings, SetupHookInput, SetupHookSpecificOutput, SlashCommand, SpawnOptions, SpawnedProcess, StopFailureHookInput, StopHookInput, StopHookSpecificOutput, SubagentStartHookInput, SubagentStartHookSpecificOutput, SubagentStopHookInput, SubagentStopHookSpecificOutput, SyncHookJSONOutput, TaskCompletedHookInput, TaskCreatedHookInput, TeammateIdleHookInput, TerminalReason, ThinkingAdaptive, ThinkingConfig, ThinkingDisabled, ThinkingEnabled, ToolConfig, UserDialogRequest, UserDialogResult, UserPromptExpansionHookInput, UserPromptExpansionHookSpecificOutput, UserPromptSubmitHookInput, UserPromptSubmitHookSpecificOutput, WarmQuery, WorktreeCreateHookInput, WorktreeCreateHookSpecificOutput, WorktreeRemoveHookInput, createSdkMcpServer, deleteSession, foldSessionSummary, forkSession, getSessionInfo, getSessionMessages, getSubagentMessages, importSessionToStore, listSessions, listSubagents, renameSession, startup, tagSession, tool } from '@anthropic-ai/claude-agent-sdk';
 import { ZodObject, ZodRawShape } from 'zod';
 
 type StreamingInputMode = 'auto' | 'always' | 'off';
@@ -72,13 +72,15 @@ interface ClaudeCodeSettings {
     /**
      * Agent SDK system prompt configuration. Preferred over legacy fields.
      * - string: custom system prompt
-     * - preset object: Claude Code preset, with optional append
+     * - string[]: custom system prompt blocks; include the
+     *   `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` marker (re-exported by this package)
+     *   as a standalone element to split the static (cross-session cacheable)
+     *   prefix from the dynamic (session-specific) suffix
+     * - preset object: Claude Code preset, with optional `append` and
+     *   `excludeDynamicSections` (strips per-user dynamic sections such as
+     *   working directory and git status so the prompt caches across users)
      */
-    systemPrompt?: string | {
-        type: 'preset';
-        preset: 'claude_code';
-        append?: string;
-    };
+    systemPrompt?: Options['systemPrompt'];
     /**
      * Maximum number of turns for the conversation
      */
@@ -106,11 +108,12 @@ interface ClaudeCodeSettings {
      * - `'low'` — Minimal thinking, fastest responses
      * - `'medium'` — Moderate thinking
      * - `'high'` — Deep reasoning (default)
+     * - `'xhigh'` — Extra-high effort
      * - `'max'` — Maximum effort (Opus 4.6 only)
      *
      * @see https://docs.anthropic.com/en/docs/build-with-claude/effort
      */
-    effort?: 'low' | 'medium' | 'high' | 'max';
+    effort?: EffortLevel;
     /**
      * Enable prompt suggestions. When true, the agent emits a predicted
      * next user prompt after each turn (arrives after the result message).
@@ -130,7 +133,11 @@ interface ClaudeCodeSettings {
      */
     executableArgs?: string[];
     /**
-     * Permission mode for tool usage
+     * Permission mode for tool usage.
+     *
+     * Note: `'delegate'` was removed in Agent SDK 0.3.x — the CLI rejects
+     * `--permission-mode delegate` at argv parsing — so it is no longer
+     * accepted here either.
      * @default 'default'
      */
     permissionMode?: PermissionMode;
@@ -149,6 +156,13 @@ interface ClaudeCodeSettings {
     /**
      * Use a specific session ID for this query.
      * Allows deterministic session identifiers for tracking and correlation.
+     *
+     * Must be a valid UUID (the CLI rejects other formats). Cannot be combined
+     * with `continue` or `resume` unless `forkSession` is also set (it then
+     * names the forked session's ID); the provider rejects those combinations
+     * at validation time. On multi-turn conversations the provider forwards
+     * `sessionId` only on the first turn — subsequent turns resume the captured
+     * session (which already carries the custom ID).
      */
     sessionId?: string;
     /**
@@ -187,19 +201,103 @@ interface ClaudeCodeSettings {
     resumeSessionAt?: string;
     /**
      * Configure sandbox behavior programmatically.
+     *
+     * Cannot be combined with a `settings` FILE PATH (the SDK throws at query
+     * time); pass `settings` as an inline object instead, or move the sandbox
+     * configuration into the settings file. The provider rejects the
+     * combination at validation time.
      */
     sandbox?: SandboxSettings;
     /**
      * Tool configuration (array of tool names or Claude Code preset).
      */
     tools?: Options['tools'];
+    /**
+     * Skills to enable for the main session. This is the single place to turn
+     * skills on; you do not need to add `'Skill'` to `allowedTools` yourself
+     * when using this option.
+     *
+     * - `'all'`: enable every discovered skill
+     * - `string[]`: enable only the listed skills (SKILL.md `name`/directory
+     *   name, or `plugin:skill` for plugin-qualified skills)
+     * - omitted (default): no SDK auto-configuration
+     *
+     * Note: filesystem skills are discovered via `settingSources` — set it
+     * (e.g. `['user', 'project']`) so skill definitions can be loaded.
+     */
+    skills?: string[] | 'all';
+    /**
+     * Inline settings object or path to a settings JSON file.
+     * Applied as an additional settings layer for the session.
+     *
+     * A settings file path cannot be combined with the `sandbox` option (the
+     * SDK throws at query time; inline objects are fine). The provider rejects
+     * the combination at validation time.
+     */
+    settings?: string | Settings;
+    /**
+     * Policy-tier settings supplied by the spawning parent process.
+     * Filtered restrictive-only by the SDK; intended for embedding
+     * applications that need to enforce lockdown settings on the
+     * subprocess without writing root-owned files.
+     */
+    managedSettings?: Settings;
+    /**
+     * Map built-in tool names to replacement tools (e.g. MCP tools).
+     *
+     * @example
+     * ```typescript
+     * toolAliases: { Bash: 'mcp__workspace__bash' }
+     * ```
+     */
+    toolAliases?: Record<string, string>;
+    /**
+     * Per-tool configuration for built-in tools
+     * (e.g. `{ askUserQuestion: { previewFormat: 'html' } }`).
+     */
+    toolConfig?: ToolConfig;
+    /**
+     * Custom workflow instructions for plan mode. When `permissionMode` is
+     * `'plan'`, this string replaces the default code-implementation workflow
+     * body in the plan-mode system reminder.
+     */
+    planModeInstructions?: string;
+    /**
+     * 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, the resumed session's persisted title takes precedence.
+     */
+    title?: string;
+    /**
+     * Forward subagent text and thinking blocks as messages with
+     * `parent_tool_use_id` set so consumers can render a nested transcript.
+     * By default only tool_use/tool_result blocks from subagents are emitted.
+     */
+    forwardSubagentText?: boolean;
+    /**
+     * Enable periodic AI-generated progress summaries for running subagents,
+     * emitted on `task_progress` events via the `summary` field.
+     */
+    agentProgressSummaries?: boolean;
+    /**
+     * Include hook lifecycle events (`hook_started`, `hook_progress`,
+     * `hook_response`) in the output stream for all hook event types.
+     * @default false
+     */
+    includeHookEvents?: boolean;
     /**
      * MCP server configuration
      */
     mcpServers?: Record<string, McpServerConfig>;
     /**
      * Filesystem settings sources to load (CLAUDE.md, settings.json, etc.)
-     * When omitted, the Agent SDK loads no filesystem settings.
+     * When omitted, the provider explicitly passes `[]` to the Agent SDK so that
+     * no filesystem settings are loaded (isolation mode).
+     *
+     * Note: Agent SDK 0.3.x changed the SDK-level default — omitting
+     * `settingSources` now loads ALL filesystem settings (matching CLI behavior).
+     * The provider pins isolation mode unless you set this option (or override
+     * `settingSources` via the `sdkOptions` escape hatch).
      *
      * Required for Skills support - skills are loaded from these sources.
      * @example ['user', 'project']
@@ -208,6 +306,17 @@ interface ClaudeCodeSettings {
     /**
      * Hook callbacks for lifecycle events (e.g., PreToolUse, PostToolUse).
      * Note: typed loosely to support multiple SDK versions.
+     *
+     * Two verified upstream CLI behaviors to be aware of (CLI 2.1.172):
+     * - A `PreToolUse` hook returning `permissionDecision: 'defer'` combined
+     *   with a {@link canUseTool} callback fails the tool call before
+     *   `canUseTool` is ever consulted. Return no decision (or `'allow'`)
+     *   instead of `'defer'` when `canUseTool` should handle the call.
+     * - The `PermissionDenied` hook only fires for CLI-internal auto-mode
+     *   classifier denials (e.g. `permissionMode: 'auto'`). Denials issued by
+     *   `canUseTool` do NOT trigger it; they surface via the result message's
+     *   `permission_denials`, exposed as
+     *   `providerMetadata['claude-code'].permissionDenials`.
      */
     hooks?: Partial<Record<string, Array<{
         matcher?: string;
@@ -216,8 +325,45 @@ interface ClaudeCodeSettings {
     /**
      * Dynamic permission callback invoked before a tool is executed.
      * Allows runtime approval/denial and optional input mutation.
+     *
+     * Upstream CLI caveats (verified on CLI 2.1.172):
+     * - Do not combine with a `PreToolUse` hook that returns
+     *   `permissionDecision: 'defer'` — the CLI fails the tool call before
+     *   this callback is consulted.
+     * - Denials returned here do not fire the `PermissionDenied` hook (it only
+     *   fires for auto-mode classifier denials); they surface in
+     *   `providerMetadata['claude-code'].permissionDenials` instead.
      */
     canUseTool?: CanUseTool;
+    /**
+     * Callback for handling `request_user_dialog` control requests — blocking
+     * dialogs the CLI asks the host to render (e.g. the refusal-fallback
+     * prompt). Each `dialogKind` defines its own payload and result shape;
+     * answer unrecognized kinds with `{ behavior: 'cancelled' }` so the CLI
+     * applies the dialog's default behavior.
+     *
+     * The SDK fails closed around dialogs: when the CLI requests a dialog and
+     * no handler/declared kind exists, the dialog-gated flow degrades to its
+     * no-dialog behavior (for `'refusal_fallback_prompt'`, the classic refusal
+     * error ends the turn). Wire this callback together with
+     * `supportedDialogKinds` to opt in — providing the callback alone does NOT
+     * make the CLI emit dialogs.
+     */
+    onUserDialog?: OnUserDialog;
+    /**
+     * Dialog kinds (`request_user_dialog` `dialog_kind` values, e.g.
+     * `'refusal_fallback_prompt'`) that your `onUserDialog` callback can
+     * actually render. The CLI only emits dialog kinds declared here and
+     * fails closed on absence: an undeclared kind is never emitted and the
+     * flow behind it degrades to its no-dialog behavior instead. Omitting the
+     * option entirely means no dialogs are emitted, even with `onUserDialog`
+     * wired.
+     *
+     * Requires `onUserDialog` — the SDK throws at option intake when a
+     * non-empty list is passed without the callback (the provider also warns
+     * at validation time).
+     */
+    supportedDialogKinds?: string[];
     /**
      * Controls whether to send streaming input to the SDK (enables canUseTool).
      * - 'auto' (default): stream when canUseTool is provided
@@ -260,7 +406,14 @@ interface ClaudeCodeSettings {
      */
     logger?: Logger | false;
     /**
-     * Environment variables to set
+     * Environment variables to set for the Claude Code subprocess.
+     *
+     * The provider always constructs the subprocess environment from a sanitizing
+     * allowlist of `process.env` (HOME, PATH, proxy/TLS vars, `ANTHROPIC_*`,
+     * `CLAUDE_*`, `AWS_*`, `GOOGLE_*`, etc.), then merges these values over it
+     * (set a key to `undefined` to remove it). Agent SDK 0.3.x treats
+     * `Options.env` as a full replacement for the subprocess environment, so
+     * variables outside the allowlist are not inherited unless set here.
      */
     env?: Record<string, string | undefined>;
     /**
@@ -269,29 +422,24 @@ interface ClaudeCodeSettings {
     additionalDirectories?: string[];
     /**
      * Programmatically defined subagents.
+     *
+     * Uses the Agent SDK's `AgentDefinition` directly, which includes
+     * `effort`, `permissionMode`, `background`, `memory`, `initialPrompt`,
+     * `skills`, `maxTurns`, and full model ID strings in addition to the
+     * core `description`/`prompt`/`tools` fields.
      */
-    agents?: Record<string, {
-        /** Natural language description of when to use this agent */
-        description: string;
-        /** Array of allowed tool names. If omitted, inherits all tools from parent */
-        tools?: string[];
-        /** Array of tool names to explicitly disallow for this agent */
-        disallowedTools?: string[];
-        /** The agent's system prompt */
-        prompt: string;
-        /** Model to use for this agent. If omitted or 'inherit', uses the main model */
-        model?: 'sonnet' | 'opus' | 'haiku' | 'inherit';
-        /** MCP servers available to this agent (server names or inline configs) */
-        mcpServers?: AgentMcpServerSpec[];
-        /** Experimental: Critical reminder added to system prompt */
-        criticalSystemReminder_EXPERIMENTAL?: string;
-    }>;
+    agents?: Record<string, AgentDefinition>;
     /**
      * Include partial message events from the SDK stream.
      */
     includePartialMessages?: boolean;
     /**
-     * Model to use if primary fails.
+     * Model(s) to use if the primary model is overloaded or unavailable.
+     * Accepts a comma-separated list to try each in order; the primary model
+     * is re-tried at the start of each user turn.
+     *
+     * Must differ from the main model (the SDK throws when they are equal);
+     * the provider rejects the combination before invoking the SDK.
      */
     fallbackModel?: string;
     /**
@@ -317,6 +465,45 @@ interface ClaudeCodeSettings {
      * @default true
      */
     persistSession?: boolean;
+    /**
+     * API-side task budget in tokens. When set, the model is made aware of
+     * its remaining token budget so it can pace tool use and wrap up before
+     * the limit.
+     *
+     * @alpha Subject to change in upstream Agent SDK releases.
+     */
+    taskBudget?: {
+        total: number;
+    };
+    /**
+     * Mirror session transcripts to a custom storage adapter (e.g. Postgres,
+     * S3, Redis) in addition to local JSONL files. Cannot be combined with
+     * `persistSession: false` — local writes are required for the mirror to
+     * function — or with `enableFileCheckpointing: true` — checkpoint backup
+     * blobs are not mirrored, so `rewindFiles()` fails after a store-backed
+     * resume. Combining it with `continue: true` (without a `resume` ID)
+     * additionally requires the store to implement `listSessions()`, which the
+     * SDK uses to discover the most recent session. The provider rejects all
+     * three invalid combinations at validation time.
+     *
+     * @alpha Subject to change in upstream Agent SDK releases.
+     */
+    sessionStore?: SessionStore;
+    /**
+     * Flush strategy for `sessionStore` transcript mirroring:
+     * `'batched'` (default) or `'eager'`. Ignored when `sessionStore` is unset.
+     *
+     * @alpha Subject to change in upstream Agent SDK releases.
+     */
+    sessionStoreFlush?: SessionStoreFlush;
+    /**
+     * Timeout in milliseconds for each `sessionStore.load()` /
+     * `sessionStore.listSubkeys()` call during resume materialization.
+     *
+     * @default 60000
+     * @alpha Subject to change in upstream Agent SDK releases.
+     */
+    loadTimeoutMs?: number;
     /**
      * Custom function to spawn the Claude Code process.
      * Use this to run Claude Code in VMs, containers, or remote environments.
@@ -373,6 +560,34 @@ interface ClaudeCodeSettings {
      * ```
      */
     onStreamStart?: (injector: MessageInjector) => void;
+    /**
+     * Callback invoked when the agent emits a prompt suggestion (a predicted
+     * next user prompt). Suggestions are enabled when `promptSuggestions` is
+     * `true` OR left unset (the SDK enables them when the option is absent or
+     * true and disables them only when explicitly `false`). When the callback
+     * is set and `promptSuggestions !== false`, the provider drains post-result
+     * messages to deliver the suggestion. Delivery is still subject to CLI
+     * heuristics — suppressed on the first turn, after API errors, in plan
+     * mode, and by `CLAUDE_CODE_ENABLE_PROMPT_SUGGESTION=false` — so it may not
+     * fire on every turn.
+     *
+     * The SDK emits at most one `prompt_suggestion` message per turn, and it
+     * arrives AFTER the `result` message — i.e. after the AI SDK response has
+     * already finished. That is why suggestions are delivered through this
+     * callback instead of `providerMetadata` (which is finalized with the
+     * finish event/result).
+     *
+     * @example
+     * ```typescript
+     * const model = claudeCode('sonnet', {
+     *   promptSuggestions: true,
+     *   onPromptSuggestion: (suggestion) => {
+     *     console.log('Suggested next prompt:', suggestion);
+     *   }
+     * });
+     * ```
+     */
+    onPromptSuggestion?: (suggestion: string) => void;
 }
 /**
  * Controller for injecting messages into an active Claude Code session.
@@ -494,6 +709,7 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     private static readonly MAX_TOOL_INPUT_SIZE;
     private static readonly MAX_TOOL_INPUT_WARN;
     private static readonly MAX_DELTA_CALC_SIZE;
+    private static readonly PROMPT_SUGGESTION_DRAIN_TIMEOUT_MS;
     readonly modelId: ClaudeCodeModelId;
     readonly settings: ClaudeCodeSettings;
     private sessionId?;
@@ -505,18 +721,136 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     private getModel;
     private getSanitizedSdkOptions;
     private getEffectiveResume;
-    private extractTextAndThinking;
+    /**
+     * Single source of truth for the CLI's `--session-id` exclusivity rule.
+     *
+     * The CLI rejects `--session-id` together with `--resume`/`--continue`
+     * unless `--fork-session` is also set (forkSession then names the forked
+     * session's own ID). This predicate captures "there IS a resume/continue
+     * target AND we are not forking", i.e. the case where a session id must NOT
+     * coexist. It is referenced by both:
+     *   - the pre-merge forwarding guard (via its inverse), which decides whether
+     *     to forward `settings.sessionId` onto the base options, and
+     *   - the post-merge exclusivity drop, which removes any session id that the
+     *     generic sdkOptions overlay (or the auto-resume turn) re-introduced.
+     *
+     * Keeping one definition guarantees both sites agree on what "conflicts with
+     * a session id" means. The mirror in validation.ts (construction-time)
+     * intentionally stays separate: it reads settings+sdkOptions, not a built
+     * opts object.
+     */
+    private static sessionIdConflictsWithResumeOrContinue;
+    /**
+     * Owns ALL session-id / resume cross-option resolution on the FINAL merged
+     * options, in the single correct order. Called once, immediately after the
+     * generic sdkOptions overlay in createQueryOptions.
+     *
+     * Two concerns, in this exact order (order matters: step 1 can change whether
+     * step 2 sees a resume target):
+     *
+     *  1. Blank-resume restoration. The overlay copies the raw `sdkOptions.resume`
+     *     verbatim, which can re-introduce a blank/whitespace value over the
+     *     base `resume` that getEffectiveResume already normalized. The SDK treats
+     *     a blank resume as absent, so a blank must NOT clobber the computed
+     *     fallback — restore `effectiveResume` (already blank-stripped; may itself
+     *     be undefined for a genuinely new session) rather than leaving '' or
+     *     forcing undefined, which would erase a real settings.resume / captured
+     *     session id.
+     *
+     *  2. Session-id exclusivity. Drop `opts.sessionId` whenever it conflicts with
+     *     a resume/continue target (see sessionIdConflictsWithResumeOrContinue).
+     *     This runs on the merged opts so it catches a sessionId re-added by the
+     *     sdkOptions overlay AND the auto-resumed second turn (where resume was
+     *     populated from the captured session id). It complements — does not
+     *     replace — the pre-merge forwarding guard, which governs whether
+     *     settings.sessionId was forwarded BEFORE the overlay could mutate
+     *     forkSession/continue/resume.
+     */
+    private applySessionResolution;
     private extractToolUses;
     private extractToolResults;
     private extractToolErrors;
     private serializeToolInput;
     private checkInputSize;
     private normalizeToolResult;
+    /**
+     * Builds a provider-executed `tool-call` part from an assistant `tool_use`
+     * block. Shared by doGenerate (content part) and doStream (stream part) so
+     * the two paths cannot drift in field shape.
+     */
+    private buildToolCallPart;
+    /**
+     * Builds a provider-executed `tool-result` part from a user-message
+     * `tool_result` block, applying normalization and `maxToolResultSize`
+     * truncation. Shared by doGenerate and doStream.
+     */
+    private buildToolResultPart;
+    private serializeToolError;
+    /**
+     * Builds a provider-executed `tool-error` STREAM part from a user-message
+     * `tool_error` block (doStream only; AI SDK core handles tool-error stream
+     * parts natively).
+     */
+    private buildToolErrorPart;
+    /**
+     * Builds a V3 `tool-result` CONTENT part with `isError: true` from a
+     * user-message `tool_error` block (doGenerate only). The V3 content union
+     * has no `tool-error` member and AI SDK core's asContent() silently drops
+     * unknown content part types, so an extension tool-error part would never
+     * reach `generateText` users — an isError tool-result, by contrast,
+     * round-trips into a proper tool-error part in steps content.
+     */
+    private buildToolErrorResultPart;
+    /**
+     * Policy (P3): late-frame drop guard, shared by all four tool_result/tool_error
+     * sites (doGenerate result+error, doStream result+error). When a frame's tool
+     * id is tombstoned (its tool-call was retracted by a supersede/refusal-fallback
+     * signal), the frame must be DROPPED rather than re-synthesized into an orphan
+     * tool-call. Centralizing the predicate + debug message keeps the four sites in
+     * lockstep so a future tombstone change can't be applied to only some of them.
+     */
+    private isRetractedToolFrame;
     private generateAllWarnings;
     private createQueryOptions;
     private handleClaudeCodeError;
     private setSessionId;
     private logMcpConnectionIssues;
+    /**
+     * Handles SDK 0.3.x system messages other than 'init', shared by doGenerate
+     * and doStream:
+     * - 'api_retry' is counted into providerMetadata (`apiRetries`) and debug-logged.
+     * - 'permission_denied' is warn-logged and recorded into providerMetadata
+     *   (`permissionDenials`); without this a denial is invisible until the
+     *   model talks about it.
+     * - 'model_refusal_fallback' is debug-logged (the superseding assistant
+     *   message is handled by the text-dedup guard in the message loops).
+     * - 'thinking_tokens' deltas are accumulated into providerMetadata
+     *   (`estimatedThinkingTokens`); the estimate is explicitly not the
+     *   authoritative billed output tokens, so it is surfaced as metadata
+     *   instead of feeding `usage.outputTokens.reasoning`.
+     * - The subtypes in {@link INFORMATIONAL_SYSTEM_SUBTYPES} are intentionally
+     *   informational and only debug-logged.
+     */
+    private handleSystemMessage;
+    /**
+     * Merges the result message's `permission_denials` list into the tracked
+     * denials. PreToolUse-hook denies bypass canUseTool and emit no
+     * `permission_denied` system event (per the SDK docs on
+     * SDKPermissionDeniedMessage), so the result list is the only place they
+     * surface. Entries already recorded from stream-time events are deduped by
+     * `tool_use_id`.
+     */
+    private mergeResultPermissionDenials;
+    /**
+     * Bounded post-result drain for the `prompt_suggestion` message
+     * (promptSuggestions: true), shared by doGenerate and doStream. The
+     * suggestion arrives AFTER the result message; the SDK emits at most one
+     * per turn, so stop once it is delivered, and a timeout closes the
+     * iterator (tearing down the subprocess) if the CLI lingers after the
+     * result without emitting one. Advances the response's own generator, so
+     * the caller's surrounding loop resumes to a finished iterator.
+     */
+    private drainPromptSuggestion;
     doGenerate(options: Parameters<LanguageModelV3['doGenerate']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doGenerate']>>>;
     doStream(options: Parameters<LanguageModelV3['doStream']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doStream']>>>;
     private serializeWarningsForMetadata;
@@ -726,6 +1060,122 @@ declare function createCustomMcpServer<Tools extends Record<string, {
     version?: string;
     tools: Tools;
 }): McpSdkServerConfigWithInstance;
+/**
+ * Minimal per-call options passed to an AI SDK tool's `execute` function
+ * when it is invoked through {@link createAiSdkMcpServer}.
+ *
+ * Note that the AI SDK's full `ToolCallOptions` (e.g. `messages`,
+ * `experimental_context`) is not available here: the tool runs inside the
+ * Claude Code CLI's MCP transport, outside the AI SDK call loop.
+ */
+type AiSdkToolExecuteOptions = {
+    /**
+     * Identifier of the MCP request that triggered this call, when available.
+     *
+     * Note: this is the MCP JSON-RPC request id (often a small integer like
+     * `'42'`), not the model's `toolu_...` tool_use id, so it will not match
+     * the `toolCallId` on the AI SDK's `tool-call`/`tool-result` stream parts.
+     */
+    toolCallId?: string;
+    /** Abort signal for the MCP request, when available. */
+    abortSignal?: AbortSignal;
+};
+/**
+ * Structural shape of an AI SDK tool (what the `ai` package's `tool()` helper
+ * returns) as accepted by {@link createAiSdkMcpServer}. Deliberately
+ * structurally typed so this package does not depend on the `ai` package.
+ *
+ * Constraints:
+ * - `inputSchema` must be a Zod object schema (`z.object({...})`, Zod v3 or
+ *   v4) — the same schema you would pass to the `ai` package's `tool()`
+ *   helper. Schemas created with the AI SDK's `jsonSchema()` helper are not
+ *   supported because the Agent SDK's `tool()` requires a Zod shape.
+ * - `execute` is required: only tools that execute locally can be bridged.
+ */
+type AiSdkLikeTool = {
+    description?: string;
+    /** A Zod object schema (`z.object({...})`), Zod v3 or v4. */
+    inputSchema: unknown;
+    /**
+     * Tool implementation. Receives the validated input and a minimal options
+     * object ({@link AiSdkToolExecuteOptions}).
+     *
+     * Optional in the type only to stay assignment-compatible with the AI
+     * SDK's `Tool` type — {@link createAiSdkMcpServer} throws at creation time
+     * if it is missing.
+     */
+    execute?(input: never, options?: AiSdkToolExecuteOptions): PromiseLike<unknown> | unknown;
+};
+/**
+ * Bridges AI SDK tool definitions (the `ai` package's `tool()` helper) into
+ * an in-process SDK MCP server that the Claude Code CLI can execute.
+ *
+ * Why this helper exists: the Claude Code CLI executes its own tools, so AI
+ * SDK tools passed to `generateText`/`streamText` via the `tools` option
+ * cannot be auto-bridged by the provider — at the `LanguageModelV3` layer the
+ * provider only receives tool *declarations* (name, description, JSON
+ * schema); the `execute` functions live in the `ai` package layer and never
+ * reach providers. This helper is the explicit alternative: pass your tools
+ * here and wire the result into the `mcpServers` setting.
+ *
+ * Validation scope: the Agent SDK's `tool()` takes only the schema SHAPE and
+ * validates incoming args against a default `z.object(shape)` — running
+ * FIELD-LEVEL validation and transforms (the handler receives each field's
+ * parsed `_output`) and STRIPPING unknown keys — before this handler runs. The
+ * bridge does NOT re-parse on top of that: re-parsing the SDK's already-parsed
+ * output against the original schema would re-run field transforms and would
+ * outright reject any schema whose output type differs from its input (e.g.
+ * `z.string().transform(v => v.length)`). Consequently OBJECT-LEVEL constructs
+ * are NOT enforced by the bridge — `.refine()`/`.superRefine()` (cross-field
+ * invariants) and `.strict()`/`.passthrough()`/`.catchall()` (unknown-key
+ * modes) — so perform those checks inside `execute()`.
+ *
+ * Each tool's `execute` is called with the SDK-validated input and a minimal
+ * options object ({@link AiSdkToolExecuteOptions}). String results pass
+ * through as MCP text content; all other results are `JSON.stringify`'d.
+ * Errors thrown (or rejections) become `isError: true` tool results instead
+ * of crashing the CLI session. Results that cannot be serialized to JSON
+ * (e.g. circular objects) also become `isError: true` results with a
+ * serialization message, even though the tool itself succeeded.
+ *
+ * Tool results surface to the AI SDK as provider-executed dynamic tool parts
+ * (`tool-call`/`tool-result` with `mcp__<serverName>__<toolName>` names), not
+ * as executions of your local `tools` option.
+ *
+ * @param name - MCP server name. Tools are exposed to the CLI as
+ *   `mcp__<name>__<toolName>`.
+ * @param tools - Map of tool name to AI SDK tool. Each tool must have an
+ *   `execute` function and a Zod object schema as its `inputSchema`
+ *   (`jsonSchema()`-based tools are rejected).
+ * @returns An SDK MCP server config for the `mcpServers` setting.
+ * @throws If a tool lacks an `execute` function or its `inputSchema` is not
+ *   a Zod object schema.
+ *
+ * @example
+ * ```typescript
+ * import { generateText, tool } from 'ai';
+ * import { z } from 'zod';
+ * import { claudeCode, createAiSdkMcpServer } from 'ai-sdk-provider-claude-code';
+ *
+ * const tools = {
+ *   add: tool({
+ *     description: 'Add two numbers',
+ *     inputSchema: z.object({ a: z.number(), b: z.number() }),
+ *     execute: async ({ a, b }) => ({ sum: a + b }),
+ *   }),
+ * };
+ *
+ * const { text } = await generateText({
+ *   model: claudeCode('sonnet', {
+ *     mcpServers: { myTools: createAiSdkMcpServer('myTools', tools) },
+ *     // Tools are named mcp__<serverName>__<toolName>
+ *     allowedTools: ['mcp__myTools__add'],
+ *   }),
+ *   prompt: 'What is 2 + 3? Use the add tool.',
+ * });
+ * ```
+ */
+declare function createAiSdkMcpServer(name: string, tools: Record<string, AiSdkLikeTool>): McpSdkServerConfigWithInstance;
 
 /**
  * Metadata associated with Claude Code SDK errors.
@@ -876,4 +1326,4 @@ declare function isTimeoutError(error: unknown): boolean;
  */
 declare function getErrorMetadata(error: unknown): ClaudeCodeErrorMetadata | undefined;
 
-export { type ClaudeCodeErrorMetadata, ClaudeCodeLanguageModel, type ClaudeCodeLanguageModelOptions, type ClaudeCodeModelId, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeCodeSettings, type Logger, type MessageInjector, type MinimalCallToolResult, type ToolAnnotations, claudeCode, createAPICallError, createAuthenticationError, createClaudeCode, createCustomMcpServer, createTimeoutError, getErrorMetadata, isAuthenticationError, isTimeoutError };
+export { type AiSdkLikeTool, type AiSdkToolExecuteOptions, type ClaudeCodeErrorMetadata, ClaudeCodeLanguageModel, type ClaudeCodeLanguageModelOptions, type ClaudeCodeModelId, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeCodeSettings, type Logger, type MessageInjector, type MinimalCallToolResult, type ToolAnnotations, claudeCode, createAPICallError, createAiSdkMcpServer, createAuthenticationError, createClaudeCode, createCustomMcpServer, createTimeoutError, getErrorMetadata, isAuthenticationError, isTimeoutError };