fixo-cli 1.0.0

package/dist/agent/tool-executor.js

@@ -0,0 +1,2519 @@
+/**
+ * Tool definitions and executor for the single-agent tool-calling loop.
+ * Provides: read_file, write_file, run_command, search_code, list_dir
+ */
+import fs from 'fs';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { colors } from '../ui/colors.js';
+import { renderToolCall } from '../ui/render-primitives.js';
+import { WorkspaceGuard } from '../workspace-guard.js';
+import { classifyCommand } from '../runtime/policy.js';
+import { checkPermission } from './permissions.js';
+import { redactedEnv, redactSecrets } from '../runtime/redaction.js';
+import { McpManager } from './mcp-manager.js';
+import { estimateReadCost, shouldDeferRead, formatPredictiveGateDirective, DEFAULT_PREDICTIVE_BUDGET_PCT } from './predictive-gate.js';
+import { createBranch, commitChanges, pushBranch, createPullRequest } from '../git/git-ops.js';
+import { pathToFileURL } from 'url';
+import * as p from '@clack/prompts';
+import { loadConfig, saveConfig } from '../config.js';
+import { AtomicStagingManager } from '../runtime/staging.js';
+import { LspPreSaveGate, makeLspProvider } from '../lsp/lsp-pre-save.js';
+import { syntaxHealthCheck, formatSyntaxVerdict } from '../lsp/syntax-fallback.js';
+import { PlatformPathLockedError } from '../workspace-guard.js';
+import { McpBridgeManager } from './mcp-bridge.js';
+import { LspManager } from '../lsp/lsp-manager.js';
+import { webFetch, webSearch } from './web.js';
+import { loadTodoList, saveTodoList, addItem, setItemStatus, removeItem, clearDoneItems, renderTodoList, summariseTodoList, } from '../context/todo.js';
+import { recordTelemetry, telemetry } from './telemetry.js';
+import { applyModifiedArgs, fireHooks } from './hooks.js';
+import { BackgroundJobRegistry } from '../runtime/background-jobs.js';
+import { ParserFactory, languageIdFromExtension, } from './parser-adapter.js';
+export const mcpManager = new McpManager();
+export const mcpBridgeManager = new McpBridgeManager();
+let lspManagerInstance = null;
+export function getLspManager(workspaceRoot) {
+    if (!lspManagerInstance) {
+        lspManagerInstance = new LspManager(workspaceRoot);
+    }
+    return lspManagerInstance;
+}
+export async function stopLspManager() {
+    if (lspManagerInstance) {
+        await lspManagerInstance.stopAll();
+        lspManagerInstance = null;
+    }
+}
+export const loadedPlugins = [];
+export async function initializePlugins(cwd, projectConfig) {
+    if (!projectConfig || !projectConfig.plugins || !Array.isArray(projectConfig.plugins)) {
+        return;
+    }
+    const guard = new WorkspaceGuard(cwd);
+    const globalConfig = loadConfig();
+    if (!globalConfig.approvedPlugins) {
+        globalConfig.approvedPlugins = [];
+    }
+    const trusted = projectConfig.trustedPlugins || [];
+    for (const pluginPath of projectConfig.plugins) {
+        try {
+            const resolvedPath = guard.resolve(pluginPath);
+            const isTrusted = trusted.includes(pluginPath) || trusted.includes(resolvedPath);
+            if (!isTrusted) {
+                console.error(`\n${colors.red}[Plugin Loader] Error: Plugin "${pluginPath}" is listed in "plugins" but is not in the "trustedPlugins" allowlist inside .freellmapi.yml. Skipping.${colors.reset}`);
+                continue;
+            }
+            const fileUrl = pathToFileURL(resolvedPath).toString();
+            const mod = await import(fileUrl);
+            const tools = (mod.tools || []);
+            const execute = mod.execute;
+            if (typeof execute !== 'function') {
+                console.error(`\n${colors.red}[Plugin Loader] Error: Plugin "${pluginPath}" does not export an "execute" function. Skipping.${colors.reset}`);
+                continue;
+            }
+            const approvedKey = `${resolvedPath}`;
+            const isApproved = globalConfig.approvedPlugins.includes(approvedKey);
+            if (!isApproved) {
+                console.log(`\n${colors.yellow}╔════════════════════════════════════════════════════════════════╗`);
+                console.log(`║                  PLUGIN SECURITY VERIFICATION                  ║`);
+                console.log(`╚════════════════════════════════════════════════════════════════╝`);
+                console.log(`A new plugin is requesting to be loaded for this workspace:`);
+                console.log(`- Path: ${colors.cyan}${pluginPath}${colors.reset}`);
+                console.log(`- Resolved: ${colors.cyan}${resolvedPath}${colors.reset}`);
+                console.log(`- Registers tools: ${colors.green}${tools.map(t => t.function.name).join(', ') || '(none)'}${colors.reset}`);
+                console.log(`\n${colors.yellow}WARNING: Plugins run with full access to the user shell and can make network calls or exfiltrate credentials.${colors.reset}`);
+                const confirmed = await p.confirm({
+                    message: `Do you trust and want to load this plugin?`,
+                    initialValue: false,
+                });
+                if (p.isCancel(confirmed) || !confirmed) {
+                    console.log(`[Plugin Loader] Load cancelled for "${pluginPath}". Skipping.`);
+                    continue;
+                }
+                globalConfig.approvedPlugins.push(approvedKey);
+                saveConfig(globalConfig);
+                console.log(`${colors.green}✓ Plugin approved and saved to ~/.fixocli/config.json${colors.reset}`);
+            }
+            loadedPlugins.push({
+                path: pluginPath,
+                tools,
+                execute,
+            });
+        }
+        catch (err) {
+            console.error(`\n${colors.red}[Plugin Loader] Failed to load plugin "${pluginPath}": ${err instanceof Error ? err.message : String(err)}${colors.reset}`);
+        }
+    }
+}
+/* ──────────────────────── Tool Definitions ──────────────────────── */
+/**
+ * Names of all tools that perform a write / mutation. Used by
+ * {@link getActiveTools} to enforce role-based tool masking
+ * (Pillar 5 / Protection 2 — Strict Runtime Role Isolation).
+ * Kept as a Set for O(1) membership checks; never read in
+ * production paths.
+ */
+export const MUTATION_TOOL_NAMES = new Set([
+    'write_file',
+    'apply_patch',
+    'replace_range',
+    'insert_after',
+    'rename_file',
+    'delete_file',
+    'create_branch',
+    'commit_changes',
+    'push_branch',
+    'create_pull_request',
+    'run_command',
+    'str_replace',
+    'todo_write',
+    'run_command_async',
+]);
+/**
+ * Build the active tool list for a given execution role. The
+ * mode argument is the role the agent is operating in:
+ *
+ *   - `BUILD`  — the default; all tools are available.
+ *   - `EXPLORE` — only read + LSP navigation tools.
+ *   - `SCOUT`  — only web fetch / search.
+ *   - `PLAN`   — read + web + LSP, but no mutations.
+ *   - `READ_ONLY` (Pillar 5) — no mutation tools at all.
+ *     This is the role forced on during vulnerability audits,
+ *     reviews, and explanations, so the LLM has zero
+ *     visibility of code-writing tools and cannot accidentally
+ *     mutate the workspace.
+ */
+export function getActiveTools(mode) {
+    const pluginTools = loadedPlugins.flatMap(p => p.tools);
+    let tools = [...TOOL_DEFINITIONS, ...mcpManager.getTools(), ...mcpBridgeManager.getTools(), ...pluginTools];
+    if (mode === 'EXPLORE') {
+        const allowed = ['read_file', 'list_dir', 'search_code', 'lsp_goto_definition', 'lsp_find_references', 'lsp_hover'];
+        tools = tools.filter(t => allowed.includes(t.function.name));
+    }
+    else if (mode === 'SCOUT') {
+        const allowed = ['web_fetch', 'web_search'];
+        tools = tools.filter(t => allowed.includes(t.function.name));
+    }
+    else if (mode === 'PLAN') {
+        const readOnly = ['read_file', 'list_dir', 'search_code', 'lsp_goto_definition', 'lsp_find_references', 'lsp_hover', 'web_fetch', 'web_search'];
+        tools = tools.filter(t => readOnly.includes(t.function.name));
+    }
+    else if (mode === 'READ_ONLY') {
+        // Pillar 5 — strip every mutation tool. The agent sees
+        // only read + search + LSP navigation.
+        tools = tools.filter(t => !MUTATION_TOOL_NAMES.has(t.function.name));
+    }
+    return tools;
+}
+/**
+ * Classify a task into an execution role. Read-only tasks
+ * (analysis, explanation, review) get the `READ_ONLY` role so
+ * mutation tools are not even visible to the model. This is
+ * the dynamic-tool-masking layer of Pillar 5.
+ */
+export function classifyExecutionRole(task) {
+    const lower = task.toLowerCase();
+    // Read-only keywords — the agent must answer a question or
+    // describe something, not modify files.
+    const readOnlyPatterns = [
+        /\b(analy[sz]e|analysing|analysed)\b/,
+        /\b(review|auditing|audit)\b/,
+        /\b(explain|describe|what does|how does|why does)\b/,
+        /\b(vulnerabilit(y|ies)|security review|threat model)\b/,
+        /\b(read(ing)? the (entire )?code(base)?)\b/,
+        /\b(find (the )?bugs?|find (the )?vulnerabilities|find (the )?issues?)\b/,
+        /\b(list(ing)? (the )?files|show (me )?the files|what files)\b/,
+        /\b(without (modif|chang|edit|alter)ing)\b/,
+        /\b(read[\s-]only)\b/,
+    ];
+    for (const pattern of readOnlyPatterns) {
+        if (pattern.test(lower))
+            return 'READ_ONLY';
+    }
+    return 'BUILD';
+}
+export const TOOL_DEFINITIONS = [
+    {
+        type: 'function',
+        function: {
+            name: 'read_file',
+            description: 'Read the full text contents of a file at the given path. Use this to understand existing code before making changes. Returns the file contents as a string. Files larger than the large-file gate (15 KiB / 350 lines by default) will return a [Context-Budget Guard] synthetic directive telling you to call extract_symbols or extract_imports first.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to read, relative to the workspace root or absolute.',
+                    },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'extract_symbols',
+            description: 'Extract symbol declarations (classes, functions, interfaces, types, consts) from a file. Output is capped at 100 entries. Cheaper than read_file for large files because it skips the body content.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to inspect, relative to the workspace root or absolute.',
+                    },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'extract_imports',
+            description: 'Extract import statements from a file. Output is capped at 100 entries. Cheaper than read_file for large files because it skips the body content.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to inspect, relative to the workspace root or absolute.',
+                    },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'apply_patch',
+            description: 'Apply a unified diff patch to files in the workspace. Prefer this over write_file for editing existing files.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    patch: { type: 'string', description: 'Unified diff patch text.' },
+                },
+                required: ['patch'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'replace_range',
+            description: 'Replace inclusive 1-based line range in a file. Requires reading the file first.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    startLine: { type: 'string' },
+                    endLine: { type: 'string' },
+                    content: { type: 'string' },
+                },
+                required: ['path', 'startLine', 'endLine', 'content'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'insert_after',
+            description: 'Insert content after the first exact anchor match in a file. Requires reading the file first.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string' },
+                    anchor: { type: 'string' },
+                    content: { type: 'string' },
+                },
+                required: ['path', 'anchor', 'content'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'rename_file',
+            description: 'Rename or move a workspace file.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    from: { type: 'string' },
+                    to: { type: 'string' },
+                },
+                required: ['from', 'to'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'write_file',
+            description: 'Write a complete file to disk. Use ONLY for new files or full rewrites where the prior content is irrelevant. For ANY change to an existing file (single-region edit, symbol rename, line tweak, multi-line refactor) you MUST use `str_replace` (single hunk) or `apply_patch` (multi-region) instead — both go through the same atomic staging pipeline but preserve the rest of the file. Rewriting an existing file with write_file when str_replace would do is an error: it wastes tokens, defeats LSP pre-save gating granularity, and risks losing concurrent edits. Creates parent directories if missing.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to write, relative to the workspace root or absolute.',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'The full file content to write.',
+                    },
+                },
+                required: ['path', 'content'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'run_command',
+            description: 'Execute a shell command and return its stdout and stderr output. Use this to run tests, build projects, install dependencies, or verify changes. Commands run in the workspace directory.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    command: {
+                        type: 'string',
+                        description: 'The shell command to execute.',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Working directory for the command (optional, defaults to workspace root).',
+                    },
+                },
+                required: ['command'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'run_command_async',
+            description: 'Spawn a long-running command in the background and return immediately with a jobId. Use poll_command_status to retrieve output and kill_command to terminate. Output streams cap at 64 KiB each; the larger totalByte counters survive the cap. Rejected in PLAN mode. Workspace-escape and sensitive-file commands are blocked at spawn time by the same command-parser used by run_command.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    cmd: { type: 'string', description: 'The binary to spawn.' },
+                    args: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Argument vector.',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Working directory (defaults to workspace root).',
+                    },
+                },
+                required: ['cmd'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'poll_command_status',
+            description: 'Read a snapshot of a background job. The snapshot includes status, exitCode, startedAt/exitedAt, and the (capped) stdout and stderr streams. tailLines truncates each stream to its last N lines; sinceBytes returns only the bytes after the given offset on stdout/stderr (delta fields).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string', description: 'The jobId returned by run_command_async.' },
+                    tailLines: { type: 'integer', description: 'Truncate each stream to last N lines.' },
+                    sinceBytes: { type: 'integer', description: 'Return only bytes after this offset.' },
+                },
+                required: ['jobId'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'kill_command',
+            description: 'Send SIGTERM to a background job. No-op if the job has already exited.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    jobId: { type: 'string', description: 'The jobId to terminate.' },
+                },
+                required: ['jobId'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'search_code',
+            description: 'Search for a text or regex pattern in workspace files. Returns matching lines with file paths and line numbers. Use this to find where functions, classes, or variables are defined or used.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: {
+                        type: 'string',
+                        description: 'The search pattern (plain text or regex).',
+                    },
+                    path: {
+                        type: 'string',
+                        description: 'Directory or file to search in (optional, defaults to workspace root).',
+                    },
+                    file_pattern: {
+                        type: 'string',
+                        description: 'Glob pattern to filter files, e.g., "*.ts" or "*.py" (optional).',
+                    },
+                },
+                required: ['query'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'list_dir',
+            description: 'List files and directories at the given path. Returns names, types (file/dir), and sizes.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The directory path to list (optional, defaults to workspace root).',
+                    },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'delete_file',
+            description: 'Delete a file at the given path from the workspace.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to delete, relative to the workspace root or absolute.',
+                    },
+                },
+                required: ['path'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'create_branch',
+            description: 'Create and checkout a new Git branch.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    branchName: { type: 'string', description: 'The name of the branch to create.' },
+                },
+                required: ['branchName'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'commit_changes',
+            description: 'Stage all current changes and commit them.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    message: { type: 'string', description: 'The commit message.' },
+                },
+                required: ['message'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'push_branch',
+            description: 'Push the current active branch to origin or custom remote.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    remote: { type: 'string', description: 'The remote repository name (default: origin).' },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'create_pull_request',
+            description: 'Create a pull request on GitHub for the current branch.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    baseBranch: { type: 'string', description: 'The base branch to merge into (default: main).' },
+                },
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'lsp_goto_definition',
+            description: 'Find definition coordinates for a symbol at a given 0-indexed line and character position using LSP.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path containing the symbol.' },
+                    line: { type: 'integer', description: '0-indexed line number.' },
+                    character: { type: 'integer', description: '0-indexed character offset.' },
+                },
+                required: ['path', 'line', 'character'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'lsp_find_references',
+            description: 'Find all reference locations for a symbol at a given 0-indexed line and character position using LSP.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path containing the symbol.' },
+                    line: { type: 'integer', description: '0-indexed line number.' },
+                    character: { type: 'integer', description: '0-indexed character offset.' },
+                },
+                required: ['path', 'line', 'character'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'lsp_hover',
+            description: 'Retrieve type information and documentation for a symbol at a given 0-indexed line and character position using LSP.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: { type: 'string', description: 'File path containing the symbol.' },
+                    line: { type: 'integer', description: '0-indexed line number.' },
+                    character: { type: 'integer', description: '0-indexed character offset.' },
+                },
+                required: ['path', 'line', 'character'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'web_fetch',
+            description: 'Fetch a webpage using an HTTP GET request and return its content converted to Markdown. Use this to read documentation or external references.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    url: { type: 'string', description: 'The absolute URL to fetch.' },
+                },
+                required: ['url'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'web_search',
+            description: 'Perform a web search for a given query and return a list of search results as Markdown snippets. Use this to find information on the web.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    query: { type: 'string', description: 'The search query.' },
+                },
+                required: ['query'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'str_replace',
+            description: 'Use this tool by default for any in-place edit to an existing file. Performs a surgical, atomic replacement of oldString with newString. By default, oldString must be unique within the file (expectUnique=true) — non-unique matches are rejected with a clear error so the caller can narrow the snippet. Pass replaceAll=true to substitute every occurrence. Rejected in PLAN mode. Refused for platform-locked paths. Goes through the same atomic staging pipeline as write_file and the LSP pre-save gate before any disk mutation.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    path: {
+                        type: 'string',
+                        description: 'The file path to edit, relative to the workspace root or absolute.',
+                    },
+                    oldString: {
+                        type: 'string',
+                        description: 'The exact substring to replace. Must appear in the file.',
+                    },
+                    newString: {
+                        type: 'string',
+                        description: 'The replacement content.',
+                    },
+                    replaceAll: {
+                        type: 'boolean',
+                        description: 'If true, replace every occurrence. Default false.',
+                    },
+                    expectUnique: {
+                        type: 'boolean',
+                        description: 'If true (default), the operation aborts when oldString is not unique. Set to false to allow non-unique matches with the first occurrence replaced.',
+                    },
+                },
+                required: ['path', 'oldString', 'newString'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'todo_read',
+            description: 'Read the current project todo list from <cwd>/.fixo/todo_list.json. Returns a human-readable rendering of all items grouped into Open and Completed. A missing or unreadable file yields an empty list — by design.',
+            parameters: {
+                type: 'object',
+                properties: {},
+                required: [],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'todo_write',
+            description: 'Mutate the project todo list. Operations: add (content+blockedBy optional), set_status (id+status), remove (id), clear_done. Persisted atomically to <cwd>/.fixo/todo_list.json. Rejected in PLAN mode.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    op: {
+                        type: 'string',
+                        enum: ['add', 'set_status', 'remove', 'clear_done'],
+                        description: 'The mutation to apply.',
+                    },
+                    content: {
+                        type: 'string',
+                        description: 'Item content (op=add only).',
+                    },
+                    id: {
+                        type: 'string',
+                        description: 'Item id (op=set_status, op=remove).',
+                    },
+                    status: {
+                        type: 'string',
+                        enum: ['pending', 'in_progress', 'done', 'cancelled'],
+                        description: 'New status (op=set_status only).',
+                    },
+                    blockedBy: {
+                        type: 'string',
+                        description: 'Optional blocker description (op=add only).',
+                    },
+                },
+                required: ['op'],
+            },
+        },
+    },
+    {
+        type: 'function',
+        function: {
+            name: 'glob_files',
+            description: 'High-performance filesystem pattern matcher. Returns paths matching the given glob pattern, relative to the workspace root. Built on Node 22+ native fs.promises.glob. By default, common build/VCS directories (node_modules, .git, dist, .fixo, .fixocli) are excluded. Symlinks are not followed and hidden files are excluded unless explicitly enabled. Capped at maxResults (default 1000, hard cap 5000).',
+            parameters: {
+                type: 'object',
+                properties: {
+                    pattern: {
+                        type: 'string',
+                        description: 'Glob pattern, e.g. "src/**/*.ts" or "**/package.json".',
+                    },
+                    cwd: {
+                        type: 'string',
+                        description: 'Optional directory to scope the glob. Must resolve inside the workspace. Defaults to the workspace root.',
+                    },
+                    ignore: {
+                        type: 'string',
+                        description: 'Optional extra glob pattern (or comma-separated patterns) to add to the default skip set.',
+                    },
+                    maxResults: {
+                        type: 'integer',
+                        description: 'Maximum number of results to return. Default 1000, hard cap 5000.',
+                    },
+                    includeHidden: {
+                        type: 'boolean',
+                        description: 'If true, do not exclude dotfile entries from the match. Default false.',
+                    },
+                    followSymlinks: {
+                        type: 'boolean',
+                        description: 'If true, follow symbolic links during traversal. Default false (safer).',
+                    },
+                },
+                required: ['pattern'],
+            },
+        },
+    },
+];
+/* ──────────────────────── Per-process Run ID (Pillar 2) ──────────── */
+let cachedRunId = null;
+/**
+ * Lazily generate a per-process run id. Used to namespace
+ * `.fixo/staging/<runId>/` so concurrent runs against the same
+ * workspace never collide. The id is a 12-character base36 token.
+ */
+export function getOrCreateRunId() {
+    if (cachedRunId)
+        return cachedRunId;
+    cachedRunId = Math.random().toString(36).slice(2, 8) +
+        Date.now().toString(36).slice(-6);
+    return cachedRunId;
+}
+/** Test/utility hook — reset the cached run id. */
+export function resetRunId() {
+    cachedRunId = null;
+}
+/* ──────────────────────── LSP Pre-Save Gate (Pillar 3) ──────────── */
+let cachedLspGate = null;
+/**
+ * Lazily construct a singleton {@link LspPreSaveGate} that wires
+ * the tool-executor to the live `LspManager`. Mode is read from
+ * the user's safety config (default: `'warn'`). The gate is a
+ * no-op when no language server is installed on `PATH`, matching
+ * the existing `LspManager` behaviour.
+ */
+export function getOrCreateLspGate(cwd, safety) {
+    if (cachedLspGate)
+        return cachedLspGate;
+    cachedLspGate = new LspPreSaveGate({
+        mode: safety.lspPreSave,
+        provider: makeLspProvider(getLspManager(cwd)),
+    });
+    return cachedLspGate;
+}
+/** Test/utility hook — reset the cached gate. */
+export function resetLspGate() {
+    cachedLspGate = null;
+}
+function riskOf(action, detail) {
+    if (action === 'command')
+        return classifyCommand(detail);
+    if (action === 'delete')
+        return 'high';
+    if (action === 'write')
+        return 'medium';
+    return 'low';
+}
+function evaluateToolGate(toolName, args, cwd, policy, action, detail) {
+    const check = checkPermission(toolName, args, cwd, policy);
+    const risk = riskOf(action, detail);
+    if (check.decision === 'deny') {
+        return {
+            allowed: false,
+            needsConfirmation: false,
+            reason: check.reason,
+            risk,
+            source: check.source,
+            matchedRule: check.matchedRule,
+        };
+    }
+    return {
+        allowed: true,
+        needsConfirmation: check.decision === 'ask',
+        reason: check.reason,
+        risk,
+        source: check.source,
+        matchedRule: check.matchedRule,
+    };
+}
+/* ──────────────────────── Atomic Write Helper (Pillar 2) ─────────── */
+/**
+ * Stage-and-commit a file write. When `safety.atomicStaging` is
+ * true, the new content goes through
+ * {@link AtomicStagingManager} so the swap is atomic and the
+ * pre-commit hook (Pillar 3) gets a chance to validate. When
+ * false, the legacy direct-write path is used and a `null`
+ * staging manager is returned to the caller.
+ */
+async function applyAtomicWrite(cwd, filePath, content, safety, session) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    const existed = fs.existsSync(resolved);
+    if (!safety?.atomicStaging) {
+        // Legacy path: write directly (preserves the existing diff-printing
+        // and session semantics inside the caller).
+        const parentDir = path.dirname(resolved);
+        if (!fs.existsSync(parentDir)) {
+            fs.mkdirSync(parentDir, { recursive: true });
+        }
+        fs.writeFileSync(resolved, content, 'utf-8');
+        session?.noteChange(resolved);
+        return {
+            result: existed ? `File updated: ${filePath}` : `File created: ${filePath}`,
+            staged: false,
+            created: !existed,
+        };
+    }
+    const mgr = new AtomicStagingManager(cwd, getOrCreateRunId(), {
+        ttlMs: safety.stagingTtlMs,
+        // Pillar 3 — wire the LSP pre-save gate as the staging
+        // manager's pre-commit hook. The gate runs diagnostics on
+        // the staged file; in `block` mode it throws on any
+        // error-severity diagnostic, which causes the staging
+        // manager to surface a PreCommitHookRejectedError and the
+        // user keeps the original file. In `warn` mode the gate
+        // just logs via onResult and lets the commit proceed.
+        preCommitHook: async (e) => {
+            const gate = getOrCreateLspGate(cwd, safety);
+            const result = await gate.check(e);
+            gate.enforce(result, e);
+        },
+        // Pillar 5 / Protection 3 — structural syntax health check.
+        // JS/TS files are passed through the brace/paren/bracket
+        // balance check in `src/lsp/syntax-fallback.ts`. The real
+        // TypeScript compile is the LSP gate's job; this is a fast
+        // structural sanity check that catches the catastrophic case
+        // (unclosed `try` block, dangling `catch` keyword, etc.).
+        syntaxHealthCheck: async (e, content) => {
+            const lower = e.targetPath.toLowerCase();
+            const isJs = lower.endsWith('.js') || lower.endsWith('.cjs') || lower.endsWith('.mjs');
+            const isTs = lower.endsWith('.ts') || lower.endsWith('.tsx');
+            if (!isJs && !isTs)
+                return;
+            const verdict = syntaxHealthCheck(content);
+            if (verdict.state === 'ok')
+                return;
+            const e2 = new Error(`Structural syntax check failed for ${path.basename(e.targetPath)}: ` +
+                `${formatSyntaxVerdict(verdict)} ` +
+                `The staged write was rejected to protect the target file.`);
+            e2.code = 'FIXO_STRUCTURAL_SYNTAX';
+            throw e2;
+        },
+    });
+    const entry = mgr.stage(filePath, content, 0o644);
+    const commit = await mgr.commit(entry.id);
+    if (commit.committed) {
+        session?.noteChange(resolved);
+    }
+    return {
+        result: existed
+            ? `File updated (atomic): ${filePath}`
+            : `File created (atomic): ${filePath}`,
+        staged: commit.committed,
+        created: !existed,
+    };
+}
+async function askUnsafeCommandPermission(command, reason, allowWithoutPrompt) {
+    if (allowWithoutPrompt) {
+        console.log(`\n${colors.yellow}⚠ Security Warning: Executing potentially unsafe command: ${colors.bold}${command}${colors.reset}\nReason: ${reason}`);
+        return true;
+    }
+    console.log(`\n${colors.red}${colors.bold}⚠ SECURITY WARNING:${colors.reset}`);
+    console.log(`The agent is attempting to execute a command that violates safety sandboxing:`);
+    console.log(`- Command: ${colors.yellow}${command}${colors.reset}`);
+    console.log(`- Danger: ${colors.red}${reason}${colors.reset}\n`);
+    const confirmed = await p.confirm({
+        message: `Do you want to bypass this warning and allow execution?`,
+        initialValue: false,
+    });
+    return !p.isCancel(confirmed) && confirmed;
+}
+/**
+ * Execute a tool call and return its result string.
+ * Also logs the operation to the terminal with colored output.
+ */
+export async function executeTool(name, args, cwd, verbose = false, options = {}) {
+    const event = {
+        tool: name,
+        args,
+        result: '',
+        isWrite: false,
+    };
+    try {
+        const policy = options.policy ?? options.session?.policy ?? 'shell-confirm';
+        // ──── PreToolUse hooks (§3.4) ────
+        // Run any user-defined pre-tool hooks. A `deny` decision
+        // short-circuits the call; a `modify` decision replaces
+        // args after a `WorkspaceGuard` re-check.
+        const sessionId = options.session?.id ?? 'no-session';
+        const preHook = fireHooks(cwd, 'PreToolUse', {
+            tool: name,
+            args: args,
+            sessionId,
+        });
+        if (preHook.fired && preHook.decision === 'deny') {
+            const reason = preHook.reason ?? 'pre-tool hook denied';
+            event.result = `Error: hook denied (${preHook.hookId ?? 'unknown'}): ${reason}`;
+            options.session?.record('tool_denied', { tool: name, reason, args });
+            renderToolCall({ kind: 'error', name, detail: `hook denied: ${reason}` });
+            return event;
+        }
+        if (preHook.fired && preHook.decision === 'modify' && preHook.modifiedArgs) {
+            const applied = applyModifiedArgs(cwd, args, preHook.modifiedArgs);
+            if (!applied.ok) {
+                const reason = applied.reason ?? 'pre-hook modify rejected';
+                event.result = `Error: hook modify rejected: ${reason}`;
+                options.session?.record('tool_denied', { tool: name, reason, args });
+                renderToolCall({ kind: 'error', name, detail: `hook modify rejected: ${reason}` });
+                return event;
+            }
+            for (const [k, v] of Object.entries(applied.args)) {
+                if (typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean') {
+                    args[k] = String(v);
+                }
+            }
+        }
+        const plugin = loadedPlugins.find(p => p.tools.some(t => t.function.name === name));
+        if (plugin) {
+            const action = name.includes('read') || name.includes('get') || name.includes('list') || name.includes('view') ? 'read' : 'write';
+            const decision = evaluateToolGate(name, args, cwd, policy, action, name);
+            if (!decision.allowed) {
+                event.result = `Error: ${decision.reason}`;
+                options.session?.record('tool_denied', { tool: name, reason: decision.reason, args, matchedRule: decision.matchedRule, source: decision.source });
+                return event;
+            }
+            options.session?.record('tool_started', { tool: name, args, risk: decision.risk, matchedRule: decision.matchedRule, source: decision.source });
+            console.log(`  ${colors.dim}🔌 Plugin: ${name}${colors.reset}`);
+            try {
+                event.result = await plugin.execute(name, args, { cwd, verbose, policy, options });
+                event.isWrite = action === 'write';
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                event.result = `Error: ${msg}`;
+                renderToolCall({ kind: 'error', name, detail: truncate(msg, 80) });
+            }
+            options.session?.record('tool_finished', { tool: name, result: truncate(event.result, 2000), isWrite: event.isWrite });
+            return event;
+        }
+        if (mcpManager.hasTool(name)) {
+            const action = name.includes('read') || name.includes('get') || name.includes('list') || name.includes('view') ? 'read' : 'write';
+            const decision = evaluateToolGate(name, args, cwd, policy, action, name);
+            if (!decision.allowed) {
+                event.result = `Error: ${decision.reason}`;
+                options.session?.record('tool_denied', { tool: name, reason: decision.reason, args, matchedRule: decision.matchedRule, source: decision.source });
+                return event;
+            }
+            options.session?.record('tool_started', { tool: name, args, risk: decision.risk, matchedRule: decision.matchedRule, source: decision.source });
+            console.log(`  ${colors.dim}🔌 MCP: ${name}${colors.reset}`);
+            try {
+                event.result = await mcpManager.executeTool(name, args);
+                event.isWrite = action === 'write';
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                event.result = `Error: ${msg}`;
+                renderToolCall({ kind: 'error', name, detail: truncate(msg, 80) });
+            }
+            options.session?.record('tool_finished', { tool: name, result: truncate(event.result, 2000), isWrite: event.isWrite });
+            return event;
+        }
+        if (mcpBridgeManager.hasTool(name)) {
+            const action = name.includes('read') || name.includes('get') || name.includes('list') || name.includes('view') ? 'read' : 'write';
+            const decision = evaluateToolGate(name, args, cwd, policy, action, name);
+            if (!decision.allowed) {
+                event.result = `Error: ${decision.reason}`;
+                options.session?.record('tool_denied', { tool: name, reason: decision.reason, args, matchedRule: decision.matchedRule, source: decision.source });
+                return event;
+            }
+            options.session?.record('tool_started', { tool: name, args, risk: decision.risk, matchedRule: decision.matchedRule, source: decision.source });
+            console.log(`  ${colors.dim}🔌 Local MCP: ${name}${colors.reset}`);
+            try {
+                event.result = await mcpBridgeManager.executeTool(name, args);
+                event.isWrite = action === 'write';
+            }
+            catch (error) {
+                const msg = error instanceof Error ? error.message : String(error);
+                event.result = `Error: ${msg}`;
+                renderToolCall({ kind: 'error', name, detail: truncate(msg, 80) });
+            }
+            options.session?.record('tool_finished', { tool: name, result: truncate(event.result, 2000), isWrite: event.isWrite });
+            return event;
+        }
+        const action = name === 'run_command'
+            ? 'command'
+            : name === 'read_file' || name === 'search_code' || name === 'list_dir' || name === 'web_fetch' || name === 'web_search'
+                ? 'read'
+                : name === 'delete_file'
+                    ? 'delete'
+                    : 'write';
+        const policyTargetRaw = name === 'web_fetch' ? args.url : name === 'web_search' ? args.query : (args.command ?? args.path ?? '');
+        const policyTarget = typeof policyTargetRaw === 'string' ? policyTargetRaw : String(policyTargetRaw ?? '');
+        const decision = evaluateToolGate(name, args, cwd, policy, action, policyTarget);
+        if (!decision.allowed) {
+            event.result = `Error: ${decision.reason}`;
+            options.session?.record('tool_denied', { tool: name, reason: decision.reason, args, matchedRule: decision.matchedRule, source: decision.source });
+            return event;
+        }
+        options.session?.record('tool_started', { tool: name, args, risk: decision.risk, matchedRule: decision.matchedRule, source: decision.source });
+        switch (name) {
+            case 'read_file': {
+                const guard = new WorkspaceGuard(cwd);
+                const resolved = guard.resolve(args.path, 'file');
+                const budgetPct = options.safety?.predictiveBudgetPct ?? DEFAULT_PREDICTIVE_BUDGET_PCT;
+                // Skip the predictive gate when it is explicitly disabled
+                // (>=1.0) or when no model is configured (we cannot map
+                // model → context window without one).
+                if (budgetPct < 1 && options.model) {
+                    const estimate = estimateReadCost(resolved, options.model);
+                    const convoTokens = options.getConversationTokens?.() ?? 0;
+                    const deferDecision = shouldDeferRead(estimate, convoTokens, options.model, budgetPct);
+                    if (deferDecision.defer) {
+                        event.result = formatPredictiveGateDirective(args.path, estimate, deferDecision);
+                        event.affectedPath = resolved;
+                        renderToolCall({ kind: 'read', name: 'Read', detail: `${shortenPath(args.path, cwd)} (deferred — predictive gate)` });
+                        options.session?.record('predictive_gate_fired', {
+                            path: args.path,
+                            projectedTokens: estimate.projectedTokens,
+                            projectedTotal: deferDecision.projectedTotal,
+                            hardCap: deferDecision.hardCap,
+                        });
+                        break;
+                    }
+                }
+                event.result = executeReadFile(args.path, cwd, options.session, options.safety?.largeFileGateBytes, options.safety?.largeFileGateLines);
+                event.affectedPath = resolved;
+                renderToolCall({ kind: 'read', name: 'Read', detail: shortenPath(args.path, cwd) });
+                break;
+            }
+            case 'extract_symbols':
+                event.result = await executeExtractSymbols(args.path, cwd, options.session);
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                renderToolCall({ kind: 'read', name: 'Symbols', detail: shortenPath(args.path, cwd) });
+                break;
+            case 'extract_imports':
+                event.result = await executeExtractImports(args.path, cwd, options.session);
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                renderToolCall({ kind: 'read', name: 'Imports', detail: shortenPath(args.path, cwd) });
+                break;
+            case 'write_file':
+                event.result = await executeWriteFile(args.path, args.content, cwd, options);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                renderToolCall({ kind: 'write', name: 'Write', detail: shortenPath(args.path, cwd) });
+                break;
+            case 'run_command':
+                renderToolCall({ kind: 'bash', name: 'Run', detail: truncate(args.command, 60) });
+                let safetyResult = { safe: true, reason: '' };
+                try {
+                    const { isCommandSafe } = await import('./command-parser.js');
+                    const safety = await isCommandSafe(args.command, cwd);
+                    if (!safety.safe) {
+                        safetyResult = { safe: false, reason: safety.reason || 'Unsafe command detected' };
+                    }
+                }
+                catch (err) {
+                    if (verbose) {
+                        console.error('Failed to run AST command safety check, falling back to regex safety check:', err.message);
+                    }
+                    const trimmed = args.command.trim();
+                    const { DANGEROUS_COMMANDS } = await import('../runtime/policy.js');
+                    for (const pattern of DANGEROUS_COMMANDS) {
+                        if (pattern.test(trimmed)) {
+                            safetyResult = {
+                                safe: false,
+                                reason: `Regex security match: Command contains potentially unsafe pattern/metacharacter: ${pattern.toString()}`
+                            };
+                            break;
+                        }
+                    }
+                }
+                if (!safetyResult.safe) {
+                    const allowed = await askUnsafeCommandPermission(args.command, safetyResult.reason, options.allowWithoutPrompt);
+                    if (!allowed) {
+                        event.result = `Error: Security block - Execution denied for unsafe command: ${safetyResult.reason}`;
+                        break;
+                    }
+                }
+                event.result = executeRunCommand(args.command, args.cwd || cwd, cwd, options.session);
+                break;
+            case 'search_code':
+                renderToolCall({ kind: 'search', name: 'Search', detail: `"${truncate(args.query, 40)}" in ${args.path ?? '.'}` });
+                event.result = executeSearchCode(args.query, args.path, args.file_pattern, cwd);
+                break;
+            case 'list_dir':
+                renderToolCall({ kind: 'read', name: 'List', detail: args.path ?? '.' });
+                event.result = executeListDir(args.path, cwd);
+                break;
+            case 'delete_file':
+                renderToolCall({ kind: 'write', name: 'Delete', detail: shortenPath(args.path, cwd) });
+                event.result = executeDeleteFile(args.path, cwd, options.session);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                break;
+            case 'apply_patch':
+                renderToolCall({ kind: 'write', name: 'Patch', detail: 'unified diff' });
+                event.result = await executeApplyPatch(args.patch, cwd, options);
+                event.isWrite = true;
+                break;
+            case 'replace_range':
+                renderToolCall({ kind: 'write', name: 'Replace', detail: shortenPath(args.path, cwd) });
+                event.result = await executeReplaceRange(args.path, Number(args.startLine), Number(args.endLine), args.content, cwd, options);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                break;
+            case 'insert_after':
+                renderToolCall({ kind: 'write', name: 'Insert', detail: shortenPath(args.path, cwd) });
+                event.result = await executeInsertAfter(args.path, args.anchor, args.content, cwd, options);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                break;
+            case 'rename_file':
+                renderToolCall({ kind: 'write', name: 'Rename', detail: `${args.from} -> ${args.to}` });
+                event.result = await executeRenameFile(args.from, args.to, cwd, options);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.to, 'file');
+                break;
+            case 'create_branch':
+                renderToolCall({ kind: 'write', name: 'Branch', detail: args.branchName });
+                event.result = createBranch(cwd, args.branchName);
+                event.isWrite = true;
+                break;
+            case 'commit_changes':
+                renderToolCall({ kind: 'write', name: 'Commit', detail: truncate(args.message, 60) });
+                event.result = commitChanges(cwd, args.message);
+                event.isWrite = true;
+                break;
+            case 'push_branch':
+                renderToolCall({ kind: 'write', name: 'Push', detail: args.remote || 'origin' });
+                event.result = pushBranch(cwd, args.remote || 'origin');
+                event.isWrite = true;
+                break;
+            case 'create_pull_request':
+                renderToolCall({ kind: 'write', name: 'PR', detail: `base: ${args.baseBranch || 'main'}` });
+                if (!options.client) {
+                    throw new Error('Agent client is required to generate pull request description');
+                }
+                event.result = await createPullRequest(cwd, options.client, options.model || 'auto', args.baseBranch || 'main');
+                event.isWrite = true;
+                break;
+            case 'lsp_goto_definition': {
+                const line = Number(args.line);
+                const char = Number(args.character);
+                const fileBasename = path.basename(args.path);
+                renderToolCall({ kind: 'read', name: 'Definition', detail: `${fileBasename}:${line}:${char}` });
+                const manager = getLspManager(cwd);
+                const resolvedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                const def = await manager.gotoDefinition(resolvedPath, line, char);
+                event.result = JSON.stringify(def || null, null, 2);
+                break;
+            }
+            case 'lsp_find_references': {
+                const line = Number(args.line);
+                const char = Number(args.character);
+                const fileBasename = path.basename(args.path);
+                renderToolCall({ kind: 'read', name: 'References', detail: `${fileBasename}:${line}:${char}` });
+                const manager = getLspManager(cwd);
+                const resolvedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                const refs = await manager.findReferences(resolvedPath, line, char);
+                event.result = JSON.stringify(refs || null, null, 2);
+                break;
+            }
+            case 'lsp_hover': {
+                const line = Number(args.line);
+                const char = Number(args.character);
+                const fileBasename = path.basename(args.path);
+                renderToolCall({ kind: 'read', name: 'Hover', detail: `${fileBasename}:${line}:${char}` });
+                const manager = getLspManager(cwd);
+                const resolvedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                const hoverRes = await manager.hover(resolvedPath, line, char);
+                event.result = JSON.stringify(hoverRes || null, null, 2);
+                break;
+            }
+            case 'web_fetch':
+                renderToolCall({ kind: 'search', name: 'Fetch', detail: args.url });
+                event.result = await webFetch(args.url);
+                break;
+            case 'web_search':
+                renderToolCall({ kind: 'search', name: 'Search', detail: truncate(args.query, 40) });
+                event.result = await webSearch(args.query);
+                break;
+            case 'str_replace':
+                renderToolCall({ kind: 'write', name: 'Surgical', detail: shortenPath(args.path, cwd) });
+                event.result = await executeStrReplace(args, cwd, options);
+                event.isWrite = true;
+                event.affectedPath = new WorkspaceGuard(cwd).resolve(args.path, 'file');
+                break;
+            case 'glob_files':
+                renderToolCall({ kind: 'search', name: 'Glob', detail: truncate(args.pattern, 60) });
+                event.result = await executeGlobFiles(args, cwd, options);
+                break;
+            case 'todo_read':
+                renderToolCall({ kind: 'search', name: 'Todo', detail: 'read' });
+                event.result = executeTodoRead(cwd);
+                break;
+            case 'todo_write':
+                renderToolCall({ kind: 'write', name: 'Todo', detail: String(args.op ?? 'add') });
+                event.result = await executeTodoWrite(args, cwd, options);
+                event.isWrite = true;
+                break;
+            case 'run_command_async':
+                renderToolCall({ kind: 'bash', name: 'Async', detail: truncate(args.cmd, 30) });
+                event.result = await executeRunCommandAsync(args, cwd, options);
+                break;
+            case 'poll_command_status':
+                renderToolCall({ kind: 'bash', name: 'Poll', detail: String(args.jobId ?? '?') });
+                event.result = executePollCommandStatus(args, cwd);
+                break;
+            case 'kill_command':
+                renderToolCall({ kind: 'bash', name: 'Kill', detail: String(args.jobId ?? '?') });
+                event.result = executeKillCommand(args, cwd);
+                break;
+            default:
+                event.result = `Error: Unknown tool "${name}"`;
+        }
+    }
+    catch (error) {
+        const msg = error instanceof Error ? error.message : String(error);
+        event.result = `Error: ${msg}`;
+        renderToolCall({ kind: 'error', name, detail: truncate(msg, 80) });
+    }
+    options.session?.record('tool_finished', { tool: name, result: truncate(event.result, 2000), isWrite: event.isWrite });
+    // ──── PostToolUse hooks (§3.4) ────
+    // Fire any user-defined post-tool hooks. The tool has
+    // already executed; we only emit telemetry + honour a
+    // `deny` decision by appending a marker to the result so
+    // the caller knows the post-hook flagged it.
+    const postHook = fireHooks(cwd, 'PostToolUse', {
+        tool: name,
+        args: args,
+        sessionId: options.session?.id ?? 'no-session',
+    });
+    if (postHook.fired && postHook.decision === 'deny') {
+        const reason = postHook.reason ?? 'post-tool hook denied';
+        event.result = `${event.result}\n[post-hook denied: ${reason}]`;
+    }
+    return event;
+}
+/* ──────────────────────── Tool Implementations ──────────────────────── */
+function executeReadFile(filePath, cwd, session, largeFileGateBytes = 15 * 1024, largeFileGateLines = 350) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    if (!fs.existsSync(resolved)) {
+        return `Error: File not found: ${filePath}`;
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        return `Error: "${filePath}" is a directory, not a file. Use list_dir instead.`;
+    }
+    // Skip binary files
+    if (stat.size > 500_000) {
+        return `Error: File is too large (${(stat.size / 1024).toFixed(0)} KB). Read a smaller file or search for specific content.`;
+    }
+    if (guard.isBinaryFile(resolved)) {
+        return `Error: File appears to be binary: ${filePath}`;
+    }
+    // Pillar 3 — Context-Budget Guard. When a file exceeds either
+    // the byte or line gate we refuse to return the full body and
+    // instead hand the LLM a synthetic directive telling it to use
+    // the structural pre-scan tools (`extract_symbols` /
+    // `extract_imports`) instead. This prevents an LLM from
+    // dumping half the workspace into the context window.
+    if (stat.size > largeFileGateBytes ||
+        // Read just enough to count lines without holding the file in
+        // memory twice. `readFileSync` is unavoidable for the content
+        // path below, so accept the cost here.
+        countLines(resolved) > largeFileGateLines) {
+        return buildContextBudgetGuardDirective(resolved, stat.size, largeFileGateBytes, largeFileGateLines);
+    }
+    const content = fs.readFileSync(resolved, 'utf-8');
+    session?.noteRead(resolved);
+    return content;
+}
+/**
+ * Count lines in a file. Uses a streaming read so a 500 KB binary
+ * that has slipped past `isBinaryFile` cannot OOM the process.
+ */
+function countLines(filePath) {
+    let count = 0;
+    let sawNewline = true;
+    const stream = fs.openSync(filePath, 'r');
+    try {
+        const buf = Buffer.allocUnsafe(64 * 1024);
+        let bytesRead = 0;
+        while ((bytesRead = fs.readSync(stream, buf, 0, buf.length, null)) > 0) {
+            for (let i = 0; i < bytesRead; i++) {
+                if (buf[i] === 0x0a) {
+                    count++;
+                    sawNewline = true;
+                }
+                else {
+                    sawNewline = false;
+                }
+            }
+        }
+        if (!sawNewline)
+            count++;
+    }
+    finally {
+        fs.closeSync(stream);
+    }
+    return count;
+}
+/**
+ * Build the [Context-Budget Guard] directive returned to the LLM
+ * when `read_file` would otherwise flood the context window.
+ */
+function buildContextBudgetGuardDirective(resolved, bytes, byteLimit, lineLimit) {
+    const relPath = path.relative(process.cwd(), resolved) || resolved;
+    return (`[Context-Budget Guard] File '${relPath}' is ${(bytes / 1024).toFixed(1)} KiB ` +
+        `(> ${(byteLimit / 1024).toFixed(0)} KiB) or exceeds ${lineLimit} lines. ` +
+        `Full body suppressed to protect the context window. ` +
+        `Call extract_symbols(path='${relPath}') to list top-level declarations, ` +
+        `or extract_imports(path='${relPath}') to list dependencies, before ` +
+        `narrowing your read with a tool like search_code.`);
+}
+/**
+ * Resolve a file's `LanguageId` from its extension. Falls back to
+ * 'generic' for unrecognised suffixes.
+ */
+function resolveLanguageId(filePath) {
+    return languageIdFromExtension(path.extname(filePath));
+}
+async function executeExtractSymbols(filePath, cwd, session) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    if (!fs.existsSync(resolved)) {
+        return `Error: File not found: ${filePath}`;
+    }
+    if (guard.isBinaryFile(resolved)) {
+        return `Error: File appears to be binary: ${filePath}`;
+    }
+    const content = fs.readFileSync(resolved, 'utf-8');
+    const language = resolveLanguageId(resolved);
+    const parser = await ParserFactory.getParser();
+    const symbols = parser.extractSymbols(content, language);
+    session?.noteStructuralMap?.(resolved, { symbols: true, imports: false });
+    if (symbols.length === 0) {
+        return `No symbols detected in '${filePath}' (language=${language}).`;
+    }
+    const lines = symbols.map((s) => `- [${s.kind}${s.exported ? ', exported' : ''}] ${s.name} (line ${s.line})`);
+    return `Symbols in '${filePath}' (${symbols.length}):\n${lines.join('\n')}`;
+}
+async function executeExtractImports(filePath, cwd, session) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    if (!fs.existsSync(resolved)) {
+        return `Error: File not found: ${filePath}`;
+    }
+    if (guard.isBinaryFile(resolved)) {
+        return `Error: File appears to be binary: ${filePath}`;
+    }
+    const content = fs.readFileSync(resolved, 'utf-8');
+    const language = resolveLanguageId(resolved);
+    const parser = await ParserFactory.getParser();
+    const imports = parser.extractImports(content, language);
+    session?.noteStructuralMap?.(resolved, { symbols: false, imports: true });
+    if (imports.length === 0) {
+        return `No imports detected in '${filePath}' (language=${language}).`;
+    }
+    const lines = imports.map((i) => {
+        const tag = i.isTypeOnly ? ' [type-only]' : '';
+        const syms = i.symbols.length > 0 ? ` {${i.symbols.join(', ')}}` : '';
+        return `- '${i.source}'${tag}${syms} (line ${i.line})`;
+    });
+    return `Imports in '${filePath}' (${imports.length}):\n${lines.join('\n')}`;
+}
+function executeWriteFile(filePath, content, cwd, options = {}) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    // Pillar 5 / Protection 1 — refuse to mutate the platform's
+    // own runtime. This is the guard that prevents an autonomous
+    // agent from corrupting `src/agent/tool-executor.ts` and
+    // breaking its own host.
+    try {
+        guard.assertNotPlatformPath(resolved);
+    }
+    catch (err) {
+        if (err instanceof PlatformPathLockedError) {
+            return Promise.resolve(err.message);
+        }
+        throw err;
+    }
+    const mutation = options.session?.canMutate(resolved);
+    if (mutation && !mutation.ok)
+        return Promise.resolve(`Error: ${mutation.reason}`);
+    options.session?.captureBefore(resolved);
+    const existed = fs.existsSync(resolved);
+    return applyAtomicWrite(cwd, filePath, content, options.safety, options.session)
+        .then(() => {
+        if (!existed)
+            return `File created: ${filePath}`;
+        // Existing file — print the diff for the user.
+        try {
+            const relativePath = guard.relative(resolved);
+            const result = spawnSync('git', ['diff', '--color=always', '--', relativePath], { cwd, encoding: 'utf-8' });
+            if (result.status === 0 && result.stdout) {
+                const diffOutput = result.stdout.trim();
+                if (diffOutput) {
+                    console.log(`\n${colors.cyan}--- File Changes Diff ---${colors.reset}`);
+                    const lines = diffOutput.split('\n');
+                    if (lines.length > 50) {
+                        console.log(lines.slice(0, 48).join('\n') + `\n${colors.yellow}... (diff truncated)${colors.reset}`);
+                    }
+                    else {
+                        console.log(diffOutput);
+                    }
+                    console.log(`${colors.cyan}-------------------------${colors.reset}\n`);
+                }
+            }
+        }
+        catch {
+            // Fail-safe diff printing
+        }
+        return `File updated: ${filePath}`;
+    });
+}
+function executeRunCommand(command, requestedCwd, workspaceRoot, session) {
+    const guard = new WorkspaceGuard(workspaceRoot);
+    const commandCwd = guard.resolve(requestedCwd, 'command cwd');
+    try {
+        const result = spawnSync(command, {
+            shell: true,
+            cwd: commandCwd,
+            encoding: 'utf-8',
+            timeout: 60_000, // 60 second timeout
+            maxBuffer: 1024 * 1024, // 1MB max output
+            env: redactedEnv(),
+        });
+        const output = redactSecrets([result.stdout ?? '', result.stderr ?? ''].filter(Boolean).join('\n'));
+        const status = result.status ?? 0;
+        session?.record('command_finished', { command, cwd: guard.relative(commandCwd), status, output: truncate(output, 4000) });
+        return output || `(command completed with code ${status})`;
+    }
+    catch (error) {
+        const stdout = error.stdout ?? '';
+        const stderr = error.stderr ?? '';
+        const code = error.status ?? 'unknown';
+        return redactSecrets(`Command exited with code ${code}\n\nSTDOUT:\n${stdout}\n\nSTDERR:\n${stderr}`.trim());
+    }
+}
+function executeSearchCode(query, searchPath, filePattern, cwd) {
+    const guard = new WorkspaceGuard(cwd);
+    const targetDir = searchPath ? guard.resolve(searchPath, 'search path') : cwd;
+    // Try ripgrep first
+    let hasRg = false;
+    try {
+        const which = spawnSync('which', ['rg'], { encoding: 'utf-8' });
+        if (which.status === 0 && which.stdout.trim()) {
+            hasRg = true;
+        }
+    }
+    catch (error) {
+        if (process.env.DEBUG || process.env.VERBOSE || process.argv.includes('--verbose')) {
+            console.warn(`[Debug Warning] Failed to determine if ripgrep (rg) is installed: ${error.message || error}`);
+        }
+    }
+    let output = '';
+    if (hasRg) {
+        const args = ['-n', '--no-heading', '--color', 'never', query];
+        if (filePattern) {
+            args.push('-g', filePattern);
+        }
+        args.push(targetDir);
+        const result = spawnSync('rg', args, {
+            encoding: 'utf-8',
+            cwd,
+            maxBuffer: 512 * 1024,
+            timeout: 15000,
+        });
+        output = result.stdout ?? '';
+    }
+    else {
+        // Fallback to grep
+        const args = ['-rn', query];
+        if (filePattern) {
+            args.push(`--include=${filePattern}`);
+        }
+        args.push(targetDir);
+        const result = spawnSync('grep', args, {
+            encoding: 'utf-8',
+            cwd,
+            maxBuffer: 512 * 1024,
+            timeout: 15000,
+        });
+        output = result.stdout ?? '';
+    }
+    if (!output.trim()) {
+        return `No matches found for "${query}"`;
+    }
+    // Make paths relative to workspace and limit to 50 results
+    const lines = output.trim().split('\n').slice(0, 50).map((line) => {
+        if (line.startsWith(cwd)) {
+            return line.slice(cwd.length + 1);
+        }
+        return line;
+    });
+    return lines.join('\n');
+}
+function executeListDir(dirPath, cwd) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = dirPath ? guard.resolve(dirPath, 'directory') : cwd;
+    if (!fs.existsSync(resolved)) {
+        return `Error: Directory not found: ${dirPath ?? '.'}`;
+    }
+    const stat = fs.statSync(resolved);
+    if (!stat.isDirectory()) {
+        return `Error: "${dirPath}" is a file, not a directory. Use read_file instead.`;
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(resolved, { withFileTypes: true });
+    }
+    catch (error) {
+        return `Error: Cannot read directory: ${error instanceof Error ? error.message : String(error)}`;
+    }
+    // Filter and sort
+    const filtered = entries
+        .filter((e) => !e.name.startsWith('.') || e.name === '.env.example')
+        .filter((e) => e.name !== 'node_modules')
+        .sort((a, b) => {
+        if (a.isDirectory() !== b.isDirectory())
+            return a.isDirectory() ? -1 : 1;
+        return a.name.localeCompare(b.name);
+    });
+    const lines = [];
+    for (const entry of filtered) {
+        if (entry.isDirectory()) {
+            lines.push(`📁 ${entry.name}/`);
+        }
+        else {
+            let size = '';
+            try {
+                const s = fs.statSync(path.join(resolved, entry.name));
+                size = formatSize(s.size);
+            }
+            catch {
+                // Ignore
+            }
+            lines.push(`   ${entry.name}${size ? `  (${size})` : ''}`);
+        }
+    }
+    return lines.join('\n') || '(empty directory)';
+}
+/* ──────────────────────── Helpers ──────────────────────── */
+function resolvePath(filePath, cwd) {
+    if (path.isAbsolute(filePath))
+        return filePath;
+    return path.resolve(cwd, filePath);
+}
+function shortenPath(filePath, cwd) {
+    try {
+        const guard = new WorkspaceGuard(cwd);
+        return guard.relative(guard.resolve(filePath, 'path'));
+    }
+    catch {
+        return filePath;
+    }
+}
+function truncate(text, maxLen) {
+    if (text.length <= maxLen)
+        return text;
+    return text.slice(0, maxLen - 1) + '…';
+}
+function formatSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+function executeDeleteFile(filePath, cwd, session) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    const mutation = session?.canMutate(resolved);
+    if (mutation && !mutation.ok)
+        return `Error: ${mutation.reason}`;
+    session?.captureBefore(resolved);
+    if (!fs.existsSync(resolved)) {
+        return `Error: File not found: ${filePath}`;
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        return `Error: "${filePath}" is a directory. delete_file can only delete files.`;
+    }
+    fs.unlinkSync(resolved);
+    session?.noteChange(resolved);
+    return `File deleted: ${filePath}`;
+}
+function executeApplyPatch(patch, cwd, options = {}) {
+    if (!patch?.trim())
+        return Promise.resolve('Error: patch is required.');
+    const guard = new WorkspaceGuard(cwd);
+    // Pillar 5 — refuse to apply patches that target platform
+    // runtime files. The `git apply` invocation would otherwise
+    // succeed in corrupting our own source.
+    for (const file of filesFromPatch(patch)) {
+        try {
+            const resolved = guard.resolve(file, 'patch target');
+            guard.assertNotPlatformPath(resolved);
+        }
+        catch (err) {
+            if (err instanceof PlatformPathLockedError) {
+                return Promise.resolve(err.message);
+            }
+            if (err instanceof Error) {
+                return Promise.resolve(`Error: ${err.message}`);
+            }
+            throw err;
+        }
+    }
+    for (const file of filesFromPatch(patch)) {
+        try {
+            options.session?.captureBefore(file);
+        }
+        catch { /* best effort */ }
+    }
+    const result = spawnSync('git', ['apply', '--whitespace=nowarn', '-'], {
+        cwd,
+        input: patch,
+        encoding: 'utf-8',
+        timeout: 30_000,
+        maxBuffer: 1024 * 1024,
+    });
+    if (result.status !== 0)
+        return Promise.resolve(`Patch failed:\n${result.stderr || result.stdout}`);
+    for (const file of filesFromPatch(patch)) {
+        try {
+            options.session?.noteChange(file);
+        }
+        catch { /* best effort */ }
+    }
+    return Promise.resolve('Patch applied.');
+}
+function executeReplaceRange(filePath, startLine, endLine, content, cwd, options = {}) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    try {
+        guard.assertNotPlatformPath(resolved);
+    }
+    catch (err) {
+        if (err instanceof PlatformPathLockedError)
+            return Promise.resolve(err.message);
+        throw err;
+    }
+    const mutation = options.session?.canMutate(resolved);
+    if (mutation && !mutation.ok)
+        return Promise.resolve(`Error: ${mutation.reason}`);
+    options.session?.captureBefore(resolved);
+    const original = fs.readFileSync(resolved, 'utf-8');
+    const lines = original.split('\n');
+    if (!Number.isInteger(startLine) || !Number.isInteger(endLine) || startLine < 1 || endLine < startLine || endLine > lines.length) {
+        return Promise.resolve(`Error: invalid line range ${startLine}-${endLine}.`);
+    }
+    lines.splice(startLine - 1, endLine - startLine + 1, ...content.split('\n'));
+    return applyAtomicWrite(cwd, filePath, lines.join('\n'), options.safety, options.session)
+        .then(() => `Replaced ${filePath}:${startLine}-${endLine}.`);
+}
+function executeInsertAfter(filePath, anchor, content, cwd, options = {}) {
+    const guard = new WorkspaceGuard(cwd);
+    const resolved = guard.resolve(filePath, 'file');
+    try {
+        guard.assertNotPlatformPath(resolved);
+    }
+    catch (err) {
+        if (err instanceof PlatformPathLockedError)
+            return Promise.resolve(err.message);
+        throw err;
+    }
+    const mutation = options.session?.canMutate(resolved);
+    if (mutation && !mutation.ok)
+        return Promise.resolve(`Error: ${mutation.reason}`);
+    options.session?.captureBefore(resolved);
+    const original = fs.readFileSync(resolved, 'utf-8');
+    const idx = original.indexOf(anchor);
+    if (idx === -1)
+        return Promise.resolve(`Error: anchor not found in ${filePath}.`);
+    const insertAt = idx + anchor.length;
+    const next = original.slice(0, insertAt) + content + original.slice(insertAt);
+    return applyAtomicWrite(cwd, filePath, next, options.safety, options.session)
+        .then(() => `Inserted content in ${filePath}.`);
+}
+function executeRenameFile(from, to, cwd, options = {}) {
+    const guard = new WorkspaceGuard(cwd);
+    const source = guard.resolve(from, 'source file');
+    const target = guard.resolve(to, 'target file');
+    try {
+        guard.assertNotPlatformPath(source);
+        guard.assertNotPlatformPath(target);
+    }
+    catch (err) {
+        if (err instanceof PlatformPathLockedError)
+            return Promise.resolve(err.message);
+        throw err;
+    }
+    const mutation = options.session?.canMutate(source);
+    if (mutation && !mutation.ok)
+        return Promise.resolve(`Error: ${mutation.reason}`);
+    options.session?.captureBefore(source);
+    options.session?.captureBefore(target);
+    fs.mkdirSync(path.dirname(target), { recursive: true });
+    fs.renameSync(source, target);
+    options.session?.noteChange(source);
+    options.session?.noteChange(target);
+    return Promise.resolve(`Renamed ${from} -> ${to}.`);
+}
+function filesFromPatch(patch) {
+    const files = new Set();
+    for (const line of patch.split('\n')) {
+        if (line.startsWith('+++ b/'))
+            files.add(line.slice(6));
+        else if (line.startsWith('--- a/'))
+            files.add(line.slice(6));
+    }
+    return Array.from(files).filter(file => file !== '/dev/null');
+}
+/* ──────────────────── Typed errors ──────────────────── */
+/**
+ * Thrown by the `str_replace` tool when the replacement cannot be
+ * applied. The error is surfaced to the model as a structured tool
+ * result so the next turn can react to the precise reason.
+ */
+export class SurgicalReplaceError extends Error {
+    code;
+    details;
+    constructor(message, code, details = {}) {
+        super(message);
+        this.name = 'SurgicalReplaceError';
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * Thrown by the `glob_files` tool for any non-recoverable traversal
+ * failure (workspace escape, invalid pattern, etc.).
+ */
+export class GlobFilesError extends Error {
+    code;
+    details;
+    constructor(message, code, details = {}) {
+        super(message);
+        this.name = 'GlobFilesError';
+        this.code = code;
+        this.details = details;
+    }
+}
+export class TodoWriteError extends Error {
+    code;
+    details;
+    constructor(message, code, details = {}) {
+        super(message);
+        this.name = 'TodoWriteError';
+        this.code = code;
+        this.details = details;
+    }
+}
+/* ──────────────────── todo_read implementation ──────────────────── */
+/**
+ * Read the current todo list from `<cwd>/.fixo/todo_list.json`.
+ * Always succeeds — a missing or unreadable file returns an
+ * empty list (the loader is fault-tolerant by design).
+ */
+export function executeTodoRead(cwd) {
+    const list = loadTodoList(cwd);
+    return renderTodoList(list);
+}
+/* ──────────────────── todo_write implementation ──────────────────── */
+const VALID_TODO_STATUSES = new Set([
+    'pending',
+    'in_progress',
+    'done',
+    'cancelled',
+]);
+/**
+ * Apply a todo mutation and persist the result. Rejected in
+ * `PLAN` mode (Pillar 1) — todo state is project-level
+ * metadata, not conversation state, so even an `add` would
+ * leak a write to disk.
+ */
+export async function executeTodoWrite(args, cwd, options = {}) {
+    if (options.mode === 'PLAN') {
+        return `Error: todo_write: rejected in PLAN mode (no on-disk mutations).`;
+    }
+    const op = args.op;
+    if (op !== 'add' && op !== 'set_status' && op !== 'remove' && op !== 'clear_done') {
+        throw new TodoWriteError(`todo_write: unknown op "${String(op)}"`, 'invalid_args', { op: String(op) });
+    }
+    let list = loadTodoList(cwd);
+    switch (op) {
+        case 'add': {
+            if (typeof args.content !== 'string' || args.content.trim().length === 0) {
+                throw new TodoWriteError('todo_write: "content" is required for op=add', 'invalid_args');
+            }
+            list = addItem(list, { content: args.content, blockedBy: args.blockedBy });
+            break;
+        }
+        case 'set_status': {
+            if (typeof args.id !== 'string' || args.id.length === 0) {
+                throw new TodoWriteError('todo_write: "id" is required for op=set_status', 'invalid_args');
+            }
+            if (!args.status || !VALID_TODO_STATUSES.has(args.status)) {
+                throw new TodoWriteError(`todo_write: "status" must be one of pending|in_progress|done|cancelled (got "${String(args.status)}")`, 'invalid_args');
+            }
+            const exists = list.items.some((it) => it.id === args.id);
+            if (!exists) {
+                throw new TodoWriteError(`todo_write: item id "${args.id}" not found`, 'not_found');
+            }
+            list = setItemStatus(list, { id: args.id, status: args.status });
+            break;
+        }
+        case 'remove': {
+            if (typeof args.id !== 'string' || args.id.length === 0) {
+                throw new TodoWriteError('todo_write: "id" is required for op=remove', 'invalid_args');
+            }
+            const exists = list.items.some((it) => it.id === args.id);
+            if (!exists) {
+                throw new TodoWriteError(`todo_write: item id "${args.id}" not found`, 'not_found');
+            }
+            list = removeItem(list, { id: args.id });
+            break;
+        }
+        case 'clear_done': {
+            list = clearDoneItems(list);
+            break;
+        }
+    }
+    const save = saveTodoList(cwd, list);
+    if (!save.ok) {
+        throw new TodoWriteError(`todo_write: failed to persist: ${save.error ?? 'unknown'}`, 'io_failure', {
+            path: save.path,
+        });
+    }
+    const summary = summariseTodoList(list);
+    recordTelemetry(telemetry.todoMutation({
+        op,
+        items: list.items.length,
+        id: typeof args.id === 'string' ? args.id : undefined,
+    }));
+    // Echo the rendered list back so the LLM can confirm
+    // its mutation took effect in the same turn.
+    return `${renderTodoList(list)}\n\n(summary: ${summary})`;
+}
+/* ──────────────────── run_command_async / poll_command_status / kill_command ────────── */
+/**
+ * Process-global registry of background jobs. Lazily created on
+ * the first call to `getBackgroundJobRegistry` so the tool
+ * dispatch is hot-path-friendly and test-friendly (tests inject
+ * a custom registry via {@link setBackgroundJobRegistry}).
+ */
+let globalBackgroundRegistry = null;
+const backgroundRegistries = new Map();
+export function getBackgroundJobRegistry(cwd) {
+    let reg = backgroundRegistries.get(cwd);
+    if (!reg) {
+        reg = new BackgroundJobRegistry(cwd);
+        backgroundRegistries.set(cwd, reg);
+    }
+    return reg;
+}
+/** Test-only: inject a custom registry. */
+export function setBackgroundJobRegistry(cwd, reg) {
+    if (reg === null) {
+        const existing = backgroundRegistries.get(cwd);
+        if (existing)
+            existing.shutdown();
+        backgroundRegistries.delete(cwd);
+        return;
+    }
+    const previous = backgroundRegistries.get(cwd);
+    if (previous)
+        previous.shutdown();
+    backgroundRegistries.set(cwd, reg);
+}
+export class BackgroundCommandError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.name = 'BackgroundCommandError';
+        this.code = code;
+    }
+}
+/**
+ * Spawn a long-running command and return its jobId without
+ * blocking. The tail buffers cap at 64 KiB per stream and the
+ * snapshot is fsynced to `<cwd>/.fixo/jobs/<jobId>.json` every
+ * 5 s so a crash does not lose the recent output.
+ */
+export async function executeRunCommandAsync(args, cwd, options = {}) {
+    if (options.mode === 'PLAN') {
+        return `Error: run_command_async: rejected in PLAN mode.`;
+    }
+    if (typeof args.cmd !== 'string' || args.cmd.trim().length === 0) {
+        throw new BackgroundCommandError('run_command_async: "cmd" is required', 'invalid_args');
+    }
+    const cmdArgs = Array.isArray(args.args) ? args.args.filter((a) => typeof a === 'string') : [];
+    const reg = getBackgroundJobRegistry(cwd);
+    const result = await reg.register({
+        cmd: args.cmd,
+        args: cmdArgs,
+        cwd: args.cwd ?? cwd,
+    });
+    if (!result.ok) {
+        throw new BackgroundCommandError(`run_command_async: ${result.error ?? 'unknown'}`, 'spawn_failed');
+    }
+    return JSON.stringify({
+        ok: true,
+        jobId: result.jobId,
+        pid: result.pid,
+        note: 'poll_command_status to retrieve output; kill_command to terminate',
+    });
+}
+export function executePollCommandStatus(args, cwd) {
+    if (typeof args.jobId !== 'string' || args.jobId.length === 0) {
+        throw new BackgroundCommandError('poll_command_status: "jobId" is required', 'invalid_args');
+    }
+    const reg = getBackgroundJobRegistry(cwd);
+    const snap = reg.poll({
+        jobId: args.jobId,
+        tailLines: args.tailLines,
+        sinceBytes: args.sinceBytes,
+    });
+    if (!snap) {
+        throw new BackgroundCommandError(`poll_command_status: no such job "${args.jobId}"`, 'no_such_job');
+    }
+    return JSON.stringify(snap, null, 2);
+}
+export function executeKillCommand(args, cwd) {
+    if (typeof args.jobId !== 'string' || args.jobId.length === 0) {
+        throw new BackgroundCommandError('kill_command: "jobId" is required', 'invalid_args');
+    }
+    const reg = getBackgroundJobRegistry(cwd);
+    const out = reg.kill(args.jobId);
+    if (!out.ok) {
+        throw new BackgroundCommandError(`kill_command: ${out.error ?? 'unknown'}`, 'no_such_job');
+    }
+    return JSON.stringify({ ok: true, jobId: args.jobId });
+}
+/** Helper exported for tests + subagent use. */
+export function shutdownAllBackgroundRegistries() {
+    for (const reg of backgroundRegistries.values())
+        reg.shutdown();
+    backgroundRegistries.clear();
+}
+/** Helper exported for `/jobs` slash command. */
+export function listAllBackgroundJobs(cwd) {
+    const reg = backgroundRegistries.get(cwd);
+    if (!reg)
+        return [];
+    return reg.list().map((j) => ({
+        id: j.id,
+        status: j.status,
+        exitCode: j.exitCode,
+        startedAt: j.startedAt,
+        exitedAt: j.exitedAt,
+        cmd: j.cmd,
+        args: j.args,
+        cwd: j.cwd,
+        stdout: j.stdoutTruncated ? `${j.stdout}\n...[truncated]` : j.stdout,
+        stderr: j.stderrTruncated ? `${j.stderr}\n...[truncated]` : j.stderr,
+        totalStdoutBytes: j.totalStdoutBytes,
+        totalStderrBytes: j.totalStderrBytes,
+        stdoutTruncated: j.stdoutTruncated,
+        stderrTruncated: j.stderrTruncated,
+    }));
+}
+/* ──────────────────── str_replace implementation ──────────────────── */
+/**
+ * Count non-overlapping occurrences of `needle` inside `haystack`.
+ * Linear scan with a moving cursor — no regex, no allocation.
+ */
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let from = 0;
+    while (true) {
+        const idx = haystack.indexOf(needle, from);
+        if (idx === -1)
+            return count;
+        count += 1;
+        from = idx + needle.length;
+    }
+}
+/**
+ * Apply a single in-place string replacement. Either replaces the
+ * first match (default) or every match (when `replaceAll` is true).
+ */
+function applyReplacement(content, oldString, newString, replaceAll) {
+    if (replaceAll) {
+        // Manual split/join is faster than String.prototype.replaceAll
+        // for large strings under V8 (avoids the internal RegExp).
+        return content.split(oldString).join(newString);
+    }
+    return content.replace(oldString, newString);
+}
+/**
+ * Implementation of the `str_replace` tool. Strictly typed and
+ * gated by all four safety pillars:
+ *
+ *   - Pillar 1 (Sandbox): `ctx.mode === 'PLAN'` is rejected.
+ *   - Pillar 5 (Self-Protection): platform-locked paths are
+ *     refused by `WorkspaceGuard.assertNotPlatformPath`.
+ *   - Pillar 2 (Atomic Staging): the final commit is funneled
+ *     through {@link AtomicStagingManager.applySurgicalReplace},
+ *     not a direct `fs.writeFileSync`.
+ *   - Pillar 3 (LSP pre-save): the staged content is checked by
+ *     the gate before commit. In `block` mode a syntax error
+ *     causes the edit to abort with the diagnostic reported back
+ *     to the model.
+ */
+export async function executeStrReplace(args, cwd, options = {}) {
+    const guard = new WorkspaceGuard(cwd);
+    // Validate the input.
+    if (typeof args.path !== 'string' || args.path.length === 0) {
+        return `Error: str_replace: "path" is required.`;
+    }
+    if (typeof args.oldString !== 'string') {
+        return `Error: str_replace: "oldString" is required.`;
+    }
+    if (typeof args.newString !== 'string') {
+        return `Error: str_replace: "newString" is required.`;
+    }
+    // Pillar 1 — refuse in PLAN mode.
+    if (options.mode === 'PLAN') {
+        const err = new SurgicalReplaceError(`str_replace is not allowed in PLAN mode (read-only). Switch to BUILD mode and retry.`, 'plan_mode_rejected', { mode: options.mode });
+        return `Error: ${err.message}`;
+    }
+    // Workspace boundary check.
+    let resolved;
+    try {
+        resolved = guard.resolve(args.path, 'str_replace target');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `Error: str_replace: ${msg}`;
+    }
+    // Pillar 5 — refuse platform-locked paths.
+    try {
+        guard.assertNotPlatformPath(resolved);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `Error: ${msg}`;
+    }
+    if (!fs.existsSync(resolved)) {
+        return `Error: str_replace: file not found: ${args.path}`;
+    }
+    if (guard.isBinaryFile(resolved)) {
+        return `Error: str_replace: file appears to be binary: ${args.path}`;
+    }
+    // Load the current content.
+    const content = fs.readFileSync(resolved, 'utf-8');
+    const occurrences = countOccurrences(content, args.oldString);
+    const replaceAll = args.replaceAll === true;
+    // The uniqueness gate only fires when the caller has not already
+    // opted in to non-unique semantics via `replaceAll` or by
+    // explicitly setting `expectUnique: false`.
+    const expectUnique = !replaceAll && args.expectUnique !== false;
+    if (occurrences === 0) {
+        return `Error: str_replace: oldString not found in ${args.path}.`;
+    }
+    if (occurrences > 1 && expectUnique) {
+        return `Error: str_replace: oldString appears ${occurrences} times in ${args.path}. ` +
+            `Pass replaceAll=true or expectUnique=false to proceed.`;
+    }
+    const newContent = applyReplacement(content, args.oldString, args.newString, replaceAll);
+    const bytes = Buffer.byteLength(newContent, 'utf-8');
+    // Pillar 3 — LSP pre-save compilation gate. The gate's
+    // `enforce` throws on `block`-mode failures; we surface the
+    // diagnostics to the LLM as a structured error.
+    if (options.safety?.lspPreSave && options.safety.lspPreSave !== 'off') {
+        try {
+            const gate = getOrCreateLspGate(cwd, options.safety);
+            const synthetic = {
+                id: 'surgical-' + Date.now().toString(36),
+                targetPath: resolved,
+                pendingPath: '<surgical>',
+                metaPath: '<surgical>',
+                createdAt: Date.now(),
+                mode: 0o644,
+            };
+            const result = await gate.check(synthetic);
+            gate.enforce(result, synthetic);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            return `Error: str_replace: ${msg}`;
+        }
+    }
+    // Pillar 2 — atomic staging. Route the new content through the
+    // staging manager's new surgical-replace method.
+    try {
+        const mgr = new AtomicStagingManager(cwd, getOrCreateRunId());
+        const result = await mgr.applySurgicalReplace(resolved, newContent, {
+            runId: mgr.runId,
+            reason: 'str_replace',
+            actorId: options.session?.id ?? 'tool-executor',
+        });
+        // Telemetry.
+        try {
+            const { recordTelemetry, telemetry } = await import('./telemetry.js');
+            recordTelemetry(telemetry.surgicalEdit({
+                path: args.path,
+                occurrences: replaceAll ? occurrences : 1,
+                mode: options.safety?.lspPreSave ?? 'off',
+                bytes: result.bytes,
+            }));
+        }
+        catch {
+            // Telemetry must never break a tool call.
+        }
+        options.session?.noteChange(resolved);
+        return JSON.stringify({
+            ok: true,
+            path: args.path,
+            occurrences: replaceAll ? occurrences : 1,
+            mode: options.safety?.lspPreSave ?? 'off',
+            bytes: result.bytes,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `Error: str_replace: ${msg}`;
+    }
+}
+/* ──────────────────── glob_files implementation ──────────────────── */
+const GLOB_DEFAULT_MAX_RESULTS = 1000;
+const GLOB_HARD_MAX_RESULTS = 5000;
+const GLOB_DEFAULT_SKIP_DIRS = [
+    'node_modules',
+    '.git',
+    'dist',
+    '.fixo',
+    '.fixocli',
+];
+/**
+ * Split a comma-separated ignore spec into an array. Tolerates
+ * stray whitespace and empty entries.
+ */
+function splitIgnoreSpec(spec) {
+    if (!spec)
+        return [];
+    return spec
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+}
+/**
+ * Implementation of the `glob_files` tool. Strictly typed,
+ * workspace-bounded, and capped.
+ *
+ * Uses Node 22+ native `fs.promises.glob` for performance. Falls
+ * back to a manual recursive walker on Node < 22 (which the
+ * project's `package.json` already requires) so the tool is
+ * always functional.
+ */
+export async function executeGlobFiles(args, cwd, _options = {}) {
+    if (typeof args.pattern !== 'string' || args.pattern.length === 0) {
+        return `Error: glob_files: "pattern" is required.`;
+    }
+    const guard = new WorkspaceGuard(cwd);
+    let scope;
+    try {
+        scope = args.cwd ? guard.resolve(args.cwd, 'glob scope') : cwd;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `Error: glob_files: ${msg}`;
+    }
+    const maxResults = Math.min(Math.max(args.maxResults ?? GLOB_DEFAULT_MAX_RESULTS, 1), GLOB_HARD_MAX_RESULTS);
+    const skipDirs = new Set(GLOB_DEFAULT_SKIP_DIRS);
+    for (const extra of splitIgnoreSpec(args.ignore)) {
+        skipDirs.add(extra);
+    }
+    const includeHidden = args.includeHidden === true;
+    const followSymlinks = args.followSymlinks === true;
+    // Collect matching paths.
+    let matches;
+    try {
+        matches = await collectGlobMatches({
+            pattern: args.pattern,
+            scope,
+            skipDirs,
+            includeHidden,
+            followSymlinks,
+            maxResults: maxResults + 1,
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return `Error: glob_files: ${msg}`;
+    }
+    const truncated = matches.length > maxResults;
+    const returned = truncated ? matches.slice(0, maxResults) : matches;
+    const total = matches.length;
+    // Telemetry.
+    try {
+        const { recordTelemetry, telemetry } = await import('./telemetry.js');
+        recordTelemetry(telemetry.glob({
+            pattern: args.pattern,
+            returned: returned.length,
+            truncated,
+        }));
+    }
+    catch {
+        // Telemetry must never break a tool call.
+    }
+    if (returned.length === 0) {
+        return JSON.stringify({ pattern: args.pattern, matches: [], total: 0, truncated: false });
+    }
+    return JSON.stringify({
+        pattern: args.pattern,
+        matches: returned.map((p) => path.relative(cwd, p) || p),
+        total,
+        truncated,
+    });
+}
+/**
+ * Collect paths matching `pattern` under `scope`. Prefers Node 22+
+ * native `fs.promises.glob`; falls back to a manual recursive
+ * walker on older runtimes. Both branches honour the skip set
+ * and hidden-file policy.
+ */
+async function collectGlobMatches(opts) {
+    const { pattern, scope, skipDirs, includeHidden, followSymlinks, maxResults } = opts;
+    const results = [];
+    // Try native fs.promises.glob first.
+    const fsPromises = fs.promises;
+    if (typeof fsPromises.glob === 'function') {
+        const exclude = Array.from(skipDirs).map((d) => `**/${d}/**`);
+        const out = (await fsPromises.glob(pattern, {
+            cwd: scope,
+            exclude,
+            withFileTypes: false,
+        }));
+        if (Array.isArray(out)) {
+            for (const entry of out) {
+                if (typeof entry !== 'string')
+                    continue;
+                const absolute = path.resolve(scope, entry);
+                if (results.length >= maxResults)
+                    break;
+                // The native glob does not surface whether symlinks were
+                // followed; perform a defensive lstat and skip dotfiles if
+                // the user did not opt in.
+                try {
+                    if (!includeHidden && path.basename(absolute).startsWith('.'))
+                        continue;
+                }
+                catch {
+                    continue;
+                }
+                results.push(absolute);
+            }
+            return results;
+        }
+    }
+    // Manual fallback — recursive walker with built-in pattern
+    // matcher. Supports `**`, `*`, and literal segments.
+    const matcher = compileGlob(pattern);
+    const walk = async (dir) => {
+        if (results.length >= maxResults)
+            return;
+        let entries;
+        try {
+            entries = await fs.promises.readdir(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (results.length >= maxResults)
+                return;
+            if (!includeHidden && entry.name.startsWith('.'))
+                continue;
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (skipDirs.has(entry.name))
+                    continue;
+                if (!followSymlinks) {
+                    try {
+                        const lst = await fs.promises.lstat(full);
+                        if (lst.isSymbolicLink())
+                            continue;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                await walk(full);
+            }
+            else if (entry.isFile()) {
+                if (!includeHidden && entry.name.startsWith('.'))
+                    continue;
+                if (skipDirs.has(entry.name))
+                    continue;
+                if (!followSymlinks) {
+                    try {
+                        const lst = await fs.promises.lstat(full);
+                        if (lst.isSymbolicLink())
+                            continue;
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                if (matcher(path.relative(scope, full) || entry.name)) {
+                    results.push(full);
+                }
+            }
+        }
+    };
+    await walk(scope);
+    return results;
+}
+/**
+ * Compile a small subset of glob syntax into a predicate. Supports:
+ *   - `**`  → any number of path segments
+ *   - `*`   → any characters within a single segment
+ *   - `?`   → any single character
+ *   - everything else is a literal
+ *
+ * The matcher operates on forward-slash paths regardless of host
+ * platform. This is intentionally tiny — Node 22+'s native
+ * `fs.promises.glob` covers the common case; the fallback exists
+ * for environments where the native API is unavailable.
+ */
+function compileGlob(pattern) {
+    // Normalise separators.
+    const normalised = pattern.replace(/\\/g, '/');
+    const re = globToRegExp(normalised);
+    return (rel) => re.test(rel.replace(/\\/g, '/'));
+}
+/**
+ * Convert a glob pattern to a regular expression. Faithful to the
+ * small subset documented on {@link compileGlob}.
+ */
+function globToRegExp(pattern) {
+    let body = '';
+    let i = 0;
+    while (i < pattern.length) {
+        const ch = pattern[i];
+        if (ch === '*') {
+            if (pattern[i + 1] === '*') {
+                body += '.*';
+                i += 2;
+                // Consume an optional following slash so `**/foo` works.
+                if (pattern[i] === '/')
+                    i += 1;
+            }
+            else {
+                body += '[^/]*';
+                i += 1;
+            }
+        }
+        else if (ch === '?') {
+            body += '[^/]';
+            i += 1;
+        }
+        else if ('\\^$.|+()[]{}'.includes(ch)) {
+            body += '\\' + ch;
+            i += 1;
+        }
+        else {
+            body += ch;
+            i += 1;
+        }
+    }
+    return new RegExp('^' + body + '$');
+}
+/* ──────────────────── Tool Specification Registry ──────────────────── */
+/**
+ * Process-global registry of typed tool specifications. New tools
+ * register themselves here; the existing `TOOL_DEFINITIONS` array
+ * remains the LLM-facing JSON-Schema surface. Both surfaces are
+ * kept in lock-step by the executor's dispatch path.
+ *
+ * The registry stores entries as `ToolSpecification<Record<string, any>, string>`
+ * for compatibility with the existing switch dispatch. Strongly-typed
+ * callers can cast at the call site.
+ */
+const toolRegistry = new Map();
+/** Register a typed tool specification. Throws on duplicate. */
+export function registerTool(spec) {
+    if (toolRegistry.has(spec.name)) {
+        throw new Error(`Tool "${spec.name}" is already registered.`);
+    }
+    toolRegistry.set(spec.name, spec);
+}
+/** Look up a registered tool specification. */
+export function getToolSpecification(name) {
+    return toolRegistry.get(name);
+}
+/** List the names of all registered typed tools. */
+export function listRegisteredToolNames() {
+    return Array.from(toolRegistry.keys()).sort();
+}
+/* ──────────────────── Built-in Typed Registrations ──────────────────── */
+registerTool({
+    name: 'str_replace',
+    description: 'Use this tool by default for any in-place edit to an existing file. Performs a surgical, atomic replacement of oldString with newString. By default, oldString must be unique within the file (expectUnique=true) — non-unique matches are rejected with a clear error so the caller can narrow the snippet. Pass replaceAll=true to substitute every occurrence. Rejected in PLAN mode. Refused for platform-locked paths. Goes through the same atomic staging pipeline as write_file and the LSP pre-save gate before any disk mutation.',
+    parameters: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'The file path to edit.' },
+            oldString: { type: 'string', description: 'The substring to replace.' },
+            newString: { type: 'string', description: 'The replacement content.' },
+            replaceAll: { type: 'boolean', description: 'Replace every occurrence.' },
+            expectUnique: {
+                type: 'boolean',
+                description: 'Abort when oldString is not unique.',
+            },
+        },
+        required: ['path', 'oldString', 'newString'],
+    },
+    async execute(args, ctx) {
+        return executeStrReplace(args, ctx.cwd, ctx.options);
+    },
+});
+registerTool({
+    name: 'glob_files',
+    description: 'High-performance filesystem pattern matcher. Returns paths matching the given glob pattern, relative to the workspace root. Built on Node 22+ native fs.promises.glob. By default, common build/VCS directories (node_modules, .git, dist, .fixo, .fixocli) are excluded. Symlinks are not followed and hidden files are excluded unless explicitly enabled. Capped at maxResults (default 1000, hard cap 5000).',
+    parameters: {
+        type: 'object',
+        properties: {
+            pattern: { type: 'string', description: 'Glob pattern, e.g. "src/**/*.ts"' },
+            cwd: { type: 'string', description: 'Optional scope directory.' },
+            ignore: { type: 'string', description: 'Optional extra ignore patterns.' },
+            maxResults: { type: 'integer', description: 'Cap on returned matches.' },
+            includeHidden: { type: 'boolean', description: 'Include dotfile entries.' },
+            followSymlinks: { type: 'boolean', description: 'Follow symbolic links.' },
+        },
+        required: ['pattern'],
+    },
+    async execute(args, ctx) {
+        return executeGlobFiles(args, ctx.cwd, ctx.options);
+    },
+});
+registerTool({
+    name: 'todo_read',
+    description: 'Read the current project todo list from <cwd>/.fixo/todo_list.json. Returns a human-readable rendering of all items, grouped into Open and Completed. Missing or unreadable files yield an empty list — this is by design so the agent can always inspect todo state.',
+    parameters: {
+        type: 'object',
+        properties: {},
+        required: [],
+    },
+    async execute(_args, ctx) {
+        return executeTodoRead(ctx.cwd);
+    },
+});
+registerTool({
+    name: 'todo_write',
+    description: 'Mutate the project todo list. Operations: add (content+blockedBy optional), set_status (id+status), remove (id), clear_done. Persisted atomically to <cwd>/.fixo/todo_list.json. Rejected in PLAN mode. Status values: pending | in_progress | done | cancelled.',
+    parameters: {
+        type: 'object',
+        properties: {
+            op: { type: 'string', enum: ['add', 'set_status', 'remove', 'clear_done'] },
+            content: { type: 'string', description: 'Item content (op=add only).' },
+            id: { type: 'string', description: 'Item id (op=set_status, op=remove).' },
+            status: { type: 'string', enum: ['pending', 'in_progress', 'done', 'cancelled'] },
+            blockedBy: { type: 'string', description: 'Optional blocker (op=add).' },
+        },
+        required: ['op'],
+    },
+    async execute(args, ctx) {
+        return executeTodoWrite(args, ctx.cwd, ctx.options);
+    },
+});
+registerTool({
+    name: 'run_command_async',
+    description: 'Spawn a long-running command in the background. Returns a jobId. Streams cap at 64 KiB; tail buffers survive a crash via the .fixo/jobs/<jobId>.json snapshot. Rejected in PLAN mode. Workspace-escape and sensitive-file commands are blocked at spawn time.',
+    parameters: {
+        type: 'object',
+        properties: {
+            cmd: { type: 'string', description: 'The binary to spawn.' },
+            args: { type: 'array', items: { type: 'string' } },
+            cwd: { type: 'string' },
+        },
+        required: ['cmd'],
+    },
+    async execute(args, ctx) {
+        return executeRunCommandAsync(args, ctx.cwd, ctx.options);
+    },
+});
+registerTool({
+    name: 'poll_command_status',
+    description: 'Read a snapshot of a background job. Honours tailLines (last N lines per stream) and sinceBytes (return only the bytes after this offset on stdout/stderr).',
+    parameters: {
+        type: 'object',
+        properties: {
+            jobId: { type: 'string' },
+            tailLines: { type: 'integer' },
+            sinceBytes: { type: 'integer' },
+        },
+        required: ['jobId'],
+    },
+    async execute(args, ctx) {
+        return executePollCommandStatus(args, ctx.cwd);
+    },
+});
+registerTool({
+    name: 'kill_command',
+    description: 'SIGTERM a background job by jobId.',
+    parameters: {
+        type: 'object',
+        properties: {
+            jobId: { type: 'string' },
+        },
+        required: ['jobId'],
+    },
+    async execute(args, ctx) {
+        return executeKillCommand(args, ctx.cwd);
+    },
+});
+//# sourceMappingURL=tool-executor.js.map