@lleverage-ai/agent-sdk 0.0.6 → 0.0.8

package/dist/agent.js

@@ -15,9 +15,10 @@ import { MCPManager } from "./mcp/manager.js";
 import { applyMiddleware, mergeHooks, setupMiddleware } from "./middleware/index.js";
 import { createDefaultPromptBuilder } from "./prompt-builder/components.js";
 import { ACCEPT_EDITS_BLOCKED_PATTERNS } from "./security/index.js";
+import { createSubagent } from "./subagents.js";
 import { TaskManager } from "./task-manager.js";
+import { createCallToolTool } from "./tools/call-tool.js";
 import { coreToolsToToolSet, createCoreTools, createSearchToolsTool, createTaskOutputTool, createTaskTool, } from "./tools/factory.js";
-import { createUseToolsTool, ToolRegistry } from "./tools/tool-registry.js";
 let agentIdCounter = 0;
 /**
  * Internal signal for interrupt flow control.
@@ -630,43 +631,7 @@ export function createAgent(options) {
             return `[Background task failed: ${task.id}]\nCommand: ${command}\nError: ${task.error ?? "Unknown error"}`;
         });
     // Determine plugin loading mode
-    // Track whether it was explicitly set to distinguish from default
-    const explicitPluginLoading = options.pluginLoading !== undefined;
     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
@@ -728,6 +693,10 @@ export function createAgent(options) {
     const toolSearchMaxResults = toolSearchConfig.maxResults ?? 10;
     // Track whether deferred loading is active
     let deferredLoadingActive = false;
+    // Track whether any deferred or proxy plugins exist (for call_tool creation)
+    let hasProxiedTools = false;
+    // Auto-created subagent definitions from delegated plugins
+    const autoSubagents = [];
     // 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.
@@ -746,7 +715,7 @@ export function createAgent(options) {
     // Determine if we should use deferred loading based on tool search settings
     // Note: Only activate deferred loading if explicitly requested, not based on auto threshold
     // The auto threshold should only affect whether search_tools is created, not loading behavior
-    if (toolSearchEnabled === "always") {
+    if (toolSearchEnabled === "always" || pluginLoadingMode === "proxy") {
         deferredLoadingActive = true;
     }
     // Removed: auto threshold no longer forces deferred loading
@@ -767,7 +736,7 @@ export function createAgent(options) {
         ...coreToolsToToolSet(autoCreatedCoreTools),
         ...(options.tools ?? {}),
     };
-    // Process plugins based on loading mode and deferred loading
+    // Process plugins based on loading mode, deferred, and delegation settings
     // Note: Plugin skills are collected earlier (before createCoreTools) so
     // the skill tool can include them in progressive disclosure.
     for (const plugin of options.plugins ?? []) {
@@ -775,36 +744,18 @@ export function createAgent(options) {
         // 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);
-            // Priority order:
-            // 1. Explicit mode - don't register
-            // 2. Preload - always load immediately
-            // 3. Explicit eager - always load immediately
-            // 4. Lazy mode - register with tool registry
-            // 5. Deferred loading - register but don't load
-            // 6. Default eager - load immediately
-            if (pluginLoadingMode === "explicit") {
-                // Explicit mode: don't auto-register, user must do it manually
-                // Skip registration entirely
-            }
-            else if (shouldPreload) {
-                // Preloaded plugins: always load immediately, regardless of other settings
+            // Check if this plugin is deferred (proxy mode or per-plugin opt-in)
+            const isDeferred = plugin.deferred === true || (pluginLoadingMode === "proxy" && plugin.deferred !== false);
+            if (isDeferred) {
+                // Deferred plugin: register in MCP for discovery via search_tools + call_tool
                 mcpManager.registerPluginTools(plugin.name, plugin.tools, {
-                    autoLoad: true,
-                });
-            }
-            else if (explicitPluginLoading && pluginLoadingMode === "eager") {
-                // Explicit eager mode: always load immediately, regardless of toolSearch settings
-                mcpManager.registerPluginTools(plugin.name, plugin.tools, {
-                    autoLoad: true,
+                    autoLoad: false,
                 });
+                hasProxiedTools = true;
             }
-            else if (pluginLoadingMode === "lazy" && toolRegistry) {
-                // Lazy mode: register with registry for on-demand loading
-                toolRegistry.registerPlugin(plugin.name, plugin.tools);
-            }
-            else if (deferredLoadingActive) {
+            else if (deferredLoadingActive && plugin.deferred !== false) {
                 // Deferred loading (auto threshold or always enabled): register tools but don't load them initially
+                // Respect explicit deferred: false opt-out
                 mcpManager.registerPluginTools(plugin.name, plugin.tools, {
                     autoLoad: false,
                 });
@@ -817,33 +768,61 @@ export function createAgent(options) {
             }
         }
     }
+    // Create subagent definitions from plugins with subagent config
+    for (const plugin of options.plugins ?? []) {
+        if (plugin.subagent) {
+            autoSubagents.push({
+                type: `plugin-${plugin.name}`,
+                description: plugin.subagent.description,
+                model: plugin.subagent.model ?? "inherit",
+                create: (_ctx) => createSubagent(agent, {
+                    name: `plugin-${plugin.name}`,
+                    description: plugin.subagent.description,
+                    model: _ctx.model,
+                    tools: plugin.subagent.tools,
+                    systemPrompt: plugin.subagent.prompt ??
+                        `You are a ${plugin.name} specialist. Complete the requested task using available tools and return a clear summary.`,
+                }),
+            });
+        }
+    }
+    // Merge auto-created subagents with user-provided ones
+    const allSubagents = [...(options.subagents ?? []), ...autoSubagents];
+    const hasSubagents = allSubagents.length > 0;
+    // In proxy mode, create call_tool and configure search_tools with schema disclosure
+    const isProxyMode = pluginLoadingMode === "proxy" || hasProxiedTools;
+    if (isProxyMode && !options.disabledCoreTools?.includes("call_tool")) {
+        coreTools.call_tool = createCallToolTool({
+            mcpManager,
+        });
+    }
     // Create search_tools for MCP tool discovery and/or plugin loading
     // New behavior:
     // - Create when auto threshold is exceeded (for lazy discovery)
     // - Create when deferred loading is active (explicitly requested)
+    // - Create when proxy mode is active (for call_tool discovery)
     // - Create when external MCP servers exist (for MCP tool search)
-    // - Always auto-load tools when found (no manual load step)
+    // - Always auto-load tools when found (no manual load step) — unless proxy mode
     const shouldCreateSearchToolsForAutoThreshold = toolSearchEnabled === "auto" && totalPluginToolCount > toolSearchThreshold;
     const shouldCreateSearchTools = !options.disabledCoreTools?.includes("search_tools") &&
         (deferredLoadingActive ||
+            isProxyMode ||
             shouldCreateSearchToolsForAutoThreshold ||
             (mcpManager.hasExternalServers() && toolSearchEnabled !== "never"));
     if (shouldCreateSearchTools) {
         coreTools.search_tools = createSearchToolsTool({
             manager: mcpManager,
             maxResults: toolSearchMaxResults,
-            enableLoad: true, // Always enable auto-loading
-            autoLoad: true, // NEW: Auto-load tools after searching
+            // In proxy mode: don't auto-load, include schema for call_tool usage
+            enableLoad: !isProxyMode,
+            autoLoad: !isProxyMode,
+            includeSchema: isProxyMode,
             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.
@@ -887,9 +866,6 @@ export function createAgent(options) {
             const allTools = { ...coreTools };
             Object.assign(allTools, runtimeTools);
             Object.assign(allTools, mcpManager.getToolSet());
-            if (toolRegistry) {
-                Object.assign(allTools, toolRegistry.getLoadedTools());
-            }
             return allTools;
         })());
         // Extract tool metadata for context
@@ -926,6 +902,10 @@ export function createAgent(options) {
             permissionMode,
             currentMessages: messages,
             threadId,
+            custom: {
+                hasSubagents,
+                delegationInstructions: options.delegationInstructions,
+            },
         };
     };
     // Helper to get system prompt (either static or built from context)
@@ -947,10 +927,6 @@ export function createAgent(options) {
         // 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
@@ -991,10 +967,6 @@ export function createAgent(options) {
         // 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
@@ -1047,7 +1019,7 @@ export function createAgent(options) {
         const result = {
             ...tools,
             task: createTaskTool({
-                subagents: options.subagents ?? [],
+                subagents: allSubagents,
                 defaultModel: options.model,
                 parentAgent: agent,
                 // Always include general-purpose subagent so agents can delegate tasks
@@ -1314,6 +1286,250 @@ export function createAgent(options) {
         }
         return null;
     }
+    /**
+     * Collect all tools (core + static plugin tools + MCP tools) for
+     * deterministic tool execution during resume. This is the unwrapped set
+     * — no permission mode, hooks, or signal-catching wrappers applied.
+     */
+    function collectAllTools() {
+        const allTools = { ...coreTools };
+        for (const plugin of options.plugins ?? []) {
+            if (plugin.tools && typeof plugin.tools !== "function") {
+                Object.assign(allTools, plugin.tools);
+            }
+        }
+        Object.assign(allTools, mcpManager.getToolSet());
+        return allTools;
+    }
+    /**
+     * Shared logic for resume() and resumeDataResponse().
+     *
+     * Validates the checkpoint/interrupt, stores the user response, emits hooks,
+     * executes the interrupted tool (approval or custom), updates the checkpoint,
+     * and returns a discriminated outcome so the caller can decide how to continue.
+     */
+    async function executeResumeCore(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 keyed by interrupt ID (format: "int_<toolCallId>").
+        // The interrupt() function in the tool wrapper looks up responses using
+        // this exact key format, so we must use interrupt.id — NOT the raw
+        // toolCallId which would never match.
+        pendingResponses.set(interrupt.id, 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 = collectAllTools();
+                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 = `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`;
+                }
+            }
+            else {
+                // Denied: Create a synthetic denial result
+                toolResultOutput = `Tool "${interrupt.toolName}" was denied by user${approvalResponse.reason ? `: ${approvalResponse.reason}` : ""}`;
+            }
+            // Build the tool result message with proper ToolResultOutput format.
+            // The AI SDK validates messages against modelMessageSchema which
+            // requires output to be { type: 'text', value } or { type: 'json', value }.
+            const approvalOutput = typeof toolResultOutput === "string"
+                ? { type: "text", value: toolResultOutput }
+                : { type: "json", value: toolResultOutput };
+            const toolResultMessage = {
+                role: "tool",
+                content: [
+                    {
+                        type: "tool-result",
+                        toolCallId: interrupt.toolCallId,
+                        toolName: interrupt.toolName,
+                        output: approvalOutput,
+                    },
+                ],
+            };
+            // 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);
+            threadCheckpoints.set(threadId, updatedCheckpoint);
+            // Clean up the response from our maps
+            pendingResponses.delete(interrupt.id);
+            approvalDecisions.delete(interrupt.toolCallId);
+            return { type: "continue", threadId, genOptions };
+        }
+        // For custom interrupts (e.g. ask_user), manually execute the tool so
+        // that its interrupt() call receives the stored response deterministically.
+        // Re-running generate() would rely on the model re-calling the same tool,
+        // but tool call IDs change each generation so pendingResponses would never
+        // be matched.
+        const customToolCallId = interrupt.toolCallId;
+        const customToolName = interrupt.toolName;
+        if (!customToolCallId || !customToolName) {
+            throw new Error("Cannot resume custom interrupt: missing toolCallId or toolName on interrupt");
+        }
+        // Build the assistant message with the original tool call
+        const customAssistantMessage = {
+            role: "assistant",
+            content: [
+                {
+                    type: "tool-call",
+                    toolCallId: customToolCallId,
+                    toolName: customToolName,
+                    input: interrupt.request,
+                },
+            ],
+        };
+        // Collect all tools
+        const customTools = collectAllTools();
+        const customTool = customTools[customToolName];
+        if (!customTool || !customTool.execute) {
+            throw new Error(`Cannot resume: tool "${customToolName}" not found or has no execute function`);
+        }
+        let customToolResult;
+        try {
+            // Execute the tool, providing an interrupt function that returns
+            // the stored user response. This mirrors what happens inside the
+            // permission-mode tool wrapper when pendingResponses has a match.
+            customToolResult = await customTool.execute(interrupt.request, {
+                toolCallId: customToolCallId,
+                messages: checkpoint.messages,
+                abortSignal: genOptions?.signal,
+                interrupt: async (request) => {
+                    // First call: return the stored user response (mirrors the
+                    // permission-mode wrapper when pendingResponses has a match).
+                    if (pendingResponses.has(interrupt.id)) {
+                        const stored = pendingResponses.get(interrupt.id);
+                        pendingResponses.delete(interrupt.id);
+                        return stored;
+                    }
+                    // Subsequent calls: no stored response — throw InterruptSignal
+                    // so the tool can pause again (e.g. multi-step wizards).
+                    const newInterruptData = createInterrupt({
+                        id: `int_${customToolCallId}`,
+                        threadId,
+                        type: "custom",
+                        toolCallId: customToolCallId,
+                        toolName: customToolName,
+                        request,
+                        step: checkpoint.step,
+                    });
+                    throw new InterruptSignal(newInterruptData);
+                },
+            });
+        }
+        catch (executeError) {
+            if (isInterruptSignal(executeError)) {
+                // Tool threw another interrupt — persist it and return re-interrupted
+                const newInterrupt = executeError.interrupt;
+                const reInterruptCheckpoint = updateCheckpoint(checkpoint, {
+                    pendingInterrupt: newInterrupt,
+                });
+                await options.checkpointer.save(reInterruptCheckpoint);
+                threadCheckpoints.set(threadId, reInterruptCheckpoint);
+                return {
+                    type: "re-interrupted",
+                    interrupt: newInterrupt,
+                    checkpoint: reInterruptCheckpoint,
+                };
+            }
+            customToolResult = `Tool execution failed: ${executeError instanceof Error ? executeError.message : String(executeError)}`;
+        }
+        // Build tool result message with proper ToolResultOutput format.
+        const customOutput = typeof customToolResult === "string"
+            ? { type: "text", value: customToolResult }
+            : { type: "json", value: customToolResult };
+        const customToolResultMessage = {
+            role: "tool",
+            content: [
+                {
+                    type: "tool-result",
+                    toolCallId: customToolCallId,
+                    toolName: customToolName,
+                    output: customOutput,
+                },
+            ],
+        };
+        // Update checkpoint with tool call + result, clear interrupt
+        const customUpdatedMessages = [
+            ...checkpoint.messages,
+            customAssistantMessage,
+            customToolResultMessage,
+        ];
+        const customUpdatedCheckpoint = updateCheckpoint(checkpoint, {
+            messages: customUpdatedMessages,
+            pendingInterrupt: undefined,
+            step: checkpoint.step + 1,
+        });
+        await options.checkpointer.save(customUpdatedCheckpoint);
+        threadCheckpoints.set(threadId, customUpdatedCheckpoint);
+        // Clean up
+        pendingResponses.delete(interrupt.id);
+        return { type: "continue", threadId, genOptions };
+    }
     const agent = {
         id,
         options,
@@ -1713,9 +1929,10 @@ export function createAgent(options) {
             const retryState = createRetryLoopState(options.model);
             while (retryState.retryAttempt <= retryState.maxRetries) {
                 try {
-                    const { messages, checkpoint } = await buildMessages(effectiveGenOptions);
+                    const { messages, checkpoint, forkedSessionId } = await buildMessages(effectiveGenOptions);
                     const maxSteps = options.maxSteps ?? 10;
                     const startStep = checkpoint?.step ?? 0;
+                    const checkpointThreadId = forkedSessionId ?? effectiveGenOptions.threadId;
                     // Signal state for cooperative signal catching in streaming mode
                     const signalState = {};
                     // Build initial params - use active tools (core + dynamically loaded + task)
@@ -1814,12 +2031,39 @@ export function createAgent(options) {
                         steps: mapSteps(steps),
                     };
                     // Save checkpoint if threadId is provided
-                    if (effectiveGenOptions.threadId && options.checkpointer) {
+                    if (checkpointThreadId && options.checkpointer) {
                         const finalMessages = [
                             ...messages,
                             ...(text ? [{ role: "assistant", content: text }] : []),
                         ];
-                        await saveCheckpoint(effectiveGenOptions.threadId, finalMessages, startStep + steps.length);
+                        await saveCheckpoint(checkpointThreadId, finalMessages, startStep + steps.length);
+                    }
+                    // Save pending interrupt to checkpoint (mirrors generate() pattern)
+                    if (signalState.interrupt && checkpointThreadId && options.checkpointer) {
+                        const interrupt = signalState.interrupt.interrupt;
+                        const savedCheckpoint = threadCheckpoints.get(checkpointThreadId);
+                        if (savedCheckpoint) {
+                            const withInterrupt = updateCheckpoint(savedCheckpoint, {
+                                pendingInterrupt: interrupt,
+                            });
+                            await options.checkpointer.save(withInterrupt);
+                            threadCheckpoints.set(checkpointThreadId, withInterrupt);
+                        }
+                        // 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);
+                        }
                     }
                     // Invoke unified PostGenerate hooks
                     const postGenerateHooks = effectiveHooks?.PostGenerate ?? [];
@@ -2411,8 +2655,35 @@ export function createAgent(options) {
                             writer.merge(result.toUIMessageStream());
                             // Wait for initial generation to complete to get final text
                             const text = await result.text;
+                            // Save pending interrupt to checkpoint (mirrors stream() pattern)
+                            if (signalState.interrupt && effectiveGenOptions.threadId && options.checkpointer) {
+                                const interrupt = signalState.interrupt.interrupt;
+                                const savedCheckpoint = threadCheckpoints.get(effectiveGenOptions.threadId);
+                                if (savedCheckpoint) {
+                                    const withInterrupt = updateCheckpoint(savedCheckpoint, {
+                                        pendingInterrupt: interrupt,
+                                    });
+                                    await options.checkpointer.save(withInterrupt);
+                                    threadCheckpoints.set(effectiveGenOptions.threadId, withInterrupt);
+                                }
+                                // 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);
+                                }
+                            }
                             // --- Background task completion loop ---
-                            if (waitForBackgroundTasks) {
+                            if (waitForBackgroundTasks && !signalState.interrupt) {
                                 // Track accumulated steps for checkpoint saves
                                 const initialSteps = await result.steps;
                                 let accumulatedStepCount = initialSteps.length;
@@ -2526,17 +2797,6 @@ export function createAgent(options) {
                 delete runtimeTools[name];
             }
         },
-        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;
         },
@@ -2548,251 +2808,33 @@ export function createAgent(options) {
             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 keyed by interrupt ID (format: "int_<toolCallId>").
-            // The interrupt() function in the tool wrapper looks up responses using
-            // this exact key format, so we must use interrupt.id — NOT the raw
-            // toolCallId which would never match.
-            pendingResponses.set(interrupt.id, 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,
+            const outcome = await executeResumeCore(threadId, interruptId, response, genOptions);
+            if (outcome.type === "re-interrupted") {
+                return {
+                    status: "interrupted",
+                    interrupt: outcome.interrupt,
+                    partial: undefined,
                 };
-                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 = `Tool execution failed: ${error instanceof Error ? error.message : String(error)}`;
-                    }
-                }
-                else {
-                    // Denied: Create a synthetic denial result
-                    toolResultOutput = `Tool "${interrupt.toolName}" was denied by user${approvalResponse.reason ? `: ${approvalResponse.reason}` : ""}`;
-                }
-                // Build the tool result message with proper ToolResultOutput format.
-                // The AI SDK validates messages against modelMessageSchema which
-                // requires output to be { type: 'text', value } or { type: 'json', value }.
-                const approvalOutput = typeof toolResultOutput === "string"
-                    ? { type: "text", value: toolResultOutput }
-                    : { type: "json", value: toolResultOutput };
-                const toolResultMessage = {
-                    role: "tool",
-                    content: [
-                        {
-                            type: "tool-result",
-                            toolCallId: interrupt.toolCallId,
-                            toolName: interrupt.toolName,
-                            output: approvalOutput,
-                        },
-                    ],
-                };
-                // 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.id);
-                approvalDecisions.delete(interrupt.toolCallId);
-                // Continue generation from the updated checkpoint
-                return agent.generate({
-                    threadId,
-                    ...genOptions,
-                    prompt: undefined,
-                });
-            }
-            // For custom interrupts (e.g. ask_user), manually execute the tool so
-            // that its interrupt() call receives the stored response deterministically.
-            // Re-running generate() would rely on the model re-calling the same tool,
-            // but tool call IDs change each generation so pendingResponses would never
-            // be matched.
-            {
-                const customToolCallId = interrupt.toolCallId;
-                const customToolName = interrupt.toolName;
-                if (!customToolCallId || !customToolName) {
-                    throw new Error("Cannot resume custom interrupt: missing toolCallId or toolName on interrupt");
-                }
-                // Build the assistant message with the original tool call
-                const customAssistantMessage = {
-                    role: "assistant",
-                    content: [
-                        {
-                            type: "tool-call",
-                            toolCallId: customToolCallId,
-                            toolName: customToolName,
-                            input: interrupt.request,
-                        },
-                    ],
-                };
-                // Collect all tools (same pattern as the approval path above)
-                const customTools = { ...coreTools };
-                for (const plugin of options.plugins ?? []) {
-                    if (plugin.tools && typeof plugin.tools !== "function") {
-                        Object.assign(customTools, plugin.tools);
-                    }
-                }
-                const customMcpTools = mcpManager.getToolSet();
-                Object.assign(customTools, customMcpTools);
-                const customTool = customTools[customToolName];
-                if (!customTool || !customTool.execute) {
-                    throw new Error(`Cannot resume: tool "${customToolName}" not found or has no execute function`);
-                }
-                let customToolResult;
-                try {
-                    // Execute the tool, providing an interrupt function that returns
-                    // the stored user response. This mirrors what happens inside the
-                    // permission-mode tool wrapper when pendingResponses has a match.
-                    customToolResult = await customTool.execute(interrupt.request, {
-                        toolCallId: customToolCallId,
-                        messages: checkpoint.messages,
-                        abortSignal: genOptions?.signal,
-                        interrupt: async (request) => {
-                            // First call: return the stored user response (mirrors the
-                            // permission-mode wrapper when pendingResponses has a match).
-                            if (pendingResponses.has(interrupt.id)) {
-                                const stored = pendingResponses.get(interrupt.id);
-                                pendingResponses.delete(interrupt.id);
-                                return stored;
-                            }
-                            // Subsequent calls: no stored response — throw InterruptSignal
-                            // so the tool can pause again (e.g. multi-step wizards).
-                            const newInterruptData = createInterrupt({
-                                id: `int_${customToolCallId}`,
-                                threadId,
-                                type: "custom",
-                                toolCallId: customToolCallId,
-                                toolName: customToolName,
-                                request,
-                                step: checkpoint.step,
-                            });
-                            throw new InterruptSignal(newInterruptData);
-                        },
-                    });
-                }
-                catch (executeError) {
-                    if (isInterruptSignal(executeError)) {
-                        // Tool threw another interrupt — persist it and return interrupted
-                        const newInterrupt = executeError.interrupt;
-                        const reInterruptCheckpoint = updateCheckpoint(checkpoint, {
-                            pendingInterrupt: newInterrupt,
-                        });
-                        await options.checkpointer.save(reInterruptCheckpoint);
-                        threadCheckpoints.set(threadId, reInterruptCheckpoint);
-                        return {
-                            status: "interrupted",
-                            interrupt: newInterrupt,
-                            partial: undefined,
-                        };
-                    }
-                    customToolResult = `Tool execution failed: ${executeError instanceof Error ? executeError.message : String(executeError)}`;
-                }
-                // Build tool result message with proper ToolResultOutput format.
-                const customOutput = typeof customToolResult === "string"
-                    ? { type: "text", value: customToolResult }
-                    : { type: "json", value: customToolResult };
-                const customToolResultMessage = {
-                    role: "tool",
-                    content: [
-                        {
-                            type: "tool-result",
-                            toolCallId: customToolCallId,
-                            toolName: customToolName,
-                            output: customOutput,
-                        },
-                    ],
-                };
-                // Update checkpoint with tool call + result, clear interrupt
-                const customUpdatedMessages = [
-                    ...checkpoint.messages,
-                    customAssistantMessage,
-                    customToolResultMessage,
-                ];
-                const customUpdatedCheckpoint = updateCheckpoint(checkpoint, {
-                    messages: customUpdatedMessages,
-                    pendingInterrupt: undefined,
-                    step: checkpoint.step + 1,
-                });
-                await options.checkpointer.save(customUpdatedCheckpoint);
-                threadCheckpoints.set(threadId, customUpdatedCheckpoint);
-                // Clean up
-                pendingResponses.delete(interrupt.id);
-                // Continue generation from the updated checkpoint
-                return agent.generate({
-                    threadId,
-                    ...genOptions,
-                    prompt: undefined,
-                });
+            return agent.generate({
+                threadId: outcome.threadId,
+                ...outcome.genOptions,
+                prompt: undefined,
+            });
+        },
+        async resumeDataResponse(threadId, interruptId, response, genOptions) {
+            const outcome = await executeResumeCore(threadId, interruptId, response, genOptions);
+            if (outcome.type === "re-interrupted") {
+                // Return an empty response — the client already has the interrupt widget.
+                // The new interrupt is persisted to the checkpoint and retrievable
+                // via getInterrupt().
+                return new Response(null, { status: 204 });
             }
+            return agent.streamDataResponse({
+                threadId: outcome.threadId,
+                ...outcome.genOptions,
+                prompt: undefined,
+            });
         },
         async dispose() {
             // Kill all running background tasks