@lleverage-ai/agent-sdk 0.0.1

package/dist/agent.js

@@ -0,0 +1,2122 @@
+/**
+ * Core agent implementation.
+ *
+ * @packageDocumentation
+ */
+import { createUIMessageStream, createUIMessageStreamResponse, generateText, stepCountIs, streamText, } from "ai";
+import { isSandboxBackend } from "./backend.js";
+import { CommandBlockedError } from "./backends/sandbox.js";
+import { createAgentState, StateBackend } from "./backends/state.js";
+import { createCheckpoint, createInterrupt, isApprovalInterrupt, updateCheckpoint, } from "./checkpointer/types.js";
+import { CheckpointError, ToolExecutionError, ToolPermissionDeniedError, } from "./errors/index.js";
+import { createRetryLoopState, handleGenerationError, invokePreGenerateHooks, normalizeError, updateRetryLoopState, waitForRetryDelay, } from "./generation-helpers.js";
+import { aggregatePermissionDecisions, extractUpdatedInput, extractUpdatedResult, invokeHooksWithTimeout, invokeMatchingHooks, } from "./hooks.js";
+import { MCPManager } from "./mcp/manager.js";
+import { applyMiddleware, mergeHooks, setupMiddleware } from "./middleware/index.js";
+import { ACCEPT_EDITS_BLOCKED_PATTERNS } from "./security/index.js";
+import { coreToolsToToolSet, createCoreTools, createSearchToolsTool, createTaskTool, } from "./tools/factory.js";
+import { createUseToolsTool, ToolRegistry } from "./tools/tool-registry.js";
+let agentIdCounter = 0;
+/**
+ * Internal signal for interrupt flow control.
+ *
+ * This is thrown when a tool requires user approval or an interrupt is requested.
+ * It's caught by the generate() function and converted to an interrupted result.
+ *
+ * @internal
+ */
+class InterruptSignal extends Error {
+    interrupt;
+    constructor(interrupt) {
+        super(`Interrupt: ${interrupt.type}`);
+        this.name = "InterruptSignal";
+        this.interrupt = interrupt;
+    }
+}
+/**
+ * Check if an error is an InterruptSignal.
+ * @internal
+ */
+function isInterruptSignal(error) {
+    return error instanceof InterruptSignal;
+}
+/**
+ * File edit tool names that get auto-approved in acceptEdits mode.
+ * @internal
+ */
+const FILE_EDIT_TOOLS = new Set([
+    "write",
+    "edit",
+    // Bash commands that perform file operations (if we ever add them)
+    // For now, bash is not auto-approved even in acceptEdits mode
+]);
+/**
+ * Wraps a sandbox backend to add additional blocked command patterns.
+ * This creates a proxy that intercepts execute() calls and validates
+ * commands against the additional patterns before delegating.
+ * @internal
+ */
+function wrapSandboxWithBlockedPatterns(sandbox, additionalPatterns) {
+    // Create a proxy that intercepts execute() calls
+    return new Proxy(sandbox, {
+        get(target, prop, receiver) {
+            if (prop === "execute") {
+                return async (command) => {
+                    // Check additional patterns before delegating
+                    for (const pattern of additionalPatterns) {
+                        if (pattern.test(command)) {
+                            throw new CommandBlockedError(command, "Command blocked by acceptEdits shell file operation safety");
+                        }
+                    }
+                    // Delegate to original execute
+                    return target.execute(command);
+                };
+            }
+            // For all other properties, delegate to target
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+/**
+ * Determines if an error should trigger fallback to an alternative model.
+ * @internal
+ */
+function shouldUseFallback(error) {
+    // Check error code for known fallback-triggering conditions
+    if (error.code === "RATE_LIMIT_ERROR" || error.code === "TIMEOUT_ERROR") {
+        return true;
+    }
+    // Check for model unavailability or service errors
+    const message = error.message.toLowerCase();
+    const causeMessage = error.cause?.message?.toLowerCase() ?? "";
+    if (error.code === "MODEL_ERROR" ||
+        error.code === "UNKNOWN_ERROR" ||
+        error.code === "AGENT_ERROR") {
+        // Check both the AgentError message and the original error message
+        if (message.includes("unavailable") ||
+            message.includes("503") ||
+            message.includes("service unavailable") ||
+            causeMessage.includes("unavailable") ||
+            causeMessage.includes("503") ||
+            causeMessage.includes("service unavailable")) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Determines if an error is related to context length/token limits.
+ * @internal
+ */
+function isContextLengthError(error) {
+    const message = error.message.toLowerCase();
+    const causeMessage = error.cause?.message?.toLowerCase() ?? "";
+    // Check for common context length error patterns
+    const contextErrorPatterns = [
+        "context length",
+        "context_length",
+        "token limit",
+        "maximum context",
+        "too long",
+        "exceeds",
+        "max tokens",
+        "context size",
+    ];
+    return contextErrorPatterns.some((pattern) => message.includes(pattern) || causeMessage.includes(pattern));
+}
+/**
+ * Check if a tool should be allowed based on permission mode.
+ * Returns "allow" or "deny" for definitive decisions, or undefined to defer to canUseTool callback.
+ * @internal
+ */
+function checkPermissionMode(toolName, mode) {
+    switch (mode) {
+        case "plan":
+            // Block all tool execution in plan mode
+            return "deny";
+        case "bypassPermissions":
+            // Allow all tools (dangerous - use only for testing/demos)
+            return "allow";
+        case "acceptEdits":
+            // Auto-approve file edit operations
+            return FILE_EDIT_TOOLS.has(toolName) ? "allow" : undefined;
+        default:
+            // Defer to canUseTool callback
+            return undefined;
+    }
+}
+/**
+ * Wrap tools with permission mode checking and canUseTool callback.
+ * @internal
+ */
+function wrapToolsWithPermissionMode(tools, getPermissionMode, canUseTool, approvalState) {
+    const wrapped = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        const originalExecute = tool.execute;
+        if (!originalExecute) {
+            // Skip tools without execute function
+            wrapped[name] = tool;
+            continue;
+        }
+        // Create needsApproval function that bridges canUseTool to AI SDK's approval flow
+        // This allows the AI SDK to handle approval UI natively when canUseTool returns "ask"
+        const needsApproval = canUseTool
+            ? async (input) => {
+                const mode = getPermissionMode();
+                const modeDecision = checkPermissionMode(name, mode);
+                // If permission mode denies, don't show approval UI (execute will throw)
+                if (modeDecision === "deny") {
+                    return false;
+                }
+                // If permission mode allows, no approval needed
+                if (modeDecision === "allow") {
+                    return false;
+                }
+                // Defer to canUseTool callback
+                const decision = await canUseTool(name, input);
+                return decision === "ask";
+            }
+            : tool.needsApproval; // Preserve original needsApproval if no canUseTool
+        wrapped[name] = {
+            ...tool,
+            needsApproval,
+            execute: async (input, options) => {
+                const mode = getPermissionMode();
+                const modeDecision = checkPermissionMode(name, mode);
+                // Create the interrupt function for tool execution
+                const toolCallId = options?.toolCallId ?? `call_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
+                const threadId = approvalState?.threadId ?? "unknown";
+                const step = approvalState?.step ?? 0;
+                const interrupt = async (request, interruptOptions) => {
+                    const interruptType = interruptOptions?.type ?? "custom";
+                    const interruptId = `int_${toolCallId}`;
+                    // Check if we have a pending response for this interrupt
+                    if (approvalState?.pendingResponses.has(interruptId)) {
+                        const response = approvalState.pendingResponses.get(interruptId);
+                        // Clear the response after use
+                        approvalState.pendingResponses.delete(interruptId);
+                        return response;
+                    }
+                    // No response yet - create and throw an interrupt
+                    if (!approvalState?.checkpointSaver) {
+                        throw new ToolExecutionError(`Tool "${name}" called interrupt() but no checkpointer is configured`, {
+                            toolName: name,
+                            toolInput: input,
+                            metadata: { interruptType, request },
+                        });
+                    }
+                    const interruptData = createInterrupt({
+                        id: interruptId,
+                        threadId,
+                        type: interruptType,
+                        toolCallId,
+                        toolName: name,
+                        request,
+                        step,
+                    });
+                    throw new InterruptSignal(interruptData);
+                };
+                // Create extended options with the interrupt function
+                const extendedOptions = {
+                    ...options,
+                    interrupt,
+                };
+                // If permission mode gives a definitive answer, use it
+                if (modeDecision === "allow") {
+                    // Execute the original tool
+                    // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                    return originalExecute.call(tool, input, extendedOptions);
+                }
+                if (modeDecision === "deny") {
+                    // Denied by permission mode
+                    const errorMessage = mode === "plan"
+                        ? `Tool "${name}" is blocked in plan mode (planning/analysis only)`
+                        : `Tool "${name}" requires permission approval`;
+                    throw new ToolExecutionError(errorMessage, {
+                        toolName: name,
+                        toolInput: input,
+                        metadata: { permissionMode: mode },
+                    });
+                }
+                // Permission mode deferred to canUseTool callback
+                if (canUseTool) {
+                    const callbackDecision = await canUseTool(name, input);
+                    if (callbackDecision === "allow") {
+                        // Execute the original tool
+                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                        return originalExecute.call(tool, input, extendedOptions);
+                    }
+                    if (callbackDecision === "deny") {
+                        throw new ToolExecutionError(`Tool "${name}" was denied by canUseTool callback`, {
+                            toolName: name,
+                            toolInput: input,
+                            metadata: { permissionMode: mode, decision: callbackDecision },
+                        });
+                    }
+                    if (callbackDecision === "ask") {
+                        // When canUseTool returns "ask", we need to determine the execution path:
+                        // 1. AI SDK streaming: needsApproval (set above) triggers approval UI,
+                        //    and execute() is only called after user approves
+                        // 2. Direct tool execution: execute() is called directly without AI SDK,
+                        //    so we need to throw an error to require approval
+                        const toolUseId = options?.toolCallId;
+                        if (toolUseId && approvalState) {
+                            // Check for explicit denial in pending responses
+                            const pendingResponse = approvalState.pendingResponses.get(toolUseId);
+                            if (pendingResponse !== undefined) {
+                                const response = pendingResponse;
+                                if (response.approved === false) {
+                                    throw new ToolExecutionError(`Tool "${name}" was denied by user${response.reason ? `: ${response.reason}` : ""}`, {
+                                        toolName: name,
+                                        toolInput: input,
+                                        metadata: {
+                                            permissionMode: mode,
+                                            decision: "deny",
+                                            toolUseId,
+                                            reason: response.reason,
+                                        },
+                                    });
+                                }
+                                // Has approval response - user approved, continue to execution
+                                if (response.approved === true) {
+                                    // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                                    return originalExecute.call(tool, input, extendedOptions);
+                                }
+                            }
+                            // Check legacy approval system
+                            const decision = approvalState.approvalDecisions.get(toolUseId);
+                            if (decision === false) {
+                                throw new ToolExecutionError(`Tool "${name}" was denied by user`, {
+                                    toolName: name,
+                                    toolInput: input,
+                                    metadata: {
+                                        permissionMode: mode,
+                                        decision: "deny",
+                                        toolUseId,
+                                    },
+                                });
+                            }
+                            if (decision === true) {
+                                // Explicitly approved via legacy system
+                                // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                                return originalExecute.call(tool, input, extendedOptions);
+                            }
+                        }
+                        // No approval decision exists yet.
+                        // For AI SDK streaming, this path shouldn't be reached because
+                        // needsApproval returned true and AI SDK won't call execute.
+                        // For direct calls without AI SDK, we throw an error.
+                        throw new ToolExecutionError(`Tool "${name}" requires user approval but no checkpointer is configured`, {
+                            toolName: name,
+                            toolInput: input,
+                            metadata: {
+                                permissionMode: mode,
+                                decision: "ask",
+                                reason: "Direct tool call requires approval - use AI SDK streaming for approval UI",
+                            },
+                        });
+                    }
+                }
+                // No canUseTool callback - default to allow in default mode
+                // This preserves backward compatibility where tools work by default
+                // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                return originalExecute.call(tool, input, extendedOptions);
+            },
+        };
+    }
+    return wrapped;
+}
+/**
+ * Wraps tools to emit PreToolUse/PostToolUse/PostToolUseFailure hooks.
+ *
+ * This enables observability hooks (logging, metrics, tracing) and guardrails
+ * (rate-limiting, audit, permission checks) to fire during tool execution.
+ *
+ * @param tools - The tools to wrap
+ * @param hookRegistration - The hook registration containing tool hook matchers
+ * @param agent - The agent instance
+ * @param sessionId - The session ID for hook input
+ * @returns Wrapped tools that emit hooks
+ *
+ * @internal
+ */
+function wrapToolsWithHooks(tools, hookRegistration, agent, sessionId) {
+    // If no tool hooks are registered, return tools unchanged
+    if (!hookRegistration?.PreToolUse?.length &&
+        !hookRegistration?.PostToolUse?.length &&
+        !hookRegistration?.PostToolUseFailure?.length) {
+        return tools;
+    }
+    const wrapped = {};
+    for (const [name, tool] of Object.entries(tools)) {
+        if (!tool.execute) {
+            // Tool has no execute function (e.g., client-side only tool)
+            wrapped[name] = tool;
+            continue;
+        }
+        const originalExecute = tool.execute;
+        wrapped[name] = {
+            ...tool,
+            execute: async (input, options) => {
+                const toolUseId = options?.toolCallId ?? `tool-${Date.now()}`;
+                // Create PreToolUse input
+                const preToolUseInput = {
+                    hook_event_name: "PreToolUse",
+                    session_id: sessionId,
+                    cwd: process.cwd(),
+                    tool_name: name,
+                    tool_input: input,
+                };
+                // Invoke PreToolUse hooks
+                if (hookRegistration?.PreToolUse?.length) {
+                    const preHookOutputs = await invokeMatchingHooks(hookRegistration.PreToolUse, name, preToolUseInput, toolUseId, agent);
+                    // Check permission decisions
+                    const permissionDecision = aggregatePermissionDecisions(preHookOutputs);
+                    if (permissionDecision === "deny") {
+                        // Find the reason from hook outputs
+                        const reason = preHookOutputs.find((o) => o.hookSpecificOutput?.permissionDecisionReason)?.hookSpecificOutput?.permissionDecisionReason;
+                        const error = new ToolPermissionDeniedError(`Tool '${name}' execution denied by hook`, {
+                            toolName: name,
+                            toolInput: input,
+                            reason,
+                        });
+                        // Emit PostToolUseFailure for denied tools
+                        if (hookRegistration?.PostToolUseFailure?.length) {
+                            const failureInput = {
+                                hook_event_name: "PostToolUseFailure",
+                                session_id: sessionId,
+                                cwd: process.cwd(),
+                                tool_name: name,
+                                tool_input: input,
+                                error,
+                            };
+                            await invokeMatchingHooks(hookRegistration.PostToolUseFailure, name, failureInput, toolUseId, agent);
+                        }
+                        throw error;
+                    }
+                    // Check for input transformation
+                    const updatedInput = extractUpdatedInput(preHookOutputs);
+                    if (updatedInput !== undefined) {
+                        input = updatedInput;
+                    }
+                }
+                try {
+                    // Execute the original tool with (potentially modified) input
+                    // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                    const output = await originalExecute.call(tool, input, options);
+                    // Invoke PostToolUse hooks
+                    if (hookRegistration?.PostToolUse?.length) {
+                        const postToolUseInput = {
+                            hook_event_name: "PostToolUse",
+                            session_id: sessionId,
+                            cwd: process.cwd(),
+                            tool_name: name,
+                            tool_input: input,
+                            tool_response: output,
+                        };
+                        const postHookOutputs = await invokeMatchingHooks(hookRegistration.PostToolUse, name, postToolUseInput, toolUseId, agent);
+                        // Check for output transformation
+                        const updatedResult = extractUpdatedResult(postHookOutputs);
+                        if (updatedResult !== undefined) {
+                            return updatedResult;
+                        }
+                    }
+                    return output;
+                }
+                catch (error) {
+                    // Invoke PostToolUseFailure hooks
+                    if (hookRegistration?.PostToolUseFailure?.length) {
+                        const failureInput = {
+                            hook_event_name: "PostToolUseFailure",
+                            session_id: sessionId,
+                            cwd: process.cwd(),
+                            tool_name: name,
+                            tool_input: input,
+                            error: error instanceof Error ? error : new Error(String(error)),
+                        };
+                        await invokeMatchingHooks(hookRegistration.PostToolUseFailure, name, failureInput, toolUseId, agent);
+                    }
+                    throw error;
+                }
+            },
+        };
+    }
+    return wrapped;
+}
+/**
+ * Check if a value is a backend factory function.
+ */
+function isBackendFactory(value) {
+    return typeof value === "function";
+}
+/**
+ * Creates a new agent instance with the specified configuration.
+ *
+ * Agents are the main abstraction for interacting with AI models. They combine
+ * a language model with tools, plugins, and hooks to create intelligent assistants.
+ *
+ * @param options - Configuration options for the agent
+ * @returns A configured agent instance
+ *
+ * @example
+ * ```typescript
+ * import { createAgent } from "@lleverage-ai/agent-sdk";
+ * import { anthropic } from "@ai-sdk/anthropic";
+ * import { tool } from "ai";
+ * import { z } from "zod";
+ *
+ * const agent = createAgent({
+ *   model: anthropic("claude-sonnet-4-20250514"),
+ *   systemPrompt: "You are a helpful assistant.",
+ *   tools: {
+ *     weather: tool({
+ *       description: "Get weather for a city",
+ *       inputSchema: z.object({ city: z.string() }),
+ *       execute: async ({ city }) => `Weather in ${city}: sunny`,
+ *     }),
+ *   },
+ * });
+ *
+ * const result = await agent.generate({
+ *   prompt: "What's the weather in Tokyo?",
+ * });
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use in a Next.js API route with useChat
+ * export async function POST(req: Request) {
+ *   const { messages } = await req.json();
+ *   return agent.streamResponse({ messages });
+ * }
+ * ```
+ *
+ * @category Agent
+ */
+export function createAgent(options) {
+    const id = `agent-${++agentIdCounter}`;
+    // Process middleware to get hooks (middleware hooks come before explicit hooks)
+    const middleware = options.middleware ?? [];
+    const middlewareHooks = applyMiddleware(middleware);
+    const mergedHooks = mergeHooks(middlewareHooks, options.hooks);
+    // Create options with merged hooks for all hook lookups
+    const effectiveHooks = mergedHooks;
+    // Permission mode (mutable for setPermissionMode)
+    let permissionMode = options.permissionMode ?? "default";
+    // Store approval decisions in-memory (keyed by toolUseId)
+    // In production, this could be persisted via checkpointer
+    const approvalDecisions = new Map();
+    // Store pending interrupt responses (keyed by interrupt ID or tool call ID)
+    // Used by the new interrupt/resume system
+    const pendingResponses = new Map();
+    // Initialize agent state (shared with backend if using factory)
+    const state = createAgentState();
+    // Initialize backend - default to StateBackend if not provided
+    let backend;
+    if (options.backend) {
+        if (isBackendFactory(options.backend)) {
+            // Factory function - create backend with shared state
+            backend = options.backend(state);
+        }
+        else {
+            // Direct backend instance
+            backend = options.backend;
+        }
+    }
+    else {
+        // Default: StateBackend with shared state
+        backend = new StateBackend(state);
+    }
+    // Determine plugin loading mode
+    const pluginLoadingMode = options.pluginLoading ?? "eager";
+    const preloadPlugins = new Set(options.preloadPlugins ?? []);
+    // Initialize tool registry for lazy/explicit loading modes
+    const toolRegistry = pluginLoadingMode !== "eager"
+        ? new ToolRegistry({
+            onToolRegistered: async (input) => {
+                const hooks = effectiveHooks?.ToolRegistered ?? [];
+                if (hooks.length === 0)
+                    return;
+                const hookInput = {
+                    hook_event_name: "ToolRegistered",
+                    session_id: "default",
+                    cwd: process.cwd(),
+                    tool_name: input.tool_name,
+                    description: input.description,
+                    source: input.source,
+                };
+                await invokeHooksWithTimeout(hooks, hookInput, null, agent);
+            },
+            onToolLoadError: async (input) => {
+                const hooks = effectiveHooks?.ToolLoadError ?? [];
+                if (hooks.length === 0)
+                    return;
+                const hookInput = {
+                    hook_event_name: "ToolLoadError",
+                    session_id: "default",
+                    cwd: process.cwd(),
+                    tool_name: input.tool_name,
+                    error: input.error,
+                    source: input.source,
+                };
+                await invokeHooksWithTimeout(hooks, hookInput, null, agent);
+            },
+        })
+        : undefined;
+    // Collect skills from options and plugins
+    const skills = [...(options.skills ?? [])];
+    // Initialize MCP manager for unified plugin tool handling
+    // Note: The callbacks reference `agent` which is defined later, but they
+    // won't be called until MCP connections happen in initPromise, by which
+    // time `agent` is already defined.
+    const mcpManager = new MCPManager({
+        onConnectionFailed: async (input) => {
+            const hooks = effectiveHooks?.MCPConnectionFailed ?? [];
+            if (hooks.length === 0)
+                return;
+            const hookInput = {
+                hook_event_name: "MCPConnectionFailed",
+                session_id: "default",
+                cwd: process.cwd(),
+                server_name: input.server_name,
+                config: input.config,
+                error: input.error,
+            };
+            await invokeHooksWithTimeout(hooks, hookInput, null, agent);
+        },
+        onConnectionRestored: async (input) => {
+            const hooks = effectiveHooks?.MCPConnectionRestored ?? [];
+            if (hooks.length === 0)
+                return;
+            const hookInput = {
+                hook_event_name: "MCPConnectionRestored",
+                session_id: "default",
+                cwd: process.cwd(),
+                server_name: input.server_name,
+                tool_count: input.tool_count,
+            };
+            await invokeHooksWithTimeout(hooks, hookInput, null, agent);
+        },
+    });
+    // Determine sandbox backend if available
+    let sandbox = isSandboxBackend(backend) ? backend : undefined;
+    // Apply acceptEdits shell file operation blocking
+    // When permissionMode is "acceptEdits" and a sandbox is available,
+    // automatically block shell-based file operations unless explicitly disabled
+    if (permissionMode === "acceptEdits" && sandbox) {
+        const blockShellFileOps = options.blockShellFileOps ?? true;
+        if (blockShellFileOps) {
+            // Wrap the sandbox to block shell file operations
+            sandbox = wrapSandboxWithBlockedPatterns(sandbox, ACCEPT_EDITS_BLOCKED_PATTERNS);
+        }
+        else {
+            // User explicitly disabled shell blocking - log a warning
+            console.warn("[agent-sdk] Warning: blockShellFileOps is disabled in acceptEdits mode. " +
+                "Shell commands like 'echo > file', 'rm', 'mv', etc. can bypass file edit permissions. " +
+                "This is not recommended for production use.");
+        }
+    }
+    // Tool search configuration
+    const toolSearchConfig = options.toolSearch ?? {};
+    const toolSearchEnabled = toolSearchConfig.enabled ?? "auto";
+    const toolSearchThreshold = toolSearchConfig.threshold ?? 20;
+    const toolSearchMaxResults = toolSearchConfig.maxResults ?? 10;
+    // Track whether deferred loading is active
+    let deferredLoadingActive = false;
+    // Count total plugin tools for threshold calculation and collect plugin skills.
+    // Note: Function-based (streaming) tools are not counted since we don't know
+    // their count until they're invoked with a streaming context.
+    // IMPORTANT: Plugin skills must be collected BEFORE createCoreTools() is called
+    // so the skill tool includes them in progressive disclosure.
+    let totalPluginToolCount = 0;
+    for (const plugin of options.plugins ?? []) {
+        if (plugin.tools && typeof plugin.tools !== "function") {
+            totalPluginToolCount += Object.keys(plugin.tools).length;
+        }
+        // Collect plugin skills early so they're available for skill tool creation
+        if (plugin.skills) {
+            skills.push(...plugin.skills);
+        }
+    }
+    // Determine if we should use deferred loading based on tool search settings
+    // Note: "auto" mode enables deferred loading when tool count exceeds threshold
+    if (toolSearchEnabled === "always") {
+        deferredLoadingActive = true;
+    }
+    else if (toolSearchEnabled === "auto" && totalPluginToolCount > toolSearchThreshold) {
+        deferredLoadingActive = true;
+    }
+    // Auto-create core tools (unless user provides explicit tools)
+    // Note: search_tools is created separately with proper configuration
+    const autoCreatedCoreTools = createCoreTools({
+        backend,
+        state,
+        sandbox,
+        mcpManager: deferredLoadingActive ? undefined : mcpManager, // Only pass if not deferred
+        disabled: options.disabledCoreTools,
+        skills,
+    });
+    // Start with auto-created core tools, then overlay user-provided tools
+    const coreTools = {
+        ...coreToolsToToolSet(autoCreatedCoreTools),
+        ...(options.tools ?? {}),
+    };
+    // Process plugins based on loading mode and deferred loading
+    // Note: Plugin skills are collected earlier (before createCoreTools) so
+    // the skill tool can include them in progressive disclosure.
+    for (const plugin of options.plugins ?? []) {
+        // Handle tools via MCP manager for unified interface
+        // Note: Function-based (streaming) tools are handled separately in
+        // getActiveToolSetWithStreaming() and are not registered here
+        if (plugin.tools && typeof plugin.tools !== "function") {
+            const shouldPreload = preloadPlugins.has(plugin.name);
+            if (pluginLoadingMode === "lazy" && toolRegistry) {
+                // Lazy mode: register with registry for on-demand loading
+                toolRegistry.registerPlugin(plugin.name, plugin.tools);
+            }
+            else if (deferredLoadingActive && !shouldPreload) {
+                // Deferred loading: register tools but don't load them initially
+                mcpManager.registerPluginTools(plugin.name, plugin.tools, {
+                    autoLoad: false,
+                });
+            }
+            else if (pluginLoadingMode === "eager" || shouldPreload) {
+                // Eager mode or preloaded: register and load immediately
+                mcpManager.registerPluginTools(plugin.name, plugin.tools, {
+                    autoLoad: true,
+                });
+            }
+            // explicit mode: don't register, user must do it manually
+        }
+    }
+    // Create search_tools with load capability when deferred loading is active
+    if (deferredLoadingActive && !options.disabledCoreTools?.includes("search_tools")) {
+        coreTools.search_tools = createSearchToolsTool({
+            manager: mcpManager,
+            maxResults: toolSearchMaxResults,
+            enableLoad: true,
+            onToolsLoaded: (toolNames) => {
+                // Tools are now loaded in MCPManager and will be included in getActiveToolSet()
+                // This callback can be used for logging/notifications
+            },
+        });
+    }
+    // Add use_tools meta-tool in lazy mode
+    if (pluginLoadingMode === "lazy" && toolRegistry) {
+        coreTools.use_tools = createUseToolsTool({ registry: toolRegistry });
+    }
+    /**
+     * Filter a tool set by the allowedTools and disallowedTools restrictions.
+     * If neither is set, returns all tools.
+     *
+     * Priority: disallowedTools takes precedence over allowedTools.
+     * If a tool is in both lists, it is blocked.
+     */
+    const filterToolsByAllowed = (toolSet) => {
+        const allowed = options.allowedTools;
+        const disallowed = options.disallowedTools;
+        // If neither restriction is set, return all tools
+        if ((!allowed || allowed.length === 0) && (!disallowed || disallowed.length === 0)) {
+            return toolSet;
+        }
+        const allowedSet = allowed ? new Set(allowed) : null;
+        const disallowedSet = disallowed ? new Set(disallowed) : null;
+        const filtered = {};
+        for (const [name, tool] of Object.entries(toolSet)) {
+            // If disallowedTools is set and tool is in it, skip
+            if (disallowedSet?.has(name)) {
+                continue;
+            }
+            // If allowedTools is set, only include if in the list
+            if (allowedSet) {
+                if (allowedSet.has(name)) {
+                    filtered[name] = tool;
+                }
+            }
+            else {
+                // No allowedTools restriction, include if not disallowed
+                filtered[name] = tool;
+            }
+        }
+        return filtered;
+    };
+    // Helper to get current active tools (core + MCP + dynamically loaded from registry)
+    const getActiveToolSet = (threadId) => {
+        // Start with core tools
+        const allTools = { ...coreTools };
+        // Add MCP tools from plugin registrations
+        const mcpTools = mcpManager.getToolSet();
+        Object.assign(allTools, mcpTools);
+        // Add dynamically loaded tools from registry (lazy mode)
+        if (toolRegistry) {
+            Object.assign(allTools, toolRegistry.getLoadedTools());
+        }
+        // Apply allowedTools filtering
+        const filtered = filterToolsByAllowed(allTools);
+        // Apply permission mode wrapping with canUseTool callback and approval state
+        const withPermissions = wrapToolsWithPermissionMode(filtered, () => permissionMode, options.canUseTool, {
+            approvalDecisions,
+            pendingResponses,
+            checkpointSaver: options.checkpointer,
+            threadId,
+        });
+        // Note: Tool hooks are NOT applied here - they are applied at usage sites
+        // AFTER the task tool is added via addTaskToolIfConfigured. This ensures
+        // the task tool is also wrapped with hooks for logging/metrics.
+        return withPermissions;
+    };
+    /**
+     * Rebuild tools with streaming context for plugins with function-based tools.
+     * This enables tools to stream custom data to the client via ctx.writer.write().
+     */
+    const getActiveToolSetWithStreaming = (streamingContext, threadId, step) => {
+        // Start with core tools
+        const allTools = { ...coreTools };
+        // Process plugins - invoke function-based tools with streaming context
+        for (const plugin of options.plugins ?? []) {
+            if (plugin.tools) {
+                if (typeof plugin.tools === "function") {
+                    // Streaming-aware tools: invoke factory with context
+                    const streamingTools = plugin.tools(streamingContext);
+                    Object.assign(allTools, streamingTools);
+                }
+                else {
+                    // Static tools: use as-is
+                    Object.assign(allTools, plugin.tools);
+                }
+            }
+        }
+        // Add MCP tools from plugin registrations
+        const mcpTools = mcpManager.getToolSet();
+        Object.assign(allTools, mcpTools);
+        // Add dynamically loaded tools from registry (lazy mode)
+        if (toolRegistry) {
+            Object.assign(allTools, toolRegistry.getLoadedTools());
+        }
+        // Apply allowedTools filtering
+        const filtered = filterToolsByAllowed(allTools);
+        // Apply permission mode wrapping with canUseTool callback and approval state
+        const withPermissions = wrapToolsWithPermissionMode(filtered, () => permissionMode, options.canUseTool, {
+            approvalDecisions,
+            pendingResponses,
+            checkpointSaver: options.checkpointer,
+            threadId,
+            step,
+        });
+        // Note: Tool hooks are NOT applied here - they are applied at usage sites
+        // AFTER the task tool is added via addTaskToolIfConfigured. This ensures
+        // the task tool is also wrapped with hooks for logging/metrics.
+        return withPermissions;
+    };
+    /**
+     * Wraps all tools (including task tool) with hooks.
+     * Call this AFTER addTaskToolIfConfigured to ensure task tool is also wrapped.
+     */
+    const applyToolHooks = (tools, threadId) => {
+        return wrapToolsWithHooks(tools, effectiveHooks, agent, threadId ?? "default");
+    };
+    /**
+     * Adds the task tool to a toolset when subagents are configured.
+     *
+     * This enables the agent to delegate work to specialized subagents via the
+     * task tool. The streaming context is only passed when using streamDataResponse(),
+     * allowing streaming subagents to write to the parent's data stream.
+     *
+     * @param tools - The base toolset to augment
+     * @param streamingContext - Optional streaming context for streaming subagents
+     * @returns The toolset with task tool added (if subagents configured)
+     */
+    const addTaskToolIfConfigured = (tools, streamingContext) => {
+        // Skip if no subagents configured
+        if (!options.subagents || options.subagents.length === 0) {
+            return tools;
+        }
+        // Respect disabledCoreTools setting
+        if (options.disabledCoreTools?.includes("task")) {
+            return tools;
+        }
+        return {
+            ...tools,
+            task: createTaskTool({
+                subagents: options.subagents,
+                defaultModel: options.model,
+                parentAgent: agent,
+                // Only pass streaming context when provided (streamDataResponse)
+                streamingContext,
+            }),
+        };
+    };
+    // Track current checkpoint state per thread
+    const threadCheckpoints = new Map();
+    /**
+     * Load checkpoint for a thread if checkpointer is configured.
+     * Returns the loaded checkpoint or undefined.
+     */
+    async function loadCheckpoint(threadId) {
+        if (!options.checkpointer) {
+            return undefined;
+        }
+        // Check if we already have it cached
+        const cached = threadCheckpoints.get(threadId);
+        if (cached) {
+            return cached;
+        }
+        try {
+            // Load from checkpointer
+            const checkpoint = await options.checkpointer.load(threadId);
+            if (checkpoint) {
+                threadCheckpoints.set(threadId, checkpoint);
+                // Restore agent state from checkpoint
+                state.todos = [...checkpoint.state.todos];
+                state.files = { ...checkpoint.state.files };
+            }
+            return checkpoint;
+        }
+        catch (error) {
+            // Wrap checkpoint load errors with CheckpointError
+            throw new CheckpointError(`Failed to load checkpoint for thread ${threadId}`, {
+                operation: "load",
+                threadId,
+                cause: error instanceof Error ? error : undefined,
+                metadata: { threadId },
+            });
+        }
+    }
+    /**
+     * Save checkpoint for a thread if checkpointer is configured.
+     */
+    async function saveCheckpoint(threadId, messages, step) {
+        if (!options.checkpointer) {
+            return undefined;
+        }
+        const existingCheckpoint = threadCheckpoints.get(threadId);
+        let checkpoint;
+        if (existingCheckpoint) {
+            // Update existing checkpoint
+            checkpoint = updateCheckpoint(existingCheckpoint, {
+                messages,
+                step,
+                state: {
+                    todos: [...state.todos],
+                    files: { ...state.files },
+                },
+            });
+        }
+        else {
+            // Create new checkpoint
+            checkpoint = createCheckpoint({
+                threadId,
+                messages,
+                step,
+                state: {
+                    todos: [...state.todos],
+                    files: { ...state.files },
+                },
+            });
+        }
+        try {
+            // Save to checkpointer
+            await options.checkpointer.save(checkpoint);
+            threadCheckpoints.set(threadId, checkpoint);
+            return checkpoint;
+        }
+        catch (error) {
+            // Wrap checkpoint save errors with CheckpointError
+            throw new CheckpointError(`Failed to save checkpoint for thread ${threadId}`, {
+                operation: "save",
+                threadId,
+                cause: error instanceof Error ? error : undefined,
+                metadata: { threadId, step },
+            });
+        }
+    }
+    /**
+     * Fork an existing checkpoint to a new thread ID.
+     * Copies all checkpoint data including messages and state.
+     */
+    async function forkCheckpoint(sourceThreadId, targetThreadId) {
+        if (!options.checkpointer) {
+            return undefined;
+        }
+        // Load the source checkpoint
+        const sourceCheckpoint = await loadCheckpoint(sourceThreadId);
+        if (!sourceCheckpoint) {
+            return undefined;
+        }
+        // Create a new checkpoint with the target threadId
+        const forkedCheckpoint = createCheckpoint({
+            threadId: targetThreadId,
+            messages: [...sourceCheckpoint.messages],
+            step: sourceCheckpoint.step,
+            state: {
+                todos: [...sourceCheckpoint.state.todos],
+                files: { ...sourceCheckpoint.state.files },
+            },
+        });
+        try {
+            // Save the forked checkpoint
+            await options.checkpointer.save(forkedCheckpoint);
+            threadCheckpoints.set(targetThreadId, forkedCheckpoint);
+            return forkedCheckpoint;
+        }
+        catch (error) {
+            throw new CheckpointError(`Failed to fork checkpoint from ${sourceThreadId} to ${targetThreadId}`, {
+                operation: "fork",
+                threadId: targetThreadId,
+                cause: error instanceof Error ? error : undefined,
+                metadata: { sourceThreadId, targetThreadId },
+            });
+        }
+    }
+    /**
+     * Build the messages array for AI SDK from GenerateOptions.
+     * If a checkpoint exists for the threadId, prepends checkpoint messages.
+     * If forkSession is specified, creates a new session from the source.
+     * If contextManager is provided, applies automatic compaction if needed.
+     */
+    async function buildMessages(genOptions) {
+        const messages = [];
+        let checkpoint;
+        let forkedSessionId;
+        // Handle session forking
+        if (genOptions.forkSession && genOptions.threadId) {
+            forkedSessionId = genOptions.forkSession;
+            checkpoint = await forkCheckpoint(genOptions.threadId, forkedSessionId);
+            if (checkpoint) {
+                // Prepend forked checkpoint messages
+                messages.push(...checkpoint.messages);
+            }
+        }
+        else if (genOptions.threadId) {
+            // Normal checkpoint loading
+            checkpoint = await loadCheckpoint(genOptions.threadId);
+            if (checkpoint) {
+                // Prepend checkpoint messages
+                messages.push(...checkpoint.messages);
+            }
+        }
+        // Add conversation history if provided
+        if (genOptions.messages) {
+            messages.push(...genOptions.messages);
+        }
+        // Add user prompt if provided
+        if (genOptions.prompt) {
+            messages.push({ role: "user", content: genOptions.prompt });
+        }
+        // Apply context compaction if contextManager is configured
+        // Skip compaction if _skipCompaction flag is set (used during summary generation)
+        if (options.contextManager && !genOptions._skipCompaction) {
+            const contextManager = options.contextManager;
+            // Check if compaction is needed
+            const { trigger, reason } = contextManager.shouldCompact(messages);
+            if (trigger && reason) {
+                // Calculate token count before compaction
+                const tokensBefore = contextManager.tokenCounter.countMessages(messages);
+                const messagesBefore = messages.length;
+                // Emit PreCompact hook
+                const preCompactHooks = effectiveHooks?.PreCompact ?? [];
+                if (preCompactHooks.length > 0) {
+                    const preCompactInput = {
+                        hook_event_name: "PreCompact",
+                        session_id: genOptions.threadId ?? "default",
+                        cwd: process.cwd(),
+                        message_count: messagesBefore,
+                        tokens_before: tokensBefore,
+                    };
+                    await invokeHooksWithTimeout(preCompactHooks, preCompactInput, null, agent);
+                }
+                // Perform compaction
+                const compactionResult = await contextManager.compact(messages, agent, reason);
+                // Replace messages with compacted version
+                messages.length = 0;
+                messages.push(...compactionResult.newMessages);
+                // Emit PostCompact hook with metrics
+                const postCompactHooks = effectiveHooks?.PostCompact ?? [];
+                if (postCompactHooks.length > 0) {
+                    const postCompactInput = {
+                        hook_event_name: "PostCompact",
+                        session_id: genOptions.threadId ?? "default",
+                        cwd: process.cwd(),
+                        messages_before: compactionResult.messagesBefore,
+                        messages_after: compactionResult.messagesAfter,
+                        tokens_before: compactionResult.tokensBefore,
+                        tokens_after: compactionResult.tokensAfter,
+                        tokens_saved: compactionResult.tokensBefore - compactionResult.tokensAfter,
+                    };
+                    await invokeHooksWithTimeout(postCompactHooks, postCompactInput, null, agent);
+                }
+            }
+        }
+        return { messages, checkpoint, forkedSessionId };
+    }
+    /**
+     * Map AI SDK steps to our GenerateStep format.
+     */
+    function mapSteps(steps) {
+        return steps.map((step) => ({
+            text: step.text,
+            toolCalls: step.toolCalls.map((tc) => ({
+                toolCallId: tc.toolCallId,
+                toolName: tc.toolName,
+                input: tc.input,
+            })),
+            toolResults: step.toolResults.map((tr) => ({
+                toolCallId: tr.toolCallId,
+                toolName: tr.toolName,
+                output: tr.output,
+            })),
+            finishReason: step.finishReason,
+            usage: step.usage,
+        }));
+    }
+    const agent = {
+        id,
+        options,
+        backend,
+        state,
+        getSkills() {
+            return [...skills];
+        },
+        async generate(genOptions) {
+            // Invoke unified PreGenerate hooks
+            const preGenerateHooks = effectiveHooks?.PreGenerate ?? [];
+            const preGenResult = await invokePreGenerateHooks(preGenerateHooks, genOptions, agent);
+            // Check for cache short-circuit via respondWith
+            if (preGenResult.cachedResult !== undefined) {
+                return preGenResult.cachedResult;
+            }
+            let effectiveGenOptions = preGenResult.effectiveOptions;
+            // Initialize retry loop state
+            const retryState = createRetryLoopState(options.model);
+            // Track messages for emergency compaction (accessible in catch block)
+            let lastBuiltMessages = [];
+            while (retryState.retryAttempt <= retryState.maxRetries) {
+                try {
+                    const { messages, checkpoint, forkedSessionId } = await buildMessages(effectiveGenOptions);
+                    // Store for potential emergency compaction in catch block
+                    lastBuiltMessages = messages;
+                    const maxSteps = options.maxSteps ?? 10;
+                    const startStep = checkpoint?.step ?? 0;
+                    // Build initial params - use active tools (core + dynamically loaded + task)
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped
+                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const initialParams = {
+                        system: options.systemPrompt,
+                        messages,
+                        tools: activeTools,
+                        maxTokens: effectiveGenOptions.maxTokens,
+                        temperature: effectiveGenOptions.temperature,
+                        stopSequences: effectiveGenOptions.stopSequences,
+                        abortSignal: effectiveGenOptions.signal,
+                        providerOptions: effectiveGenOptions.providerOptions,
+                        headers: effectiveGenOptions.headers,
+                    };
+                    // Execute generation
+                    const response = await generateText({
+                        model: retryState.currentModel,
+                        system: initialParams.system,
+                        messages: initialParams.messages,
+                        tools: initialParams.tools,
+                        maxOutputTokens: initialParams.maxTokens,
+                        temperature: initialParams.temperature,
+                        stopSequences: initialParams.stopSequences,
+                        abortSignal: initialParams.abortSignal,
+                        stopWhen: stepCountIs(maxSteps),
+                        // Passthrough AI SDK options
+                        output: effectiveGenOptions.output,
+                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                        providerOptions: initialParams.providerOptions,
+                        headers: initialParams.headers,
+                    });
+                    // Only access output if an output schema was provided
+                    // (accessing response.output throws AI_NoOutputGeneratedError otherwise)
+                    let output;
+                    if (effectiveGenOptions.output) {
+                        try {
+                            output = response.output;
+                        }
+                        catch {
+                            // No structured output was generated
+                        }
+                    }
+                    const result = {
+                        status: "complete",
+                        text: response.text,
+                        usage: response.usage,
+                        finishReason: response.finishReason,
+                        output,
+                        steps: mapSteps(response.steps),
+                        forkedSessionId,
+                    };
+                    // Update context manager with actual usage if available
+                    if (options.contextManager?.updateUsage && response.usage) {
+                        options.contextManager.updateUsage({
+                            inputTokens: response.usage.inputTokens,
+                            outputTokens: response.usage.outputTokens,
+                            totalTokens: response.usage.totalTokens,
+                        });
+                    }
+                    // Save checkpoint - use forked session ID if forking, otherwise use original threadId
+                    const checkpointThreadId = forkedSessionId ?? effectiveGenOptions.threadId;
+                    if (checkpointThreadId && options.checkpointer) {
+                        // Build final messages including the assistant response
+                        const finalMessages = [
+                            ...messages,
+                            { role: "assistant", content: response.text },
+                        ];
+                        await saveCheckpoint(checkpointThreadId, finalMessages, startStep + response.steps.length);
+                    }
+                    // Invoke unified PostGenerate hooks
+                    const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                    let finalResult = result;
+                    if (postGenerateHooks.length > 0) {
+                        const postGenerateInput = {
+                            hook_event_name: "PostGenerate",
+                            session_id: effectiveGenOptions.threadId ?? "default",
+                            cwd: process.cwd(),
+                            options: effectiveGenOptions,
+                            result,
+                        };
+                        const hookOutputs = await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
+                        // Apply output transformation via updatedResult
+                        // Note: Hooks can only return complete results, not interrupted ones
+                        const updatedResult = extractUpdatedResult(hookOutputs);
+                        if (updatedResult !== undefined) {
+                            finalResult = updatedResult;
+                        }
+                    }
+                    return finalResult;
+                }
+                catch (error) {
+                    // Check if this is an InterruptSignal (new interrupt system)
+                    if (isInterruptSignal(error)) {
+                        const interrupt = error.interrupt;
+                        // Save the interrupt to checkpoint
+                        if (effectiveGenOptions.threadId && options.checkpointer) {
+                            const checkpoint = await options.checkpointer.load(effectiveGenOptions.threadId);
+                            if (checkpoint) {
+                                const updatedCheckpoint = updateCheckpoint(checkpoint, {
+                                    pendingInterrupt: interrupt,
+                                });
+                                await options.checkpointer.save(updatedCheckpoint);
+                            }
+                        }
+                        // Emit InterruptRequested hook
+                        const interruptRequestedHooks = effectiveHooks?.InterruptRequested ?? [];
+                        if (interruptRequestedHooks.length > 0) {
+                            const hookInput = {
+                                hook_event_name: "InterruptRequested",
+                                session_id: effectiveGenOptions.threadId ?? "default",
+                                cwd: process.cwd(),
+                                interrupt_id: interrupt.id,
+                                interrupt_type: interrupt.type,
+                                tool_call_id: interrupt.toolCallId,
+                                tool_name: interrupt.toolName,
+                                request: interrupt.request,
+                            };
+                            await invokeHooksWithTimeout(interruptRequestedHooks, hookInput, null, agent);
+                        }
+                        // Return interrupted result
+                        const interruptedResult = {
+                            status: "interrupted",
+                            interrupt,
+                            partial: {
+                                text: "",
+                                steps: [],
+                                usage: undefined,
+                            },
+                        };
+                        return interruptedResult;
+                    }
+                    // Normalize error to AgentError
+                    const normalizedError = normalizeError(error, "Generation failed", effectiveGenOptions.threadId);
+                    // Check for context length error and attempt emergency compaction if enabled
+                    // Note: Only attempt this ONCE to avoid infinite loops
+                    if (options.contextManager?.policy.enableErrorFallback &&
+                        retryState.retryAttempt === 0 && // Only on first error, not on retry
+                        isContextLengthError(normalizedError)) {
+                        // Emergency compaction - try to recover
+                        // We'll compact and save to checkpoint, then retry
+                        try {
+                            // Get current messages from checkpoint if available, or use the messages from the current call
+                            let messagesToCompact = [];
+                            if (effectiveGenOptions.threadId && options.checkpointer) {
+                                const checkpoint = await options.checkpointer.load(effectiveGenOptions.threadId);
+                                if (checkpoint && checkpoint.messages.length > 0) {
+                                    messagesToCompact = checkpoint.messages;
+                                }
+                            }
+                            // Fall back to messages from the current call if checkpoint is empty
+                            if (messagesToCompact.length === 0 && lastBuiltMessages.length > 0) {
+                                messagesToCompact = lastBuiltMessages;
+                            }
+                            // If we have messages to compact, do emergency compaction
+                            if (messagesToCompact.length > 0) {
+                                const compactionResult = await options.contextManager.compact(messagesToCompact, agent, "error_fallback");
+                                // Save compacted state to checkpoint and clear original messages
+                                // to prevent duplication on retry
+                                if (effectiveGenOptions.threadId && options.checkpointer) {
+                                    const existingCheckpoint = await options.checkpointer.load(effectiveGenOptions.threadId);
+                                    if (existingCheckpoint) {
+                                        const updatedCheckpoint = updateCheckpoint(existingCheckpoint, {
+                                            messages: compactionResult.newMessages,
+                                        });
+                                        await options.checkpointer.save(updatedCheckpoint);
+                                        // Update cache
+                                        threadCheckpoints.set(effectiveGenOptions.threadId, updatedCheckpoint);
+                                    }
+                                    else {
+                                        // Create a new checkpoint with compacted messages
+                                        const newCheckpoint = createCheckpoint({
+                                            threadId: effectiveGenOptions.threadId,
+                                            messages: compactionResult.newMessages,
+                                            step: 0,
+                                            state: {
+                                                todos: [...state.todos],
+                                                files: { ...state.files },
+                                            },
+                                        });
+                                        await options.checkpointer.save(newCheckpoint);
+                                        threadCheckpoints.set(effectiveGenOptions.threadId, newCheckpoint);
+                                    }
+                                    // Clear messages from effectiveGenOptions to prevent duplication
+                                    // The retry will use checkpoint messages only
+                                    effectiveGenOptions = {
+                                        ...effectiveGenOptions,
+                                        messages: undefined,
+                                    };
+                                }
+                                retryState.retryAttempt++;
+                                // Retry immediately with compacted context
+                                continue;
+                            }
+                        }
+                        catch (_compactionError) {
+                            // If compaction itself fails, don't retry - fall through to normal error handling
+                        }
+                    }
+                    // Handle error with PostGenerateFailure hooks and fallback logic
+                    const postGenerateFailureHooks = effectiveHooks?.PostGenerateFailure ?? [];
+                    const errorDecision = await handleGenerationError(normalizedError, postGenerateFailureHooks, effectiveGenOptions, agent, retryState, options.fallbackModel, shouldUseFallback);
+                    if (errorDecision.shouldRetry) {
+                        // Update retry state
+                        Object.assign(retryState, updateRetryLoopState(retryState, errorDecision));
+                        // Wait for the specified delay before retrying
+                        await waitForRetryDelay(errorDecision.retryDelayMs);
+                        // Continue to next iteration of retry loop
+                        continue;
+                    }
+                    // No retry requested or max retries exceeded - throw the normalized error
+                    throw normalizedError;
+                }
+            }
+            // This should never be reached, but TypeScript needs it for type safety
+            throw new Error("Unexpected: retry loop exited without return or throw");
+        },
+        async *stream(genOptions) {
+            // Invoke unified PreGenerate hooks
+            const preGenerateHooks = effectiveHooks?.PreGenerate ?? [];
+            const preGenResult = await invokePreGenerateHooks(preGenerateHooks, genOptions, agent);
+            // Check for cache short-circuit via respondWith
+            // For streaming, we convert the cached GenerateResult into StreamParts
+            if (preGenResult.cachedResult !== undefined) {
+                const cachedResult = preGenResult.cachedResult;
+                // Only process complete results (interrupted results can't be cached)
+                if (cachedResult.status === "complete") {
+                    // Yield cached result as stream parts
+                    // First, yield text as a single text-delta
+                    if (cachedResult.text) {
+                        yield { type: "text-delta", text: cachedResult.text };
+                    }
+                    // Yield tool calls and results from steps
+                    for (const step of cachedResult.steps ?? []) {
+                        for (const toolCall of step.toolCalls ?? []) {
+                            yield {
+                                type: "tool-call",
+                                toolCallId: toolCall.toolCallId,
+                                toolName: toolCall.toolName,
+                                input: toolCall.input,
+                            };
+                        }
+                        for (const toolResult of step.toolResults ?? []) {
+                            yield {
+                                type: "tool-result",
+                                toolCallId: toolResult.toolCallId,
+                                toolName: toolResult.toolName,
+                                output: toolResult.output,
+                            };
+                        }
+                    }
+                    // Finally yield finish
+                    yield {
+                        type: "finish",
+                        finishReason: cachedResult.finishReason,
+                        usage: cachedResult.usage,
+                    };
+                }
+                return;
+            }
+            const effectiveGenOptions = preGenResult.effectiveOptions;
+            // Initialize retry loop state
+            const retryState = createRetryLoopState(options.model);
+            while (retryState.retryAttempt <= retryState.maxRetries) {
+                try {
+                    const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
+                    const maxSteps = options.maxSteps ?? 10;
+                    const startStep = checkpoint?.step ?? 0;
+                    // Build initial params - use active tools (core + dynamically loaded + task)
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped
+                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const initialParams = {
+                        system: options.systemPrompt,
+                        messages,
+                        tools: activeTools,
+                        maxTokens: effectiveGenOptions.maxTokens,
+                        temperature: effectiveGenOptions.temperature,
+                        stopSequences: effectiveGenOptions.stopSequences,
+                        abortSignal: effectiveGenOptions.signal,
+                        providerOptions: effectiveGenOptions.providerOptions,
+                        headers: effectiveGenOptions.headers,
+                    };
+                    // Execute stream
+                    const response = streamText({
+                        model: retryState.currentModel,
+                        system: initialParams.system,
+                        messages: initialParams.messages,
+                        tools: initialParams.tools,
+                        maxOutputTokens: initialParams.maxTokens,
+                        temperature: initialParams.temperature,
+                        stopSequences: initialParams.stopSequences,
+                        abortSignal: initialParams.abortSignal,
+                        stopWhen: stepCountIs(maxSteps),
+                        // Passthrough AI SDK options
+                        output: genOptions.output,
+                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                        providerOptions: initialParams.providerOptions,
+                        headers: initialParams.headers,
+                    });
+                    for await (const part of response.fullStream) {
+                        if (part.type === "text-delta") {
+                            yield { type: "text-delta", text: part.text };
+                        }
+                        else if (part.type === "tool-call") {
+                            yield {
+                                type: "tool-call",
+                                toolCallId: part.toolCallId,
+                                toolName: part.toolName,
+                                input: part.input,
+                            };
+                        }
+                        else if (part.type === "tool-result") {
+                            yield {
+                                type: "tool-result",
+                                toolCallId: part.toolCallId,
+                                toolName: part.toolName,
+                                output: part.output,
+                            };
+                        }
+                        else if (part.type === "finish") {
+                            yield {
+                                type: "finish",
+                                finishReason: part.finishReason,
+                                usage: part.totalUsage,
+                            };
+                        }
+                        else if (part.type === "error") {
+                            yield { type: "error", error: part.error };
+                        }
+                    }
+                    // Get final result for hooks - need to await all properties
+                    const [text, usage, finishReason, steps] = await Promise.all([
+                        response.text,
+                        response.usage,
+                        response.finishReason,
+                        response.steps,
+                    ]);
+                    // Only access output if an output schema was provided
+                    let output;
+                    if (genOptions.output) {
+                        try {
+                            output = await response.output;
+                        }
+                        catch {
+                            // No structured output was generated
+                        }
+                    }
+                    const result = {
+                        status: "complete",
+                        text,
+                        usage,
+                        finishReason: finishReason,
+                        output,
+                        steps: mapSteps(steps),
+                    };
+                    // Save checkpoint if threadId is provided
+                    if (effectiveGenOptions.threadId && options.checkpointer) {
+                        const finalMessages = [
+                            ...messages,
+                            { role: "assistant", content: text },
+                        ];
+                        await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + steps.length);
+                    }
+                    // Invoke unified PostGenerate hooks
+                    const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                    if (postGenerateHooks.length > 0) {
+                        const postGenerateInput = {
+                            hook_event_name: "PostGenerate",
+                            session_id: effectiveGenOptions.threadId ?? "default",
+                            cwd: process.cwd(),
+                            options: effectiveGenOptions,
+                            result,
+                        };
+                        await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
+                        // Note: updatedResult is not applied for streaming since the stream has already been sent
+                    }
+                    // Success - break out of retry loop
+                    return;
+                }
+                catch (error) {
+                    // Normalize error to AgentError
+                    const normalizedError = normalizeError(error, "Stream generation failed", effectiveGenOptions.threadId);
+                    // Handle error with PostGenerateFailure hooks and fallback logic
+                    const postGenerateFailureHooks = effectiveHooks?.PostGenerateFailure ?? [];
+                    const errorDecision = await handleGenerationError(normalizedError, postGenerateFailureHooks, effectiveGenOptions, agent, retryState, options.fallbackModel, shouldUseFallback);
+                    if (errorDecision.shouldRetry) {
+                        // Update retry state
+                        Object.assign(retryState, updateRetryLoopState(retryState, errorDecision));
+                        // Wait for the specified delay before retrying
+                        await waitForRetryDelay(errorDecision.retryDelayMs);
+                        // Continue to next iteration of retry loop
+                        continue;
+                    }
+                    // No retry requested or max retries exceeded - throw the normalized error
+                    throw normalizedError;
+                }
+            }
+            // This should never be reached, but TypeScript needs it for type safety
+            throw new Error("Unexpected: retry loop exited without return or throw");
+        },
+        async streamResponse(genOptions) {
+            // Invoke unified PreGenerate hooks
+            const preGenerateHooks = effectiveHooks?.PreGenerate ?? [];
+            const preGenResult = await invokePreGenerateHooks(preGenerateHooks, genOptions, agent);
+            // Check for cache short-circuit via respondWith
+            // For streaming response, create a simple text response from the cached result
+            if (preGenResult.cachedResult !== undefined) {
+                const cachedResult = preGenResult.cachedResult;
+                // For cached results, return a simple Response with the cached text
+                // This is compatible with useChat and provides immediate delivery
+                // Only complete results can be cached
+                const text = cachedResult.status === "complete" ? cachedResult.text : "";
+                return new Response(text, {
+                    headers: {
+                        "Content-Type": "text/plain; charset=utf-8",
+                    },
+                });
+            }
+            const effectiveGenOptions = preGenResult.effectiveOptions;
+            // Initialize retry loop state
+            const retryState = createRetryLoopState(options.model);
+            while (retryState.retryAttempt <= retryState.maxRetries) {
+                try {
+                    const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
+                    const maxSteps = options.maxSteps ?? 10;
+                    const startStep = checkpoint?.step ?? 0;
+                    // Build initial params - use active tools (core + dynamically loaded + task)
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped
+                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const initialParams = {
+                        system: options.systemPrompt,
+                        messages,
+                        tools: activeTools,
+                        maxTokens: effectiveGenOptions.maxTokens,
+                        temperature: effectiveGenOptions.temperature,
+                        stopSequences: effectiveGenOptions.stopSequences,
+                        abortSignal: effectiveGenOptions.signal,
+                        providerOptions: effectiveGenOptions.providerOptions,
+                        headers: effectiveGenOptions.headers,
+                    };
+                    // Track step count for incremental checkpointing
+                    let currentStepCount = 0;
+                    // Execute stream
+                    const result = streamText({
+                        model: retryState.currentModel,
+                        system: initialParams.system,
+                        messages: initialParams.messages,
+                        tools: initialParams.tools,
+                        maxOutputTokens: initialParams.maxTokens,
+                        temperature: initialParams.temperature,
+                        stopSequences: initialParams.stopSequences,
+                        abortSignal: initialParams.abortSignal,
+                        stopWhen: stepCountIs(maxSteps),
+                        // Passthrough AI SDK options
+                        output: effectiveGenOptions.output,
+                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                        providerOptions: initialParams.providerOptions,
+                        headers: initialParams.headers,
+                        // Incremental checkpointing: save after each step if enabled
+                        onStepFinish: effectiveGenOptions.checkpointAfterToolCall
+                            ? async (stepResult) => {
+                                if (effectiveGenOptions.threadId && options.checkpointer) {
+                                    currentStepCount++;
+                                    // Build messages including this step's results
+                                    const stepMessages = [
+                                        ...initialParams.messages,
+                                        {
+                                            role: "assistant",
+                                            content: stepResult.text,
+                                        },
+                                    ];
+                                    await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                }
+                            }
+                            : undefined,
+                        // Save checkpoint and emit PostGenerate hook after completion
+                        onFinish: async (finishResult) => {
+                            // Update context manager with actual usage if available
+                            if (options.contextManager?.updateUsage && finishResult.usage) {
+                                options.contextManager.updateUsage({
+                                    inputTokens: finishResult.usage.inputTokens,
+                                    outputTokens: finishResult.usage.outputTokens,
+                                    totalTokens: finishResult.usage.totalTokens,
+                                });
+                            }
+                            if (effectiveGenOptions.threadId && options.checkpointer) {
+                                const finalMessages = [
+                                    ...initialParams.messages,
+                                    { role: "assistant", content: finishResult.text },
+                                ];
+                                await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
+                            }
+                            // Invoke unified PostGenerate hooks
+                            const hookResult = {
+                                status: "complete",
+                                text: finishResult.text,
+                                usage: finishResult.usage,
+                                finishReason: finishResult.finishReason,
+                                output: undefined,
+                                steps: mapSteps(finishResult.steps),
+                            };
+                            const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                            if (postGenerateHooks.length > 0) {
+                                const postGenerateInput = {
+                                    hook_event_name: "PostGenerate",
+                                    session_id: effectiveGenOptions.threadId ?? "default",
+                                    cwd: process.cwd(),
+                                    options: effectiveGenOptions,
+                                    result: hookResult,
+                                };
+                                await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
+                                // Note: updatedResult is not applied for streaming since the stream has already been sent
+                            }
+                        },
+                    });
+                    // Return AI SDK compatible response for use with useChat
+                    // Note: Not passing originalMessages since ModelMessage[] != UIMessage[]
+                    // The AI SDK will reconstruct messages from the stream
+                    return result.toUIMessageStreamResponse();
+                }
+                catch (error) {
+                    // Normalize error to AgentError
+                    const normalizedError = normalizeError(error, "Stream generation failed", effectiveGenOptions.threadId);
+                    // Handle error with PostGenerateFailure hooks and fallback logic
+                    const postGenerateFailureHooks = effectiveHooks?.PostGenerateFailure ?? [];
+                    const errorDecision = await handleGenerationError(normalizedError, postGenerateFailureHooks, effectiveGenOptions, agent, retryState, options.fallbackModel, shouldUseFallback);
+                    if (errorDecision.shouldRetry) {
+                        // Update retry state
+                        Object.assign(retryState, updateRetryLoopState(retryState, errorDecision));
+                        // Wait for the specified delay before retrying
+                        await waitForRetryDelay(errorDecision.retryDelayMs);
+                        // Continue to next iteration of retry loop
+                        continue;
+                    }
+                    // No retry requested or max retries exceeded - throw the normalized error
+                    throw normalizedError;
+                }
+            }
+            // This should never be reached, but TypeScript needs it for type safety
+            throw new Error("Unexpected: retry loop exited without return or throw");
+        },
+        async streamRaw(genOptions) {
+            // Invoke unified PreGenerate hooks
+            // Note: respondWith cache short-circuit is NOT supported for streamRaw()
+            // because it returns the raw AI SDK streamText result which cannot be mocked.
+            // Use stream(), streamResponse(), or streamDataResponse() for caching support.
+            const preGenerateHooks = effectiveHooks?.PreGenerate ?? [];
+            const preGenResult = await invokePreGenerateHooks(preGenerateHooks, genOptions, agent);
+            // Input transformation is applied even though respondWith is not supported
+            const effectiveGenOptions = preGenResult.effectiveOptions;
+            // Initialize retry loop state
+            const retryState = createRetryLoopState(options.model);
+            while (retryState.retryAttempt <= retryState.maxRetries) {
+                try {
+                    const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
+                    const maxSteps = options.maxSteps ?? 10;
+                    const startStep = checkpoint?.step ?? 0;
+                    // Build initial params - use active tools (core + dynamically loaded + task)
+                    // Apply hooks AFTER adding task tool so task tool is also wrapped
+                    const activeTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSet(effectiveGenOptions.threadId)), effectiveGenOptions.threadId);
+                    const initialParams = {
+                        system: options.systemPrompt,
+                        messages,
+                        tools: activeTools,
+                        maxTokens: effectiveGenOptions.maxTokens,
+                        temperature: effectiveGenOptions.temperature,
+                        stopSequences: effectiveGenOptions.stopSequences,
+                        abortSignal: effectiveGenOptions.signal,
+                        providerOptions: effectiveGenOptions.providerOptions,
+                        headers: effectiveGenOptions.headers,
+                    };
+                    // Track step count for incremental checkpointing
+                    let currentStepCount = 0;
+                    // Execute stream
+                    const result = streamText({
+                        model: retryState.currentModel,
+                        system: initialParams.system,
+                        messages: initialParams.messages,
+                        tools: initialParams.tools,
+                        maxOutputTokens: initialParams.maxTokens,
+                        temperature: initialParams.temperature,
+                        stopSequences: initialParams.stopSequences,
+                        abortSignal: initialParams.abortSignal,
+                        stopWhen: stepCountIs(maxSteps),
+                        // Passthrough AI SDK options
+                        output: effectiveGenOptions.output,
+                        // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                        providerOptions: initialParams.providerOptions,
+                        headers: initialParams.headers,
+                        // Incremental checkpointing: save after each step if enabled
+                        onStepFinish: effectiveGenOptions.checkpointAfterToolCall
+                            ? async (stepResult) => {
+                                if (effectiveGenOptions.threadId && options.checkpointer) {
+                                    currentStepCount++;
+                                    // Build messages including this step's results
+                                    const stepMessages = [
+                                        ...initialParams.messages,
+                                        {
+                                            role: "assistant",
+                                            content: stepResult.text,
+                                        },
+                                    ];
+                                    await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                }
+                            }
+                            : undefined,
+                        // Save checkpoint and invoke unified PostGenerate hook after completion
+                        onFinish: async (finishResult) => {
+                            // Update context manager with actual usage if available
+                            if (options.contextManager?.updateUsage && finishResult.usage) {
+                                options.contextManager.updateUsage({
+                                    inputTokens: finishResult.usage.inputTokens,
+                                    outputTokens: finishResult.usage.outputTokens,
+                                    totalTokens: finishResult.usage.totalTokens,
+                                });
+                            }
+                            if (effectiveGenOptions.threadId && options.checkpointer) {
+                                const finalMessages = [
+                                    ...initialParams.messages,
+                                    { role: "assistant", content: finishResult.text },
+                                ];
+                                await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
+                            }
+                            // Invoke unified PostGenerate hooks
+                            const hookResult = {
+                                status: "complete",
+                                text: finishResult.text,
+                                usage: finishResult.usage,
+                                finishReason: finishResult.finishReason,
+                                output: undefined,
+                                steps: mapSteps(finishResult.steps),
+                            };
+                            const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                            if (postGenerateHooks.length > 0) {
+                                const postGenerateInput = {
+                                    hook_event_name: "PostGenerate",
+                                    session_id: effectiveGenOptions.threadId ?? "default",
+                                    cwd: process.cwd(),
+                                    options: effectiveGenOptions,
+                                    result: hookResult,
+                                };
+                                await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
+                                // Note: updatedResult is not applied for streaming since the stream has already been sent
+                            }
+                        },
+                    });
+                    return result;
+                }
+                catch (error) {
+                    // Normalize error to AgentError
+                    const normalizedError = normalizeError(error, "Stream generation failed", effectiveGenOptions.threadId);
+                    // Handle error with PostGenerateFailure hooks and fallback logic
+                    const postGenerateFailureHooks = effectiveHooks?.PostGenerateFailure ?? [];
+                    const errorDecision = await handleGenerationError(normalizedError, postGenerateFailureHooks, effectiveGenOptions, agent, retryState, options.fallbackModel, shouldUseFallback);
+                    if (errorDecision.shouldRetry) {
+                        // Update retry state
+                        Object.assign(retryState, updateRetryLoopState(retryState, errorDecision));
+                        // Wait for the specified delay before retrying
+                        await waitForRetryDelay(errorDecision.retryDelayMs);
+                        // Continue to next iteration of retry loop
+                        continue;
+                    }
+                    // No retry requested or max retries exceeded - throw the normalized error
+                    throw normalizedError;
+                }
+            }
+            // This should never be reached, but TypeScript needs it for type safety
+            throw new Error("Unexpected: retry loop exited without return or throw");
+        },
+        async streamDataResponse(genOptions) {
+            // Invoke unified PreGenerate hooks
+            const preGenerateHooks = effectiveHooks?.PreGenerate ?? [];
+            const preGenResult = await invokePreGenerateHooks(preGenerateHooks, genOptions, agent);
+            // Check for cache short-circuit via respondWith
+            // For data stream response, create a simple text response from the cached result
+            if (preGenResult.cachedResult !== undefined) {
+                const cachedResult = preGenResult.cachedResult;
+                // For cached results, return a simple Response with the cached text
+                // This is compatible with useChat and provides immediate delivery
+                // Only complete results can be cached
+                const text = cachedResult.status === "complete" ? cachedResult.text : "";
+                return new Response(text, {
+                    headers: {
+                        "Content-Type": "text/plain; charset=utf-8",
+                    },
+                });
+            }
+            const effectiveGenOptions = preGenResult.effectiveOptions;
+            // Initialize retry loop state
+            const retryState = createRetryLoopState(options.model);
+            while (retryState.retryAttempt <= retryState.maxRetries) {
+                try {
+                    const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
+                    const maxSteps = options.maxSteps ?? 10;
+                    const startStep = checkpoint?.step ?? 0;
+                    // Capture currentModel for use in the callback closure
+                    const modelToUse = retryState.currentModel;
+                    // Create a UI message stream that tools can write to
+                    const stream = createUIMessageStream({
+                        execute: async ({ writer }) => {
+                            // Notify caller that writer is ready (for log streaming setup)
+                            if (effectiveGenOptions.onStreamWriterReady) {
+                                effectiveGenOptions.onStreamWriterReady(writer);
+                            }
+                            // Create streaming context for tools
+                            const streamingContext = { writer };
+                            // Build tools with streaming context and task tool
+                            // Apply hooks AFTER adding task tool so task tool is also wrapped
+                            const streamingTools = applyToolHooks(addTaskToolIfConfigured(getActiveToolSetWithStreaming(streamingContext, effectiveGenOptions.threadId), streamingContext), effectiveGenOptions.threadId);
+                            // Build initial params with streaming-aware tools
+                            const initialParams = {
+                                system: options.systemPrompt,
+                                messages,
+                                tools: streamingTools,
+                                maxTokens: effectiveGenOptions.maxTokens,
+                                temperature: effectiveGenOptions.temperature,
+                                stopSequences: effectiveGenOptions.stopSequences,
+                                abortSignal: effectiveGenOptions.signal,
+                                providerOptions: effectiveGenOptions.providerOptions,
+                                headers: effectiveGenOptions.headers,
+                            };
+                            // Track step count for incremental checkpointing
+                            let currentStepCount = 0;
+                            // Execute stream
+                            const result = streamText({
+                                model: modelToUse,
+                                system: initialParams.system,
+                                messages: initialParams.messages,
+                                tools: initialParams.tools,
+                                maxOutputTokens: initialParams.maxTokens,
+                                temperature: initialParams.temperature,
+                                stopSequences: initialParams.stopSequences,
+                                abortSignal: initialParams.abortSignal,
+                                stopWhen: stepCountIs(maxSteps),
+                                // Passthrough AI SDK options
+                                output: effectiveGenOptions.output,
+                                // biome-ignore lint/suspicious/noExplicitAny: Type cast needed for AI SDK compatibility
+                                providerOptions: initialParams.providerOptions,
+                                headers: initialParams.headers,
+                                // Incremental checkpointing: save after each step if enabled
+                                onStepFinish: effectiveGenOptions.checkpointAfterToolCall
+                                    ? async (stepResult) => {
+                                        if (effectiveGenOptions.threadId && options.checkpointer) {
+                                            currentStepCount++;
+                                            // Build messages including this step's results
+                                            const stepMessages = [
+                                                ...initialParams.messages,
+                                                {
+                                                    role: "assistant",
+                                                    content: stepResult.text,
+                                                },
+                                            ];
+                                            await saveCheckpoint(effectiveGenOptions.threadId, stepMessages, startStep + currentStepCount);
+                                        }
+                                    }
+                                    : undefined,
+                                // Save checkpoint and invoke unified PostGenerate hook after completion
+                                onFinish: async (finishResult) => {
+                                    // Update context manager with actual usage if available
+                                    if (options.contextManager?.updateUsage && finishResult.usage) {
+                                        options.contextManager.updateUsage({
+                                            inputTokens: finishResult.usage.inputTokens,
+                                            outputTokens: finishResult.usage.outputTokens,
+                                            totalTokens: finishResult.usage.totalTokens,
+                                        });
+                                    }
+                                    if (effectiveGenOptions.threadId && options.checkpointer) {
+                                        const finalMessages = [
+                                            ...initialParams.messages,
+                                            {
+                                                role: "assistant",
+                                                content: finishResult.text,
+                                            },
+                                        ];
+                                        await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + finishResult.steps.length);
+                                    }
+                                    // Invoke unified PostGenerate hooks
+                                    const hookResult = {
+                                        status: "complete",
+                                        text: finishResult.text,
+                                        usage: finishResult.usage,
+                                        finishReason: finishResult.finishReason,
+                                        output: undefined,
+                                        steps: mapSteps(finishResult.steps),
+                                    };
+                                    const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
+                                    if (postGenerateHooks.length > 0) {
+                                        const postGenerateInput = {
+                                            hook_event_name: "PostGenerate",
+                                            session_id: effectiveGenOptions.threadId ?? "default",
+                                            cwd: process.cwd(),
+                                            options: effectiveGenOptions,
+                                            result: hookResult,
+                                        };
+                                        await invokeHooksWithTimeout(postGenerateHooks, postGenerateInput, null, agent);
+                                        // Note: updatedResult is not applied for streaming since the stream has already been sent
+                                    }
+                                },
+                            });
+                            // Merge the streamText output into the UI message stream
+                            writer.merge(result.toUIMessageStream());
+                        },
+                    });
+                    // Convert the stream to a Response
+                    return createUIMessageStreamResponse({ stream });
+                }
+                catch (error) {
+                    // Normalize error to AgentError
+                    const normalizedError = normalizeError(error, "Stream generation failed", effectiveGenOptions.threadId);
+                    // Handle error with PostGenerateFailure hooks and fallback logic
+                    const postGenerateFailureHooks = effectiveHooks?.PostGenerateFailure ?? [];
+                    const errorDecision = await handleGenerationError(normalizedError, postGenerateFailureHooks, effectiveGenOptions, agent, retryState, options.fallbackModel, shouldUseFallback);
+                    if (errorDecision.shouldRetry) {
+                        // Update retry state
+                        Object.assign(retryState, updateRetryLoopState(retryState, errorDecision));
+                        // Wait for the specified delay before retrying
+                        await waitForRetryDelay(errorDecision.retryDelayMs);
+                        // Continue to next iteration of retry loop
+                        continue;
+                    }
+                    // No retry requested or max retries exceeded - throw the normalized error
+                    throw normalizedError;
+                }
+            }
+            // This should never be reached, but TypeScript needs it for type safety
+            throw new Error("Unexpected: retry loop exited without return or throw");
+        },
+        getActiveTools() {
+            return getActiveToolSet();
+        },
+        loadTools(toolNames) {
+            if (!toolRegistry) {
+                // No registry in eager mode - all tools already loaded
+                return { loaded: [], notFound: toolNames };
+            }
+            const result = toolRegistry.load(toolNames);
+            return {
+                loaded: result.loaded,
+                notFound: result.notFound,
+            };
+        },
+        setPermissionMode(mode) {
+            permissionMode = mode;
+        },
+        async getInterrupt(threadId) {
+            if (!options.checkpointer) {
+                return undefined;
+            }
+            const checkpoint = await options.checkpointer.load(threadId);
+            return checkpoint?.pendingInterrupt;
+        },
+        async resume(threadId, interruptId, response, genOptions) {
+            if (!options.checkpointer) {
+                throw new Error("Cannot resume: checkpointer is required");
+            }
+            const checkpoint = await options.checkpointer.load(threadId);
+            if (!checkpoint) {
+                throw new Error(`Cannot resume: no checkpoint found for thread ${threadId}`);
+            }
+            const interrupt = checkpoint.pendingInterrupt;
+            if (!interrupt) {
+                throw new Error(`Cannot resume: no pending interrupt found for thread ${threadId}`);
+            }
+            if (interrupt.id !== interruptId) {
+                throw new Error(`Cannot resume: interrupt ID mismatch. Expected ${interrupt.id}, got ${interruptId}`);
+            }
+            // Store the response for the tool wrapper to use
+            const toolCallId = interrupt.toolCallId;
+            if (toolCallId) {
+                pendingResponses.set(toolCallId, response);
+            }
+            // Emit InterruptResolved hook
+            const interruptResolvedHooks = effectiveHooks?.InterruptResolved ?? [];
+            if (interruptResolvedHooks.length > 0) {
+                const isApproval = isApprovalInterrupt(interrupt);
+                const approvalResponse = isApproval ? response : undefined;
+                const hookInput = {
+                    hook_event_name: "InterruptResolved",
+                    session_id: threadId,
+                    cwd: process.cwd(),
+                    interrupt_id: interrupt.id,
+                    interrupt_type: interrupt.type,
+                    tool_call_id: interrupt.toolCallId,
+                    tool_name: interrupt.toolName,
+                    response,
+                    approved: approvalResponse?.approved,
+                };
+                await invokeHooksWithTimeout(interruptResolvedHooks, hookInput, null, agent);
+            }
+            // Handle approval interrupt
+            if (isApprovalInterrupt(interrupt)) {
+                const approvalResponse = response;
+                // For backward compatibility, also store in approvalDecisions
+                approvalDecisions.set(interrupt.toolCallId, approvalResponse.approved);
+                // Build the assistant message with the tool call
+                const assistantMessage = {
+                    role: "assistant",
+                    content: [
+                        {
+                            type: "tool-call",
+                            toolCallId: interrupt.toolCallId,
+                            toolName: interrupt.toolName,
+                            input: interrupt.request.args,
+                        },
+                    ],
+                };
+                let toolResultOutput;
+                if (approvalResponse.approved) {
+                    // Approved: Execute the tool deterministically
+                    const unwrappedTools = { ...coreTools };
+                    for (const plugin of options.plugins ?? []) {
+                        if (plugin.tools && typeof plugin.tools !== "function") {
+                            Object.assign(unwrappedTools, plugin.tools);
+                        }
+                    }
+                    const mcpTools = mcpManager.getToolSet();
+                    Object.assign(unwrappedTools, mcpTools);
+                    const tool = unwrappedTools[interrupt.toolName];
+                    if (!tool || !tool.execute) {
+                        throw new Error(`Cannot resume: tool "${interrupt.toolName}" not found or has no execute function`);
+                    }
+                    try {
+                        toolResultOutput = await tool.execute(interrupt.request.args, {
+                            toolCallId: interrupt.toolCallId,
+                            messages: checkpoint.messages,
+                            abortSignal: genOptions?.signal,
+                        });
+                    }
+                    catch (error) {
+                        toolResultOutput = {
+                            error: true,
+                            message: error instanceof Error ? error.message : String(error),
+                        };
+                    }
+                }
+                else {
+                    // Denied: Create a synthetic denial result
+                    toolResultOutput = {
+                        denied: true,
+                        message: `Tool "${interrupt.toolName}" was denied by user${approvalResponse.reason ? `: ${approvalResponse.reason}` : ""}`,
+                    };
+                }
+                // Build the tool result message
+                const toolResultMessage = {
+                    role: "tool",
+                    content: [
+                        {
+                            type: "tool-result",
+                            toolCallId: interrupt.toolCallId,
+                            toolName: interrupt.toolName,
+                            output: toolResultOutput,
+                        },
+                    ],
+                };
+                // Update checkpoint with the tool call and result messages, clear interrupt
+                const updatedMessages = [
+                    ...checkpoint.messages,
+                    assistantMessage,
+                    toolResultMessage,
+                ];
+                const updatedCheckpoint = updateCheckpoint(checkpoint, {
+                    messages: updatedMessages,
+                    pendingInterrupt: undefined,
+                    step: checkpoint.step + 1,
+                });
+                await options.checkpointer.save(updatedCheckpoint);
+                // Clean up the response from our maps
+                pendingResponses.delete(interrupt.toolCallId);
+                approvalDecisions.delete(interrupt.toolCallId);
+                // Continue generation from the updated checkpoint
+                return agent.generate({
+                    threadId,
+                    ...genOptions,
+                    prompt: undefined,
+                });
+            }
+            // For custom interrupts, the tool's interrupt() call will receive the response
+            // Store it and re-run generation - the tool will get the response
+            // Clear the interrupt from checkpoint before continuing
+            const updatedCheckpoint = updateCheckpoint(checkpoint, {
+                pendingInterrupt: undefined,
+            });
+            await options.checkpointer.save(updatedCheckpoint);
+            // Continue generation - the wrapped tool will pick up the response from pendingResponses
+            return agent.generate({
+                threadId,
+                ...genOptions,
+                prompt: undefined,
+            });
+        },
+        // Initialize the ready promise
+        ready: Promise.resolve(),
+    };
+    // Initialize plugins and middleware asynchronously (including MCP server connections)
+    const initPromise = (async () => {
+        // Setup middleware first
+        await setupMiddleware(middleware);
+        for (const plugin of options.plugins ?? []) {
+            // Connect to MCP server if configured
+            if (plugin.mcpServer) {
+                try {
+                    await mcpManager.connectServer(plugin.name, plugin.mcpServer);
+                }
+                catch (error) {
+                    // Log error with full details - MCP connection failures are common
+                    // issues that are hard to debug when silently swallowed
+                    const errorMessage = error instanceof Error ? error.message : String(error);
+                    console.warn(`[Agent SDK] MCP server connection failed for plugin '${plugin.name}':\n` +
+                        `  Error: ${errorMessage}\n` +
+                        `  Server: ${JSON.stringify(plugin.mcpServer)}\n` +
+                        `  The agent will continue without this plugin's MCP tools.`);
+                }
+            }
+            // Run plugin setup
+            if (plugin.setup) {
+                await plugin.setup(agent);
+            }
+        }
+    })();
+    // Replace the ready promise with the actual initialization
+    agent.ready = initPromise;
+    return agent;
+}
+//# sourceMappingURL=agent.js.map