@phuetz/code-buddy 1.6.0 → 2.0.0

package/dist/agent/tool-handler.js

@@ -16,17 +16,30 @@
  * Tool instances are lazy-loaded on first access for optimal startup time.
  */
 import { TextEditorTool, MorphEditorTool, ImageTool, BashTool, } from "../tools/index.js";
-import { getFormalToolRegistry, createTextEditorTools, createBashTools, createLsTools, createSearchTools, createWebTools, createTodoTools, createCronjobTools, createDockerTools, createKubernetesTools, createGitTools, createMiscTools, createBrowserTools, createProcessTools, createVisionTools, createScriptTools, createPlanTools, createKnowledgeTools, createRelationshipIntelligenceTools, createInternetScoutTools, createLeadScoutTools, createBrowserOperatorTools, createWindowsTools, createMemoryTools, createParallelTools, createAttentionTools, createSkillsInspectionTools, createLessonsTools, createUserModelTools, createAliasTools, createMultimodalTools, createAdvancedTools, createCanvasTools, createLspTools, createMergeConflictTools, createVulnScannerTools, createCodebaseReplaceTools, createAdvisorTools, createFleetTools, createAskUserQuestionTools, createExitPlanModeTools, createGuiTools, createSessionTools, createCodeExplorerTools, createScreenpipeTools, } from "../tools/registry/index.js";
-import { createRegisterToolTool } from "../tools/register-tool-handler.js";
+import { isBareChangeDirectory } from "../tools/bash/bash-tool.js";
+import { getFormalToolRegistry } from "../tools/registry/index.js";
+// The adapter list (base tools + aliases, with the audit-history rationale for
+// every group) lives in interactive-adapters.ts so tests can assert the
+// invariant `interactive dispatch ⊇ LLM exposition` on the production list.
+import { createInteractiveToolAdapters } from "../tools/registry/interactive-adapters.js";
 import { getMCPManager } from "../codebuddy/tools.js";
 import { getErrorMessage } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
-import { getPolicyManager } from "../security/tool-policy/index.js";
+import { getPolicyManager, getToolGroups, } from "../security/tool-policy/index.js";
 import { getTrustFolderManager } from "../security/trust-folders.js";
 import { getToolHooksManager, registerDefaultHooks, setCurrentProvider, } from "../tools/hooks/index.js";
-import { WritePolicy, WRITE_TOOL_NAMES } from "../security/write-policy.js";
+import { WritePolicy } from "../security/write-policy.js";
 import { RunStore } from "../observability/run-store.js";
 import { isToolNameAllowed } from "../utils/tool-filter.js";
