@semalt-ai/code 1.8.4 → 1.19.0

package/lib/tools.js

@@ -1,20 +1,34 @@
 'use strict';
 
-const fs = require('fs');
-const fsp = require('fs/promises');
-const http = require('http');
-const https = require('https');
 const os = require('os');
 const path = require('path');
+// Note: fs / fs/promises / http / https are no longer required here — the file
+// and network executors moved to lib/tool_registry.js in Task 1.4b. tools.js now
+// keeps only the path/sandbox guards, the shell executor, and the parse glue.
 const { spawn } = require('child_process');
 
 const { logToolCall } = require('./audit');
+const { spawnWithGroup, killTreeEscalating } = require('./proc');
+const { classifyShellCommand } = require('./deny');
+const { resolveSandboxedSpawn } = require('./sandbox');
+const { TOOL_REGISTRY, fromInvoke, entryForAction, dynamicToolEntries } = require('./tool_registry');
 const writer = require('./ui/writer');
+const { CONFIG_PATH, protectedConfigDirs } = require('./constants');
 
 const MEMORY_PATH = path.join(os.homedir(), '.semalt-ai', 'memory.json');
 
 const _dryRun = process.argv.includes('--dry-run');
 const _allowAnywhere = process.argv.includes('--allow-anywhere');
+// Binary network isolation (Task 4.4b): the human-typed --no-network flag forces
+// kernel-level no-network for sandboxed commands. Read once at module load — a
+// human-only signal the model can never reach (the model controls only the
+// command string). sandbox.network in config does the same via decideSandbox.
+const _noNetwork = process.argv.includes('--no-network');
+// The single, explicit opt-out of ALL safety. When set, the destructive-command
+// deny-list and the config-file read guard are bypassed. This is the only flag
+// that does so — --allow-* tier flags grant approval but never disable the
+// deny-list. See lib/deny.js and Task 0.1.
+const _skipPermissions = process.argv.includes('--dangerously-skip-permissions');
 const _skippedOps = [];
 function getSkippedOps() { return _skippedOps.slice(); }
 
@@ -55,6 +69,59 @@ function _sandboxError(filePath) {
   return { error: `Path outside allowed area: ${filePath}. Use --allow-anywhere to override.` };
 }
 
+// Files that hold secrets or sensitive history and must NEVER be read back into
+// the model context — the API key / auth token live in config.json, the memory
+// store may contain secrets, and the audit log records past tool inputs. This
+// guard is intentionally NOT gated on --allow-anywhere: --allow-anywhere widens
+// where the agent may write, it does not unlock secret exfiltration. The only
+// override is --dangerously-skip-permissions (opting out of all safety).
+const _AUDIT_LOG_PATH = path.join(os.homedir(), '.semalt-ai', 'audit.log');
+const PROTECTED_READ_PATHS = new Set([
+  path.resolve(CONFIG_PATH),
+  path.resolve(MEMORY_PATH),
+  path.resolve(_AUDIT_LOG_PATH),
+]);
+
+function isProtectedSecretPath(filePath) {
+  if (_skipPermissions) return false;
+  if (typeof filePath !== 'string' || !filePath) return false;
+  return PROTECTED_READ_PATHS.has(path.resolve(filePath));
+}
+
+function _secretReadError(filePath) {
+  return { error: `Refused: ${filePath} holds secrets/credentials and cannot be read by the agent. (This guard is not overridable with --allow-anywhere.)` };
+}
+
+// Config/execution-driving paths that the AGENT must never WRITE — the write-side
+// companion to the read guard above (Pre-Task 5.0b). Covers the protected-config
+// set (lib/constants.js protectedConfigDirs): the whole ~/.semalt-ai dir AND
+// every project .semalt dir from the CWD up to the repo root, INCLUDING files
+// that do not yet exist (a missing config.json / agents/*.md / hook is inside a
+// protected DIR, so it is refused regardless of existence — the CVE-2026-25725
+// lesson). Directory-prefix matched on the resolved path, mirroring isPathSafe.
+//
+// Policy parity with isProtectedSecretPath: NOT gated on --allow-anywhere
+// (--allow-anywhere widens WHERE the agent may write, it does not unlock writing
+// the config surfaces that drive host-privileged execution). The only override is
+// --dangerously-skip-permissions (opting out of all safety). A human editing
+// their own config in an editor is unaffected — this guards the agent's tools and
+// the sandboxed shell, not the human.
+function isProtectedConfigPath(filePath) {
+  if (_skipPermissions) return false;
+  if (typeof filePath !== 'string' || !filePath) return false;
+  const resolved = path.resolve(filePath);
+  for (const dir of protectedConfigDirs()) {
+    const base = path.resolve(dir);
+    const prefix = base.endsWith(path.sep) ? base : base + path.sep;
+    if (resolved === base || resolved.startsWith(prefix)) return true;
+  }
+  return false;
+}
+
+function _protectedConfigWriteError(filePath) {
+  return { error: `Refused: ${filePath} is a protected config path (under ~/.semalt-ai or a project .semalt dir) that drives execution and cannot be written by the agent. (This guard is not overridable with --allow-anywhere.)` };
+}
+
 // Cheap ReDoS guard. Rejects pathologically long patterns, common
 // catastrophic-backtracking anti-patterns, and pattern×data sizes large
 // enough to hang the regex engine.
@@ -73,8 +140,34 @@ function _checkRegexSafety(pattern, data) {
   return null;
 }
 
