fixo-cli 1.0.3 → 2.0.0

package/dist/agent/tool-executor.js

@@ -2,18 +2,23 @@
  * Tool definitions and executor for the single-agent tool-calling loop.
  * Provides: read_file, write_file, run_command, search_code, list_dir
  */
+import { TOOL_DEFINITIONS } from './tool-definitions.js';
+export { TOOL_DEFINITIONS };
 import fs from 'fs';
 import path from 'path';
 import { spawnSync } from 'child_process';
+import { randomBytes } from 'node:crypto';
 import { colors } from '../ui/colors.js';
 import { renderToolCall, startInlineToolSpinner, } 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 { runSandboxed, SandboxUnavailableError } from '../runtime/os-sandbox.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 { GitManager } from '../git/git-manager.js';
 import { pathToFileURL } from 'url';
 import * as p from '@clack/prompts';
 import { loadConfig, saveConfig } from '../config.js';
@@ -29,6 +34,7 @@ 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';
+import { getRunInventory } from '../runtime/run-inventory.js';
 export const mcpManager = new McpManager();
 export const mcpBridgeManager = new McpBridgeManager();
 let lspManagerInstance = null;
@@ -192,524 +198,6 @@ export function classifyExecutionRole(task) {
     }
     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;
 /**
@@ -720,8 +208,10 @@ let cachedRunId = null;
 export function getOrCreateRunId() {
     if (cachedRunId)
         return cachedRunId;
-    cachedRunId = Math.random().toString(36).slice(2, 8) +
-        Date.now().toString(36).slice(-6);
+    // Use crypto.randomBytes for collision-free staging namespace IDs.
+    // Math.random() has a 1-in-2^30 collision chance; crypto.randomBytes
+    // is cryptographically secure and eliminates any collision risk.
+    cachedRunId = randomBytes(6).toString('hex') + Date.now().toString(36).slice(-6);
     return cachedRunId;
 }
 /** Test/utility hook — reset the cached run id. */
@@ -902,6 +392,20 @@ export async function executeTool(name, args, cwd, verbose = false, options = {}
     };
     try {
         const policy = options.policy ?? options.session?.policy ?? 'shell-confirm';
+        // Auto-init git repo on first mutating tool call (Finding C)
+        if (MUTATION_TOOL_NAMES.has(name)) {
+            const git = new GitManager(cwd);
+            if (!git.isGitRepo()) {
+                try {
+                    spawnSync('git', ['init'], { cwd, encoding: 'utf-8', stdio: 'ignore' });
+                    spawnSync('git', ['add', '.'], { cwd, encoding: 'utf-8', stdio: 'ignore' });
+                    spawnSync('git', ['commit', '-m', 'chore: initial checkpoint by fixo'], { cwd, encoding: 'utf-8', stdio: 'ignore' });
+                }
+                catch (e) {
+                    // Ignore if git fails (e.g. no user.name, empty directory, or git not installed)
+                }
+            }
+        }
         // ──── PreToolUse hooks (§3.4) ────
         // Run any user-defined pre-tool hooks. A `deny` decision
         // short-circuits the call; a `modify` decision replaces
@@ -1083,19 +587,12 @@ export async function executeTool(name, args, cwd, verbose = false, options = {}
                 }
                 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;
-                        }
+                        console.error('Failed to run AST command safety check, failing closed for security:', err.message);
                     }
+                    safetyResult = {
+                        safe: false,
+                        reason: `Error: AST command safety check failed and regex fallback is disabled for security reasons: ${err.message}`
+                    };
                 }
                 if (!safetyResult.safe) {
                     const allowed = await askUnsafeCommandPermission(args.command, safetyResult.reason, options.allowWithoutPrompt);
@@ -1104,7 +601,7 @@ export async function executeTool(name, args, cwd, verbose = false, options = {}
                         break;
                     }
                 }
-                event.result = executeRunCommand(args.command, args.cwd || cwd, cwd, options.session);
+                event.result = executeRunCommand(args.command, args.cwd || cwd, cwd, options.session, options.safety?.sandboxMode);
                 break;
             case 'search_code':
                 setSpinner({ kind: 'search', name: 'Search', detail: `"${truncate(args.query, 40)}" in ${args.path ?? '.'}` });
