@windagency/valora 2.0.1

package/dist/executor/tool-execution.service.js

@@ -0,0 +1,1124 @@
+/**
+ * Tool Execution Service
+ *
+ * Defines and executes file manipulation tools for LLM-driven code generation.
+ * These tools allow the LLM to actually create, modify, and delete files.
+ *
+ * Tools supported:
+ * - write: Create or overwrite files
+ * - read_file: Read file contents
+ * - search_replace: Make targeted edits to files
+ * - delete_file: Remove files
+ * - run_terminal_cmd: Execute shell commands
+ * - list_dir: List directory contents
+ * - glob_file_search: Find files by pattern
+ * - grep: Search file contents
+ * - codebase_search: Semantic code search
+ * - query_session: Query previous session data for context reuse
+ */
+import { exec } from 'child_process';
+import { DEFAULT_TIMEOUT_MS } from '../config/constants.js';
+import { existsSync, readdirSync, rmSync, statSync } from 'fs';
+import { getColorAdapter } from '../output/color-adapter.interface.js';
+import { getConsoleOutput } from '../output/console-output.js';
+import { getLogger } from '../output/logger.js';
+import { getIdempotencyStore } from '../services/idempotency-store.service.js';
+import { isMCPTool } from '../types/command.types.js';
+import { isIdempotentTool } from '../types/idempotency.types.js';
+import { getServerIdFromTool } from '../types/mcp-registry.types.js';
+import { SemanticAttributes, SpanKind } from '../types/tracing.types.js';
+import { getPromptAdapter } from '../ui/prompt-adapter.interface.js';
+import { promisify } from 'util';
+import { formatErrorMessage } from '../utils/error-utils.js';
+import { readFile, writeFile } from '../utils/file-utils.js';
+import { validateNotForbiddenPath } from '../utils/input-validator.js';
+import { getTracer } from '../utils/tracing.js';
+import { getHookExecutionService } from './hook-execution.service.js';
+import { getDryRunSimulator } from './tools/dry-run-simulator.service.js';
+import { PendingWriteApproverService } from './tools/pending-write-approver.service.js';
+import { getSearchToolsService } from './tools/search-tools.service.js';
+import { getSessionToolsService } from './tools/session-tools.service.js';
+const execAsync = promisify(exec);
+/**
+ * Tool definitions for the LLM (built-in tools only)
+ * These are passed to the LLM so it knows what tools are available.
+ * MCP tool definitions are generated dynamically based on connected MCP servers.
+ */
+const BUILT_IN_TOOL_DEFINITIONS = {
+    codebase_search: {
+        description: 'Semantic search across the codebase to find relevant code snippets',
+        name: 'codebase_search',
+        parameters: {
+            properties: {
+                query: {
+                    description: 'Natural language search query',
+                    type: 'string'
+                }
+            },
+            required: ['query'],
+            type: 'object'
+        }
+    },
+    delete_file: {
+        description: 'Delete a file from the filesystem',
+        name: 'delete_file',
+        parameters: {
+            properties: {
+                path: {
+                    description: 'Path to the file to delete',
+                    type: 'string'
+                }
+            },
+            required: ['path'],
+            type: 'object'
+        }
+    },
+    glob_file_search: {
+        description: `Find files matching a glob pattern.
+
+⚠️ RECOMMENDED: Use run_terminal_cmd with 'fd' for better performance.
+
+This tool uses basic glob matching.
+
+PREFERRED: Use run_terminal_cmd with modern 'fd' tool for:
+  • 5-10x faster file discovery
+  • .gitignore awareness (skips node_modules, .git, build/)
+  • Better pattern matching
+
+Examples:
+  ✅ run_terminal_cmd("fd -e ts src/")  # Find all .ts files in src/
+  ✅ run_terminal_cmd("fd -e tsx -e jsx .")  # Multiple extensions
+  ✅ run_terminal_cmd("fd --type f 'test' .")  # Files containing 'test'
+  ✅ run_terminal_cmd("fd --glob '**/*.config.js'")  # Glob pattern
+
+This tool (glob_file_search) is acceptable for simple patterns, but fd is faster and more powerful.`,
+        name: 'glob_file_search',
+        parameters: {
+            properties: {
+                pattern: {
+                    description: 'Glob pattern (e.g., "**/*.ts", "src/**/*.tsx")',
+                    type: 'string'
+                }
+            },
+            required: ['pattern'],
+            type: 'object'
+        }
+    },
+    grep: {
+        description: `⚠️ DEPRECATED: Use run_terminal_cmd with 'rg' (ripgrep) instead.
+
+This tool uses legacy grep which:
+  ❌ Searches node_modules, .git, and other ignored directories (wastes tokens)
+  ❌ Produces verbose, unstructured output
+  ❌ Lacks .gitignore awareness
+  ❌ Slower on large codebases
+
+PREFERRED: Use run_terminal_cmd with modern 'rg' (ripgrep) tool:
+
+Examples:
+  ✅ run_terminal_cmd("rg 'pattern' src/")  # Fast, .gitignore-aware
+  ✅ run_terminal_cmd("rg -A 5 'pattern' file.ts")  # With 5 lines of context
+  ✅ run_terminal_cmd("rg --json 'pattern' .")  # Structured output for parsing
+  ✅ run_terminal_cmd("rg -l 'pattern' .")  # List matching files only
+
+Benefits of rg over grep:
+  • 5-10x faster
+  • Respects .gitignore by default (skips node_modules, .git, build artifacts)
+  • Structured JSON output available (--json flag)
+  • Better regex engine
+  • Saves 60-80% tokens by excluding irrelevant files
+
+Only use this legacy grep tool if:
+  • You need to search in .gitignore'd directories
+  • rg is not available (rare)`,
+        name: 'grep',
+        parameters: {
+            properties: {
+                path: {
+                    description: 'Directory or file to search in',
+                    type: 'string'
+                },
+                pattern: {
+                    description: 'Regex pattern to search for',
+                    type: 'string'
+                }
+            },
+            required: ['pattern'],
+            type: 'object'
+        }
+    },
+    list_dir: {
+        description: 'List contents of a directory',
+        name: 'list_dir',
+        parameters: {
+            properties: {
+                path: {
+                    description: 'Path to the directory to list',
+                    type: 'string'
+                }
+            },
+            required: ['path'],
+            type: 'object'
+        }
+    },
+    query_session: {
+        description: 'Query previous session data to find relevant context, decisions, or outputs. ' +
+            'Use this to avoid re-running analysis or to understand prior work. ' +
+            'Can list sessions, search across sessions, or get specific session details.',
+        name: 'query_session',
+        parameters: {
+            properties: {
+                action: {
+                    description: 'Action to perform: "list" (show recent sessions), "search" (find content across sessions), "get" (get session details)',
+                    type: 'string'
+                },
+                query: {
+                    description: 'Search query for "search" action - finds matching content in session outputs',
+                    type: 'string'
+                },
+                session_id: {
+                    description: 'Session ID for "get" action - retrieves specific session details',
+                    type: 'string'
+                }
+            },
+            required: ['action'],
+            type: 'object'
+        }
+    },
+    read_file: {
+        description: `Read SMALL files only (max 100 lines).
+
+⚠️ CRITICAL RESTRICTIONS:
+
+NEVER use this tool for files >100 lines - this wastes 80-90% of your context window.
+NEVER use this tool for JSON/YAML/TOML/XML files - use jq/yq via run_terminal_cmd instead.
+
+DO NOT USE for these files (use run_terminal_cmd with rg instead):
+  ❌ PRD.md, BACKLOG.md, FUNCTIONAL.md (150-500 lines)
+  ❌ package.json, tsconfig.json (use jq)
+  ❌ docker-compose.yml, *.yaml (use yq)
+
+CORRECT usage examples:
+  ✅ read_file("README.md") - if < 100 lines
+  ✅ read_file("CONTRIBUTING.md") - if < 100 lines
+
+INCORRECT usage (use run_terminal_cmd instead):
+  ❌ read_file("knowledge-base/PRD.md") → use: run_terminal_cmd("rg '^## ' knowledge-base/PRD.md")
+  ❌ read_file("package.json") → use: run_terminal_cmd("jq '.dependencies' package.json")
+  ❌ read_file("knowledge-base/BACKLOG.md") → use: run_terminal_cmd("rg -A 5 'TASK-ID' knowledge-base/BACKLOG.md")
+
+Violating these restrictions wastes tokens and degrades performance.`,
+        name: 'read_file',
+        parameters: {
+            properties: {
+                path: {
+                    description: 'Path to the file to read',
+                    type: 'string'
+                }
+            },
+            required: ['path'],
+            type: 'object'
+        }
+    },
+    run_terminal_cmd: {
+        description: 'Execute a shell command and return the output',
+        name: 'run_terminal_cmd',
+        parameters: {
+            properties: {
+                command: {
+                    description: 'The shell command to execute',
+                    type: 'string'
+                },
+                timeout_ms: {
+                    description: 'Timeout in milliseconds (default: 30000)',
+                    type: 'number'
+                }
+            },
+            required: ['command'],
+            type: 'object'
+        }
+    },
+    search_replace: {
+        description: 'Make targeted edits to a file by replacing specific text',
+        name: 'search_replace',
+        parameters: {
+            properties: {
+                new_str: {
+                    description: 'The text to replace it with',
+                    type: 'string'
+                },
+                old_str: {
+                    description: 'The exact text to search for and replace',
+                    type: 'string'
+                },
+                path: {
+                    description: 'Path to the file to edit',
+                    type: 'string'
+                }
+            },
+            required: ['path', 'old_str', 'new_str'],
+            type: 'object'
+        }
+    },
+    web_search: {
+        description: 'Search the web for information',
+        name: 'web_search',
+        parameters: {
+            properties: {
+                query: {
+                    description: 'Search query',
+                    type: 'string'
+                }
+            },
+            required: ['query'],
+            type: 'object'
+        }
+    },
+    write: {
+        description: 'Create a new file or overwrite an existing file with the specified content',
+        name: 'write',
+        parameters: {
+            properties: {
+                content: {
+                    description: 'The content to write to the file',
+                    type: 'string'
+                },
+                path: {
+                    description: 'Path where the file should be created',
+                    type: 'string'
+                }
+            },
+            required: ['path', 'content'],
+            type: 'object'
+        }
+    }
+};
+export class ToolExecutionService {
+    hookExecutionService = getHookExecutionService();
+    idempotencyStore;
+    logger = getLogger();
+    mcpClientManager = null;
+    mcpToolHandler = null;
+    searchToolsService;
+    sessionToolsService;
+    tracer = getTracer();
+    workingDir;
+    /**
+     * Session ID for scoping idempotency keys
+     * When set, idempotency is scoped to the current session
+     */
+    sessionId;
+    /**
+     * Trace context for distributed tracing
+     * When set, tool execution spans are linked to the parent trace
+     */
+    traceContext;
+    /**
+     * Idempotency options for tool execution
+     */
+    idempotencyOptions = {};
+    /**
+     * Tracks files that have been read in this session.
+     * Used to allow writes to protected files only if they were read first,
+     * preventing blind overwrites while still allowing intentional updates.
+     */
+    readFiles = new Set();
+    /**
+     * Dry-run mode flag
+     * When enabled, state-changing tools are simulated instead of executed
+     */
+    dryRunMode = false;
+    /**
+     * Dry-run simulator instance (lazy-initialized)
+     */
+    dryRunSimulator = null;
+    constructor(workingDir = process.cwd()) {
+        this.workingDir = workingDir;
+        this.idempotencyStore = getIdempotencyStore();
+        this.searchToolsService = getSearchToolsService(workingDir);
+        this.sessionToolsService = getSessionToolsService(workingDir);
+    }
+    /**
+     * Set the trace context for distributed tracing
+     * Tool execution spans will be children of this context
+     */
+    setTraceContext(context) {
+        this.traceContext = context;
+    }
+    /**
+     * Get the current trace context
+     */
+    getTraceContext() {
+        return this.traceContext;
+    }
+    /**
+     * Set the session ID for idempotency scoping
+     * This should be called at the start of a command execution
+     */
+    setSessionId(sessionId) {
+        this.sessionId = sessionId;
+        this.idempotencyOptions.session_id = sessionId;
+        this.hookExecutionService.setSessionId(sessionId);
+    }
+    /**
+     * Configure idempotency options
+     */
+    setIdempotencyOptions(options) {
+        this.idempotencyOptions = { ...this.idempotencyOptions, ...options };
+    }
+    /**
+     * Set the MCP tool handler for executing MCP tools
+     */
+    setMCPToolHandler(handler) {
+        this.mcpToolHandler = handler;
+    }
+    /**
+     * Set the MCP client manager for generating MCP tool definitions
+     */
+    setMCPClientManager(clientManager) {
+        this.mcpClientManager = clientManager;
+    }
+    /**
+     * Disable idempotency for the current execution
+     * Useful when you want to force re-execution of all tools
+     */
+    disableIdempotency() {
+        this.idempotencyOptions.force_execute = true;
+    }
+    /**
+     * Enable idempotency for the current execution
+     */
+    enableIdempotency() {
+        this.idempotencyOptions.force_execute = false;
+    }
+    /**
+     * Enable or disable dry-run mode
+     * In dry-run mode, state-changing tools are simulated instead of executed
+     */
+    setDryRunMode(enabled) {
+        this.dryRunMode = enabled;
+        if (enabled && !this.dryRunSimulator) {
+            this.dryRunSimulator = getDryRunSimulator(this.workingDir);
+        }
+        this.logger.debug(`Dry-run mode ${enabled ? 'enabled' : 'disabled'}`);
+    }
+    /**
+     * Check if dry-run mode is enabled
+     */
+    isDryRunMode() {
+        return this.dryRunMode;
+    }
+    /**
+     * Get simulated operations from dry-run mode
+     */
+    getSimulatedOperations() {
+        if (!this.dryRunSimulator) {
+            return [];
+        }
+        return this.dryRunSimulator.getSimulatedOperations();
+    }
+    /**
+     * Clear simulated operations
+     */
+    clearSimulatedOperations() {
+        if (this.dryRunSimulator) {
+            this.dryRunSimulator.clear();
+        }
+    }
+    /**
+     * Get tool definitions for the specified allowed tools
+     * Built-in tools are returned from static definitions.
+     * MCP tools are generated as gateway tools that route to external MCP servers.
+     */
+    getToolDefinitions(allowedTools) {
+        const definitions = [];
+        for (const tool of allowedTools) {
+            if (isMCPTool(tool)) {
+                // Generate MCP gateway tool definition
+                const mcpDefinition = this.generateMCPToolDefinition(tool);
+                if (mcpDefinition) {
+                    definitions.push(mcpDefinition);
+                }
+                continue;
+            }
+            const definition = BUILT_IN_TOOL_DEFINITIONS[tool];
+            if (definition) {
+                definitions.push(definition);
+            }
+        }
+        return definitions;
+    }
+    /**
+     * Build the description for an MCP tool definition
+     */
+    buildMCPToolDescription(serverId, serverDescription, availableToolNames, capabilities) {
+        let description = `Call tools on the ${serverId} MCP server. ${serverDescription}`;
+        if (availableToolNames.length > 0) {
+            description += `\n\nAvailable tools: ${availableToolNames.join(', ')}`;
+        }
+        else {
+            description += '\n\nThe server will be connected on first use, and available tools will be discovered.';
+        }
+        if (capabilities) {
+            description += `\n\nCapabilities: ${capabilities.join(', ')}`;
+        }
+        return description;
+    }
+    /**
+     * Get the tool_name parameter description based on available tools
+     */
+    getToolNameDescription(availableToolNames) {
+        return availableToolNames.length > 0
+            ? `The name of the tool to call. Available: ${availableToolNames.join(', ')}`
+            : 'The name of the tool to call on this MCP server';
+    }
+    /**
+     * Generate a gateway tool definition for an MCP tool
+     * This creates a tool that accepts tool_name and arguments parameters,
+     * allowing the LLM to call any tool on the connected MCP server.
+     */
+    generateMCPToolDefinition(mcpTool) {
+        const serverId = getServerIdFromTool(mcpTool);
+        if (!serverId) {
+            this.logger.warn(`Invalid MCP tool name: ${mcpTool}`);
+            return null;
+        }
+        // Get server info if connected
+        const connectedServer = this.mcpClientManager?.getConnectedServer(serverId);
+        const serverDescription = connectedServer?.config.description ?? `External MCP server: ${serverId}`;
+        const availableToolNames = connectedServer?.availableTools.map((t) => t.name) ?? [];
+        const capabilities = connectedServer?.config.security.capabilities;
+        const description = this.buildMCPToolDescription(serverId, serverDescription, availableToolNames, capabilities);
+        return {
+            description,
+            name: mcpTool,
+            parameters: {
+                additionalProperties: false,
+                properties: {
+                    arguments: {
+                        additionalProperties: true,
+                        description: 'Arguments to pass to the tool (varies by tool)',
+                        type: 'object'
+                    },
+                    tool_name: {
+                        description: this.getToolNameDescription(availableToolNames),
+                        type: 'string'
+                    }
+                },
+                required: ['tool_name'],
+                type: 'object'
+            }
+        };
+    }
+    /**
+     * Reset state for a new command execution
+     * Clears pending writes and resets confirmation state
+     * Should be called at the start of each command execution
+     */
+    resetForNewCommand() {
+        this.pendingWrites = [];
+        this.readFiles.clear();
+        // Reset idempotency options but keep session_id
+        this.idempotencyOptions = { session_id: this.sessionId };
+        // Reset dry-run state
+        this.dryRunMode = false;
+        this.clearSimulatedOperations();
+    }
+    /**
+     * Invalidate all idempotency records for the current session
+     * Call this when session state changes significantly
+     */
+    async invalidateSessionIdempotency() {
+        if (this.sessionId) {
+            return this.idempotencyStore.invalidateSession(this.sessionId);
+        }
+        return 0;
+    }
+    /**
+     * Invalidate idempotency records for a specific tool
+     * Useful when external changes affect tool results
+     */
+    invalidateToolIdempotency(toolName) {
+        return this.idempotencyStore.invalidateTool(toolName);
+    }
+    /**
+     * Get idempotency store statistics
+     */
+    getIdempotencyStats() {
+        return this.idempotencyStore.getStats();
+    }
+    /**
+     * Execute a tool call and return the result
+     *
+     * For idempotent tools (write, search_replace, delete_file, run_terminal_cmd),
+     * checks the idempotency store first and returns cached result if available.
+     * This prevents duplicate operations when the same tool call is retried.
+     *
+     * In dry-run mode, state-changing tools are simulated instead of executed.
+     * Read-only tools execute normally even in dry-run mode.
+     */
+    async executeTool(toolCall) {
+        const { name } = toolCall;
+        // Handle dry-run mode for non-read-only tools
+        if (this.dryRunMode && this.dryRunSimulator && !this.dryRunSimulator.isReadOnlyTool(name)) {
+            this.logger.debug(`Simulating tool in dry-run mode: ${name}`);
+            const simulated = await this.dryRunSimulator.simulateTool(toolCall);
+            return simulated.result;
+        }
+        // === PreToolUse hooks (before span, can block/modify) ===
+        if (this.hookExecutionService.hasHooks('PreToolUse')) {
+            const hookResult = await this.hookExecutionService.executePreToolUseHooks(toolCall);
+            if (!hookResult.allowed) {
+                this.logger.info(`Tool blocked by PreToolUse hook: ${name}`, {
+                    reason: hookResult.blockReason
+                });
+                return {
+                    output: `Tool call blocked by hook: ${hookResult.blockReason ?? 'No reason provided'}`,
+                    tool_call_id: toolCall.id
+                };
+            }
+            if (hookResult.updatedArgs) {
+                toolCall = { ...toolCall, arguments: { ...toolCall.arguments, ...hookResult.updatedArgs } };
+            }
+        }
+        // Start a span for this tool execution
+        const span = this.tracer.startSpan(`tool.${name}`, {
+            attributes: {
+                [SemanticAttributes.SESSION_ID]: this.sessionId,
+                [SemanticAttributes.TOOL_NAME]: name
+            },
+            kind: SpanKind.INTERNAL,
+            parent: this.traceContext
+        });
+        try {
+            return await this.executeToolWithSpan(toolCall, span);
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Internal method to execute a tool with span tracking
+     */
+    async executeToolWithSpan(toolCall, span) {
+        const { arguments: args, id, name } = toolCall;
+        const argSummary = this.getToolArgSummary(name, args);
+        const color = getColorAdapter();
+        // Check idempotency for state-changing tools
+        if (isIdempotentTool(name)) {
+            const checkResult = await this.idempotencyStore.check(toolCall, this.idempotencyOptions);
+            if (checkResult.found && checkResult.record) {
+                span.setAttribute(SemanticAttributes.TOOL_CACHE_HIT, true);
+                span.setAttribute(SemanticAttributes.TOOL_IDEMPOTENCY_KEY, checkResult.key);
+                span.addEvent('idempotency_cache_hit');
+                span.setOk();
+                this.logger.info(`Idempotency cache hit: ${name}${argSummary ? ` ${color.dim(`(${argSummary})`)}` : ''}`, {
+                    idempotency_key: checkResult.key
+                });
+                return {
+                    output: checkResult.record.result.output,
+                    tool_call_id: id
+                };
+            }
+        }
+        span.setAttribute(SemanticAttributes.TOOL_CACHE_HIT, false);
+        span.addEvent('tool_execution_start');
+        this.logger.info(`Executing tool: ${name}${argSummary ? ` ${color.dim(`(${argSummary})`)}` : ''}`, { args });
+        try {
+            const output = await this.executeToolByName(name, args);
+            span.setAttribute(SemanticAttributes.TOOL_RESULT_SIZE, output.length);
+            span.setAttribute(SemanticAttributes.TOOL_SUCCESS, true);
+            span.addEvent('tool_execution_complete');
+            span.setOk();
+            this.logger.debug(`Tool ${name} completed successfully`, {
+                outputLength: output.length
+            });
+            // Store result for idempotent tools
+            if (isIdempotentTool(name)) {
+                await this.idempotencyStore.store(toolCall, { output, success: true }, this.idempotencyOptions);
+            }
+            // === PostToolUse hooks (after execution, non-blocking) ===
+            if (this.hookExecutionService.hasHooks('PostToolUse')) {
+                // Fire-and-forget: do not await, do not block
+                this.hookExecutionService.executePostToolUseHooks(toolCall, output).catch((err) => {
+                    this.logger.warn('PostToolUse hook error', { error: formatErrorMessage(err) });
+                });
+            }
+            return {
+                output,
+                tool_call_id: id
+            };
+        }
+        catch (error) {
+            const errorMessage = formatErrorMessage(error);
+            span.setAttribute(SemanticAttributes.TOOL_SUCCESS, false);
+            span.recordException(error);
+            this.logger.error(`Tool ${name} failed`, error);
+            // Store failed result for idempotent tools (prevents retrying failed operations)
+            if (isIdempotentTool(name)) {
+                await this.idempotencyStore.store(toolCall, { error: errorMessage, output: `Error: ${errorMessage}`, success: false }, this.idempotencyOptions);
+            }
+            return {
+                output: `Error: ${errorMessage}`,
+                tool_call_id: id
+            };
+        }
+    }
+    /**
+     * Execute multiple tool calls in parallel
+     */
+    async executeTools(toolCalls) {
+        if (toolCalls.length === 0) {
+            return [];
+        }
+        // Create a parent span for batch execution
+        const span = this.tracer.startSpan('tool.batch_execute', {
+            attributes: {
+                [SemanticAttributes.SESSION_ID]: this.sessionId,
+                'tool.batch_size': toolCalls.length,
+                'tool.names': toolCalls.map((c) => c.name).join(',')
+            },
+            kind: SpanKind.INTERNAL,
+            parent: this.traceContext
+        });
+        try {
+            const results = await Promise.all(toolCalls.map((call) => this.executeTool(call)));
+            span.setAttribute('tool.success_count', results.filter((r) => !r.output.startsWith('Error:')).length);
+            span.setOk();
+            return results;
+        }
+        catch (error) {
+            span.recordException(error);
+            throw error;
+        }
+        finally {
+            span.end();
+        }
+    }
+    /**
+     * Route tool execution to the appropriate handler
+     */
+    async executeToolByName(name, args) {
+        // Check if this is an MCP tool (handled separately in Phase 2)
+        if (isMCPTool(name)) {
+            return this.executeMcpTool(name, args);
+        }
+        // Built-in tool handlers
+        const toolHandlers = {
+            ['codebase_search']: (a) => this.searchToolsService.executeCodebaseSearch(a),
+            ['delete_file']: (a) => this.executeDeleteFile(a),
+            ['glob_file_search']: (a) => this.searchToolsService.executeGlobSearch(a),
+            ['grep']: (a) => this.searchToolsService.executeGrep(a),
+            ['list_dir']: (a) => this.executeListDir(a),
+            ['query_session']: (a) => this.sessionToolsService.executeQuerySession(a),
+            ['read_file']: (a) => this.executeReadFile(a),
+            ['run_terminal_cmd']: (a) => this.executeTerminalCmd(a),
+            ['search_replace']: (a) => this.executeSearchReplace(a),
+            ['web_search']: (a) => this.executeWebSearch(a),
+            ['write']: (a) => this.executeWrite(a)
+        };
+        const handler = toolHandlers[name];
+        if (!handler) {
+            throw new Error(`Unknown tool: ${name}`);
+        }
+        return handler(args);
+    }
+    /**
+     * Execute an MCP tool call
+     * Routes the call to MCPToolHandler for connection management and execution
+     */
+    async executeMcpTool(mcpToolName, args) {
+        // Check if MCP handler is available
+        if (!this.mcpToolHandler) {
+            this.logger.warn('MCP tool handler not configured', { mcpToolName });
+            return JSON.stringify({
+                error: 'MCP tool handler not configured. MCP tools are not available.',
+                status: 'not_configured'
+            });
+        }
+        // Extract the actual tool name from args (e.g., playwright_navigate)
+        // The mcpToolName is the MCP identifier (e.g., mcp_playwright)
+        // The actual tool to call should be in args.tool_name or we use the full name
+        const actualToolName = args['tool_name'] ?? mcpToolName;
+        const toolArgs = args['arguments'] ?? args;
+        try {
+            const result = await this.mcpToolHandler.executeTool(mcpToolName, actualToolName, toolArgs);
+            if (result.success) {
+                return JSON.stringify({
+                    duration_ms: result.durationMs,
+                    output: result.output,
+                    server: result.serverId,
+                    status: 'success',
+                    tool: result.toolName
+                });
+            }
+            else {
+                return JSON.stringify({
+                    duration_ms: result.durationMs,
+                    error: result.error,
+                    server: result.serverId,
+                    status: 'error',
+                    tool: result.toolName
+                });
+            }
+        }
+        catch (error) {
+            const errorMessage = error.message;
+            this.logger.error(`MCP tool execution failed: ${mcpToolName}`, error);
+            return JSON.stringify({
+                error: errorMessage,
+                status: 'error',
+                tool: mcpToolName
+            });
+        }
+    }
+    /**
+     * Paths that require confirmation before writing
+     * These are typically documentation/knowledge-base paths where user review is important
+     */
+    static CONFIRM_WRITE_PATHS = ['knowledge-base/', 'docs/'];
+    /**
+     * Pending writes that require confirmation
+     * These are queued during pipeline execution and processed at the end
+     */
+    pendingWrites = [];
+    /**
+     * Write content to a file
+     */
+    async executeWrite(args) {
+        const path = args['path'];
+        const content = args['content'];
+        if (!path || content === undefined) {
+            throw new Error('write requires path and content arguments');
+        }
+        const fullPath = this.validateAndResolvePath(path, 'write to');
+        // Check if this is a protected file that already exists
+        const fileName = path.split('/').pop() ?? path;
+        const isProtectedFile = ToolExecutionService.PROTECTED_FILES.some((protectedFile) => fileName === protectedFile || path.endsWith(`/${protectedFile}`));
+        // Allow writes to protected files only if they were read first
+        // This prevents blind overwrites while allowing intentional updates
+        if (isProtectedFile && existsSync(fullPath) && !this.readFiles.has(fullPath)) {
+            throw new Error(`Cannot overwrite existing protected file: ${path}. ` +
+                `This file already exists and is protected from accidental overwrite. ` +
+                `Use 'read_file' to see its current contents first, then you can overwrite it.`);
+        }
+        // Check if this path requires confirmation
+        const requiresConfirmation = ToolExecutionService.CONFIRM_WRITE_PATHS.some((confirmPath) => path.includes(confirmPath) || fullPath.includes(confirmPath));
+        if (requiresConfirmation) {
+            // Queue the write for confirmation at the end of pipeline
+            this.pendingWrites.push({ content, fullPath, path });
+            this.logger.info(`Queued file for confirmation: ${path}`, {
+                contentLength: content.length,
+                pendingCount: this.pendingWrites.length
+            });
+            return `File queued for writing: ${path} (will confirm at end of pipeline)`;
+        }
+        await writeFile(fullPath, content);
+        this.logger.info(`Created/updated file: ${fullPath}`, {
+            contentLength: content.length
+        });
+        return `Successfully wrote ${content.length} characters to ${path}`;
+    }
+    /**
+     * Check if there are pending writes that need confirmation
+     */
+    hasPendingWrites() {
+        return this.pendingWrites.length > 0;
+    }
+    /**
+     * Get the count of pending writes
+     */
+    getPendingWritesCount() {
+        return this.pendingWrites.length;
+    }
+    /**
+     * Process all pending writes with user confirmation
+     * Called at the end of pipeline execution
+     * Returns the number of files successfully written
+     */
+    async flushPendingWrites() {
+        if (this.pendingWrites.length === 0) {
+            return { skipped: 0, written: 0 };
+        }
+        const approver = new PendingWriteApproverService(getConsoleOutput(), getColorAdapter(), getPromptAdapter(), this.logger);
+        const result = await approver.flush(this.pendingWrites);
+        // Clear the pending writes
+        this.pendingWrites = [];
+        return result;
+    }
+    /**
+     * Maximum file size to read (1MB) - prevents reading extremely large files
+     * that could cause context overflow
+     */
+    static MAX_READ_FILE_SIZE = 1 * 1024 * 1024;
+    /**
+     * Paths that should not be read (contain sensitive or very large data)
+     */
+    static BLOCKED_READ_PATHS = ['.valora/sessions', 'node_modules', '.git/objects'];
+    /**
+     * Protected files that should not be overwritten if they already exist.
+     * The write tool will reject attempts to overwrite these files and suggest
+     * using search_replace instead.
+     */
+    static PROTECTED_FILES = [
+        '.gitignore',
+        '.gitattributes',
+        '.env',
+        '.env.local',
+        '.env.production',
+        '.env.development',
+        '.npmrc',
+        '.nvmrc',
+        '.editorconfig',
+        'package.json',
+        'package-lock.json',
+        'pnpm-lock.yaml',
+        'yarn.lock',
+        'bun.lockb',
+        'tsconfig.json'
+    ];
+    /**
+     * Read file contents
+     */
+    async executeReadFile(args) {
+        const path = args['path'];
+        if (!path) {
+            throw new Error('read_file requires path argument');
+        }
+        // Check if path is in a blocked directory using find for lookup
+        const blockedPath = ToolExecutionService.BLOCKED_READ_PATHS.find((blocked) => path.includes(blocked));
+        if (blockedPath) {
+            throw new Error(`Cannot read files in ${blockedPath} - these files may be very large or contain session data`);
+        }
+        const fullPath = this.resolvePath(path);
+        if (!existsSync(fullPath)) {
+            throw new Error(`File not found: ${path}`);
+        }
+        // Check file size before reading
+        const stat = statSync(fullPath);
+        if (stat.size > ToolExecutionService.MAX_READ_FILE_SIZE) {
+            throw new Error(`File too large to read: ${path} (${Math.round(stat.size / 1024)}KB > ${Math.round(ToolExecutionService.MAX_READ_FILE_SIZE / 1024)}KB limit)`);
+        }
+        this.validateNotStructuredFile(path);
+        const content = await readFile(fullPath);
+        this.validateFileLineCount(path, content);
+        // Track that this file was read (enables writes to protected files)
+        this.readFiles.add(fullPath);
+        return content;
+    }
+    /**
+     * Enforce modern CLI tool usage: block structured files (JSON/YAML/TOML/XML).
+     */
+    validateNotStructuredFile(path) {
+        const structuredFileExtensions = ['.json', '.yaml', '.yml', '.toml', '.xml'];
+        const isStructuredFile = structuredFileExtensions.some((ext) => path.toLowerCase().endsWith(ext));
+        if (!isStructuredFile) {
+            return;
+        }
+        const tool = path.endsWith('.json') ? 'jq' : 'yq';
+        throw new Error(`Cannot use read_file for structured files: ${path}\n\n` +
+            `Structured files (JSON/YAML/TOML/XML) must be read with ${tool} via run_terminal_cmd.\n\n` +
+            `Use instead:\n` +
+            `  run_terminal_cmd("${tool} '.' ${path}")  # Read entire file\n` +
+            `  run_terminal_cmd("${tool} '.key' ${path}")  # Extract specific field\n\n` +
+            `This saves 85-95% of tokens compared to read_file.`);
+    }
+    /**
+     * Enforce modern CLI tool usage: block files with >100 lines.
+     */
+    validateFileLineCount(path, content) {
+        const lineCount = content.split('\n').length;
+        if (lineCount <= 100) {
+            return;
+        }
+        const fileName = path.split('/').pop() ?? path;
+        let suggestion = `run_terminal_cmd("rg '^## ' ${path}")  # Get markdown structure`;
+        if (fileName.includes('PRD') || fileName.includes('BACKLOG') || fileName.includes('FUNCTIONAL')) {
+            suggestion =
+                `run_terminal_cmd("rg '^## ' ${path}")  # Get document structure\n` +
+                    `  run_terminal_cmd("rg -A 50 '^## Functional Requirements' ${path}")  # Extract section`;
+        }
+        else if (fileName.endsWith('.ts') || fileName.endsWith('.tsx') || fileName.endsWith('.js')) {
+            suggestion = `run_terminal_cmd("rg -A 10 'class|function|export' ${path}")  # Extract key definitions`;
+        }
+        throw new Error(`File too large: ${path} (${lineCount} lines > 100 line limit)\n\n` +
+            `Files with >100 lines must be read with selective extraction via run_terminal_cmd.\n\n` +
+            `Use instead:\n  ${suggestion}\n\n` +
+            `This saves 80-90% of tokens compared to reading the entire file.`);
+    }
+    /**
+     * Search and replace in a file
+     */
+    async executeSearchReplace(args) {
+        const path = args['path'];
+        const oldStr = args['old_str'];
+        const newStr = args['new_str'];
+        if (!path || oldStr === undefined || newStr === undefined) {
+            throw new Error('search_replace requires path, old_str, and new_str arguments');
+        }
+        const fullPath = this.validateAndResolvePath(path, 'modify');
+        if (!existsSync(fullPath)) {
+            throw new Error(`File not found: ${path}`);
+        }
+        const content = await readFile(fullPath);
+        if (!content.includes(oldStr)) {
+            throw new Error(`Text not found in file: "${oldStr.substring(0, 50)}..."`);
+        }
+        const newContent = content.replace(oldStr, newStr);
+        await writeFile(fullPath, newContent);
+        this.logger.info(`Updated file: ${fullPath}`, {
+            newStrLength: newStr.length,
+            oldStrLength: oldStr.length
+        });
+        return `Successfully replaced text in ${path}`;
+    }
+    /**
+     * Delete a file
+     */
+    executeDeleteFile(args) {
+        const path = args['path'];
+        if (!path) {
+            return Promise.reject(new Error('delete_file requires path argument'));
+        }
+        try {
+            const fullPath = this.validateAndResolvePath(path, 'delete');
+            if (!existsSync(fullPath)) {
+                return Promise.reject(new Error(`File not found: ${path}`));
+            }
+            rmSync(fullPath);
+            this.logger.info(`Deleted file: ${fullPath}`);
+            return Promise.resolve(`Successfully deleted ${path}`);
+        }
+        catch (error) {
+            return Promise.reject(error);
+        }
+    }
+    /**
+     * Execute a terminal command
+     */
+    async executeTerminalCmd(args) {
+        const command = args['command'];
+        const timeoutMs = args['timeout_ms'] ?? DEFAULT_TIMEOUT_MS;
+        if (!command) {
+            throw new Error('run_terminal_cmd requires command argument');
+        }
+        this.logger.info(`Executing command: ${command}`);
+        try {
+            const { stderr, stdout } = await execAsync(command, {
+                cwd: this.workingDir,
+                timeout: timeoutMs
+            });
+            const output = stdout + (stderr ? `\nStderr: ${stderr}` : '');
+            return output || 'Command completed successfully (no output)';
+        }
+        catch (error) {
+            const execError = error;
+            const output = (execError.stdout ?? '') + (execError.stderr ?? '');
+            throw new Error(`Command failed: ${output || error.message}`);
+        }
+    }
+    /**
+     * List directory contents
+     */
+    executeListDir(args) {
+        const path = args['path'] ?? '.';
+        const fullPath = this.resolvePath(path);
+        if (!existsSync(fullPath)) {
+            return Promise.reject(new Error(`Directory not found: ${path}`));
+        }
+        const stat = statSync(fullPath);
+        if (!stat.isDirectory()) {
+            return Promise.reject(new Error(`Not a directory: ${path}`));
+        }
+        const entries = readdirSync(fullPath, { withFileTypes: true });
+        const formatted = entries.map((entry) => {
+            const prefix = entry.isDirectory() ? '[DIR]' : '[FILE]';
+            return `${prefix} ${entry.name}`;
+        });
+        return Promise.resolve(formatted.join('\n'));
+    }
+    /**
+     * Web search (placeholder - would integrate with actual web search)
+     */
+    executeWebSearch(args) {
+        const query = args['query'];
+        if (!query) {
+            throw new Error('web_search requires query argument');
+        }
+        return Promise.resolve(`Web search not implemented. Query: ${query}`);
+    }
+    /**
+     * Resolve a path relative to the working directory
+     */
+    resolvePath(path) {
+        if (path.startsWith('/')) {
+            return path;
+        }
+        return `${this.workingDir}/${path}`;
+    }
+    /**
+     * Validate and resolve a path for write operations.
+     * Validates both the original path and the resolved full path against forbidden paths.
+     *
+     * @param path - The path to validate and resolve
+     * @param operation - The operation being attempted (e.g., "write to", "delete", "modify")
+     * @returns The resolved full path
+     * @throws Error if the path is in a forbidden location
+     */
+    validateAndResolvePath(path, operation) {
+        // Validate the original path
+        validateNotForbiddenPath(path, operation);
+        const fullPath = this.resolvePath(path);
+        // Also validate the resolved path (catches absolute path manipulation)
+        validateNotForbiddenPath(fullPath, operation);
+        return fullPath;
+    }
+    /**
+     * Get a summary of tool arguments for logging
+     * Returns the primary argument value that identifies what the tool is operating on
+     */
+    getToolArgSummary(toolName, args) {
+        // Map of tool names to their primary argument keys
+        const primaryArgKeys = {
+            codebase_search: ['query'],
+            delete_file: ['path'],
+            glob_file_search: ['pattern'],
+            grep: ['pattern', 'path'],
+            list_dir: ['path'],
+            mcp_tool_call: ['tool_name'],
+            query_session: ['action', 'query', 'session_id'],
+            read_file: ['path'],
+            run_terminal_cmd: ['command'],
+            search_replace: ['path'],
+            web_search: ['query'],
+            write: ['path']
+        };
+        const keys = primaryArgKeys[toolName];
+        if (!keys) {
+            return '';
+        }
+        const values = keys
+            .map((key) => {
+            const value = args[key];
+            if (value === undefined || value === null) {
+                return null;
+            }
+            const strValue = String(value);
+            // Truncate long values
+            return strValue.length > 50 ? `${strValue.slice(0, 47)}...` : strValue;
+        })
+            .filter(Boolean);
+        return values.join(', ');
+    }
+}
+/**
+ * Singleton instance for the tool execution service
+ */
+let toolExecutionService = null;
+export function getToolExecutionService(workingDir) {
+    if (!toolExecutionService || workingDir) {
+        toolExecutionService = new ToolExecutionService(workingDir);
+    }
+    return toolExecutionService;
+}
+//# sourceMappingURL=tool-execution.service.js.map