@dexto/core 1.5.6 → 1.5.8

package/dist/tools/tool-manager.js

@@ -9,13 +9,15 @@ import { ToolError } from "./errors.js";
 import { ToolErrorCode } from "./error-codes.js";
 import { DextoRuntimeError } from "../errors/index.js";
 import { DextoLogComponent } from "../logger/v2/types.js";
-import { ApprovalStatus, ApprovalType } from "../approval/types.js";
+import { ApprovalStatus, ApprovalType, DenialReason } from "../approval/types.js";
 import { InstrumentClass } from "../telemetry/decorators.js";
+import { extractToolCallMeta, wrapToolParametersSchema } from "./tool-call-metadata.js";
 import {
   generateBashPatternKey,
   generateBashPatternSuggestions,
   isDangerousCommand
 } from "./bash-pattern-utils.js";
+import { isBackgroundTasksEnabled } from "../utils/env.js";
 _ToolManager_decorators = [InstrumentClass({
   prefix: "tool",
   excludeMethods: [
@@ -45,6 +47,14 @@ let _ToolManager = class _ToolManager {
   toolsCache = {};
   cacheValid = false;
   logger;
+  // Session-level auto-approve tools for skills
+  // When a skill with allowedTools is invoked, those tools are auto-approved (skip confirmation)
+  // This is ADDITIVE - other tools are NOT blocked, they just go through normal approval flow
+  sessionAutoApproveTools = /* @__PURE__ */ new Map();
+  // Session-level auto-approve tools set by users (UI)
+  sessionUserAutoApproveTools = /* @__PURE__ */ new Map();
+  sessionDisabledTools = /* @__PURE__ */ new Map();
+  globalDisabledTools = [];
   constructor(mcpManager, approvalManager, allowedToolsProvider, approvalMode, agentEventBus, toolPolicies, options, logger) {
     this.mcpManager = mcpManager;
     this.approvalManager = approvalManager;
@@ -96,6 +106,204 @@ let _ToolManager = class _ToolManager {
       this.logger.debug("Agent reference configured for custom tools");
     }
   }
+  /**
+   * Set prompt manager for invoke_skill tool (called after construction to avoid circular dependencies)
+   * Must be called before initialize() if invoke_skill tool is enabled
+   */
+  setPromptManager(promptManager) {
+    if (this.internalToolsProvider) {
+      this.internalToolsProvider.setPromptManager(promptManager);
+      this.logger.debug("PromptManager reference configured for invoke_skill tool");
+    }
+  }
+  /**
+   * Set task forker for context:fork skill execution (late-binding)
+   * Called by agent-spawner custom tool provider after RuntimeService is created.
+   * This enables invoke_skill to fork execution to an isolated subagent.
+   */
+  setTaskForker(taskForker) {
+    if (this.internalToolsProvider) {
+      this.internalToolsProvider.setTaskForker(taskForker);
+      this.logger.debug(
+        "TaskForker reference configured for invoke_skill (context:fork support)"
+      );
+    }
+  }
+  // ============= SESSION AUTO-APPROVE TOOLS =============
+  /**
+   * Set session-level auto-approve tools.
+   * When set, these tools will skip confirmation prompts for this session.
+   * This is ADDITIVE - other tools are NOT blocked, they just go through normal approval flow.
+   *
+   * @param sessionId The session ID
+   * @param autoApproveTools Array of tool names to auto-approve (e.g., ['custom--bash_exec', 'custom--read_file'])
+   */
+  setSessionAutoApproveTools(sessionId, autoApproveTools) {
+    if (autoApproveTools.length === 0) {
+      this.clearSessionAutoApproveTools(sessionId);
+      return;
+    }
+    this.sessionAutoApproveTools.set(sessionId, autoApproveTools);
+    this.logger.info(
+      `Session auto-approve tools set for '${sessionId}': ${autoApproveTools.length} tools`
+    );
+    this.logger.debug(`Auto-approve tools: ${autoApproveTools.join(", ")}`);
+  }
+  /**
+   * Set session-level auto-approve tools chosen by the user.
+   */
+  setSessionUserAutoApproveTools(sessionId, autoApproveTools) {
+    if (autoApproveTools.length === 0) {
+      this.clearSessionUserAutoApproveTools(sessionId);
+      return;
+    }
+    this.sessionUserAutoApproveTools.set(sessionId, autoApproveTools);
+    this.logger.info(
+      `Session user auto-approve tools set for '${sessionId}': ${autoApproveTools.length} tools`
+    );
+    this.logger.debug(`User auto-approve tools: ${autoApproveTools.join(", ")}`);
+  }
+  /**
+   * Clear session-level auto-approve tools chosen by the user.
+   */
+  clearSessionUserAutoApproveTools(sessionId) {
+    const hadAutoApprove = this.sessionUserAutoApproveTools.has(sessionId);
+    this.sessionUserAutoApproveTools.delete(sessionId);
+    if (hadAutoApprove) {
+      this.logger.info(`Session user auto-approve tools cleared for '${sessionId}'`);
+    }
+  }
+  /**
+   * Clear session-level auto-approve tools.
+   * Call this when the session ends or when the skill completes.
+   *
+   * @param sessionId The session ID to clear auto-approve tools for
+   */
+  clearSessionAutoApproveTools(sessionId) {
+    const hadAutoApprove = this.sessionAutoApproveTools.has(sessionId);
+    this.sessionAutoApproveTools.delete(sessionId);
+    if (hadAutoApprove) {
+      this.logger.info(`Session auto-approve tools cleared for '${sessionId}'`);
+    }
+  }
+  hasSessionUserAutoApproveTools(sessionId) {
+    return this.sessionUserAutoApproveTools.has(sessionId);
+  }
+  // ============= ENABLED/DISABLED TOOLS =============
+  /**
+   * Set global disabled tools (agent-level preferences).
+   */
+  setGlobalDisabledTools(toolNames) {
+    this.globalDisabledTools = [...toolNames];
+    this.logger.info("Global disabled tools updated", {
+      count: toolNames.length
+    });
+    this.agentEventBus.emit("tools:enabled-updated", {
+      scope: "global",
+      disabledTools: [...this.globalDisabledTools]
+    });
+  }
+  getGlobalDisabledTools() {
+    return [...this.globalDisabledTools];
+  }
+  /**
+   * Set session-level disabled tools (overrides global list).
+   */
+  setSessionDisabledTools(sessionId, toolNames) {
+    if (toolNames.length === 0) {
+      this.clearSessionDisabledTools(sessionId);
+      return;
+    }
+    this.sessionDisabledTools.set(sessionId, [...toolNames]);
+    this.logger.info("Session disabled tools updated", {
+      sessionId,
+      count: toolNames.length
+    });
+    this.agentEventBus.emit("tools:enabled-updated", {
+      scope: "session",
+      sessionId,
+      disabledTools: [...toolNames]
+    });
+  }
+  /**
+   * Clear session-level disabled tools.
+   */
+  clearSessionDisabledTools(sessionId) {
+    const hadOverrides = this.sessionDisabledTools.has(sessionId);
+    this.sessionDisabledTools.delete(sessionId);
+    if (hadOverrides) {
+      this.logger.info("Session disabled tools cleared", { sessionId });
+    }
+  }
+  /**
+   * Get disabled tools for a session (session override wins).
+   */
+  getDisabledTools(sessionId) {
+    if (sessionId && this.sessionDisabledTools.has(sessionId)) {
+      return this.sessionDisabledTools.get(sessionId) ?? [];
+    }
+    return this.globalDisabledTools;
+  }
+  /**
+   * Filter a tool set based on disabled tools for a session.
+   */
+  filterToolsForSession(toolSet, sessionId) {
+    const disabled = new Set(this.getDisabledTools(sessionId));
+    if (disabled.size === 0) {
+      return toolSet;
+    }
+    return Object.fromEntries(
+      Object.entries(toolSet).filter(([toolName]) => !disabled.has(toolName))
+    );
+  }
+  /**
+   * Check if a session has auto-approve tools set.
+   *
+   * @param sessionId The session ID to check
+   * @returns true if the session has auto-approve tools
+   */
+  hasSessionAutoApproveTools(sessionId) {
+    return this.sessionAutoApproveTools.has(sessionId);
+  }
+  /**
+   * Get the auto-approve tools for a session (skill-provided list).
+   *
+   * @param sessionId The session ID to check
+   * @returns Array of auto-approve tool names, or undefined if none set
+   */
+  getSessionAutoApproveTools(sessionId) {
+    return this.sessionAutoApproveTools.get(sessionId);
+  }
+  /**
+   * Get the user auto-approve tools for a session.
+   */
+  getSessionUserAutoApproveTools(sessionId) {
+    return this.sessionUserAutoApproveTools.get(sessionId);
+  }
+  /**
+   * Combined auto-approve list for a session.
+   */
+  getCombinedSessionAutoApproveTools(sessionId) {
+    return [
+      ...this.sessionAutoApproveTools.get(sessionId) ?? [],
+      ...this.sessionUserAutoApproveTools.get(sessionId) ?? []
+    ];
+  }
+  /**
+   * Check if a tool should be auto-approved for a session.
+   * Returns true if the tool is in the session's auto-approve list.
+   *
+   * @param sessionId The session ID
+   * @param toolName The tool name to check
+   * @returns true if the tool should be auto-approved
+   */
+  isToolAutoApprovedForSession(sessionId, toolName) {
+    const autoApproveTools = this.getCombinedSessionAutoApproveTools(sessionId);
+    if (autoApproveTools.length === 0) {
+      return false;
+    }
+    return autoApproveTools.some((pattern) => this.matchesToolPolicy(toolName, pattern));
+  }
   /**
    * Invalidate the tools cache when tool sources change
    */
@@ -121,6 +329,14 @@ let _ToolManager = class _ToolManager {
       );
       this.invalidateCache();
     });
+    this.agentEventBus.on("run:complete", (payload) => {
+      if (this.hasSessionAutoApproveTools(payload.sessionId)) {
+        this.logger.debug(
+          `\u{1F513} Run complete, clearing session auto-approve tools for '${payload.sessionId}'`
+        );
+        this.clearSessionAutoApproveTools(payload.sessionId);
+      }
+    });
   }
   // ==================== Bash Pattern Approval Helpers ====================
   /**
@@ -280,7 +496,8 @@ let _ToolManager = class _ToolManager {
       allTools[qualifiedName] = {
         ...toolDef,
         name: qualifiedName,
-        description: `${toolDef.description || "No description provided"} (internal tool)`
+        description: `${toolDef.description || "No description provided"} (internal tool)`,
+        parameters: wrapToolParametersSchema(toolDef.parameters)
       };
     }
     for (const [toolName, toolDef] of Object.entries(customTools)) {
@@ -288,7 +505,8 @@ let _ToolManager = class _ToolManager {
       allTools[qualifiedName] = {
         ...toolDef,
         name: qualifiedName,
-        description: `${toolDef.description || "No description provided"} (custom tool)`
+        description: `${toolDef.description || "No description provided"} (custom tool)`,
+        parameters: wrapToolParametersSchema(toolDef.parameters)
       };
     }
     for (const [toolName, toolDef] of Object.entries(mcpTools)) {
@@ -296,7 +514,8 @@ let _ToolManager = class _ToolManager {
       allTools[qualifiedName] = {
         ...toolDef,
         name: qualifiedName,
-        description: `${toolDef.description || "No description provided"} (via MCP servers)`
+        description: `${toolDef.description || "No description provided"} (via MCP servers)`,
+        parameters: wrapToolParametersSchema(toolDef.parameters)
       };
     }
     const totalTools = Object.keys(allTools).length;
@@ -332,21 +551,25 @@ let _ToolManager = class _ToolManager {
    * @param abortSignal Optional abort signal for cancellation support
    */
   async executeTool(toolName, args, toolCallId, sessionId, abortSignal) {
+    const { toolArgs: rawToolArgs, meta } = extractToolCallMeta(args);
+    let toolArgs = rawToolArgs;
+    const backgroundTasksEnabled = isBackgroundTasksEnabled();
     this.logger.debug(`\u{1F527} Tool execution requested: '${toolName}' (toolCallId: ${toolCallId})`);
-    this.logger.debug(`Tool args: ${JSON.stringify(args, null, 2)}`);
+    this.logger.debug(`Tool args: ${JSON.stringify(toolArgs, null, 2)}`);
     if (sessionId) {
       this.agentEventBus.emit("llm:tool-call", {
         toolName,
-        args,
+        args: toolArgs,
         callId: toolCallId,
         sessionId
       });
     }
     const { requireApproval, approvalStatus } = await this.handleToolApproval(
       toolName,
-      args,
+      toolArgs,
       toolCallId,
-      sessionId
+      sessionId,
+      meta.callDescription
     );
     this.logger.debug(`\u2705 Tool execution approved: ${toolName}`);
     this.logger.info(
@@ -363,7 +586,7 @@ let _ToolManager = class _ToolManager {
     if (this.pluginManager && this.sessionManager && this.stateManager) {
       const beforePayload = {
         toolName,
-        args,
+        args: toolArgs,
         ...sessionId !== void 0 && { sessionId }
       };
       const modifiedPayload = await this.pluginManager.executePlugins(
@@ -377,10 +600,21 @@ let _ToolManager = class _ToolManager {
           ...sessionId !== void 0 && { sessionId }
         }
       );
-      args = modifiedPayload.args;
+      toolArgs = modifiedPayload.args;
     }
     try {
       let result;
+      const registerBackgroundTask = (promise, description) => {
+        const fallbackId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        return {
+          result: {
+            taskId: toolCallId ?? fallbackId,
+            status: "running",
+            description
+          },
+          promise
+        };
+      };
       if (toolName.startsWith(_ToolManager.MCP_TOOL_PREFIX)) {
         this.logger.debug(`\u{1F527} Detected MCP tool: '${toolName}'`);
         const actualToolName = toolName.substring(_ToolManager.MCP_TOOL_PREFIX.length);
@@ -388,7 +622,34 @@ let _ToolManager = class _ToolManager {
           throw ToolError.invalidName(toolName, "tool name cannot be empty after prefix");
         }
         this.logger.debug(`\u{1F3AF} MCP routing: '${toolName}' -> '${actualToolName}'`);
-        result = await this.mcpManager.executeTool(actualToolName, args, sessionId);
+        const runInBackground = backgroundTasksEnabled && meta.runInBackground === true && sessionId !== void 0;
+        if (meta.runInBackground === true && !backgroundTasksEnabled) {
+          this.logger.debug(
+            "Background tool execution disabled; running synchronously instead.",
+            { toolName }
+          );
+        }
+        if (runInBackground) {
+          const backgroundSessionId = sessionId;
+          const { result: backgroundResult, promise } = registerBackgroundTask(
+            this.mcpManager.executeTool(actualToolName, toolArgs, backgroundSessionId),
+            `MCP tool ${actualToolName}`
+          );
+          this.agentEventBus.emit("tool:background", {
+            toolName,
+            toolCallId: backgroundResult.taskId,
+            sessionId: backgroundSessionId,
+            description: backgroundResult.description,
+            promise,
+            ...meta.timeoutMs !== void 0 && { timeoutMs: meta.timeoutMs },
+            ...meta.notifyOnComplete !== void 0 && {
+              notifyOnComplete: meta.notifyOnComplete
+            }
+          });
+          result = backgroundResult;
+        } else {
+          result = await this.mcpManager.executeTool(actualToolName, toolArgs, sessionId);
+        }
       } else if (toolName.startsWith(_ToolManager.INTERNAL_TOOL_PREFIX)) {
         this.logger.debug(`\u{1F527} Detected internal tool: '${toolName}'`);
         const actualToolName = toolName.substring(_ToolManager.INTERNAL_TOOL_PREFIX.length);
@@ -399,13 +660,46 @@ let _ToolManager = class _ToolManager {
           throw ToolError.internalToolsNotInitialized(toolName);
         }
         this.logger.debug(`\u{1F3AF} Internal routing: '${toolName}' -> '${actualToolName}'`);
-        result = await this.internalToolsProvider.executeTool(
-          actualToolName,
-          args,
-          sessionId,
-          abortSignal,
-          toolCallId
-        );
+        const runInBackground = backgroundTasksEnabled && meta.runInBackground === true && sessionId !== void 0;
+        if (meta.runInBackground === true && !backgroundTasksEnabled) {
+          this.logger.debug(
+            "Background tool execution disabled; running synchronously instead.",
+            { toolName }
+          );
+        }
+        if (runInBackground) {
+          const backgroundSessionId = sessionId;
+          const { result: backgroundResult, promise } = registerBackgroundTask(
+            this.internalToolsProvider.executeTool(
+              actualToolName,
+              toolArgs,
+              backgroundSessionId,
+              abortSignal,
+              toolCallId
+            ),
+            `Internal tool ${actualToolName}`
+          );
+          this.agentEventBus.emit("tool:background", {
+            toolName,
+            toolCallId: backgroundResult.taskId,
+            sessionId: backgroundSessionId,
+            description: backgroundResult.description,
+            promise,
+            ...meta.timeoutMs !== void 0 && { timeoutMs: meta.timeoutMs },
+            ...meta.notifyOnComplete !== void 0 && {
+              notifyOnComplete: meta.notifyOnComplete
+            }
+          });
+          result = backgroundResult;
+        } else {
+          result = await this.internalToolsProvider.executeTool(
+            actualToolName,
+            toolArgs,
+            sessionId,
+            abortSignal,
+            toolCallId
+          );
+        }
       } else if (toolName.startsWith(_ToolManager.CUSTOM_TOOL_PREFIX)) {
         this.logger.debug(`\u{1F527} Detected custom tool: '${toolName}'`);
         const actualToolName = toolName.substring(_ToolManager.CUSTOM_TOOL_PREFIX.length);
@@ -416,13 +710,46 @@ let _ToolManager = class _ToolManager {
           throw ToolError.internalToolsNotInitialized(toolName);
         }
         this.logger.debug(`\u{1F3AF} Custom routing: '${toolName}' -> '${actualToolName}'`);
-        result = await this.internalToolsProvider.executeTool(
-          actualToolName,
-          args,
-          sessionId,
-          abortSignal,
-          toolCallId
-        );
+        const runInBackground = backgroundTasksEnabled && meta.runInBackground === true && sessionId !== void 0;
+        if (meta.runInBackground === true && !backgroundTasksEnabled) {
+          this.logger.debug(
+            "Background tool execution disabled; running synchronously instead.",
+            { toolName }
+          );
+        }
+        if (runInBackground) {
+          const backgroundSessionId = sessionId;
+          const { result: backgroundResult, promise } = registerBackgroundTask(
+            this.internalToolsProvider.executeTool(
+              actualToolName,
+              toolArgs,
+              backgroundSessionId,
+              abortSignal,
+              toolCallId
+            ),
+            `Custom tool ${actualToolName}`
+          );
+          this.agentEventBus.emit("tool:background", {
+            toolName,
+            toolCallId: backgroundResult.taskId,
+            sessionId: backgroundSessionId,
+            description: backgroundResult.description,
+            promise,
+            ...meta.timeoutMs !== void 0 && { timeoutMs: meta.timeoutMs },
+            ...meta.notifyOnComplete !== void 0 && {
+              notifyOnComplete: meta.notifyOnComplete
+            }
+          });
+          result = backgroundResult;
+        } else {
+          result = await this.internalToolsProvider.executeTool(
+            actualToolName,
+            toolArgs,
+            sessionId,
+            abortSignal,
+            toolCallId
+          );
+        }
       } else {
         this.logger.debug(`\u{1F527} Detected tool without proper prefix: '${toolName}'`);
         const stats = await this.getToolStats();
@@ -672,21 +999,34 @@ let _ToolManager = class _ToolManager {
     throw ToolError.executionDenied(toolName, sessionId);
   }
   /**
-   * Handle tool approval/confirmation flow
-   * Checks allowed list, manages approval modes (manual, auto-approve, auto-deny),
-   * and handles remember choice logic
+   * Handle tool approval flow. Checks various precedence levels to determine
+   * if a tool should be auto-approved, denied, or requires manual approval.
+   */
+  async handleToolApproval(toolName, args, toolCallId, sessionId, callDescription) {
+    const quickResult = await this.tryQuickApprovalResolution(toolName, args, sessionId);
+    if (quickResult !== null) {
+      return quickResult;
+    }
+    return this.requestManualApproval(toolName, args, toolCallId, sessionId, callDescription);
+  }
+  /**
+   * Try to resolve tool approval quickly based on policies and cached permissions.
+   * Returns null if manual approval is needed.
    *
-   * @param toolName The fully qualified tool name
-   * @param args The arguments for the tool
-   * @param toolCallId The unique tool call ID for tracking parallel tool calls
-   * @param sessionId Optional session ID for context
+   * Precedence order (highest to lowest):
+   * 1. Static deny list (security - always blocks)
+   * 2. Custom approval override (tool-specific approval flows)
+   * 3. Session auto-approve (skill allowed-tools)
+   * 4. Static allow list
+   * 5. Dynamic "remembered" allowed list
+   * 6. Bash command patterns
+   * 7. Approval mode (auto-approve/auto-deny)
    */
-  async handleToolApproval(toolName, args, toolCallId, sessionId) {
+  async tryQuickApprovalResolution(toolName, args, sessionId) {
     if (this.isInAlwaysDenyList(toolName)) {
       this.logger.info(
         `Tool '${toolName}' is in static deny list \u2013 blocking execution (session: ${sessionId ?? "global"})`
       );
-      this.logger.debug(`\u{1F6AB} Tool execution blocked by policy: ${toolName}`);
       throw ToolError.executionDenied(toolName, sessionId);
     }
     const customApprovalResult = await this.checkCustomApprovalOverride(
@@ -697,25 +1037,29 @@ let _ToolManager = class _ToolManager {
     if (customApprovalResult.handled) {
       return { requireApproval: true, approvalStatus: "approved" };
     }
+    if (sessionId && this.isToolAutoApprovedForSession(sessionId, toolName)) {
+      this.logger.info(
+        `Tool '${toolName}' is in session's auto-approve list \u2013 skipping confirmation (session: ${sessionId})`
+      );
+      return { requireApproval: false };
+    }
     if (this.isInAlwaysAllowList(toolName)) {
       this.logger.info(
         `Tool '${toolName}' is in static allow list \u2013 skipping confirmation (session: ${sessionId ?? "global"})`
       );
       return { requireApproval: false };
     }
-    const isAllowed = await this.allowedToolsProvider.isToolAllowed(toolName, sessionId);
-    if (isAllowed) {
+    if (await this.allowedToolsProvider.isToolAllowed(toolName, sessionId)) {
       this.logger.info(
         `Tool '${toolName}' already allowed for session '${sessionId ?? "global"}' \u2013 skipping confirmation.`
       );
       return { requireApproval: false };
     }
-    let bashPatternResult;
     if (this.isBashTool(toolName)) {
       const command = args.command;
       if (command) {
-        bashPatternResult = this.checkBashPatternApproval(command);
-        if (bashPatternResult.approved) {
+        const bashResult = this.checkBashPatternApproval(command);
+        if (bashResult.approved) {
           this.logger.info(
             `Bash command '${command}' matched approved pattern \u2013 skipping confirmation.`
           );
@@ -731,79 +1075,38 @@ let _ToolManager = class _ToolManager {
       this.logger.debug(`\u{1F6AB} Auto-denying tool execution: ${toolName}`);
       throw ToolError.executionDenied(toolName, sessionId);
     }
+    return null;
+  }
+  /**
+   * Request manual approval from the user for a tool execution.
+   * Generates preview, sends approval request, and handles the response.
+   */
+  async requestManualApproval(toolName, args, toolCallId, sessionId, callDescription) {
     this.logger.info(
       `Tool confirmation requested for ${toolName}, sessionId: ${sessionId ?? "global"}`
     );
     try {
-      let displayPreview;
-      const actualToolName = toolName.replace(/^internal--/, "").replace(/^custom--/, "");
-      const internalTool = this.internalToolsProvider?.getTool(actualToolName);
-      if (internalTool?.generatePreview) {
-        try {
-          const context = { sessionId, toolCallId };
-          const preview = await internalTool.generatePreview(args, context);
-          displayPreview = preview ?? void 0;
-          this.logger.debug(`Generated preview for ${toolName}`);
-        } catch (previewError) {
-          if (previewError instanceof DextoRuntimeError && previewError.code === ToolErrorCode.VALIDATION_FAILED) {
-            this.logger.debug(
-              `Validation failed for ${toolName}: ${previewError.message}`
-            );
-            throw previewError;
-          }
-          this.logger.debug(
-            `Preview generation failed for ${toolName}: ${previewError instanceof Error ? previewError.message : String(previewError)}`
-          );
-        }
-      }
-      const requestData = {
+      const displayPreview = await this.generateToolPreview(
         toolName,
+        args,
         toolCallId,
-        args
-      };
-      if (sessionId !== void 0) {
-        requestData.sessionId = sessionId;
-      }
-      if (displayPreview !== void 0) {
-        requestData.displayPreview = displayPreview;
-      }
-      if (bashPatternResult?.suggestedPatterns && bashPatternResult.suggestedPatterns.length > 0) {
-        requestData.suggestedPatterns = bashPatternResult.suggestedPatterns;
-      }
-      const response = await this.approvalManager.requestToolConfirmation(requestData);
+        sessionId
+      );
+      const suggestedPatterns = this.getBashSuggestedPatterns(toolName, args);
+      const response = await this.approvalManager.requestToolConfirmation({
+        toolName,
+        toolCallId,
+        args,
+        ...callDescription !== void 0 && { description: callDescription },
+        ...sessionId !== void 0 && { sessionId },
+        ...displayPreview !== void 0 && { displayPreview },
+        ...suggestedPatterns !== void 0 && { suggestedPatterns }
+      });
       if (response.status === ApprovalStatus.APPROVED && response.data) {
-        const rememberChoice = "rememberChoice" in response.data ? response.data.rememberChoice : false;
-        const rememberPattern = "rememberPattern" in response.data ? response.data.rememberPattern : void 0;
-        if (rememberChoice) {
-          const allowSessionId = sessionId ?? response.sessionId;
-          await this.allowedToolsProvider.allowTool(toolName, allowSessionId);
-          this.logger.info(
-            `Tool '${toolName}' added to allowed tools for session '${allowSessionId ?? "global"}' (remember choice selected)`
-          );
-          this.autoApprovePendingToolRequests(toolName, allowSessionId);
-        } else if (rememberPattern && typeof rememberPattern === "string" && this.isBashTool(toolName)) {
-          this.approvalManager.addBashPattern(rememberPattern);
-          this.logger.info(
-            `Bash pattern '${rememberPattern}' added for session approval`
-          );
-          this.autoApprovePendingBashRequests(rememberPattern, sessionId);
-        }
+        await this.handleRememberChoice(toolName, response, sessionId);
       }
-      const approved = response.status === ApprovalStatus.APPROVED;
-      if (!approved) {
-        if (response.status === ApprovalStatus.CANCELLED && response.reason === "timeout") {
-          this.logger.info(
-            `Tool confirmation timed out for ${toolName}, sessionId: ${sessionId ?? "global"}`
-          );
-          this.logger.debug(`\u23F1\uFE0F Tool execution timed out: ${toolName}`);
-          const timeoutMs = response.timeoutMs ?? 0;
-          throw ToolError.executionTimeout(toolName, timeoutMs, sessionId);
-        }
-        this.logger.info(
-          `Tool confirmation denied for ${toolName}, sessionId: ${sessionId ?? "global"}, reason: ${response.reason ?? "unknown"}`
-        );
-        this.logger.debug(`\u{1F6AB} Tool execution denied: ${toolName}`);
-        throw ToolError.executionDenied(toolName, sessionId);
+      if (response.status !== ApprovalStatus.APPROVED) {
+        this.handleApprovalDenied(toolName, response, sessionId);
       }
       this.logger.info(
         `Tool confirmation approved for ${toolName}, sessionId: ${sessionId ?? "global"}`
@@ -816,6 +1119,81 @@ let _ToolManager = class _ToolManager {
       throw error;
     }
   }
+  /**
+   * Generate a preview for the tool approval UI if the tool supports it.
+   */
+  async generateToolPreview(toolName, args, toolCallId, sessionId) {
+    const actualToolName = toolName.replace(/^internal--/, "").replace(/^custom--/, "");
+    const internalTool = this.internalToolsProvider?.getTool(actualToolName);
+    if (!internalTool?.generatePreview) {
+      return void 0;
+    }
+    try {
+      const context = { sessionId, toolCallId };
+      const preview = await internalTool.generatePreview(args, context);
+      this.logger.debug(`Generated preview for ${toolName}`);
+      return preview ?? void 0;
+    } catch (previewError) {
+      if (previewError instanceof DextoRuntimeError && previewError.code === ToolErrorCode.VALIDATION_FAILED) {
+        this.logger.debug(`Validation failed for ${toolName}: ${previewError.message}`);
+        throw previewError;
+      }
+      this.logger.debug(
+        `Preview generation failed for ${toolName}: ${previewError instanceof Error ? previewError.message : String(previewError)}`
+      );
+      return void 0;
+    }
+  }
+  /**
+   * Get suggested bash patterns for the approval UI.
+   */
+  getBashSuggestedPatterns(toolName, args) {
+    if (!this.isBashTool(toolName)) {
+      return void 0;
+    }
+    const command = args.command;
+    if (!command) {
+      return void 0;
+    }
+    const result = this.checkBashPatternApproval(command);
+    return result.suggestedPatterns?.length ? result.suggestedPatterns : void 0;
+  }
+  /**
+   * Handle "remember choice" or "remember pattern" when user approves a tool.
+   */
+  async handleRememberChoice(toolName, response, sessionId) {
+    const data = response.data;
+    if (!data) return;
+    const rememberChoice = data.rememberChoice;
+    const rememberPattern = data.rememberPattern;
+    if (rememberChoice) {
+      const allowSessionId = sessionId ?? response.sessionId;
+      await this.allowedToolsProvider.allowTool(toolName, allowSessionId);
+      this.logger.info(
+        `Tool '${toolName}' added to allowed tools for session '${allowSessionId ?? "global"}' (remember choice selected)`
+      );
+      this.autoApprovePendingToolRequests(toolName, allowSessionId);
+    } else if (rememberPattern && this.isBashTool(toolName)) {
+      this.approvalManager.addBashPattern(rememberPattern);
+      this.logger.info(`Bash pattern '${rememberPattern}' added for session approval`);
+      this.autoApprovePendingBashRequests(rememberPattern, sessionId);
+    }
+  }
+  /**
+   * Handle approval denied/timeout - throws appropriate error.
+   */
+  handleApprovalDenied(toolName, response, sessionId) {
+    if (response.status === ApprovalStatus.CANCELLED && response.reason === DenialReason.TIMEOUT) {
+      this.logger.info(
+        `Tool confirmation timed out for ${toolName}, sessionId: ${sessionId ?? "global"}`
+      );
+      throw ToolError.executionTimeout(toolName, response.timeoutMs ?? 0, sessionId);
+    }
+    this.logger.info(
+      `Tool confirmation denied for ${toolName}, sessionId: ${sessionId ?? "global"}, reason: ${response.reason ?? "unknown"}`
+    );
+    throw ToolError.executionDenied(toolName, sessionId, response.message);
+  }
   /**
    * Refresh tool discovery (call when MCP servers change)
    * Refreshes both MCPManager's cache (server capabilities) and ToolManager's cache (combined tools)