ai-sdk-provider-claude-code 3.5.2 → 4.0.0

package/dist/index.d.ts

@@ -1,9 +1,133 @@
-import { LanguageModelV3, ProviderV3, APICallError, LoadAPIKeyError } from '@ai-sdk/provider';
-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 { LanguageModelV4, LanguageModelV4CallOptions, LanguageModelV4GenerateResult, LanguageModelV4StreamResult, ProviderV4, APICallError, LoadAPIKeyError } from '@ai-sdk/provider';
+import { Options, ThinkingConfig, EffortLevel, PermissionMode, SdkBeta, SdkPluginConfig, SandboxSettings, Settings, ToolConfig, SDKMessage, SDKTaskStartedMessage, SDKTaskProgressMessage, SDKTaskUpdatedMessage, SDKTaskNotificationMessage, SDKHookStartedMessage, SDKHookProgressMessage, SDKHookResponseMessage, McpServerStatus, McpServerConfig, CanUseTool, OnUserDialog, OnElicitation, AgentDefinition, SessionStore, SessionStoreFlush, SpawnOptions, SpawnedProcess, Query, McpSetServersResult, SDKControlGetContextUsageResponse, RewindFilesResult, SDKUserMessage, 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, OnElicitation, OnUserDialog, Options, OutputFormat, PermissionBehavior, PermissionDecisionClassification, PermissionDeniedHookInput, PermissionDeniedHookSpecificOutput, PermissionMode, PermissionRequestHookInput, PermissionRequestHookSpecificOutput, PermissionResult, PermissionRuleValue, PermissionUpdate, PermissionUpdateDestination, PolicySettingsOrigin, PostCompactHookInput, PostToolBatchHookInput, PostToolBatchHookSpecificOutput, PostToolUseFailureHookInput, PostToolUseFailureHookSpecificOutput, PostToolUseHookInput, PostToolUseHookSpecificOutput, PreCompactHookInput, PreToolUseHookInput, PreToolUseHookSpecificOutput, ProvenanceEntry, Query, ResolveSettingsOptions, ResolvedSettingSource, ResolvedSettings, RewindFilesResult, SDKControlGetContextUsageResponse, SDKFilesPersistedEvent, SDKHookProgressMessage, SDKHookResponseMessage, SDKHookStartedMessage, SDKMessage, SDKMessageOrigin, SDKSessionInfo, SDKTaskNotificationMessage, SDKTaskProgressMessage, SDKTaskStartedMessage, SDKTaskUpdatedMessage, SDKUserMessage, SYSTEM_PROMPT_DYNAMIC_BOUNDARY, SandboxCredentialsConfig, 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, filterEscalatingDefaultMode, foldSessionSummary, forkSession, getSessionInfo, getSessionMessages, getSubagentMessages, importSessionToStore, listSessions, listSubagents, renameSession, resolveSettings, startup, tagSession, tool } from '@anthropic-ai/claude-agent-sdk';
 import { ZodObject, ZodRawShape } from 'zod';
 
 type StreamingInputMode = 'auto' | 'always' | 'off';