-function createToolExecutor(permissionManager, ui, getConfig) {
+function createToolExecutor(permissionManager, ui, getConfig, options = {}) {
   const { BOLD, DIM, FG_DARK, FG_GRAY, FG_GREEN, FG_RED, FG_YELLOW, RST, renderDiff } = ui;
+  // Checkpoints & rewind (Task 4.3). When a store is wired, the prior state of a
+  // file is snapshotted in agentExecFile AFTER the permission gate approves and
+  // BEFORE the executor mutates. Optional — undefined in tests/headless paths
+  // that don't opt in. Subagents reuse this same agentExecFile, so a child's
+  // mutations are checkpointed into the parent session for free.
+  const checkpointStore = options.checkpointStore || null;
+  // OS sandbox fallback approver (Task 4.4). When the sandbox is unavailable in
+  // `auto` mode, agentExecShell asks a HUMAN before running a command
+  // unsandboxed via this callback (it returns true to allow, false to refuse).
+  // Undefined in non-TTY/headless/test paths → the command is REFUSED (never a
+  // silent unsandboxed run). This is injected by the executor owner (index.js),
+  // never reachable by the model, so the agent can't approve its own escape.
+  const onUnsandboxed = typeof options.onUnsandboxed === 'function' ? options.onUnsandboxed : null;
+  // Web-fetch secondary summarizer (Task W.1). An injected async LLM call
+  // `(messages, { model, signal }) => Promise<string>` (the api client's
+  // chatComplete) used by http_get to summarize extracted page content in a
+  // separate call — only the summary enters the main context. Optional: when
+  // absent (headless/oneshot paths without an api client), http_get returns the
+  // extracted Markdown instead of summarizing, never the raw page.
+  const webChat = typeof options.webChat === 'function' ? options.webChat : null;
+  // Web search backend (Task W.2b). An injected async call
+  // `(query, { count }) => Promise<{ results: [{title,url,snippet}], … }>` (the
+  // api client's dashboardSearch, which hits the backend POST /api/search).
+  // Optional: when absent (headless/oneshot paths without an api client) the
+  // web_search tool degrades to a clean tool error, never a crash.
+  const webSearch = typeof options.webSearch === 'function' ? options.webSearch : null;
   // Continuation lines in a system-message bubble (chat-history.js else branch)
   // are indented by 5 spaces. Let the diff renderer reserve those columns so
   // its lines don't auto-wrap inside the bubble.
@@ -89,7 +182,95 @@ function createToolExecutor(permissionManager, ui, getConfig) {
     return options.length >= 2 ? options : [];
   }
 
-  async function agentExecShell(command) {
+  // Build the permission descriptor for a [action, ...args] call tuple.
+  // Returns null when no permission gate is needed — read-only ops, dry-run
+  // skips, and --readonly blocks short-circuit through the executor's own
+  // error path. When non-null the caller (the agent loop) feeds the three
+  // fields straight into permissionManager.askPermission.
+  //
+  // Side effects, intentionally hosted here so they fire pre-picker:
+  //   - write/append: render the file diff. In CLI mode the diff is
+  //     emitted to scrollback; in TUI mode it's appended to `description`
+  //     so it renders inside the picker bubble.
+  //   - delete_file / move_file: emit a CLI warning line above the picker.
+  // Centralizing these means the executor body stays purely about the
+  // operation itself.
+  async function describePermission(call) {
+    if (!Array.isArray(call) || call.length === 0) return null;
+    const [action, ...args] = call;
+
+    // Dry-run skips the gate for every tool whose executor has a dry-run
+    // early return — asking the user to authorize an op that won't run is
+    // confusing UX. write/append are handled inside their own case so the
+    // diff still renders before the skip. Tools without dry-run support
+    // (delete_file, make_dir, etc.) fall through and get gated normally.
+    if (_dryRun && (action === 'shell' || action === 'exec' || action === 'download' || action === 'http_get')) {
+      return null;
+    }
+
+    // --readonly blocks the op deterministically; no point prompting first.
+    // The executor's own readonlyBlock() check produces the user-facing
+    // error message on the next dispatch step.
+    const READONLY_TAG = {
+      write: 'write_file',
+      append: 'append_file',
+      delete_file: 'delete_file',
+      move_file: 'move_file',
+      copy_file: 'copy_file',
+      download: 'download',
+      edit_file: 'edit_file',
+      replace_in_file: 'replace_in_file',
+      make_dir: 'make_dir',
+      remove_dir: 'remove_dir',
+      upload: 'upload',
+    };
+    const roTag = READONLY_TAG[action];
+    if (roTag && permissionManager.readonlyBlock(roTag)) return null;
+
+    // Per-tool descriptor now lives on the registry entry (Task 1.4b). Read-only
+    // ops resolve to a permission() that returns null (no gate). The side effects
+    // that used to live in the switch cases (write/append diff render,
+    // delete/move warning lines) moved into those permission() bodies unchanged.
+    const entry = entryForAction(action);
+    if (entry && typeof entry.permission === 'function') return entry.permission(ctx, args);
+    return null;
+  }
+
+  async function agentExecShell(command, options = {}) {
+    // Destructive-command deny-list. Enforced for EVERY shell call regardless
+    // of approval mode (interactive, non-TTY, or any --allow-* flag). This is
+    // the unbypassable chokepoint: all shell execution funnels through here.
+    // The only escape hatch is --dangerously-skip-permissions.
+    //
+    // The `initiator` distinguishes agent-initiated calls (the model asked) from
+    // user-initiated ones (a human typed `!cmd` / `semalt-code shell`). Agent
+    // calls keep the hard block. User calls are exempt from the block, except for
+    // the catastrophic subset (disk wipe / fork bomb), which gets a one-time y/N
+    // confirmation via options.confirm as a typo guard. See lib/deny.js.
+    const initiator = options.initiator === 'user' ? 'user' : 'agent';
+    if (!_skipPermissions) {
+      const verdict = classifyShellCommand(command, initiator);
+      if (verdict.action === 'block') {
+        const msg = `Blocked by safety deny-list: ${verdict.label}. Refuse to run: ${command}. To override, restart with --dangerously-skip-permissions.`;
+        _log(`  ${FG_RED}✗ ${msg}${RST}`);
+        logToolCall('exec', { command }, false, 'denied');
+        return { exit_code: -1, stdout: '', stderr: msg, blocked: true };
+      }
+      if (verdict.action === 'confirm') {
+        let approved = false;
+        if (typeof options.confirm === 'function') {
+          try { approved = await options.confirm(verdict.label, command); }
+          catch { approved = false; }
+        }
+        if (!approved) {
+          const msg = `Cancelled (${verdict.label}): ${command}`;
+          _log(`  ${FG_RED}✗ ${msg}${RST}`);
+          logToolCall('exec', { command }, false, 'cancelled');
+          return { exit_code: -1, stdout: '', stderr: msg, blocked: true };
+        }
+      }
+    }
+
     if (_dryRun) {
       _log(`  ${FG_DARK}[dry-run] $ ${command}${RST}`);
       _skippedOps.push({ category: 'cmd', symbol: '▶', desc: command });
@@ -97,859 +278,208 @@ function createToolExecutor(permissionManager, ui, getConfig) {
       return { exit_code: 0, stdout: '', stderr: 'dry-run: command skipped' };
     }
 
-    const approved = await permissionManager.askPermission('shell', command, 'exec');
-    if (!approved) {
-      logToolCall('exec', { command }, false, 'denied');
-      return { exit_code: -1, stdout: '', stderr: 'Permission denied by user' };
-    }
-
     const cfg = getConfig ? getConfig() : {};
     const timeout = cfg.command_timeout_ms || 30000;
+    const { signal } = options;
+
+    // ---------------------------------------------------------------------
+    // OS sandbox (Task 4.4; unified chokepoint Pre-Task 5.0a). EVERY shell call
+    // — here, self-verification, and command-type hooks — funnels through the
+    // SHARED resolveSandboxedSpawn shim, so the model has no path that runs a
+    // command outside this decision. --dangerously-skip-permissions (a
+    // human-only flag) opts out of all safety, sandbox included.
+    //
+    //   run:true  → spawn the resolved file/args (jailed when sandbox 'on';
+    //               plain { shell:true } when 'off'/human-approved 'unavailable').
+    //   run:false → fail-safe refusal: failIfUnavailable hard error (hard:true)
+    //               or no/declined human approval — NEVER a silent unsandboxed run.
+    // ---------------------------------------------------------------------
+    const resolution = await resolveSandboxedSpawn({
+      command,
+      getConfig,
+      onUnsandboxed,
+      cwd: process.cwd(),
+      allowAnywhere: _allowAnywhere,
+      skipPermissions: _skipPermissions,
+      noNetwork: _noNetwork,
+    });
+    if (!resolution.run) {
+      _log(`  ${FG_RED}✗ ${resolution.message}${RST}`);
+      logToolCall('exec', { command, sandbox: 'unavailable' }, false, resolution.hard ? 'sandbox-blocked' : 'sandbox-refused');
+      return { exit_code: -1, stdout: '', stderr: resolution.message, blocked: true, sandbox: 'unavailable' };
+    }
+    const spawnFile = resolution.file;
+    const spawnArgs = resolution.useShell ? [] : resolution.args;
+    const spawnOpts = resolution.useShell ? { shell: true } : {};
+    const sandboxStatus = resolution.sandbox;
+    // Binary network mode for this run (Task 4.4b): 'on' (host network) | 'off'
+    // (kernel-level no-network). Surfaced in the result + audit (net:on|off).
+    const networkStatus = resolution.network || 'on';
 
     return new Promise((resolve) => {
       let child;
       try {
-        child = spawn(command, { shell: true });
+        // spawnWithGroup gives us a process-group leader on POSIX so
+        // killTreeEscalating can reach descendants via -pid. With shell:true
+        // a plain child.kill targets only the sh wrapper, leaving the real
+        // workload (find /, pipelines, etc.) running as orphans. When sandboxed,
+        // the group leader is the bwrap/sandbox-exec process — killing the group
+        // tears down the whole jailed subtree, so child-process confinement
+        // composes with the existing tree-kill plumbing.
+        child = spawnWithGroup(spawn, spawnFile, spawnArgs, spawnOpts);
       } catch (error) {
         _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('exec', { command }, true, 'error');
-        return resolve({ exit_code: -1, stdout: '', stderr: error.message });
+        logToolCall('exec', { command, sandbox: sandboxStatus, network: networkStatus }, true, 'error');
+        return resolve({ exit_code: -1, stdout: '', stderr: error.message, sandbox: sandboxStatus, network: networkStatus });
       }
+      const startedAt = Date.now();
       let stdout = '';
       let stderr = '';
       let killed = false;
+      let abortedByUser = false;
+
       const timer = setTimeout(() => {
         killed = true;
-        try { child.kill('SIGTERM'); } catch {}
+        killTreeEscalating(child);
       }, timeout);
+
+      let onAbort = null;
+      const detachAbort = () => {
+        if (onAbort && signal) {
+          signal.removeEventListener('abort', onAbort);
+          onAbort = null;
+        }
+      };
+      if (signal) {
+        if (signal.aborted) {
+          abortedByUser = true;
+          killTreeEscalating(child);
+        } else {
+          onAbort = () => {
+            abortedByUser = true;
+            killTreeEscalating(child);
+          };
+          signal.addEventListener('abort', onAbort, { once: true });
+        }
+      }
+
       child.stdout.setEncoding('utf8');
       child.stderr.setEncoding('utf8');
       child.stdout.on('data', (c) => { stdout += c; });
       child.stderr.on('data', (c) => { stderr += c; });
       child.on('error', (error) => {
         clearTimeout(timer);
+        detachAbort();
         _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('exec', { command }, true, 'error');
-        resolve({ exit_code: -1, stdout, stderr: stderr || error.message });
+        logToolCall('exec', { command, sandbox: sandboxStatus, network: networkStatus }, true, 'error');
+        resolve({ exit_code: -1, stdout, stderr: stderr || error.message, sandbox: sandboxStatus, network: networkStatus });
       });
-      child.on('close', (code, signal) => {
+      child.on('close', (code, sigName) => {
         clearTimeout(timer);
+        detachAbort();
+        if (abortedByUser) {
+          const elapsed_s = Math.max(0, Math.round((Date.now() - startedAt) / 1000));
+          const note = `[user interrupted after ${elapsed_s}s]`;
+          stderr += (stderr ? '\n' : '') + note;
+          logToolCall('exec', { command, sandbox: sandboxStatus, network: networkStatus }, true, 'aborted');
+          resolve({ exit_code: -1, stdout, stderr, aborted: true, elapsed_s, sandbox: sandboxStatus, network: networkStatus });
+          return;
+        }
         if (killed) stderr += (stderr ? '\n' : '') + `[timed out after ${timeout}ms]`;
-        const exit_code = killed ? -1 : (code != null ? code : (signal ? -1 : 0));
-        logToolCall('exec', { command }, true, exit_code === 0 ? 'ok' : 'error');
-        resolve({ exit_code, stdout, stderr });
+        const exit_code = killed ? -1 : (code != null ? code : (sigName ? -1 : 0));
+        logToolCall('exec', { command, sandbox: sandboxStatus, network: networkStatus }, true, exit_code === 0 ? 'ok' : 'error');
+        resolve({ exit_code, stdout, stderr, sandbox: sandboxStatus, network: networkStatus });
       });
     });
   }
 
-  async function agentExecFile(action, ...args) {
-    const [arg0 = null, arg1 = null, arg2 = null, arg3 = null] = args;
-
-    if (action === 'read') {
-      const filePath = arg0;
-      const stat = await fsp.stat(filePath).catch(() => null);
-      if (stat) {
-        const cfg = getConfig ? getConfig() : {};
-        const maxBytes = (cfg.max_file_size_kb || 512) * 1024;
-        if (stat.size > maxBytes) {
-          const kb = (stat.size / 1024).toFixed(0);
-          logToolCall('read_file', { path: filePath }, false, 'error');
-          return { error: `File too large: ${kb} KB exceeds max_file_size_kb=${cfg.max_file_size_kb || 512}` };
-        }
-      }
-      try {
-        const data = await fsp.readFile(filePath, 'utf8');
-        const lines = data.split('\n').length;
-        if (lines > 10) {
-          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Read ${filePath} (${lines} lines, ${data.length} chars)${RST}`);
-        } else {
-          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Read ${filePath}${RST}`);
-        }
-        logToolCall('read_file', { path: filePath }, true, 'ok');
-        return { content: data, path: filePath, bytes: Buffer.byteLength(data, 'utf8') };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('read_file', { path: filePath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'write' || action === 'append') {
-      const filePath = arg0;
-      const content = arg1;
-      const tag = action === 'write' ? 'write_file' : 'append_file';
-
-      const blocked = permissionManager.readonlyBlock(tag);
-      if (blocked) {
-        logToolCall(tag, { path: filePath, content }, false, 'denied');
-        return blocked;
-      }
-
-      if (!isPathSafe(filePath)) {
-        logToolCall(tag, { path: filePath }, false, 'denied');
-        return _sandboxError(filePath);
-      }
-
-      // Read existing content for diff display
-      let existing = '';
-      try { existing = await fsp.readFile(filePath, 'utf8'); } catch {}
-
-      // For append the final state is existing + new content
-      const finalContent = action === 'write' ? (content || '') : (existing + (content || ''));
-
-      // In CLI mode, print the diff inline. In TUI mode, direct stdout writes
-      // collide with the live chat-history/status-bar redraw, so we route the
-      // diff into the permission description instead (where it renders inside
-      // the permission bubble and is safely truncated by MAX_DESC_LINES).
-      const diffOutput = _uiActive
-        ? renderDiff(existing, finalContent, filePath, { inset: DIFF_BUBBLE_INSET })
-        : renderDiff(existing, finalContent, filePath);
-      if (!_uiActive) writer.scrollback(diffOutput);
-
-      // Dry-run: record the skipped op and return without writing
-      if (_dryRun) {
-        const verb = action === 'write' ? 'write' : 'append';
-        _skippedOps.push({ category: 'file', symbol: '✎', desc: `${verb} ${filePath}` });
-        logToolCall(tag, { path: filePath }, false, 'dry-run');
-        return { status: 'dry-run', message: 'dry-run: write skipped', path: filePath };
-      }
-
-      // Permission check — routes through TUI dialog in chat mode, interactiveSelect in non-TUI flows
-      let desc = `${action === 'write' ? 'Write' : 'Append to'} ${filePath}`;
-      if (content) desc += ` (${content.length} chars)`;
-      if (_uiActive) desc = `${desc}\n${diffOutput}`;
-      const approved = await permissionManager.askPermission('file', desc, tag);
-      if (!approved) {
-        logToolCall(tag, { path: filePath, content }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const dir = path.dirname(filePath);
-        if (dir && dir !== '.') await fsp.mkdir(dir, { recursive: true });
-        if (action === 'write') await fsp.writeFile(filePath, content || '');
-        else await fsp.appendFile(filePath, content || '');
-        const verb = action === 'write' ? 'Wrote' : 'Appended to';
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}${verb} ${filePath}${RST}`);
-        logToolCall(tag, { path: filePath, content }, true, 'ok');
-        return { status: 'ok', path: filePath, bytes: (content || '').length };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall(tag, { path: filePath, content }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'list_dir') {
-      const dirPath = arg0;
-      try {
-        const entries = await fsp.readdir(dirPath, { withFileTypes: true });
-        const items = entries.map((e) => {
-          if (e.isSymbolicLink()) return `[L] ${e.name}`;
-          if (e.isDirectory()) return `[D] ${e.name}`;
-          return `[F] ${e.name}`;
-        });
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Listed ${dirPath} (${items.length} items)${RST}`);
-        logToolCall('list_dir', { path: dirPath }, true, 'ok');
-        return { items, path: dirPath };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('list_dir', { path: dirPath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'delete_file') {
-      const filePath = arg0;
-
-      const blocked = permissionManager.readonlyBlock('delete_file');
-      if (blocked) {
-        logToolCall('delete_file', { path: filePath }, false, 'denied');
-        return blocked;
-      }
-
-      if (!isPathSafe(filePath)) {
-        logToolCall('delete_file', { path: filePath }, false, 'denied');
-        return _sandboxError(filePath);
-      }
-
-      _log(`  ${FG_YELLOW}${BOLD}⚠ Deleting: ${filePath}${RST}`);
-
-      const approved = await permissionManager.askPermission('file', `Delete ${filePath}`, 'delete_file');
-      if (!approved) {
-        logToolCall('delete_file', { path: filePath }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        await fsp.unlink(filePath);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Deleted ${filePath}${RST}`);
-        logToolCall('delete_file', { path: filePath }, true, 'ok');
-        return { status: 'ok', path: filePath };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('delete_file', { path: filePath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'make_dir') {
-      const dirPath = arg0;
-      if (!isPathSafe(dirPath)) {
-        logToolCall('make_dir', { path: dirPath }, false, 'denied');
-        return _sandboxError(dirPath);
-      }
-      const approved = await permissionManager.askPermission('file', `Create directory ${dirPath}`, 'make_dir');
-      if (!approved) {
-        logToolCall('make_dir', { path: dirPath }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        await fsp.mkdir(dirPath, { recursive: true });
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Created directory ${dirPath}${RST}`);
-        logToolCall('make_dir', { path: dirPath }, true, 'ok');
-        return { status: 'ok', path: dirPath };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('make_dir', { path: dirPath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'remove_dir') {
-      const dirPath = arg0;
-      if (!isPathSafe(dirPath)) {
-        logToolCall('remove_dir', { path: dirPath }, false, 'denied');
-        return _sandboxError(dirPath);
-      }
-      const approved = await permissionManager.askPermission('file', `Remove directory ${dirPath}`, 'remove_dir');
-      if (!approved) {
-        logToolCall('remove_dir', { path: dirPath }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        await fsp.rm(dirPath, { recursive: true, force: true });
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Removed directory ${dirPath}${RST}`);
-        logToolCall('remove_dir', { path: dirPath }, true, 'ok');
-        return { status: 'ok', path: dirPath };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('remove_dir', { path: dirPath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'move_file') {
-      const src = arg0;
-      const dst = arg1;
-
-      const blocked = permissionManager.readonlyBlock('move_file');
-      if (blocked) {
-        logToolCall('move_file', { src, dst }, false, 'denied');
-        return blocked;
-      }
-
-      if (!isPathSafe(dst)) {
-        logToolCall('move_file', { src, dst }, false, 'denied');
-        return _sandboxError(dst);
-      }
-
-      _log(`  ${FG_YELLOW}${BOLD}⚠ Moving: ${src} → ${dst}${RST}`);
-
-      const approved = await permissionManager.askPermission('file', `Move ${src} to ${dst}`, 'move_file');
-      if (!approved) {
-        logToolCall('move_file', { src, dst }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const dstDir = path.dirname(dst);
-        if (dstDir && dstDir !== '.') await fsp.mkdir(dstDir, { recursive: true });
-        try {
-          await fsp.rename(src, dst);
-        } catch (renameErr) {
-          if (renameErr.code !== 'EXDEV') throw renameErr;
-          // Cross-device rename not supported — copy then remove
-          await fsp.cp(src, dst, { recursive: true });
-          await fsp.rm(src, { recursive: true, force: true });
-        }
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Moved ${src} → ${dst}${RST}`);
-        logToolCall('move_file', { src, dst }, true, 'ok');
-        return { status: 'ok', src, dst };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('move_file', { src, dst }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'copy_file') {
-      const src = arg0;
-      const dst = arg1;
-
-      const blocked = permissionManager.readonlyBlock('copy_file');
-      if (blocked) {
-        logToolCall('copy_file', { src, dst }, false, 'denied');
-        return blocked;
-      }
-
-      if (!isPathSafe(dst)) {
-        logToolCall('copy_file', { src, dst }, false, 'denied');
-        return _sandboxError(dst);
-      }
-
-      const approved = await permissionManager.askPermission('file', `Copy ${src} to ${dst}`, 'copy_file');
-      if (!approved) {
-        logToolCall('copy_file', { src, dst }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const dstDir = path.dirname(dst);
-        if (dstDir && dstDir !== '.') await fsp.mkdir(dstDir, { recursive: true });
-        await fsp.cp(src, dst, { recursive: true });
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Copied ${src} → ${dst}${RST}`);
-        logToolCall('copy_file', { src, dst }, true, 'ok');
-        return { status: 'ok', src, dst };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('copy_file', { src, dst }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'edit_file') {
-      const filePath = arg0;
-      const lineNum = arg1;
-      const newContent = arg2;
-      const approved = await permissionManager.askPermission('file', `Edit line ${lineNum} in ${filePath}`, 'edit_file');
-      if (!approved) {
-        logToolCall('edit_file', { path: filePath, line: lineNum }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const data = await fsp.readFile(filePath, 'utf8');
-        const lines = data.split('\n');
-        if (lineNum < 1 || lineNum > lines.length) {
-          logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
-          return { error: `Line ${lineNum} out of range (file has ${lines.length} lines)` };
-        }
-        lines[lineNum - 1] = newContent;
-        await fsp.writeFile(filePath, lines.join('\n'));
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited line ${lineNum} in ${filePath}${RST}`);
-        logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'ok');
-        return { status: 'ok', path: filePath, line: lineNum };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'search_in_file') {
-      const filePath = arg0;
-      const pattern = arg1;
-      try {
-        const data = await fsp.readFile(filePath, 'utf8');
-        const guardErr = _checkRegexSafety(pattern, data);
-        if (guardErr) {
-          logToolCall('search_in_file', { path: filePath, pattern }, true, 'error');
-          return guardErr;
-        }
-        const regex = new RegExp(pattern);
-        const matches = data.split('\n')
-          .map((content, idx) => regex.test(content) ? { line: idx + 1, content } : null)
-          .filter(Boolean);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Found ${matches.length} match(es) in ${filePath}${RST}`);
-        logToolCall('search_in_file', { path: filePath, pattern }, true, 'ok');
-        return { matches, path: filePath };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('search_in_file', { path: filePath, pattern }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'replace_in_file') {
-      const filePath = arg0;
-      const searchStr = arg1;
-      const replaceStr = arg2;
-      const flags = arg3 || '';
-      const approved = await permissionManager.askPermission('file', `Replace in ${filePath}`, 'replace_in_file');
-      if (!approved) {
-        logToolCall('replace_in_file', { path: filePath, search: searchStr }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const data = await fsp.readFile(filePath, 'utf8');
-        const guardErr = _checkRegexSafety(searchStr, data);
-        if (guardErr) {
-          logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
-          return guardErr;
-        }
-        const safeFlags = flags.replace(/[^gimsuy]/g, '');
-        const countFlags = safeFlags.includes('g') ? safeFlags : safeFlags + 'g';
-        const count = (data.match(new RegExp(searchStr, countFlags)) || []).length;
-        const regex = new RegExp(searchStr, safeFlags || undefined);
-        const newData = data.replace(regex, replaceStr);
-        await fsp.writeFile(filePath, newData);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath}${RST}`);
-        logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'ok');
-        return { status: 'ok', path: filePath, count };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'search_files') {
-      const pattern = arg0;
-      const searchDir = arg1 || '.';
-      try {
-        let regStr = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
-        regStr = regStr.replace(/\*\*/g, '\x00');
-        regStr = regStr.replace(/\*/g, '[^/]*');
-        regStr = regStr.replace(/\x00\//g, '(?:.*/)?');
-        regStr = regStr.replace(/\x00/g, '.*');
-        const regex = new RegExp(`^${regStr}$`);
-        const matchName = !pattern.includes('/');
-        const files = [];
-        async function walk(dir, rel) {
-          let entries;
-          try { entries = await fsp.readdir(dir, { withFileTypes: true }); } catch { return; }
-          for (const entry of entries) {
-            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
-            if (regex.test(matchName ? entry.name : relPath)) files.push(relPath);
-            if (entry.isDirectory()) await walk(path.join(dir, entry.name), relPath);
-          }
-        }
-        await walk(searchDir, '');
-        files.sort();
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Found ${files.length} file(s) matching "${pattern}"${RST}`);
-        logToolCall('search_files', { pattern, dir: searchDir }, true, 'ok');
-        return { files, pattern, dir: searchDir };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('search_files', { pattern, dir: searchDir }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'file_stat') {
-      const filePath = arg0;
-      try {
-        const stat = await fsp.stat(filePath);
-        const type = stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : 'file';
-        const size_kb = (stat.size / 1024).toFixed(2);
-        const mode = '0o' + stat.mode.toString(8);
-        const mtime = stat.mtime.toISOString();
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Stat ${filePath}${RST}`);
-        logToolCall('file_stat', { path: filePath }, true, 'ok');
-        return { path: filePath, size_kb, mtime, type, mode };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('file_stat', { path: filePath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'get_env') {
-      const varName = arg0;
-      const value = process.env[varName];
-      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Got env ${varName}${RST}`);
-      logToolCall('get_env', { name: varName }, true, 'ok');
-      return { name: varName, value: value !== undefined ? value : null };
-    }
-
-    if (action === 'set_env') {
-      const varName = arg0;
-      const value = arg1 || '';
-      const approved = await permissionManager.askPermission('env', `Set env ${varName}=${value}`, 'set_env');
-      if (!approved) {
-        logToolCall('set_env', { name: varName }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      process.env[varName] = value;
-      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Set env ${varName}${RST}`);
-      logToolCall('set_env', { name: varName }, true, 'ok');
-      return { status: 'ok', name: varName };
-    }
-
-    if (action === 'download') {
-      const url = arg0;
-      if (_dryRun) {
-        _skippedOps.push({ category: 'net', symbol: '↓', desc: `download ${url}` });
-        logToolCall('download', { url }, false, 'dry-run');
-        return { status: 'dry-run', message: 'dry-run: network call skipped' };
-      }
-      let fileName;
-      try {
-        fileName = path.basename(new URL(url).pathname) || 'download';
-      } catch {
-        fileName = 'download';
-      }
-      const outPath = path.join(process.cwd(), fileName);
-      const approved = await permissionManager.askPermission('net', `Download ${url}`, 'download');
-      if (!approved) {
-        logToolCall('download', { url }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      return new Promise((resolve) => {
-        function doDownload(target, redirectsLeft) {
-          const proto = target.startsWith('https') ? https : http;
-          const req = proto.get(target, (res) => {
-            if ([301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0 && res.headers.location) {
-              res.resume();
-              return doDownload(res.headers.location, redirectsLeft - 1);
-            }
-            if (res.statusCode >= 400) {
-              res.resume();
-              const msg = `HTTP ${res.statusCode}`;
-              _log(`  ${FG_RED}✗ ${msg}${RST}`);
-              logToolCall('download', { url }, true, 'error');
-              return resolve({ error: msg });
-            }
-            const file = fs.createWriteStream(outPath);
-            res.pipe(file);
-            file.on('finish', () => {
-              file.close();
-              _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Downloaded to ${outPath}${RST}`);
-              logToolCall('download', { url }, true, 'ok');
-              resolve({ status: 'ok', path: outPath });
-            });
-            file.on('error', (err) => {
-              fs.unlink(outPath, () => {});
-              _log(`  ${FG_RED}✗ ${err.message}${RST}`);
-              logToolCall('download', { url }, true, 'error');
-              resolve({ error: err.message });
-            });
-          });
-          req.on('error', (err) => {
-            fs.unlink(outPath, () => {});
-            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
-            logToolCall('download', { url }, true, 'error');
-            resolve({ error: err.message });
-          });
-          req.setTimeout(120000, () => {
-            req.destroy();
-            fs.unlink(outPath, () => {});
-            logToolCall('download', { url }, true, 'error');
-            resolve({ error: 'Request timeout' });
-          });
-        }
-        doDownload(url, 5);
-      });
-    }
-
-    if (action === 'upload') {
-      const filePath = arg0;
-      const encodedContent = arg1 || '';
-      if (!isPathSafe(filePath)) {
-        logToolCall('upload', { path: filePath }, false, 'denied');
-        return _sandboxError(filePath);
-      }
-      const approved = await permissionManager.askPermission('file', `Upload to ${filePath}`, 'upload');
-      if (!approved) {
-        logToolCall('upload', { path: filePath }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        const dir = path.dirname(filePath);
-        if (dir && dir !== '.') await fsp.mkdir(dir, { recursive: true });
-        const buffer = Buffer.from(encodedContent.trim(), 'base64');
-        await fsp.writeFile(filePath, buffer);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Uploaded ${buffer.length} bytes to ${filePath}${RST}`);
-        logToolCall('upload', { path: filePath }, true, 'ok');
-        return { status: 'ok', path: filePath, bytes: buffer.length };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('upload', { path: filePath }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'http_get') {
-      const url = arg0;
-      if (_dryRun) {
-        _skippedOps.push({ category: 'net', symbol: '↓', desc: `GET ${url}` });
-        logToolCall('http_get', { url }, false, 'dry-run');
-        return { status: 'dry-run', message: 'dry-run: network call skipped' };
-      }
-      const approved = await permissionManager.askPermission('net', `HTTP GET ${url}`, 'http_get');
-      if (!approved) {
-        logToolCall('http_get', { url }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      const httpCfg = getConfig ? getConfig() : {};
-      const reqTimeoutMs = Math.max(15000, httpCfg.request_timeout_ms || 15000);
-      const maxBytes = Math.max(1024, httpCfg.http_fetch_max_bytes || 262144);
-      return new Promise((resolve) => {
-        function doGet(target, redirectsLeft) {
-          const proto = target.startsWith('https') ? https : http;
-          const req = proto.get(target, (res) => {
-            if ([301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0 && res.headers.location) {
-              res.resume();
-              return doGet(res.headers.location, redirectsLeft - 1);
-            }
-            const bufs = [];
-            let totalBytes = 0;
-            let capped = false;
-            res.on('data', (chunk) => {
-              totalBytes += chunk.length;
-              if (!capped) {
-                if (totalBytes <= maxBytes) {
-                  bufs.push(chunk);
-                } else {
-                  const keep = maxBytes - (totalBytes - chunk.length);
-                  if (keep > 0) bufs.push(chunk.slice(0, keep));
-                  capped = true;
-                  // Keep the connection draining so totalBytes reflects reality,
-                  // but stop buffering further bytes.
-                }
-              }
-            });
-            res.on('end', () => {
-              const kept = Buffer.concat(bufs);
-              const keptBytes = kept.length;
-              let body = kept.toString('utf8');
-              if (capped) {
-                const origKb = (totalBytes / 1024).toFixed(0);
-                const keptKb = (keptBytes / 1024).toFixed(0);
-                const droppedKb = ((totalBytes - keptBytes) / 1024).toFixed(0);
-                body += `\n\n[... truncated: original was ${origKb}KB, showing first ${keptKb}KB. The remaining ${droppedKb}KB was discarded. If you need the rest, narrow your request (e.g. fetch a specific subpage) rather than retrying this URL.]`;
-              }
-              _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}HTTP GET ${target} (${res.statusCode}, ${totalBytes} bytes${capped ? `, truncated to ${keptBytes}` : ''})${RST}`);
-              logToolCall('http_get', { url: target }, true, res.statusCode < 400 ? 'ok' : 'error');
-              // `bytes` is the total transferred payload length (pre-cap);
-              // consumers that want to know the wire size without parsing
-              // the appended truncation note rely on this.
-              resolve({ status_code: res.statusCode, body, bytes: totalBytes });
-            });
-          });
-          req.on('error', (err) => {
-            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
-            logToolCall('http_get', { url: target }, true, 'error');
-            resolve({ error: err.message, error_code: err.code });
-          });
-          req.setTimeout(reqTimeoutMs, () => {
-            req.destroy();
-            logToolCall('http_get', { url: target }, true, 'error');
-            resolve({ error: 'Request timeout', error_code: 'ETIMEDOUT' });
-          });
-        }
-        doGet(url, 5);
-      });
-    }
-
-    if (action === 'ask_user') {
-      const question = arg0;
-      const approved = await permissionManager.askPermission('user', `Ask user: ${question}`, 'ask_user');
-      if (!approved) {
-        logToolCall('ask_user', { question }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      const options = _parseNumberedOptions(question);
-      if (options.length >= 2) {
-        const selected = await permissionManager.captureSelect({ options });
-        logToolCall('ask_user', { question }, true, 'ok');
-        return { question, answer: selected || options[0] };
-      }
-      if (!process.stdout.isTTY || process.stdin.isRaw) {
-        writer.scrollback(`\n  ${FG_YELLOW}?${RST} ${question}\n  ${DIM}[auto-answering 'y']${RST}`);
-        logToolCall('ask_user', { question }, true, 'ok');
-        return { question, answer: 'y' };
-      }
-      // audit: allowed — inline prompt without trailing newline; unreachable when TUI writer is active
-      // (process.stdin.isRaw is true while the TUI input field holds raw mode).
-      process.stdout.write(`\n  ${FG_YELLOW}?${RST} ${question}\n  ${FG_GRAY}>${RST} `);
-      const buf = Buffer.alloc(4096);
-      let input = '';
-      while (true) {
-        const n = fs.readSync(0, buf, 0, 1);
-        if (n === 0) break;
-        const ch = buf[0];
-        if (ch === 0x0a) break;
-        if (ch === 0x0d) continue;
-        input += String.fromCharCode(ch);
-      }
-      _log();
-      logToolCall('ask_user', { question }, true, 'ok');
-      return { question, answer: input };
-    }
-
-    if (action === 'store_memory') {
-      const key = arg0;
-      const value = arg1 || '';
-      const approved = await permissionManager.askPermission('memory', `Store memory: ${key}`, 'store_memory');
-      if (!approved) {
-        logToolCall('store_memory', { key }, false, 'denied');
-        return { error: 'Permission denied' };
-      }
-      try {
-        let mem = {};
-        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
-        mem[key] = value;
-        await fsp.mkdir(path.dirname(MEMORY_PATH), { recursive: true });
-        await fsp.writeFile(MEMORY_PATH, JSON.stringify(mem, null, 2));
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Stored memory: ${key}${RST}`);
-        logToolCall('store_memory', { key }, true, 'ok');
-        return { status: 'ok', key };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('store_memory', { key }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'recall_memory') {
-      const key = arg0;
-      try {
-        let mem = {};
-        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
-        const found = key in mem;
-        const value = found ? mem[key] : null;
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Recalled memory: ${key}${RST}`);
-        logToolCall('recall_memory', { key }, true, 'ok');
-        return { key, value, found };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('recall_memory', { key }, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'list_memories') {
-      try {
-        let mem = {};
-        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
-        const keys = Object.keys(mem);
-        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Listed ${keys.length} memory key(s)${RST}`);
-        logToolCall('list_memories', {}, true, 'ok');
-        return { keys };
-      } catch (error) {
-        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
-        logToolCall('list_memories', {}, true, 'error');
-        return { error: error.message };
-      }
-    }
-
-    if (action === 'system_info') {
-      const info = {
-        platform: os.platform(),
-        arch: os.arch(),
-        hostname: os.hostname(),
-        user: process.env.USER || process.env.USERNAME || '',
-        total_mem_mb: Math.round(os.totalmem() / 1024 / 1024),
-        free_mem_mb: Math.round(os.freemem() / 1024 / 1024),
-        node_version: process.version,
-        cwd: process.cwd(),
-      };
-      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}System info: ${info.platform}/${info.arch}${RST}`);
-      logToolCall('system_info', {}, true, 'ok');
-      return info;
-    }
-
-    logToolCall(action, { action }, false, 'error');
-    return { error: `Unknown action: ${action}` };
-  }
+  async function agentExecFile(action, ...rest) {
+    // The trailing arg may be an options object `{ signal }`. Detect and peel
+    // it off so positional args line up with the existing per-action branches.
+    // All real positional args are strings or numbers, so a plain object at
+    // the tail is unambiguously options.
+    let signal = null;
+    let args = rest;
+    const last = rest[rest.length - 1];
+    if (last && typeof last === 'object' && !Array.isArray(last)
+        && Object.getPrototypeOf(last) === Object.prototype) {
+      signal = last.signal || null;
+      args = rest.slice(0, -1);
+    }
+
+    // Dispatch via the tool registry (Task 1.4b). The per-action executor body
+    // lives on its TOOL_REGISTRY entry; ctx carries the collaborators the body
+    // closes over. Signature is unchanged, so agent.js stays untouched.
+    const entry = entryForAction(action);
+    if (!entry || typeof entry.execute !== 'function') {
+      logToolCall(action, { action }, false, 'error');
+      return { error: `Unknown action: ${action}` };
+    }
+
+    // Checkpoint capture (Task 4.3): snapshot prior state BEFORE the mutation
+    // (post-gate — a denied call never reaches here). Skip under --dry-run (no
+    // mutation will happen). beginCapture is fail-safe (returns null on error),
+    // and commit only fires on a status:'ok' result, so a call the executor
+    // itself refuses (--readonly, sandbox) produces no committed checkpoint.
+    let _cp = null;
+    if (checkpointStore && !_dryRun) {
+      try { _cp = await checkpointStore.beginCapture(action, args); } catch { _cp = null; }
+    }
+    const result = await entry.execute(ctx, args, { signal });
+    if (_cp) {
+      try { if (result && result.status === 'ok') _cp.commit(); } catch { /* fail-safe: never block a completed mutation */ }
+    }
+    return result;
+  }
+
+  // Dependency bag passed to every registry execute()/permission(). Built once
+  // here so the moved executor bodies see the same collaborators they had inside
+  // this factory closure. _uiActive is a getter so it always reflects the live
+  // module flag rather than a snapshot.
+  const ctx = {
+    _log,
+    logToolCall,
+    isPathSafe,
+    isProtectedSecretPath,
+    isProtectedConfigPath,
+    _sandboxError,
+    _secretReadError,
+    _protectedConfigWriteError,
+    _checkRegexSafety,
+    _parseNumberedOptions,
+    _dryRun,
+    _skippedOps,
+    MEMORY_PATH,
+    permissionManager,
+    getConfig,
+    webChat,
+    webSearch,
+    renderDiff,
+    DIFF_BUBBLE_INSET,
+    writer,
+    agentExecShell,
+    FG_GREEN,
+    FG_GRAY,
+    FG_RED,
+    FG_YELLOW,
+    RST,
+    DIM,
+    BOLD,
+    get _uiActive() { return _uiActive; },
+  };
 
   return {
     agentExecFile,
     agentExecShell,
+    describePermission,
   };
 }
 
-// Map a MiniMax-style {name, params} invocation to the internal
-// [action, arg1, arg2, …] call tuple consumed by the agent loop.
+// Native function-calling path → internal [action, ...args] call tuple.
+// Delegates to the tool registry (lib/tool_registry.js) — the single source
+// shared with the XML path. Kept here (and exported) for backward compatibility.
 function mapInvokeToCall(toolName, params) {
-  const name = (toolName || '').toLowerCase();
-  const p = params || {};
-  switch (name) {
-    case 'write_file':
-    case 'create_file':
-      return p.path ? ['write', p.path, p.content != null ? p.content : ''] : null;
-    case 'read_file':
-      return p.path ? ['read', p.path] : null;
-    case 'append_file':
-      return p.path ? ['append', p.path, p.content != null ? p.content : ''] : null;
-    case 'delete_file':
-      return p.path ? ['delete_file', p.path] : null;
-    case 'list_dir':
-      return ['list_dir', p.path || p.dir || '.'];
-    case 'make_dir':
-      return p.path ? ['make_dir', p.path] : null;
-    case 'remove_dir':
-      return p.path ? ['remove_dir', p.path] : null;
-    case 'move_file':
-      return p.src && p.dst ? ['move_file', p.src, p.dst] : null;
-    case 'copy_file':
-      return p.src && p.dst ? ['copy_file', p.src, p.dst] : null;
-    case 'file_stat':
-      return p.path ? ['file_stat', p.path] : null;
-    case 'search_files':
-      return ['search_files', p.pattern || p.glob || '*', p.dir || '.'];
-    case 'search_in_file':
-      return p.path && p.pattern ? ['search_in_file', p.path, p.pattern] : null;
-    case 'replace_in_file':
-      return p.path && p.search !== undefined
-        ? ['replace_in_file', p.path, p.search, p.replace != null ? p.replace : '', p.flags || '']
-        : null;
-    case 'edit_file':
-      return p.path && p.line !== undefined
-        ? ['edit_file', p.path, parseInt(p.line, 10), p.content != null ? p.content : '']
-        : null;
-    case 'get_env':
-      return p.name ? ['get_env', p.name] : null;
-    case 'set_env':
-      return p.name ? ['set_env', p.name, p.value != null ? p.value : ''] : null;
-    case 'download':
-      return p.url ? ['download', p.url] : null;
-    case 'upload':
-      return p.path ? ['upload', p.path, p.content != null ? p.content : ''] : null;
-    case 'http_get':
-      return p.url ? ['http_get', p.url] : null;
-    case 'ask_user':
-      return p.question ? ['ask_user', p.question] : null;
-    case 'store_memory':
-      return p.key ? ['store_memory', p.key, p.value != null ? p.value : ''] : null;
-    case 'recall_memory':
-      return p.key ? ['recall_memory', p.key] : null;
-    case 'list_memories':
-      return ['list_memories'];
-    case 'system_info':
-      return ['system_info'];
-    case 'exec':
-    case 'shell':
-    case 'run':
-    case 'run_command':
-    case 'bash':
-      return p.command ? ['shell', p.command] : null;
-    default:
-      return null;
-  }
-}
-
-// Compile a regex twice — once with double quotes, once with single — from a
-// template where `Q` stands for the quote char. Matches from both variants
-// are returned in a single iterable.
-function _matchDual(text, template) {
-  const results = [];
-  for (const q of ['"', "'"]) {
-    const re = new RegExp(template.replace(/Q/g, q), 'g');
-    for (const m of text.matchAll(re)) results.push(m);
-  }
-  return results;
-}
-
-// Models sometimes wrap the inline body of a single-value tool tag in a nested
-// pseudo-tag, e.g. `<list_dir><path>/tmp/foo</path></list_dir>` instead of the
-// documented `<list_dir>/tmp/foo</list_dir>`. When the body is exactly one
-// wrapper element (no siblings, no surrounding text), unwrap it once so the
-// parser recovers the intended value. Safe to call on any inline-content body
-// — a plain path/command/URL won't match the regex and is returned as-is.
-function _unwrapInnerTag(inner) {
-  if (inner == null) return inner;
-  const trimmed = String(inner).trim();
-  const m = trimmed.match(/^<(\w+)(?:\s[^>]*)?>([\s\S]*)<\/\1>$/);
-  if (!m) return inner;
-  return m[2].trim();
+  return fromInvoke(toolName, params);
 }
 
 // MiniMax-M2 tool-call XML repair. Some inference backends — notably mlx-lm
@@ -1155,130 +685,21 @@ function extractToolCalls(text, options = {}) {
     }
   }
 
-  for (const match of text.matchAll(/<(?:shell|exec|run_command|run)>([\s\S]*?)<\/(?:shell|exec|run_command|run)>/g)) {
-    calls.push(['shell', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<read_file>([\s\S]*?)<\/read_file>/g)) {
-    calls.push(['read', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of _matchDual(text, '<read_file\\s+path=Q([^Q]+)Q\\s*\\/?>')) {
-    calls.push(['read', match[1]]);
-  }
-
-  for (const match of _matchDual(text, '<write_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/write_file>')) {
-    calls.push(['write', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<create_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/create_file>')) {
-    calls.push(['write', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<append_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/append_file>')) {
-    calls.push(['append', match[1], match[2]]);
-  }
-
-  for (const match of text.matchAll(/<list_dir>([\s\S]*?)<\/list_dir>/g)) {
-    calls.push(['list_dir', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<search_files>([\s\S]*?)<\/search_files>/g)) {
-    calls.push(['search_files', _unwrapInnerTag(match[1]).trim(), '.']);
-  }
-
-  for (const match of _matchDual(text, '<search_files\\s+pattern=Q([^Q]+)Q(?:\\s+dir=Q([^Q]*)Q)?\\s*(?:><\\/search_files>|\\/>)')) {
-    calls.push(['search_files', match[1], match[2] || '.']);
-  }
-
-  for (const match of text.matchAll(/<delete_file>([\s\S]*?)<\/delete_file>/g)) {
-    calls.push(['delete_file', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<make_dir>([\s\S]*?)<\/make_dir>/g)) {
-    calls.push(['make_dir', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<remove_dir>([\s\S]*?)<\/remove_dir>/g)) {
-    calls.push(['remove_dir', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<get_env>([\s\S]*?)<\/get_env>/g)) {
-    calls.push(['get_env', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of _matchDual(text, '<set_env\\s+name=Q([^Q]+)Q\\s+value=Q([^Q]*)Q\\s*(?:><\\/set_env>|\\/>)')) {
-    calls.push(['set_env', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<move_file\\s+src=Q([^Q]+)Q\\s+dst=Q([^Q]+)Q\\s*(?:><\\/move_file>|\\/>)')) {
-    calls.push(['move_file', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<copy_file\\s+src=Q([^Q]+)Q\\s+dst=Q([^Q]+)Q\\s*(?:><\\/copy_file>|\\/>)')) {
-    calls.push(['copy_file', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<edit_file\\s+path=Q([^Q]+)Q\\s+line=Q(\\d+)Q>([\\s\\S]*?)<\\/edit_file>')) {
-    calls.push(['edit_file', match[1], parseInt(match[2], 10), match[3]]);
-  }
-
-  for (const match of _matchDual(text, '<search_in_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/search_in_file>')) {
-    calls.push(['search_in_file', match[1], match[2].trim()]);
-  }
-
-  for (const match of _matchDual(text, '<replace_in_file\\s+path=Q([^Q]+)Q\\s+search=Q([^Q]*)Q\\s+replace=Q([^Q]*)Q>([\\s\\S]*?)<\\/replace_in_file>')) {
-    calls.push(['replace_in_file', match[1], match[2], match[3], match[4].trim()]);
-  }
-
-  for (const match of text.matchAll(/<download>([\s\S]*?)<\/download>/g)) {
-    calls.push(['download', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of _matchDual(text, '<upload\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/upload>')) {
-    calls.push(['upload', match[1], match[2]]);
-  }
-
-  for (const match of text.matchAll(/<file_stat>([\s\S]*?)<\/file_stat>/g)) {
-    calls.push(['file_stat', _unwrapInnerTag(match[1]).trim()]);
-  }
-
-  for (const match of text.matchAll(/<http_get\b([^>]*?)(?:><\/http_get>|\/>)/g)) {
-    const attrStr = match[1];
-    const urlMatch = attrStr.match(/url="([^"]+)"/) || attrStr.match(/url='([^']+)'/);
-    if (urlMatch) calls.push(['http_get', urlMatch[1]]);
-  }
-
-  // Inline-content form: <http_get>URL</http_get>. Models mirror the style of
-  // <list_dir>, <download>, etc. even though the system prompt advertises the
-  // attribute form — accept both so the second tag in a multi-call response
-  // isn't silently dropped. Also tolerate `<http_get>url="URL"</http_get>` where
-  // the model put the attribute syntax in the body.
-  for (const match of text.matchAll(/<http_get>([\s\S]*?)<\/http_get>/g)) {
-    const inner = match[1].trim();
-    if (!inner) continue;
-    const urlAttr = inner.match(/url="([^"]+)"/) || inner.match(/url='([^']+)'/);
-    calls.push(['http_get', urlAttr ? urlAttr[1] : _unwrapInnerTag(inner).trim()]);
-  }
-
-  for (const match of _matchDual(text, '<ask_user\\s+question=Q([^Q]+)Q\\s*(?:><\\/ask_user>|\\/>)')) {
-    calls.push(['ask_user', match[1]]);
-  }
-
-  for (const match of _matchDual(text, '<store_memory\\s+key=Q([^Q]+)Q>([\\s\\S]*?)<\\/store_memory>')) {
-    calls.push(['store_memory', match[1], match[2]]);
-  }
-
-  for (const match of _matchDual(text, '<recall_memory\\s+key=Q([^Q]+)Q\\s*(?:><\\/recall_memory>|\\/>)')) {
-    calls.push(['recall_memory', match[1]]);
-  }
-
-  for (const match of text.matchAll(/<list_memories\s*(?:><\/list_memories>|\/>)/g)) {
-    calls.push(['list_memories']);
+  // XML/tag path: each tool's parseAttrs (parseXml) lives next to its spec in
+  // the tool registry. Entries run in array order, which — together with the
+  // wrapper/JSON/fence passes above — reproduces the exact emission order the
+  // characterization tests pin (test/extract-tool-calls.test.js). This replaces
+  // the ~25 standalone regex blocks that used to be inlined here.
+  for (const entry of TOOL_REGISTRY) {
+    if (!entry.parseXml) continue;
+    for (const call of entry.parseXml(text)) calls.push(call);
   }
 
-  for (const match of text.matchAll(/<system_info\s*(?:><\/system_info>|\/>)/g)) {
-    calls.push(['system_info']);
+  // Dynamic tools (MCP, Task 3.3) get the same XML pass so non-native models can
+  // invoke them via `<mcp__server__tool>{json args}</mcp__server__tool>`.
+  for (const entry of dynamicToolEntries()) {
+    if (!entry.parseXml) continue;
+    for (const call of entry.parseXml(text)) calls.push(call);
   }
 
   return calls;
@@ -1307,6 +728,11 @@ module.exports = {
   createToolExecutor,
   extractToolCalls,
   getSkippedOps,
+  // Exported for unit testing (Task 1.1). These pure path guards are otherwise
+  // private; exposing them changes no runtime behavior.
+  isPathSafe,
+  isProtectedSecretPath,
+  isProtectedConfigPath,
   isUIActive,
   mapInvokeToCall,
   repairMinimaxMalformedXml,