@@ -1294,6 +791,16 @@ function executeReadFile(filePath, cwd, session, largeFileGateBytes = 15 * 1024,
     if (!fs.existsSync(resolved)) {
         return `Error: File not found: ${filePath}`;
     }
+    const baseName = path.basename(resolved).toLowerCase();
+    const lowerPath = resolved.toLowerCase();
+    if (baseName === '.env' ||
+        baseName.startsWith('.env.') ||
+        baseName === 'id_rsa' ||
+        baseName === 'providers.json' ||
+        lowerPath.includes('/.ssh/') ||
+        lowerPath.endsWith('.pem')) {
+        return `Error: Access to sensitive file "${filePath}" is blocked for security reasons.`;
+    }
     const stat = fs.statSync(resolved);
     if (stat.isDirectory()) {
         return `Error: "${filePath}" is a directory, not a file. Use list_dir instead.`;
@@ -1328,7 +835,7 @@ function executeReadFile(filePath, cwd, session, largeFileGateBytes = 15 * 1024,
  */
 function countLines(filePath) {
     let count = 0;
-    let sawNewline = true;
+    let lastCharWasNewline = true;
     const stream = fs.openSync(filePath, 'r');
     try {
         const buf = Buffer.allocUnsafe(64 * 1024);
@@ -1337,14 +844,14 @@ function countLines(filePath) {
             for (let i = 0; i < bytesRead; i++) {
                 if (buf[i] === 0x0a) {
                     count++;
-                    sawNewline = true;
+                    lastCharWasNewline = true;
                 }
                 else {
-                    sawNewline = false;
+                    lastCharWasNewline = false;
                 }
             }
         }
-        if (!sawNewline)
+        if (!lastCharWasNewline)
             count++;
     }
     finally {
@@ -1419,6 +926,16 @@ async function executeExtractImports(filePath, cwd, session) {
 function executeWriteFile(filePath, content, cwd, options = {}) {
     const guard = new WorkspaceGuard(cwd);
     const resolved = guard.resolve(filePath, 'file');
+    const baseName = path.basename(resolved).toLowerCase();
+    const lowerPath = resolved.toLowerCase();
+    if (baseName === '.env' ||
+        baseName.startsWith('.env.') ||
+        baseName === 'id_rsa' ||
+        baseName === 'providers.json' ||
+        lowerPath.includes('/.ssh/') ||
+        lowerPath.endsWith('.pem')) {
+        return Promise.resolve(`Error: Access to sensitive file "${filePath}" is blocked for security reasons.`);
+    }
     // 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
@@ -1466,27 +983,53 @@ function executeWriteFile(filePath, content, cwd, options = {}) {
         return `File updated: ${filePath}`;
     });
 }
-function executeRunCommand(command, requestedCwd, workspaceRoot, session) {
+function executeRunCommand(command, requestedCwd, workspaceRoot, session, sandboxMode) {
     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(),
-        });
+        let result;
+        if (sandboxMode === 'os-sandbox') {
+            // Opt-in OS-level sandbox. The regex command-parser layer that
+            // ran upstream is left in place — this is defence in depth.
+            // If the platform binary is missing we surface a structured
+            // error instead of silently downgrading to unsandboxed exec.
+            try {
+                result = runSandboxed(command, {
+                    cwd: commandCwd,
+                    allowedWritePaths: [workspaceRoot],
+                    allowNetwork: true,
+                    timeout: 60_000,
+                    maxBuffer: 1024 * 1024,
+                    env: redactedEnv(),
+                });
+            }
+            catch (sandboxErr) {
+                if (sandboxErr instanceof SandboxUnavailableError) {
+                    return `Error: OS sandbox mode is enabled but cannot be applied — ${sandboxErr.message}. Either install the platform binary or set preferences.safety.sandboxMode to 'guard'.`;
+                }
+                throw sandboxErr;
+            }
+        }
+        else {
+            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';
+        const err = error;
+        const stdout = err.stdout ?? '';
+        const stderr = err.stderr ?? '';
+        const code = err.status ?? 'unknown';
         return redactSecrets(`Command exited with code ${code}\n\nSTDOUT:\n${stdout}\n\nSTDERR:\n${stderr}`.trim());
     }
 }
@@ -1503,7 +1046,8 @@ function executeSearchCode(query, searchPath, filePattern, cwd) {
     }
     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}`);
+            const msg = error instanceof Error ? error.message : String(error);
+            console.warn(`[Debug Warning] Failed to determine if ripgrep (rg) is installed: ${msg}`);
         }
     }
     let output = '';
@@ -1560,7 +1104,8 @@ function executeListDir(dirPath, cwd) {
     }
     let entries;
     try {
-        entries = fs.readdirSync(resolved, { withFileTypes: true });
+        const inv = getRunInventory(getOrCreateRunId());
+        entries = inv.listDir(resolved);
     }
     catch (error) {
         return `Error: Cannot read directory: ${error instanceof Error ? error.message : String(error)}`;
@@ -1575,6 +1120,7 @@ function executeListDir(dirPath, cwd) {
         return a.name.localeCompare(b.name);
     });
     const lines = [];
+    const inv = getRunInventory(getOrCreateRunId());
     for (const entry of filtered) {
         if (entry.isDirectory()) {
             lines.push(`📁 ${entry.name}/`);
@@ -1582,7 +1128,7 @@ function executeListDir(dirPath, cwd) {
         else {
             let size = '';
             try {
-                const s = fs.statSync(path.join(resolved, entry.name));
+                const s = inv.fileStats(path.join(resolved, entry.name));
                 size = formatSize(s.size);
             }
             catch {
@@ -1898,7 +1444,7 @@ export async function executeTodoWrite(args, cwd, options = {}) {
  * dispatch is hot-path-friendly and test-friendly (tests inject
  * a custom registry via {@link setBackgroundJobRegistry}).
  */
-let globalBackgroundRegistry = null;
+const globalBackgroundRegistry = null;
 const backgroundRegistries = new Map();
 export function getBackgroundJobRegistry(cwd) {
     let reg = backgroundRegistries.get(cwd);