+/**
+ * Normalized Task/subagent lifecycle events surfaced by the provider.
+ * The original Agent SDK message is preserved on `raw`.
+ */
+type ClaudeCodeTaskEvent = {
+    subtype: 'task_started';
+    taskId: string;
+    toolUseId?: string;
+    description: string;
+    subagentType?: string;
+    taskType?: string;
+    workflowName?: string;
+    prompt?: string;
+    skipTranscript?: boolean;
+    uuid: string;
+    sessionId: string;
+    raw: SDKTaskStartedMessage;
+} | {
+    subtype: 'task_progress';
+    taskId: string;
+    toolUseId?: string;
+    description: string;
+    subagentType?: string;
+    usage: SDKTaskProgressMessage['usage'];
+    lastToolName?: string;
+    summary?: string;
+    uuid: string;
+    sessionId: string;
+    raw: SDKTaskProgressMessage;
+} | {
+    subtype: 'task_updated';
+    taskId: string;
+    patch: SDKTaskUpdatedMessage['patch'];
+    uuid: string;
+    sessionId: string;
+    raw: SDKTaskUpdatedMessage;
+} | {
+    subtype: 'task_notification';
+    taskId: string;
+    toolUseId?: string;
+    status: SDKTaskNotificationMessage['status'];
+    outputFile: string;
+    summary: string;
+    usage?: SDKTaskNotificationMessage['usage'];
+    skipTranscript?: boolean;
+    uuid: string;
+    sessionId: string;
+    raw: SDKTaskNotificationMessage;
+};
+/**
+ * Normalized hook lifecycle events surfaced by the provider.
+ * The original Agent SDK message is preserved on `raw`.
+ */
+type ClaudeCodeHookEvent = {
+    subtype: 'hook_started';
+    hookId: string;
+    hookName: string;
+    hookEvent: string;
+    uuid: string;
+    sessionId: string;
+    raw: SDKHookStartedMessage;
+} | {
+    subtype: 'hook_progress';
+    hookId: string;
+    hookName: string;
+    hookEvent: string;
+    stdout: string;
+    stderr: string;
+    output: string;
+    uuid: string;
+    sessionId: string;
+    raw: SDKHookProgressMessage;
+} | {
+    subtype: 'hook_response';
+    hookId: string;
+    hookName: string;
+    hookEvent: string;
+    output: string;
+    stdout: string;
+    stderr: string;
+    exitCode?: number;
+    outcome: SDKHookResponseMessage['outcome'];
+    uuid: string;
+    sessionId: string;
+    raw: SDKHookResponseMessage;
+};
+/**
+ * Snapshot of MCP server connection state reported by the provider.
+ */
+interface ClaudeCodeMcpStatusEvent {
+    subtype: 'init';
+    sessionId?: string;
+    uuid?: string;
+    servers: McpServerStatus[];
+    raw?: unknown;
+}
+/**
+ * Safe runtime controller for common Agent SDK Query operations.
+ * The underlying Query is intentionally exposed as `rawQuery`.
+ */
+interface ClaudeCodeQueryController {
+    readonly rawQuery: Query;
+    interrupt(): Promise<void>;
+    setPermissionMode(mode: PermissionMode): Promise<void>;
+    setMcpPermissionModeOverride(serverName: string, mode: 'default' | 'auto' | null): Promise<{
+        warning?: string;
+    }>;
+    setModel(model?: string): Promise<void>;
+    setMaxThinkingTokens(maxThinkingTokens: number | null, thinkingDisplay?: 'summarized' | 'omitted' | null): Promise<void>;
+    applyFlagSettings(settings: {
+        [K in keyof Settings]?: Settings[K] | null;
+    }): Promise<void>;
+    mcpServerStatus(): Promise<McpServerStatus[]>;
+    reconnectMcpServer(serverName: string): Promise<void>;
+    toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
+    setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
+    getContextUsage(): Promise<SDKControlGetContextUsageResponse>;
+    rewindFiles(userMessageId: string, options?: {
+        dryRun?: boolean;
+    }): Promise<RewindFilesResult>;
+    stopTask(taskId: string): Promise<void>;
+    backgroundTasks(toolUseId?: string): Promise<boolean>;
+    streamInput?(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
+}
 /**
  * Logger interface for custom logging.
  * Allows consumers to provide their own logging implementation
@@ -117,6 +241,7 @@ interface ClaudeCodeSettings {
     /**
      * Enable prompt suggestions. When true, the agent emits a predicted
      * next user prompt after each turn (arrives after the result message).
+     * Disabled by default; set this explicitly to true to receive suggestions.
      */
     promptSuggestions?: boolean;
     /**
@@ -285,6 +410,31 @@ interface ClaudeCodeSettings {
      * @default false
      */
     includeHookEvents?: boolean;
+    /**
+     * Callback invoked for every raw Agent SDK message emitted by the query.
+     * Use this as a forward-compatible escape hatch when the provider does not
+     * yet expose a dedicated callback or metadata field for a new SDK subtype.
+     */
+    onSdkMessage?: (message: SDKMessage) => void | PromiseLike<void>;
+    /**
+     * Callback invoked for Task/subagent lifecycle messages after they are
+     * normalized to camelCase provider events. The original SDK message is
+     * available on `event.raw`.
+     */
+    onTaskEvent?: (event: ClaudeCodeTaskEvent) => void | PromiseLike<void>;
+    /**
+     * Callback invoked for hook lifecycle messages when hook events are emitted.
+     * Set `includeHookEvents: true` to receive all hook event types; the SDK may
+     * still emit startup/setup hook events independently.
+     */
+    onHookEvent?: (event: ClaudeCodeHookEvent) => void | PromiseLike<void>;
+    /**
+     * Callback invoked once with the initial MCP server status snapshot observed
+     * from the SDK init message. For live status after runtime MCP changes, call
+     * `controller.mcpServerStatus()` while the query is live and SDK streaming
+     * input/output is active.
+     */
+    onMcpStatusChange?: (status: ClaudeCodeMcpStatusEvent) => void | PromiseLike<void>;
     /**
      * MCP server configuration
      */
@@ -350,6 +500,12 @@ interface ClaudeCodeSettings {
      * make the CLI emit dialogs.
      */
     onUserDialog?: OnUserDialog;
+    /**
+     * Callback for MCP elicitation requests that are not handled by hooks.
+     * Return an Agent SDK elicitation result to accept, decline, or cancel the
+     * request; when omitted, the SDK declines unhandled elicitations.
+     */
+    onElicitation?: OnElicitation;
     /**
      * Dialog kinds (`request_user_dialog` `dialog_kind` values, e.g.
      * `'refusal_fallback_prompt'`) that your `onUserDialog` callback can
@@ -365,10 +521,12 @@ interface ClaudeCodeSettings {
      */
     supportedDialogKinds?: string[];
     /**
-     * Controls whether to send streaming input to the SDK (enables canUseTool).
-     * - 'auto' (default): stream when canUseTool is provided
+     * Controls whether to send streaming input to the SDK.
+     * - 'auto' (default): stream when canUseTool is provided or the prompt contains
+     *   image parts
      * - 'always': always stream
-     * - 'off': never stream (legacy behavior)
+     * - 'off': disable streaming input, including streaming image input; emits a
+     *   warning when the prompt contains image parts
      */
     streamingInput?: StreamingInputMode;
     /**
@@ -420,6 +578,12 @@ interface ClaudeCodeSettings {
      * Additional directories Claude can access.
      */
     additionalDirectories?: string[];
+    /**
+     * Named agent persona for the main conversation. The agent must be defined
+     * in `agents` or loaded from settings; its prompt/tools/model augment the
+     * main thread similarly to the Claude Code `--agent` flag.
+     */
+    agent?: string;
     /**
      * Programmatically defined subagents.
      *
@@ -538,6 +702,12 @@ interface ClaudeCodeSettings {
      * ```
      */
     onQueryCreated?: (query: Query) => void;
+    /**
+     * Callback invoked when a safe Claude Code query controller is created.
+     * Prefer this over `onQueryCreated` for common runtime controls; the raw
+     * SDK Query remains available as `controller.rawQuery`.
+     */
+    onQueryControllerCreated?: (controller: ClaudeCodeQueryController) => void | PromiseLike<void>;
     /**
      * Callback invoked when streaming input mode starts.
      * Provides a MessageInjector that can be used to inject messages mid-session.
@@ -562,14 +732,14 @@ 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.
+     * next user prompt). Suggestions are emitted only when `promptSuggestions`
+     * is `true` (set via settings or `sdkOptions`); when it is unset, the CLI
+     * emits none and this callback never fires. 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
+     * enabled 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
@@ -642,7 +812,7 @@ interface MessageInjector {
 interface ClaudeCodeLanguageModelOptions {
     /**
      * The model identifier to use.
-     * Can be 'opus', 'sonnet', 'haiku', or a custom model string.
+     * Can be 'fable', 'opus', 'sonnet', 'haiku', or a custom model string.
      */
     id: ClaudeCodeModelId;
     /**
@@ -657,23 +827,25 @@ interface ClaudeCodeLanguageModelOptions {
 }
 /**
  * Supported Claude model identifiers.
- * - 'opus': Claude Opus (most capable)
+ * - 'fable': Claude Fable (most capable)
+ * - 'opus': Claude Opus (highly capable)
  * - 'sonnet': Claude Sonnet (balanced performance)
  * - 'haiku': Claude Haiku (fastest, most cost-effective)
  * - Custom string: Any full model identifier (e.g., 'claude-opus-4-5', 'claude-sonnet-4-5-20250514')
  *
  * @example
  * ```typescript
+ * const fableModel = claudeCode('fable');
  * const opusModel = claudeCode('opus');
  * const sonnetModel = claudeCode('sonnet');
  * const haikuModel = claudeCode('haiku');
- * const customModel = claudeCode('claude-opus-4-5');
+ * const customModel = claudeCode('claude-fable-5');
  * ```
  */
-type ClaudeCodeModelId = 'opus' | 'sonnet' | 'haiku' | (string & {});
+type ClaudeCodeModelId = 'fable' | 'opus' | 'sonnet' | 'haiku' | (string & {});
 /**
  * Language model implementation for Claude Code SDK.
- * This class implements the AI SDK's LanguageModelV3 interface to provide
+ * This class implements the AI SDK's LanguageModelV4 interface to provide
  * integration with Claude models through the Claude Agent SDK.
  *
  * Features:
@@ -694,13 +866,17 @@ type ClaudeCodeModelId = 'opus' | 'sonnet' | 'haiku' | (string & {});
  * });
  *
  * const result = await model.doGenerate({
- *   prompt: [{ role: 'user', content: 'Hello!' }],
- *   mode: { type: 'regular' }
+ *   prompt: [
+ *     {
+ *       role: 'user',
+ *       content: [{ type: 'text', text: 'Hello!' }]
+ *     }
+ *   ]
  * });
  * ```
  */
-declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
-    readonly specificationVersion: "v3";
+declare class ClaudeCodeLanguageModel implements LanguageModelV4 {
+    readonly specificationVersion: "v4";
     readonly defaultObjectGenerationMode: "json";
     readonly supportsImageUrls = false;
     readonly supportedUrls: {};
@@ -721,6 +897,12 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     private getModel;
     private getSanitizedSdkOptions;
     private getEffectiveResume;
+    private invokeObservabilityCallback;
+    private invokeSdkMessageCallback;
+    private notifyQueryCreated;
+    private trackTaskEvent;
+    private trackHookEvent;
+    private trackMcpStatusFromInit;
     /**
      * Single source of truth for the CLI's `--session-id` exclusivity rule.
      *
@@ -787,20 +969,12 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
     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).
+     * Builds a V4 provider `tool-result` part with `isError: true` from a
+     * user-message `tool_error` block. V4 has no provider-level `tool-error`
+     * content or stream part; AI SDK core derives user-facing tool-error
+     * semantics from this result while preserving providerMetadata.
      */
-    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;
+    private buildErroredToolResultPart;
     /**
      * 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
@@ -810,6 +984,8 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * lockstep so a future tombstone change can't be applied to only some of them.
      */
     private isRetractedToolFrame;
+    private resolvePortableReasoningOptions;
+    private applyClaudeReasoningProviderOptions;
     private generateAllWarnings;
     private createQueryOptions;
     private handleClaudeCodeError;
@@ -847,17 +1023,17 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
      * 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.
+     * result without emitting one. Drained messages still pass through the
+     * generic raw SDK callback before prompt-specific handling.
      */
     private drainPromptSuggestion;
-    doGenerate(options: Parameters<LanguageModelV3['doGenerate']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doGenerate']>>>;
-    doStream(options: Parameters<LanguageModelV3['doStream']>[0]): Promise<Awaited<ReturnType<LanguageModelV3['doStream']>>>;
+    doGenerate(options: LanguageModelV4CallOptions): Promise<LanguageModelV4GenerateResult>;
+    doStream(options: LanguageModelV4CallOptions): Promise<LanguageModelV4StreamResult>;
     private serializeWarningsForMetadata;
 }
 
 /**
- * Claude Code provider interface that extends the AI SDK's ProviderV3.
+ * Claude Code provider interface that extends the AI SDK's ProviderV4.
  * Provides methods to create language models for interacting with Claude via the CLI.
  *
  * @example
@@ -872,32 +1048,33 @@ declare class ClaudeCodeLanguageModel implements LanguageModelV3 {
  * const languageModel = claudeCode.languageModel('opus', { maxTurns: 10 });
  * ```
  */
-interface ClaudeCodeProvider extends ProviderV3 {
+interface ClaudeCodeProvider extends ProviderV4 {
     /**
      * Creates a language model instance for the specified model ID.
      * This is a shorthand for calling `languageModel()`.
      *
-     * @param modelId - The Claude model to use ('opus' or 'sonnet')
+     * @param modelId - The Claude model to use (e.g. 'fable', 'opus', 'sonnet', 'haiku', or a full model id)
      * @param settings - Optional settings to configure the model
      * @returns A language model instance
      */
-    (modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+    (modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV4;
     /**
      * Creates a language model instance for text generation.
      *
-     * @param modelId - The Claude model to use ('opus' or 'sonnet')
+     * @param modelId - The Claude model to use (e.g. 'fable', 'opus', 'sonnet', 'haiku', or a full model id)
      * @param settings - Optional settings to configure the model
      * @returns A language model instance
      */
-    languageModel(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+    languageModel(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV4;
     /**
      * Alias for `languageModel()` to maintain compatibility with AI SDK patterns.
      *
-     * @param modelId - The Claude model to use ('opus' or 'sonnet')
+     * @param modelId - The Claude model to use (e.g. 'fable', 'opus', 'sonnet', 'haiku', or a full model id)
      * @param settings - Optional settings to configure the model
      * @returns A language model instance
      */
-    chat(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV3;
+    chat(modelId: ClaudeCodeModelId, settings?: ClaudeCodeSettings): LanguageModelV4;
+    embeddingModel(modelId: string): never;
     imageModel(modelId: string): never;
 }
 /**
@@ -958,6 +1135,12 @@ declare function createClaudeCode(options?: ClaudeCodeProviderSettings): ClaudeC
  */
 declare const claudeCode: ClaudeCodeProvider;
 
+/**
+ * Creates a safe controller for common runtime operations on an Agent SDK Query.
+ * The raw Query remains available as `rawQuery` for SDK features not wrapped here.
+ */
+declare function createClaudeCodeQueryController(query: Query): ClaudeCodeQueryController;
+
 /**
  * Optional annotations for content items, per MCP specification.
  * Validated against MCP SDK schema version 2025-06-18.
@@ -1090,10 +1273,12 @@ type AiSdkToolExecuteOptions = {
  *   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.
+ * - Call-context description functions accepted by AI SDK v7 tools cannot be
+ *   evaluated here, so only static string descriptions are forwarded.
  * - `execute` is required: only tools that execute locally can be bridged.
  */
 type AiSdkLikeTool = {
-    description?: string;
+    description?: string | ((options: never) => string);
     /** A Zod object schema (`z.object({...})`), Zod v3 or v4. */
     inputSchema: unknown;
     /**
@@ -1112,7 +1297,7 @@ type AiSdkLikeTool = {
  *
  * 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
+ * cannot be auto-bridged by the provider — at the `LanguageModelV4` 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
@@ -1326,4 +1511,4 @@ declare function isTimeoutError(error: unknown): boolean;
  */
 declare function getErrorMetadata(error: unknown): ClaudeCodeErrorMetadata | undefined;
 
-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 };
+export { type AiSdkLikeTool, type AiSdkToolExecuteOptions, type ClaudeCodeErrorMetadata, type ClaudeCodeHookEvent, ClaudeCodeLanguageModel, type ClaudeCodeLanguageModelOptions, type ClaudeCodeMcpStatusEvent, type ClaudeCodeModelId, type ClaudeCodeProvider, type ClaudeCodeProviderSettings, type ClaudeCodeQueryController, type ClaudeCodeSettings, type ClaudeCodeTaskEvent, type Logger, type MessageInjector, type MinimalCallToolResult, type ToolAnnotations, claudeCode, createAPICallError, createAiSdkMcpServer, createAuthenticationError, createClaudeCode, createClaudeCodeQueryController, createCustomMcpServer, createTimeoutError, getErrorMetadata, isAuthenticationError, isTimeoutError };