+import { isToolVisibleForSurface } from '../config/feature-surface.js';
+import { loadAuthoredTools } from "./self-improvement/tool-skill-mutator.js";
+import { ConfirmationService } from "../utils/confirmation-service.js";
+import { buildToolApprovalKey, toolArgsApprovalPreview, } from "../security/tool-policy/approval-scope.js";
+import { TOOL_METADATA } from "../tools/metadata.js";
+import { formatToolResultForRecovery, getRestorableCompressor, } from '../context/restorable-compression.js';
+import { attachCodeExecRuntime, createCodeExecToolCallId, } from '../tools/code-exec-tool.js';
+import { realpathSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
 /**
  * Tools that only READ files/directories (no mutation). Used by the trust gate
  * to grant a narrow read-only exception for the agent's own skills directory
@@ -44,7 +57,22 @@ const READ_ONLY_FILE_TOOLS = new Set([
     'find_references',
     'find_definition',
     'search_multi',
+    'workspace_search',
+    'workspace_read',
 ]);
+/** Shell adapters own a stricter argv/sandbox/escalation pipeline. */
+const PRECISE_RUNTIME_APPROVAL_TOOLS = new Set([
+    'bash',
+    'terminal',
+    'shell_exec',
+]);
+const LEGACY_TOOL_METADATA = new Map(TOOL_METADATA.map((metadata) => [metadata.name, metadata]));
+function abortSignalFromExecutionExtra(executionExtra) {
+    const candidate = executionExtra?.abortSignal;
+    return candidate && typeof candidate === 'object' && 'aborted' in candidate
+        ? candidate
+        : undefined;
+}
 export function normalizeHallucinatedLocalToolCall(toolName, args) {
     const normalizedName = toolName.toLowerCase().replace(/\s+/g, '');
     const thoughtToolCallSuffix = normalizedName.match(/^thought_tool_call_\d+(?:_\d+)*\.(bash|create_file|write_file|view_file|read_file)$/)?.[1];
@@ -143,8 +171,13 @@ export class ToolHandler {
      */
     currentWorkingDirectory;
     currentBotId;
+    /** Host-provided conversation scope for raw tool-result recovery. */
+    currentRecoverySessionId;
+    /** Keeps code_exec stores and executors isolated between agent instances. */
+    codeExecAgentScopeId;
     constructor(deps) {
         this.deps = deps;
+        this.codeExecAgentScopeId = deps.agentId?.trim() || `agent_${createCodeExecToolCallId()}`;
         this.registry = getFormalToolRegistry();
         this.initializeRegistry();
         this.initializeToolHooks();
@@ -182,6 +215,87 @@ export class ToolHandler {
      */
     setWorkingDirectory(dir) {
         this.currentWorkingDirectory = dir;
+        if (dir) {
+            try {
+                const loaded = loadAuthoredTools(dir);
+                if (loaded.length > 0) {
+                    logger.info(`[self-improve] loaded ${loaded.length} workspace-authored tool(s): ${loaded.join(', ')}`);
+                }
+            }
+            catch (error) {
+                logger.warn('[self-improve] failed to load workspace-authored tools', {
+                    cwd: dir,
+                    error: getErrorMessage(error),
+                });
+            }
+        }
+    }
+    /** Restore a session-owned cwd without re-registering workspace-authored tools. */
+    restoreWorkingDirectory(dir) {
+        this.currentWorkingDirectory = dir;
+    }
+    /** Workspace currently used by tool execution and recovery storage. */
+    getWorkingDirectory() {
+        return this.currentWorkingDirectory ?? process.cwd();
+    }
+    /** Handle the stateful `cd` builtin without ever mutating process.cwd(). */
+    changeSessionDirectory(command, baseCwd) {
+        // Second chemin de la « famille cwd embarqué » : ne traiter comme changement de
+        // répertoire de session qu'un `cd` SEUL. `command.startsWith('cd ')` interceptait
+        // aussi `cd /repo && node --test`, dont tout ce qui suit était stat comme un
+        // répertoire — l'agent headless n'exécutait plus rien. Une commande composée
+        // repart au shell, où `cd X && Y` a son sens.
+        if (!isBareChangeDirectory(command))
+            return null;
+        const requested = command.substring(3).trim().replace(/^["']|["']$/g, '');
+        try {
+            const candidate = resolve(baseCwd, requested);
+            if (!statSync(candidate).isDirectory()) {
+                return { success: false, error: `Cannot change directory: not a directory: ${candidate}` };
+            }
+            this.currentWorkingDirectory = realpathSync(candidate);
+            return {
+                success: true,
+                output: `Changed directory to: ${this.currentWorkingDirectory}`,
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: `Cannot change directory: ${getErrorMessage(error)}`,
+            };
+        }
+    }
+    /**
+     * Set an embedding host's stable conversation ID (Cowork/channel session).
+     * RestorableCompressor hashes this value before disk use. Undefined falls
+     * back to SessionStore and finally to this agent instance's private scope.
+     */
+    setRecoverySessionId(sessionId) {
+        this.currentRecoverySessionId = sessionId && sessionId.length > 0
+            ? sessionId
+            : undefined;
+    }
+    /** Return a stable, non-empty recovery scope without exposing it on disk. */
+    getRecoverySessionId() {
+        if (this.currentRecoverySessionId)
+            return this.currentRecoverySessionId;
+        try {
+            const persisted = this.deps.sessionIdProvider?.();
+            if (persisted)
+                return persisted;
+        }
+        catch {
+            // A host session provider is best-effort; the per-agent scope remains safe.
+        }
+        return this.codeExecAgentScopeId;
+    }
+    /** Allow an internal nested-agent executor to preserve its own recovery scope. */
+    recoverySessionIdForExecution(executionExtra) {
+        const nestedScope = executionExtra?.recoverySessionId;
+        return typeof nestedScope === 'string' && nestedScope.length > 0
+            ? nestedScope
+            : this.getRecoverySessionId();
     }
     /**
      * Multi-bot channels: tag tool-execution contexts with the bot id so per-bot
@@ -203,57 +317,11 @@ export class ToolHandler {
     initializeRegistry() {
         if (this.registryInitialized)
             return;
-        // Register all tool adapters
-        const allTools = [
-            ...createTextEditorTools(),
-            ...createBashTools(),
-            ...createLsTools(),
-            ...createSearchTools(),
-            ...createWebTools(),
-            ...createTodoTools(),
-            ...createCronjobTools(),
-            ...createDockerTools(),
-            ...createKubernetesTools(),
-            ...createGitTools(),
-            ...createMiscTools(),
-            ...createBrowserTools(),
-            ...createProcessTools(),
-            ...createVisionTools(),
-            ...createScriptTools(),
-            ...createPlanTools(),
-            ...createKnowledgeTools(),
-            ...createRelationshipIntelligenceTools(),
-            ...createInternetScoutTools(),
-            ...createLeadScoutTools(),
-            ...createBrowserOperatorTools(),
-            ...(process.platform === 'win32' ? createWindowsTools() : []),
-            ...createMemoryTools(),
-            ...createParallelTools(),
-            ...createAttentionTools(),
-            ...createSkillsInspectionTools(),
-            ...createLessonsTools(),
-            ...createUserModelTools(),
-            ...createMultimodalTools(),
-            ...createAdvancedTools(),
-            ...createCanvasTools(),
-            ...createLspTools(),
-            ...createMergeConflictTools(),
-            ...createVulnScannerTools(),
-            ...createCodebaseReplaceTools(),
-            ...createAdvisorTools(),
-            ...createFleetTools(),
-            ...createAskUserQuestionTools(),
-            ...createExitPlanModeTools(),
-            ...createGuiTools(),
-            ...createSessionTools(),
-            ...createCodeExplorerTools(),
-            ...createScreenpipeTools(),
-            // Self-improvement: the agent can author its own tools (opt-in only).
-            ...(process.env.CODEBUDDY_SELF_IMPROVE === 'true' ? [createRegisterToolTool()] : []),
-        ];
-        // Register canonical-prefix alias tools (shell_exec→bash, file_read→view_file, etc.)
-        const aliasTools = createAliasTools(allTools);
-        allTools.push(...aliasTools);
+        // The full interactive dispatch list (base adapters + canonical aliases)
+        // lives in registry/interactive-adapters.ts so the invariant
+        // `interactive dispatch ⊇ LLM exposition` is enforceable by
+        // tests/tools/tool-surface.test.ts against the exact production list.
+        const allTools = createInteractiveToolAdapters();
         for (const tool of allTools) {
             if (!this.registry.has(tool.name)) {
                 this.registry.register(tool);
@@ -313,7 +381,64 @@ export class ToolHandler {
      * @param toolCall - Tool call structure from the LLM response
      * @returns Tool execution result with success status and output/error
      */
-    async executeTool(toolCall) {
+    /**
+     * Execute the two vetted operational self-inspection tools without any user,
+     * plugin, lifecycle, analytics, registry-event, or confirmation hooks. This
+     * is intentionally separate from executeTool(): an arbitrary hook can run a
+     * command or network request even around an otherwise read-only tool.
+     */
+    async executeStrictSelfInspectionTool(toolCall, executionExtra) {
+        const toolName = toolCall.function.name;
+        let args;
+        try {
+            const parsed = JSON.parse(toolCall.function.arguments || '{}');
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                return { success: false, error: 'Self-inspection tool arguments must be an object' };
+            }
+            args = parsed;
+        }
+        catch {
+            return { success: false, error: 'Self-inspection tool arguments must be valid JSON' };
+        }
+        const contextExtra = {
+            ...(executionExtra ?? {}),
+            ...(toolName === 'restore_context'
+                ? { recoverySessionId: this.recoverySessionIdForExecution(executionExtra) }
+                : {}),
+        };
+        const sessionId = this.deps.sessionIdProvider?.() ?? this.currentRunId;
+        const abortSignal = abortSignalFromExecutionExtra(executionExtra);
+        const context = {
+            cwd: this.currentWorkingDirectory ?? process.cwd(),
+            botId: this.currentBotId,
+            ...(sessionId ? { sessionId } : {}),
+            ...(abortSignal ? { abortSignal } : {}),
+            ...(Object.keys(contextExtra).length > 0 ? { extra: contextExtra } : {}),
+        };
+        if (toolName === 'self_describe') {
+            const { SelfDescribeTool } = await import('../tools/registry/self-describe-tools.js');
+            const tool = new SelfDescribeTool();
+            const validation = tool.validate(args);
+            if (!validation.valid) {
+                return { success: false, error: `Validation failed: ${validation.errors?.join(', ')}` };
+            }
+            return tool.execute(args, context);
+        }
+        if (toolName === 'restore_context') {
+            const { RestoreContextTool } = await import('../tools/registry/attention-tools.js');
+            const tool = new RestoreContextTool();
+            const validation = tool.validate(args);
+            if (!validation.valid) {
+                return { success: false, error: `Validation failed: ${validation.errors?.join(', ')}` };
+            }
+            return tool.execute(args, context);
+        }
+        return {
+            success: false,
+            error: `Tool "${toolName}" is not available in strict self-inspection`,
+        };
+    }
+    async executeTool(toolCall, executionExtra) {
         const startTime = Date.now();
         const hooksManager = getToolHooksManager();
         try {
@@ -348,92 +473,11 @@ export class ToolHandler {
             if (filterBlock) {
                 return filterBlock;
             }
-            // Check permission mode before execution
-            try {
-                const { getPermissionModeManager } = await import('../security/permission-modes.js');
-                const permManager = getPermissionModeManager();
-                const permDecision = permManager.checkPermission('execute', toolName);
-                if (!permDecision.allowed) {
-                    return { success: false, error: `Permission denied: ${permDecision.reason}` };
-                }
-            }
-            catch { /* permission-modes module optional */ }
-            // Check policy before execution
-            const policyDecision = this.checkToolPolicy(toolName, args);
-            if (policyDecision.action === 'deny') {
-                logger.info(`Tool denied by policy: ${toolName}`, { reason: policyDecision.reason });
-                // Execute denied hooks
-                await hooksManager.executeDeniedHooks(hookContext, new Error(policyDecision.reason || 'Tool denied by policy'));
-                return {
-                    success: false,
-                    error: `Tool "${toolName}" is not allowed: ${policyDecision.reason}`,
-                };
-            }
-            if (policyDecision.action === 'confirm') {
-                // Request user confirmation if callback is set
-                if (this.confirmationCallback) {
-                    const confirmed = await this.confirmationCallback(toolName, args, policyDecision);
-                    if (!confirmed) {
-                        logger.info(`Tool execution cancelled by user: ${toolName}`);
-                        // Execute denied hooks for user cancellation
-                        await hooksManager.executeDeniedHooks(hookContext, new Error('User cancelled execution'));
-                        return {
-                            success: false,
-                            error: `User cancelled execution of "${toolName}"`,
-                        };
-                    }
-                    // User confirmed - set session override to allow future executions
-                    getPolicyManager().setSessionOverride(toolName, 'allow');
-                }
-                // If no callback, proceed (for backwards compatibility)
-            }
-            // Check trust folders for file/bash operations
-            const trustManager = getTrustFolderManager();
-            if (trustManager.isEnforcementEnabled()) {
-                const targetPath = args.path || args.file_path || args.target_file;
-                if (typeof targetPath === 'string' && !trustManager.isTrusted(targetPath)) {
-                    // Narrow exception: read-only file tools may read the agent's own
-                    // managed skills directory (~/.codebuddy/skills) without a trust
-                    // prompt, so it can follow its own SKILL.md instructions. This is
-                    // scoped to read-only tools AND to skills/ only — it never authorizes
-                    // a write, and never exposes the rest of ~/.codebuddy (credentials).
-                    const isReadOnlySkillsRead = READ_ONLY_FILE_TOOLS.has(toolName) &&
-                        trustManager.isReadableSkillsPath(targetPath);
-                    if (!isReadOnlySkillsRead) {
-                        logger.info(`Tool blocked by trust folder: ${toolName}`, { path: targetPath });
-                        return {
-                            success: false,
-                            error: `Path "${targetPath}" is not in a trusted directory. Run Code Buddy from within that directory, or add it to ~/.codebuddy/trusted-folders.json (the "folders" array).`,
-                        };
-                    }
-                }
-            }
-            // ── WritePolicy gating (strict / confirm modes) ──────────────
-            if (WRITE_TOOL_NAMES.has(toolName)) {
-                const writePolicy = WritePolicy.getInstance();
-                const paths = [];
-                if (typeof args.path === 'string')
-                    paths.push(args.path);
-                if (typeof args.file_path === 'string')
-                    paths.push(args.file_path);
-                if (typeof args.target_file === 'string')
-                    paths.push(args.target_file);
-                if (Array.isArray(args.files)) {
-                    for (const f of args.files) {
-                        if (typeof f === 'string')
-                            paths.push(f);
-                        else if (typeof f?.path === 'string')
-                            paths.push(f.path);
-                    }
-                }
-                const gateResult = await writePolicy.gate({ toolName, paths, description: args.description }, this.currentRunId);
-                if (!gateResult.allowed) {
-                    return {
-                        success: false,
-                        error: gateResult.reason || `WritePolicy blocked tool "${toolName}"`,
-                    };
-                }
-            }
+            const authorizationCwd = this.currentWorkingDirectory ?? process.cwd();
+            const authorizedScope = buildToolApprovalKey(toolName, args, authorizationCwd);
+            const authorizationError = await this.authorizeToolAction(toolName, args, hookContext, hooksManager);
+            if (authorizationError)
+                return authorizationError;
             // ── RunStore: emit tool_call event ───────────────────────────
             if (this.currentRunId) {
                 RunStore.getInstance().emit(this.currentRunId, {
@@ -485,6 +529,16 @@ export class ToolHandler {
             toolCall.function.arguments = JSON.stringify(lifecycleModifiedArgs);
             hookContext.args = lifecycleModifiedArgs;
             const finalArgs = hookContext.args;
+            // Hooks are allowed to enrich arguments, but changed arguments describe a
+            // different action. Re-run every permission/trust/write gate against the
+            // actual values that will be dispatched. This closes the preflight→hook
+            // TOCTOU where an approved workspace path could become an outside path.
+            const finalScope = buildToolApprovalKey(toolName, finalArgs, authorizationCwd);
+            if (finalScope !== authorizedScope) {
+                const modifiedAuthorizationError = await this.authorizeToolAction(toolName, finalArgs, hookContext, hooksManager);
+                if (modifiedAuthorizationError)
+                    return modifiedAuthorizationError;
+            }
             // Execute tool with potentially modified args
             let result;
             // Handle special tool prefixes first
@@ -508,7 +562,7 @@ export class ToolHandler {
             }
             else if (this.registry.has(toolName)) {
                 // Dispatch through registry for all other tools
-                result = await this.executeRegistryTool(toolName, finalArgs);
+                result = await this.executeRegistryTool(toolName, finalArgs, executionExtra);
             }
             else {
                 // Suggest common alternatives for hallucinated tool names
@@ -544,6 +598,12 @@ export class ToolHandler {
                 };
             }
             // Convert to hook result format
+            // Preserve the native result before provider-facing sanitizers or legacy
+            // RTK hooks can truncate it. This is the recovery source used by
+            // restore_context; the model may receive a compact representation later.
+            if (toolCall.id) {
+                getRestorableCompressor().writeToolResult(toolCall.id, formatToolResultForRecovery(result), this.currentWorkingDirectory ?? process.cwd(), this.recoverySessionIdForExecution(executionExtra));
+            }
             const hookResult = {
                 success: result.success,
                 output: result.output,
@@ -598,11 +658,16 @@ export class ToolHandler {
                 }
             }
             catch { /* analytics module optional */ }
-            // Return final result
+            // Return final result. Hooks may rewrite success/output/error, but the
+            // structured `data` block must survive: downstream consumers rely on it
+            // (tool_search → data.names drives the selection expansion; web_test →
+            // data.passed; gui/browser overlays). Rebuilding without it silently
+            // stripped data from EVERY interactive tool result.
             return {
                 success: finalHookResult.success,
                 output: finalHookResult.output,
                 error: finalHookResult.error,
+                ...(result.data !== undefined ? { data: result.data } : {}),
             };
         }
         catch (error) {
@@ -654,7 +719,7 @@ export class ToolHandler {
      * request a hidden tool after the schema had already removed it.
      */
     checkActiveToolFilter(toolName, toolCallId, startTime = Date.now()) {
-        if (isToolNameAllowed(toolName)) {
+        if (isToolNameAllowed(toolName) && isToolVisibleForSurface(toolName)) {
             return null;
         }
         logger.info(`Tool blocked by active filter: ${toolName}`);
@@ -692,6 +757,144 @@ export class ToolHandler {
             },
         });
     }
+    /**
+     * One authorization stage shared by the original tool call and the final
+     * post-hook arguments. A `confirm` decision can never silently fall through.
+     */
+    async authorizeToolAction(toolName, args, hookContext, hooksManager) {
+        try {
+            const { getPermissionModeManager } = await import('../security/permission-modes.js');
+            const shellCommand = typeof args.command === 'string'
+                ? args.command
+                : typeof args.cmd === 'string'
+                    ? args.cmd
+                    : null;
+            const permissionAction = PRECISE_RUNTIME_APPROVAL_TOOLS.has(toolName) && shellCommand
+                ? shellCommand
+                : 'execute';
+            const decision = getPermissionModeManager().checkPermission(permissionAction, toolName);
+            if (!decision.allowed) {
+                return { success: false, error: `Permission denied: ${decision.reason}` };
+            }
+        }
+        catch {
+            /* permission-modes module optional */
+        }
+        const policyDecision = this.checkToolPolicy(toolName, args);
+        if (policyDecision.action === 'deny') {
+            logger.info(`Tool denied by policy: ${toolName}`, { reason: policyDecision.reason });
+            await hooksManager.executeDeniedHooks(hookContext, new Error(policyDecision.reason || 'Tool denied by policy'));
+            return {
+                success: false,
+                error: `Tool "${toolName}" is not allowed: ${policyDecision.reason}`,
+            };
+        }
+        const trustManager = getTrustFolderManager();
+        if (trustManager.isEnforcementEnabled()) {
+            const targetPath = args.path ||
+                args.file_path ||
+                args.target_file ||
+                args.outputPath ||
+                args.output_path;
+            if (typeof targetPath === 'string' && !trustManager.isTrusted(targetPath)) {
+                const isReadOnlySkillsRead = READ_ONLY_FILE_TOOLS.has(toolName) &&
+                    trustManager.isReadableSkillsPath(targetPath);
+                if (!isReadOnlySkillsRead) {
+                    logger.info(`Tool blocked by trust folder: ${toolName}`, { path: targetPath });
+                    return {
+                        success: false,
+                        error: `Path "${targetPath}" is not in a trusted directory. Run Code Buddy from within that directory, or add it to ~/.codebuddy/trusted-folders.json (the "folders" array).`,
+                    };
+                }
+            }
+        }
+        const isConditionalMeetingWrite = toolName === 'meeting_notes' &&
+            typeof args.output_prefix === 'string' &&
+            args.output_prefix.trim().length > 0;
+        const writePolicy = WritePolicy.getInstance();
+        if (writePolicy.isWriteTool(toolName) && (toolName !== 'meeting_notes' || isConditionalMeetingWrite)) {
+            const paths = [];
+            if (typeof args.path === 'string')
+                paths.push(args.path);
+            if (typeof args.file_path === 'string')
+                paths.push(args.file_path);
+            if (typeof args.target_file === 'string')
+                paths.push(args.target_file);
+            if (typeof args.output_prefix === 'string')
+                paths.push(args.output_prefix);
+            if (Array.isArray(args.files)) {
+                for (const file of args.files) {
+                    if (typeof file === 'string')
+                        paths.push(file);
+                    else if (typeof file?.path === 'string')
+                        paths.push(file.path);
+                }
+            }
+            const gateResult = await writePolicy.gate({ toolName, paths, description: args.description }, this.currentRunId);
+            if (!gateResult.allowed) {
+                return {
+                    success: false,
+                    error: gateResult.reason || `WritePolicy blocked tool "${toolName}"`,
+                };
+            }
+        }
+        const shellCommand = typeof args.command === 'string'
+            ? args.command
+            : typeof args.cmd === 'string'
+                ? args.cmd
+                : '';
+        if (shellCommand &&
+            (toolName === 'bash' || toolName === 'shell_exec' || toolName === 'shell')) {
+            const shellGate = await writePolicy.gateShell(shellCommand);
+            if (!shellGate.allowed) {
+                return {
+                    success: false,
+                    error: shellGate.reason || `WritePolicy blocked tool "${toolName}"`,
+                };
+            }
+        }
+        // Shell adapters own a more precise full-expression policy followed by a
+        // workspace sandbox. Prompting here would happen before that safer attempt.
+        // All deterministic trust/write gates above intentionally run first.
+        if (policyDecision.action === 'confirm' &&
+            !PRECISE_RUNTIME_APPROVAL_TOOLS.has(toolName)) {
+            let confirmed;
+            if (this.confirmationCallback) {
+                confirmed = await this.confirmationCallback(toolName, args, policyDecision);
+            }
+            else {
+                const cwd = this.currentWorkingDirectory ?? process.cwd();
+                const groups = getToolGroups(toolName);
+                const highRisk = groups.includes('group:dangerous') ||
+                    groups.includes('group:mcp') ||
+                    groups.includes('group:plugin');
+                const result = await ConfirmationService.getInstance().requestConfirmation({
+                    operation: `Execute tool: ${toolName}`,
+                    filename: `${toolName} @ ${cwd}`,
+                    toolName,
+                    toolArgs: args,
+                    showVSCodeOpen: false,
+                    content: `Policy: ${policyDecision.reason}\nWorking directory: ${cwd}\nArguments:\n` +
+                        toolArgsApprovalPreview(args),
+                    approvalKey: buildToolApprovalKey(toolName, args, cwd),
+                    riskLevel: highRisk ? 'high' : 'medium',
+                    detail: { cwd, policySource: policyDecision.source },
+                }, 'tool');
+                confirmed = result.confirmed;
+            }
+            if (!confirmed) {
+                logger.info(`Tool execution cancelled by policy gate: ${toolName}`);
+                await hooksManager.executeDeniedHooks(hookContext, new Error('User cancelled execution'));
+                return {
+                    success: false,
+                    error: `User cancelled execution of "${toolName}"`,
+                };
+            }
+            // Never promote one approval to PolicyManager's process-global
+            // `toolName -> allow`. ConfirmationService retains exact arg/cwd scopes.
+        }
+        return null;
+    }
     /**
      * Check tool policy before execution
      * @param toolName Tool name to check
@@ -700,7 +903,79 @@ export class ToolHandler {
      */
     checkToolPolicy(toolName, args) {
         const policyManager = getPolicyManager();
-        return policyManager.checkTool(toolName, args);
+        const decision = policyManager.checkTool(toolName, args);
+        if (decision.action === 'deny')
+            return decision;
+        const registryMetadata = this.registry.get(toolName)?.metadata;
+        const legacyMetadata = LEGACY_TOOL_METADATA.get(toolName);
+        const requiresConfirmation = registryMetadata?.requiresConfirmation;
+        // Explicit global/session overrides are user authority. Profile/default
+        // allows still combine with the adapter's effect declaration using the
+        // strictest decision, so a forgotten group cannot erase a confirm marker.
+        if (requiresConfirmation === true &&
+            decision.action === 'allow' &&
+            (decision.source === 'profile' || decision.source === 'default')) {
+            return {
+                action: 'confirm',
+                reason: 'Tool metadata requires confirmation',
+                source: 'default',
+                timestamp: new Date(),
+            };
+        }
+        if (decision.source !== 'default')
+            return decision;
+        // Asking Lisa for a photo is already the user's authorization for this
+        // bounded companion action. The tool rotates an existing local cache when
+        // possible (or uses the configured image backend), archives a copy, and
+        // returns/sends the requested media. A second generic tool confirmation
+        // adds no meaningful safety boundary. Explicit policy overrides still win
+        // because they are returned above, and adult content remains guarded in
+        // companion/lisa-selfie.ts.
+        if (toolName === 'lisa_selfie') {
+            return {
+                action: 'allow',
+                reason: 'The Lisa photo request itself authorizes bounded selfie delivery',
+                source: 'default',
+                timestamp: new Date(),
+            };
+        }
+        // Sharing a video is already an explicit request to inspect that media.
+        // The default path only reads captions/media and writes disposable local
+        // cache artifacts, so a second approval adds friction without granting new
+        // authority. Keep cloud:true behind the normal confirmation gate because
+        // it sends the URL/video to an external model provider.
+        if (toolName === 'understand_video' && args.cloud !== true) {
+            return {
+                action: 'allow',
+                reason: 'Local-first video understanding is read-only media analysis',
+                source: 'default',
+                timestamp: new Date(),
+            };
+        }
+        const modifiesFiles = registryMetadata?.modifiesFiles;
+        const makesNetworkRequests = registryMetadata?.makesNetworkRequests;
+        const fleetSafe = registryMetadata?.fleetSafe === true || legacyMetadata?.fleetSafe === true;
+        if (fleetSafe && modifiesFiles !== true) {
+            return {
+                action: 'allow',
+                reason: 'Read-only fleet-safe tool metadata',
+                source: 'default',
+                timestamp: new Date(),
+            };
+        }
+        const category = registryMetadata?.category;
+        const inferredReadOnly = (category === 'file_read' || category === 'file_search' || category === 'codebase') &&
+            modifiesFiles !== true &&
+            makesNetworkRequests !== true;
+        if (inferredReadOnly) {
+            return {
+                action: 'allow',
+                reason: `Read-only ${category} tool metadata`,
+                source: 'default',
+                timestamp: new Date(),
+            };
+        }
+        return decision;
     }
     /**
      * Check if a tool is allowed by policy
@@ -709,8 +984,7 @@ export class ToolHandler {
      * @returns True if tool is allowed
      */
     isToolAllowed(toolName, args) {
-        const policyManager = getPolicyManager();
-        return policyManager.isAllowed(toolName, args);
+        return this.checkToolPolicy(toolName, args || {}).action === 'allow';
     }
     /**
      * Get policy decision for a tool (for UI display)
@@ -733,7 +1007,7 @@ export class ToolHandler {
      * @param args - Tool arguments
      * @returns Tool execution result
      */
-    async executeRegistryTool(toolName, args) {
+    async executeRegistryTool(toolName, args, executionExtra) {
         const registeredTool = this.registry.get(toolName);
         if (!registeredTool) {
             return {
@@ -742,14 +1016,113 @@ export class ToolHandler {
             };
         }
         const metadata = registeredTool.metadata;
-        const context = {
+        const sessionId = toolName === 'context_expand'
+            ? this.deps.contextZoomSessionIdProvider?.() ?? this.deps.sessionIdProvider?.() ?? this.currentRunId
+            : this.deps.sessionIdProvider?.() ?? this.currentRunId;
+        const recoverySessionId = this.recoverySessionIdForExecution(executionExtra);
+        const abortSignal = abortSignalFromExecutionExtra(executionExtra);
+        const contextExtra = {
+            ...(executionExtra ?? {}),
+            ...(toolName === 'restore_context' || toolName === 'context_restore'
+                ? { recoverySessionId }
+                : {}),
+        };
+        let context = {
             cwd: this.currentWorkingDirectory ?? process.cwd(),
             botId: this.currentBotId,
+            ...(sessionId ? { sessionId } : {}),
+            ...(abortSignal ? { abortSignal } : {}),
+            ...(Object.keys(contextExtra).length > 0 ? { extra: contextExtra } : {}),
         };
+        if (toolName === 'code_exec') {
+            const availableTools = Array.from(new Set([
+                ...this.registry.getNames(),
+                ...getMCPManager().getTools().map((tool) => tool.name),
+                ...this.deps.marketplace.getTools(),
+            ]))
+                .filter((name) => name !== 'code_exec' && name !== 'exec' && isToolNameAllowed(name))
+                .sort();
+            // HTTP uses one host agent and swaps logical conversations under a
+            // mutex. Its SessionStore ID therefore cannot isolate code_exec state;
+            // the opaque recovery scope is the authoritative logical session.
+            const stateSessionId = recoverySessionId || sessionId || 'sessionless';
+            const stateAgentId = this.currentBotId
+                ? `${this.codeExecAgentScopeId}:bot:${this.currentBotId}`
+                : this.codeExecAgentScopeId;
+            context = attachCodeExecRuntime(context, {
+                scopeId: `${stateAgentId}:session:${stateSessionId}`,
+                sessionId: stateSessionId,
+                agentId: stateAgentId,
+                cwd: context.cwd,
+                availableTools,
+                executor: async (nestedToolName, nestedArgs) => {
+                    // Defense in depth: code_exec is omitted from the child bridge and
+                    // rejected again here so tools.call('code_exec', ...) cannot recurse.
+                    if (nestedToolName === 'code_exec' || nestedToolName === 'exec') {
+                        return {
+                            success: false,
+                            error: 'Recursive code_exec calls are not allowed.',
+                        };
+                    }
+                    let serializedArgs;
+                    try {
+                        serializedArgs = JSON.stringify(nestedArgs);
+                    }
+                    catch {
+                        return {
+                            success: false,
+                            error: `Arguments for nested tool "${nestedToolName}" are not JSON-serializable.`,
+                        };
+                    }
+                    return await this.executeTool({
+                        id: createCodeExecToolCallId(),
+                        type: 'function',
+                        function: {
+                            name: nestedToolName,
+                            arguments: serializedArgs,
+                        },
+                    }, {
+                        ...(executionExtra ?? {}),
+                        recoverySessionId,
+                    });
+                },
+            });
+        }
         // Handle bash tool with hooks and auto-repair
         if (toolName === 'bash') {
             return await this.executeBashWithHooks(args, context);
         }
+        // apply_patch carries no `path` arg (its files live inside the patch body),
+        // so it would otherwise skip the checkpoint/hook path below and write with
+        // no /undo snapshot. Parse the patch, checkpoint each affected file, run
+        // hooks, then execute. Checkpointing is best-effort — never block the write.
+        if (toolName === 'apply_patch' && metadata.modifiesFiles) {
+            const patchText = typeof args.patch === 'string' ? args.patch : '';
+            const affected = [];
+            try {
+                const { parsePatch } = await import('../tools/apply-patch.js');
+                for (const op of parsePatch(patchText)) {
+                    if (op.type === 'add')
+                        this.deps.checkpointManager.checkpointBeforeCreate(op.path);
+                    else
+                        this.deps.checkpointManager.checkpointBeforeEdit(op.path);
+                    affected.push(op.path);
+                    if (op.moveTo) {
+                        this.deps.checkpointManager.checkpointBeforeCreate(op.moveTo);
+                        affected.push(op.moveTo);
+                    }
+                }
+            }
+            catch { /* best-effort checkpoint — still apply the patch */ }
+            for (const file of affected) {
+                await this.deps.hooksManager.executeHooks('pre-edit', { file, content: '' });
+            }
+            const result = await this.registry.execute(toolName, args, context);
+            for (const file of affected) {
+                await this.deps.hooksManager.executeHooks('post-edit', { file, content: '', output: result.output });
+            }
+            return result;
+        }
         // Handle file-modifying tools with checkpoints and hooks
         const editPath = (args.path || args.file_path);
         if (metadata.modifiesFiles && editPath) {
@@ -799,8 +1172,10 @@ export class ToolHandler {
                 error: getErrorMessage(hookError),
             });
         }
-        // Execute bash through registry
-        let bashResult = await this.registry.execute("bash", args, context);
+        const directoryChange = this.changeSessionDirectory(command, context.cwd);
+        // Execute bash through registry unless the stateful cd builtin was handled
+        // locally; both paths still receive the normal post-bash lifecycle hook.
+        let bashResult = directoryChange ?? await this.registry.execute("bash", args, context);
         // Auto-repair on failure
         if (!bashResult.success && bashResult.error && this.deps.repairCoordinator.isRepairEnabled()) {
             const repairResult = await this.deps.repairCoordinator.attemptRepair(bashResult.error, command);
@@ -833,49 +1208,212 @@ export class ToolHandler {
         }
         return bashResult;
     }
+    /**
+     * Streaming bash dispatch. Mirrors executeTool's authorization, lifecycle
+     * hooks and RunStore events, then yields from BashTool.executeStreaming.
+     *
+     * Confirmation is not asked here: authorizeToolAction skips the generic
+     * confirm prompt for PRECISE_RUNTIME_APPROVAL_TOOLS, and the shell adapter
+     * still calls evaluateShellExecution (deny/ask/sandbox) before spawn.
+     */
+    async *executeStreamingBash(toolCall, executionExtra, startTime) {
+        const toolName = 'bash';
+        const hooksManager = getToolHooksManager();
+        let args;
+        try {
+            args = JSON.parse(toolCall.function.arguments);
+        }
+        catch (error) {
+            return { success: false, error: `Streaming execution error: ${getErrorMessage(error)}` };
+        }
+        let hookContext = {
+            toolName,
+            originalArgs: { ...args },
+            args,
+            toolCallId: toolCall.id,
+            timestamp: startTime,
+        };
+        const authorizationCwd = this.currentWorkingDirectory ?? process.cwd();
+        const authorizedScope = buildToolApprovalKey(toolName, args, authorizationCwd);
+        const authorizationError = await this.authorizeToolAction(toolName, args, hookContext, hooksManager);
+        if (authorizationError)
+            return authorizationError;
+        if (this.currentRunId) {
+            RunStore.getInstance().emit(this.currentRunId, {
+                type: 'tool_call',
+                data: {
+                    toolName,
+                    toolCallId: toolCall.id,
+                    args: this.sanitizeArgsForLog(args),
+                },
+            });
+        }
+        hookContext = await hooksManager.executeBeforeHooks(hookContext);
+        const modifiedArgs = hookContext.args;
+        let abortExecution = false;
+        let lifecycleModifiedArgs = { ...modifiedArgs };
+        try {
+            const lifecycleBeforeResult = await this.deps.hooksManager.executeHooks('before-tool-call', {
+                toolName,
+                toolArgs: modifiedArgs,
+                sessionId: this.currentRunId,
+            });
+            for (const res of lifecycleBeforeResult) {
+                if (res.abort) {
+                    abortExecution = true;
+                }
+                if (res.modified?.toolArgs) {
+                    lifecycleModifiedArgs = { ...lifecycleModifiedArgs, ...res.modified.toolArgs };
+                }
+            }
+        }
+        catch (hookError) {
+            logger.warn('before-tool-call hook failed, continuing with execution', {
+                error: getErrorMessage(hookError),
+            });
+        }
+        if (abortExecution) {
+            return {
+                success: false,
+                error: `Execution of tool "${toolName}" was aborted by a before-tool-call hook.`,
+            };
+        }
+        hookContext.args = lifecycleModifiedArgs;
+        const finalArgs = hookContext.args;
+        const finalScope = buildToolApprovalKey(toolName, finalArgs, authorizationCwd);
+        if (finalScope !== authorizedScope) {
+            const modifiedAuthorizationError = await this.authorizeToolAction(toolName, finalArgs, hookContext, hooksManager);
+            if (modifiedAuthorizationError)
+                return modifiedAuthorizationError;
+        }
+        try {
+            const command = finalArgs.command;
+            const timeout = finalArgs.timeout || 30000;
+            // A weaker model can emit a `bash` call without a `command` (or a
+            // non-string one). Fail with a clear, recoverable message instead of
+            // crashing downstream on `command.trim()` (auto-repair can then re-prompt).
+            let bashResult;
+            if (typeof command !== 'string' || command.trim() === '') {
+                bashResult = {
+                    success: false,
+                    error: 'bash: missing a non-empty "command" string argument. Put the shell command to run in the "command" field.',
+                };
+            }
+            else {
+                try {
+                    await this.deps.hooksManager.executeHooks('pre-bash', { command });
+                }
+                catch (hookError) {
+                    logger.warn('Pre-bash hook failed, continuing with execution', {
+                        error: getErrorMessage(hookError),
+                    });
+                }
+                const directoryChange = this.changeSessionDirectory(command, this.currentWorkingDirectory ?? process.cwd());
+                if (directoryChange) {
+                    bashResult = directoryChange;
+                }
+                else {
+                    // Session cwd override — the streaming path is what embedded hosts
+                    // (Cowork) actually exercise; without it, streamed bash ran in the
+                    // Electron process cwd regardless of the session workingDirectory.
+                    const gen = this.bash.executeStreaming(command, timeout, this.currentWorkingDirectory, abortSignalFromExecutionExtra(executionExtra));
+                    let streamed = await gen.next();
+                    while (!streamed.done) {
+                        yield streamed.value;
+                        streamed = await gen.next();
+                    }
+                    bashResult = streamed.value ?? { success: false, error: 'Tool returned no result' };
+                }
+                try {
+                    await this.deps.hooksManager.executeHooks('post-bash', {
+                        command,
+                        output: bashResult.output,
+                        error: bashResult.error,
+                    });
+                }
+                catch (hookError) {
+                    logger.warn('Post-bash hook failed', { error: getErrorMessage(hookError) });
+                }
+            }
+            const hookResult = {
+                success: bashResult.success,
+                output: bashResult.output,
+                error: bashResult.error,
+                executionTimeMs: Date.now() - startTime,
+            };
+            const finalHookResult = await hooksManager.executeAfterHooks(hookContext, hookResult);
+            await this.deps.hooksManager.executeHooks('after-tool-call', {
+                toolName,
+                toolArgs: finalArgs,
+                output: finalHookResult.output,
+                error: finalHookResult.error,
+                sessionId: this.currentRunId,
+            });
+            if (!finalHookResult.success && finalHookResult.error) {
+                await hooksManager.executeErrorHooks(hookContext, new Error(finalHookResult.error));
+                try {
+                    await this.deps.hooksManager.executeHooks('on-tool-failure', {
+                        toolName,
+                        error: finalHookResult.error,
+                    });
+                }
+                catch { /* hook failure non-fatal */ }
+            }
+            if (this.currentRunId) {
+                RunStore.getInstance().emit(this.currentRunId, {
+                    type: 'tool_result',
+                    data: {
+                        toolName,
+                        toolCallId: toolCall.id,
+                        success: finalHookResult.success,
+                        outputLength: finalHookResult.output?.length || 0,
+                        error: finalHookResult.error,
+                        durationMs: Date.now() - startTime,
+                    },
+                });
+            }
+            return {
+                success: finalHookResult.success,
+                output: finalHookResult.output,
+                error: finalHookResult.error,
+                ...(bashResult.data !== undefined ? { data: bashResult.data } : {}),
+            };
+        }
+        catch (error) {
+            return { success: false, error: `Streaming execution error: ${getErrorMessage(error)}` };
+        }
+    }
     /**
      * Execute a tool with streaming output.
      * Currently only supports bash. Falls back to executeTool for other tools.
      * Yields string deltas for real-time output.
      */
-    async *executeToolStreaming(toolCall) {
+    async *executeToolStreaming(toolCall, executionExtra) {
         const startTime = Date.now();
         const toolName = toolCall.function.name;
         const filterBlock = this.checkActiveToolFilter(toolName, toolCall.id, startTime);
         if (filterBlock) {
             return filterBlock;
         }
-        // Bash: stream stdout/stderr in real-time
+        // Bash: stream stdout/stderr in real-time. Authorization, lifecycle
+        // hooks and RunStore tracing must still match executeTool — this path
+        // exists only to yield chunks, not to skip the guarded dispatch.
         if (toolName === 'bash') {
-            try {
-                const args = JSON.parse(toolCall.function.arguments);
-                const command = args.command;
-                const timeout = args.timeout || 30000;
-                // A weaker model can emit a `bash` call without a `command` (or a
-                // non-string one). Fail with a clear, recoverable message instead of
-                // crashing downstream on `command.trim()` (auto-repair can then re-prompt).
-                if (typeof command !== 'string' || command.trim() === '') {
-                    return {
-                        success: false,
-                        error: 'bash: missing a non-empty "command" string argument. Put the shell command to run in the "command" field.',
-                    };
-                }
-                const gen = this.bash.executeStreaming(command, timeout);
-                let result = await gen.next();
-                while (!result.done) {
-                    yield result.value;
-                    result = await gen.next();
-                }
-                return result.value;
-            }
-            catch (error) {
-                return { success: false, error: `Streaming execution error: ${getErrorMessage(error)}` };
-            }
+            return yield* this.executeStreamingBash(toolCall, executionExtra, startTime);
         }
         // Reason: stream MCTS progress events in real-time
         if (toolName === 'reason') {
             try {
                 const args = JSON.parse(toolCall.function.arguments);
+                const authorizationError = await this.authorizeToolAction(toolName, args, {
+                    toolName,
+                    originalArgs: { ...args },
+                    args,
+                    toolCallId: toolCall.id,
+                    timestamp: startTime,
+                }, getToolHooksManager());
+                if (authorizationError)
+                    return authorizationError;
                 const { getTreeOfThoughtReasoner } = await import('./reasoning/index.js');
                 const apiKey = process.env.GROK_API_KEY || process.env.XAI_API_KEY || '';
                 const baseURL = process.env.GROK_BASE_URL;
@@ -915,13 +1453,32 @@ export class ToolHandler {
         if (toolName === 'generate_document') {
             try {
                 const args = JSON.parse(toolCall.function.arguments);
+                const authorizationError = await this.authorizeToolAction(toolName, args, {
+                    toolName,
+                    originalArgs: { ...args },
+                    args,
+                    toolCallId: toolCall.id,
+                    timestamp: startTime,
+                }, getToolHooksManager());
+                if (authorizationError)
+                    return authorizationError;
                 const { executeGenerateDocumentStreaming } = await import('../tools/document-generator.js');
+                const outputPath = args.outputPath ?? args.output_path;
+                if (typeof args.type !== 'string' ||
+                    typeof args.title !== 'string' ||
+                    typeof args.content !== 'string' ||
+                    typeof outputPath !== 'string') {
+                    return {
+                        success: false,
+                        error: 'generate_document requires string type, title, content, and outputPath arguments.',
+                    };
+                }
                 const gen = executeGenerateDocumentStreaming({
                     type: args.type,
                     title: args.title,
                     content: args.content,
-                    outputPath: args.outputPath ?? args.output_path,
-                    theme: args.theme,
+                    outputPath,
+                    theme: typeof args.theme === 'string' ? args.theme : undefined,
                 });
                 let r = await gen.next();
                 while (!r.done) {
@@ -935,7 +1492,7 @@ export class ToolHandler {
             }
         }
         // Fallback: non-streaming execution
-        return await this.executeTool(toolCall);
+        return await this.executeTool(toolCall, executionExtra);
     }
     async executeMCPTool(toolCall) {
         try {