subrouter-cli 0.0.0-stage → 0.1.0

package/src/tools.ts

@@ -0,0 +1,790 @@
+// tools.ts — filesystem tools, path confinement, and separately approved commands.
+// File operations stay inside cwd unless the host grants live absolute access.
+// Commands are NOT sandboxed and require a separate approval snapshot.
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { randomUUID } from 'node:crypto';
+import { constants } from 'node:fs';
+import { commandPolicy } from './commandpolicy.ts';
+import type { ToolCall, ToolDefinition } from './types.ts';
+import { executeCommand, validateCommand, sanitizeCommandOutput, DEFAULT_COMMAND_TIMEOUT_MS, MAX_COMMAND_TIMEOUT_MS } from './terminal.ts';
+
+export const MAX_READ_BYTES = 256 * 1024;
+export const MAX_WRITE_BYTES = 1024 * 1024;
+export const MAX_LIST_ENTRIES = 500;
+export const MAX_GREP_RESULTS = 200;
+export const MAX_GREP_FILES = 5000;
+export const MAX_BATCH_FILES = 20;
+export const MAX_TREE_ENTRIES = 5000;
+export const MAX_TREE_BYTES = 100 * 1024 * 1024;
+export const RECOVERY_DIR = '.sub-recovery';
+
+const SKIP_DIRS = new Set(['.git', RECOVERY_DIR, 'node_modules', '.venv', 'venv', '__pycache__', '.next', 'dist', 'build']);
+const SKIP_FILES = new Set(['.DS_Store']);
+const FILE_PATH_DESCRIPTION = 'path relative to the working directory; in absolute mode also accepts absolute, ~/ and parent paths';
+
+export class ConfinementError extends Error {}
+
+/**
+ * Confine a tool-supplied path to the working directory. Two checks, like the Swift
+ * FileToolbox: (1) the raw path must be relative (no absolute, ~, or drive-letter
+ * forms); (2) after resolution, both the lexical path and the realpath of its deepest
+ * existing ancestor must live under realpath(cwd), so symlinks can't escape.
+ * Returns the resolved absolute path to operate on.
+ */
+export async function confined(cwd: string, raw: unknown): Promise<string> {
+  if (typeof raw !== 'string' || raw.trim() === '') {
+    throw new ConfinementError('path must be a non-empty string');
+  }
+  if (raw.startsWith('~') || raw.startsWith('/') || /^[A-Za-z]:[\\/]/.test(raw)) {
+    throw new ConfinementError(`path must be relative to the working directory, got: ${raw}`);
+  }
+  if (raw.includes('\0')) throw new ConfinementError('path contains a null byte');
+  if (raw.split(/[\\/]/).includes(RECOVERY_DIR)) {
+    throw new ConfinementError('recovery storage is private — use list_removed / restore_file');
+  }
+  // Anchor everything at the real cwd — on macOS tmpdir/realpath differ (/var vs /private/var).
+  const realCwd = await fs.realpath(cwd);
+  const resolved = path.resolve(realCwd, raw);
+  if (resolved !== realCwd && !resolved.startsWith(realCwd + path.sep)) {
+    throw new ConfinementError(`path escapes the working directory: ${raw}`);
+  }
+  // Symlink escape guard: realpath the deepest existing ancestor and re-check.
+  let probe = resolved;
+  try {
+    probe = await fs.realpath(resolved);
+  } catch {
+    let dir = path.dirname(resolved);
+    while (true) {
+      try {
+        const realDir = await fs.realpath(dir);
+        const rest = resolved.slice(dir.length).split(path.sep).filter(Boolean);
+        probe = path.join(realDir, ...rest);
+        break;
+      } catch {
+        const parent = path.dirname(dir);
+        if (parent === dir) {
+          probe = resolved;
+          break;
+        }
+        dir = parent;
+      }
+    }
+  }
+  if (probe !== realCwd && !probe.startsWith(realCwd + path.sep)) {
+    throw new ConfinementError(`path resolves outside the working directory (symlink): ${raw}`);
+  }
+  if ([resolved, probe].some((p) => path.relative(realCwd, p).split(path.sep).includes(RECOVERY_DIR))) {
+    throw new ConfinementError('recovery storage is private — use list_removed / restore_file');
+  }
+  // A dangling symlink has no realpath; never let creation follow it outside cwd.
+  let ancestor = resolved;
+  while (ancestor !== realCwd) {
+    const stat = await fs.lstat(ancestor).catch(() => null);
+    if (stat?.isSymbolicLink()) {
+      await fs.realpath(ancestor).catch(() => {
+        throw new ConfinementError('dangling symlinks are not supported');
+      });
+    }
+    ancestor = path.dirname(ancestor);
+  }
+  return resolved;
+}
+
+// A host-only capability scoped to one execution, never model-supplied arguments.
+const absoluteAccess = new AsyncLocalStorage<boolean>();
+
+async function toolPath(cwd: string, raw: unknown, unrestricted = absoluteAccess.getStore() === true): Promise<string> {
+  if (!unrestricted) return confined(cwd, raw);
+  if (typeof raw !== 'string' || raw.trim() === '') throw new ConfinementError('path must be a non-empty string');
+  if (raw.includes('\0')) throw new ConfinementError('path contains a null byte');
+  const expanded = raw === '~' ? os.homedir() : raw.startsWith('~/') ? path.join(os.homedir(), raw.slice(2)) : raw;
+  return path.resolve(await fs.realpath(cwd), expanded);
+}
+
+export const TOOL_DEFINITIONS: ToolDefinition[] = [
+  {
+    name: 'run_command',
+    description: 'Run a noninteractive terminal command after explicit approval, guarded-auto authorization for recognized project tasks, or acknowledged absolute-mode authorization for arbitrary commands. Risky or unknown commands ask outside absolute mode; file approve-all does not authorize commands. Starts in the project by default; absolute mode permits an external cwd. NOT sandboxed: commands can access the wider machine and network. Use for project tests/builds; avoid destructive commands and prefer recoverable file tools. No persistent background jobs or interactive input. Output bounded at 64 KiB; default timeout 60s, maximum 5 minutes.',
+    parameters: {
+      type: 'object',
+      properties: {
+        command: { type: 'string', description: 'exact shell command; /bin/zsh -f -c, up to 16 KiB' },
+        cwd: { type: 'string', description: 'existing project directory (default .); in absolute mode also accepts absolute, ~/ and parent paths' },
+        timeout_ms: { type: 'integer', minimum: 1, maximum: MAX_COMMAND_TIMEOUT_MS, default: DEFAULT_COMMAND_TIMEOUT_MS },
+      },
+      required: ['command'],
+    },
+    requiresApproval: true,
+    approvalScope: 'always',
+  },
+  {
+    name: 'read_file',
+    description:
+      'Read a text file from the working directory, or across the drive in absolute mode. Refuses files larger than 256 KB — use grep to search large files instead.',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } },
+      required: ['path'],
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'write_file',
+    description:
+      'Write a text file (creating parent directories as needed), overwriting it if it exists. Refuses files larger than 1 MB.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+        content: { type: 'string', description: 'full new file contents' },
+      },
+      required: ['path', 'content'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'edit_file',
+    description:
+      'Replace one exact string occurrence in a file. old_string must match exactly once, including whitespace — use read_file first to get the exact text.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: FILE_PATH_DESCRIPTION },
+        old_string: { type: 'string', description: 'exact text to replace, unique in the file' },
+        new_string: { type: 'string', description: 'replacement text' },
+      },
+      required: ['path', 'old_string', 'new_string'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'list_dir',
+    description: 'List the entries of a directory (directories marked with /), up to 500 entries.',
+    parameters: {
+      type: 'object',
+      properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } },
+      required: ['path'],
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'grep',
+    description:
+      'Search files under a directory for a literal substring (not a regex). Skips .git, node_modules, and other build dirs. Returns file:line matches, up to 200.',
+    parameters: {
+      type: 'object',
+      properties: {
+        pattern: { type: 'string', description: 'literal text to search for' },
+        path: { type: 'string', description: `search directory (default .); ${FILE_PATH_DESCRIPTION}` },
+        include: { type: 'string', description: 'only files whose path contains this string' },
+      },
+      required: ['pattern'],
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'read_files',
+    description: 'Read up to 20 text files together. Returns JSON with content or an error for each path; 256 KB total content budget.',
+    parameters: {
+      type: 'object',
+      properties: { paths: { type: 'array', items: { type: 'string', description: FILE_PATH_DESCRIPTION }, minItems: 1, maxItems: MAX_BATCH_FILES } },
+      required: ['paths'],
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'file_info',
+    description: 'Inspect a file or directory without reading its content: type, size, permissions and modification time. Does not follow a final symlink.',
+    parameters: {
+      type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'find_files',
+    description: 'Find files and directories recursively, using an optional literal path substring (not glob/regex). Skips symlinks, recovery, .git, dependencies and build directories. Up to 500 results / 5000 entries.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: `search directory (default .); ${FILE_PATH_DESCRIPTION}` },
+        pattern: { type: 'string', description: 'literal path substring (default all)' },
+        type: { type: 'string', enum: ['file', 'directory', 'all'], description: 'default all' },
+      },
+    },
+    requiresApproval: false,
+  },
+  {
+    name: 'make_dir',
+    description: 'Create a directory and missing parent directories. Existing directories are unchanged.',
+    parameters: {
+      type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'copy_path',
+    description: 'Copy a regular file (including binary assets) or directory tree to a new path. Never overwrites. Refuses symlinks, special files and trees over 5000 entries / 100 MiB. Outside absolute mode also refuses .git and recovery data.',
+    parameters: {
+      type: 'object', properties: { source: { type: 'string', description: FILE_PATH_DESCRIPTION }, destination: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['source', 'destination'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'move_path',
+    description: 'Move or rename a file/directory to a new path inside the working directory, or across the drive in absolute mode. Never overwrites. Same tree/symlink limits as copy_path.',
+    parameters: {
+      type: 'object', properties: { source: { type: 'string', description: FILE_PATH_DESCRIPTION }, destination: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['source', 'destination'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'remove_path',
+    description: 'Recoverably remove a file/directory by moving it into private project recovery storage. Returns a recovery ID for restore_file. No permanent deletion. Same tree limits as copy_path; outside absolute mode cannot remove the working directory.',
+    parameters: {
+      type: 'object', properties: { path: { type: 'string', description: FILE_PATH_DESCRIPTION } }, required: ['path'],
+    },
+    requiresApproval: true,
+  },
+  {
+    name: 'list_removed',
+    description: 'List up to 500 recoverably removed items: recovery ID, original path and removal time. No file content is read.',
+    parameters: { type: 'object', properties: {} },
+    requiresApproval: false,
+  },
+  {
+    name: 'restore_file',
+    description: 'Restore a removed file/directory by recovery ID, to its original path or an optional new destination. Never overwrites.',
+    parameters: {
+      type: 'object',
+      properties: { recovery_id: { type: 'string' }, destination: { type: 'string', description: `optional new destination; ${FILE_PATH_DESCRIPTION}` } },
+      required: ['recovery_id'],
+    },
+    requiresApproval: true,
+  },
+];
+
+const toolByName = new Map(TOOL_DEFINITIONS.map((t) => [t.name, t]));
+
+export interface ToolResult {
+  toolCallId: string;
+  content: string;
+  isError?: boolean;
+}
+
+function argString(args: Record<string, unknown>, key: string): string {
+  const v = args[key];
+  return typeof v === 'string' ? v : '';
+}
+
+function requiredString(args: Record<string, unknown>, key: string, allowEmpty = false): string {
+  const value = args[key];
+  if (typeof value !== 'string' || (!allowEmpty && !value)) throw new Error(`${key} must be a ${allowEmpty ? '' : 'non-empty '}string`);
+  return value;
+}
+
+async function readText(abs: string, limit = MAX_READ_BYTES): Promise<Buffer> {
+  const stat = await fs.stat(abs);
+  if (!stat.isFile()) throw new Error('not a regular file — use list_dir for directories');
+  if (stat.size > limit) throw new Error(`file is ${stat.size} bytes (limit ${limit}) — use grep to search it`);
+  const file = await fs.open(abs, constants.O_RDONLY | constants.O_NONBLOCK);
+  try {
+    if (!(await file.stat()).isFile()) throw new Error('not a regular file');
+    const buffer = Buffer.alloc(limit + 1);
+    let used = 0;
+    while (used < buffer.length) {
+      const { bytesRead } = await file.read(buffer, used, buffer.length - used, null);
+      if (!bytesRead) break;
+      used += bytesRead;
+    }
+    if (used > limit) throw new Error(`file exceeds ${limit} bytes — use grep to search it`);
+    const bytes = buffer.subarray(0, used);
+    if (bytes.includes(0)) throw new Error('binary file — use file_info or copy_path');
+    return bytes;
+  } finally {
+    await file.close();
+  }
+}
+
+async function execReadFile(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await toolPath(cwd, args.path);
+  return { toolCallId: '', content: (await readText(abs)).toString('utf8') };
+}
+
+async function writeText(abs: string, content: string): Promise<void> {
+  const file = await fs.open(abs, constants.O_WRONLY | constants.O_CREAT | constants.O_NOFOLLOW | constants.O_NONBLOCK, 0o666);
+  try {
+    if (!(await file.stat()).isFile()) throw new Error('writes require a regular file');
+    await file.truncate(0);
+    await file.writeFile(content, 'utf8');
+  } finally {
+    await file.close();
+  }
+}
+
+async function execWriteFile(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await mutablePath(cwd, args.path);
+  const content = requiredString(args, 'content', true);
+  if (Buffer.byteLength(content) > MAX_WRITE_BYTES) {
+    throw new Error(`content is ${Buffer.byteLength(content)} bytes (limit ${MAX_WRITE_BYTES})`);
+  }
+  await fs.mkdir(path.dirname(abs), { recursive: true });
+  await writeText(abs, content);
+  return { toolCallId: '', content: `wrote ${Buffer.byteLength(content)} bytes to ${argString(args, 'path')}` };
+}
+
+async function execEditFile(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await mutablePath(cwd, args.path);
+  const oldString = requiredString(args, 'old_string');
+  const newString = requiredString(args, 'new_string', true);
+  const original = (await readText(abs, MAX_WRITE_BYTES)).toString('utf8');
+  const first = original.indexOf(oldString);
+  if (first === -1) throw new Error('old_string not found in the file — read it first for the exact text');
+  if (original.indexOf(oldString, first + oldString.length) !== -1) {
+    throw new Error('old_string matches more than once — make it unique');
+  }
+  const edited = original.slice(0, first) + newString + original.slice(first + oldString.length);
+  if (Buffer.byteLength(edited) > MAX_WRITE_BYTES) throw new Error(`edited file exceeds ${MAX_WRITE_BYTES} bytes`);
+  await writeText(abs, edited);
+  return { toolCallId: '', content: `edited ${argString(args, 'path')} (${original.length} -> ${edited.length} bytes)` };
+}
+
+async function execListDir(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await toolPath(cwd, args.path);
+  const entries = await fs.readdir(abs, { withFileTypes: true }).catch(() => {
+    throw new Error(`no such directory: ${argString(args, 'path')}`);
+  });
+  const lines = entries
+    .slice(0, MAX_LIST_ENTRIES)
+    .map((e) => (e.isDirectory() ? e.name + '/' : e.name))
+    .sort();
+  let content = lines.join('\n') || '(empty directory)';
+  if (entries.length > MAX_LIST_ENTRIES) content += `\n… (${entries.length - MAX_LIST_ENTRIES} more entries)`;
+  return { toolCallId: '', content };
+}
+
+async function walk(base: string, dir: string, include: string, onFile: (abs: string, rel: string) => Promise<boolean>): Promise<boolean> {
+  // Returns true when the walker should stop early (caps reached).
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+  for (const e of entries) {
+    if (e.isDirectory()) {
+      if (SKIP_DIRS.has(e.name)) continue;
+      if (await walk(base, path.join(dir, e.name), include, onFile)) return true;
+    } else if (e.isFile()) {
+      if (SKIP_FILES.has(e.name)) continue;
+      const abs = path.join(dir, e.name);
+      const rel = path.relative(base, abs);
+      if (include && !rel.includes(include)) continue;
+      if (await onFile(abs, rel)) return true;
+    }
+  }
+  return false;
+}
+
+async function execGrep(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const pattern = argString(args, 'pattern');
+  if (!pattern) throw new Error('grep needs a non-empty pattern');
+  const include = argString(args, 'include');
+  const startAbs = await toolPath(cwd, typeof args.path === 'string' && args.path ? args.path : '.');
+  const stat = await fs.stat(startAbs).catch(() => null);
+  if (!stat) throw new Error(`no such path: ${argString(args, 'path') || '.'}`);
+  if (!stat.isDirectory()) throw new Error(`${argString(args, 'path')} is not a directory — grep searches directories`);
+
+  const results: string[] = [];
+  let filesSeen = 0;
+  let capped = false;
+  await walk(startAbs, startAbs, include, async (abs, rel) => {
+    filesSeen++;
+    if (filesSeen > MAX_GREP_FILES) {
+      capped = true;
+      return true;
+    }
+    let text: string;
+    try {
+      text = (await readText(abs)).toString('utf8');
+    } catch {
+      return false;
+    }
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      if (lines[i].includes(pattern)) {
+        results.push(`${rel}:${i + 1}:${lines[i].trim()}`);
+        if (results.length >= MAX_GREP_RESULTS) {
+          capped = true;
+          return true;
+        }
+      }
+    }
+    return false;
+  });
+  let content = results.join('\n') || '(no matches)';
+  if (capped) content += `\n… (results capped at ${MAX_GREP_RESULTS}, files at ${MAX_GREP_FILES})`;
+  return { toolCallId: '', content };
+}
+
+async function execReadFiles(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  if (!Array.isArray(args.paths) || !args.paths.length || args.paths.length > MAX_BATCH_FILES || args.paths.some((p) => typeof p !== 'string')) {
+    throw new Error(`paths must contain 1–${MAX_BATCH_FILES} strings`);
+  }
+  let remaining = MAX_READ_BYTES;
+  const results: { path: string; content?: string; error?: string }[] = [];
+  for (const raw of args.paths as string[]) {
+    try {
+      const bytes = await readText(await toolPath(cwd, raw), remaining);
+      remaining -= bytes.length;
+      results.push({ path: raw, content: bytes.toString('utf8') });
+    } catch (err) {
+      results.push({ path: raw, error: err instanceof Error ? err.message : String(err) });
+    }
+  }
+  return { toolCallId: '', content: JSON.stringify(results) };
+}
+
+async function execFileInfo(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await toolPath(cwd, args.path);
+  const stat = await fs.lstat(abs);
+  return { toolCallId: '', content: JSON.stringify({
+    path: args.path,
+    type: stat.isSymbolicLink() ? 'symlink' : stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'special',
+    size_bytes: stat.size,
+    permissions: (stat.mode & 0o777).toString(8).padStart(3, '0'),
+    modified_at: stat.mtime.toISOString(),
+  }) };
+}
+
+async function execFindFiles(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const start = await toolPath(cwd, args.path ?? '.');
+  if (!(await fs.stat(start)).isDirectory()) throw new Error('find_files needs a directory');
+  const pattern = args.pattern === undefined ? '' : requiredString(args, 'pattern', true);
+  const type = args.type ?? 'all';
+  if (!['file', 'directory', 'all'].includes(type as string)) throw new Error('type must be file, directory, or all');
+  const results: string[] = [];
+  const stack = [start];
+  let seen = 0, capped = false;
+  while (stack.length && !capped) {
+    const dir = await fs.opendir(stack.pop()!);
+    for await (const entry of dir) {
+      if (++seen > MAX_TREE_ENTRIES) { capped = true; break; }
+      if (SKIP_DIRS.has(entry.name) || SKIP_FILES.has(entry.name) || entry.isSymbolicLink()) continue;
+      const abs = path.join(dir.path, entry.name);
+      const rel = path.relative(start, abs);
+      if (entry.isDirectory()) stack.push(abs);
+      if ((entry.isFile() || entry.isDirectory()) && rel.includes(pattern) &&
+          (type === 'all' || (type === 'file' ? entry.isFile() : entry.isDirectory()))) {
+        results.push(rel + (entry.isDirectory() ? '/' : ''));
+        if (results.length >= MAX_LIST_ENTRIES) { capped = true; break; }
+      }
+    }
+  }
+  let content = results.sort().join('\n') || '(no matches)';
+  if (capped) content += `\n… (capped at ${MAX_LIST_ENTRIES} results / ${MAX_TREE_ENTRIES} entries)`;
+  return { toolCallId: '', content };
+}
+
+async function mutablePath(cwd: string, raw: unknown): Promise<string> {
+  const abs = await toolPath(cwd, raw);
+  if (absoluteAccess.getStore() === true) return abs;
+  const root = await fs.realpath(cwd);
+  if (abs === root) throw new Error('cannot mutate the working directory itself');
+  let probe = abs;
+  while (probe !== root) {
+    if (path.basename(probe) === '.git') throw new Error('cannot mutate .git internals');
+    const stat = await fs.lstat(probe).catch((err: NodeJS.ErrnoException) => {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    });
+    if (stat?.isSymbolicLink()) throw new Error('filesystem mutations do not support symlink paths');
+    probe = path.dirname(probe);
+  }
+  return abs;
+}
+
+async function requireMissing(abs: string): Promise<void> {
+  const exists = await fs.lstat(abs).catch((err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (exists) throw new Error('destination already exists — choose a new path; overwriting is not supported');
+}
+
+interface TreeEntry { abs: string; rel: string; directory: boolean; mode: number; }
+
+async function inspectTree(abs: string): Promise<TreeEntry[]> {
+  const entries: TreeEntry[] = [];
+  let bytes = 0;
+  const stack = [{ abs, rel: '' }];
+  while (stack.length) {
+    const item = stack.pop()!;
+    if (entries.length >= MAX_TREE_ENTRIES) throw new Error(`tree exceeds ${MAX_TREE_ENTRIES} entries`);
+    if (absoluteAccess.getStore() !== true && item.rel.split(path.sep).some((name) => name === '.git' || name === RECOVERY_DIR)) {
+      throw new Error('tree contains protected .git or recovery storage');
+    }
+    const stat = await fs.lstat(item.abs);
+    if (!stat.isDirectory() && !stat.isFile()) throw new Error('tree contains a symlink or special file — operation refused');
+    bytes += stat.isFile() ? stat.size : 0;
+    if (bytes > MAX_TREE_BYTES) throw new Error('tree exceeds the 100 MiB limit');
+    entries.push({ ...item, directory: stat.isDirectory(), mode: stat.mode & 0o777 });
+    if (stat.isDirectory()) {
+      const dir = await fs.opendir(item.abs);
+      for await (const entry of dir) {
+        if (entries.length + stack.length >= MAX_TREE_ENTRIES) throw new Error(`tree exceeds ${MAX_TREE_ENTRIES} entries`);
+        stack.push({ abs: path.join(item.abs, entry.name), rel: path.join(item.rel, entry.name) });
+      }
+    }
+  }
+  return entries;
+}
+
+async function execMakeDir(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await mutablePath(cwd, args.path);
+  await fs.mkdir(abs, { recursive: true });
+  return { toolCallId: '', content: `directory ready: ${args.path}` };
+}
+
+async function execTransfer(cwd: string, args: Record<string, unknown>, move: boolean): Promise<ToolResult> {
+  const source = await mutablePath(cwd, args.source);
+  const destination = await mutablePath(cwd, args.destination);
+  if (destination === source || destination.startsWith(source + path.sep)) throw new Error('destination must be outside the source tree');
+  await requireMissing(destination);
+  const entries = await inspectTree(source);
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  if (move) {
+    await fs.rename(source, destination);
+  } else {
+    let created = false;
+    try {
+      for (const entry of entries) {
+        const dest = path.join(destination, entry.rel);
+        // Recheck before each copy; never deliberately follow links from the source tree.
+        await mutablePath(cwd, path.relative(await fs.realpath(cwd), entry.abs));
+        const stat = await fs.lstat(entry.abs);
+        if (entry.directory ? !stat.isDirectory() : !stat.isFile()) throw new Error('tree contains a symlink or special file — operation refused');
+        if (entry.directory) await fs.mkdir(dest);
+        else await fs.copyFile(entry.abs, dest, constants.COPYFILE_EXCL);
+        if (!entry.rel) created = true;
+        if (!entry.directory) await fs.chmod(dest, entry.mode);
+      }
+    } catch (err) {
+      if (created) await fs.rm(destination, { recursive: true, force: true });
+      throw err;
+    }
+  }
+  return { toolCallId: '', content: `${move ? 'moved' : 'copied'} ${args.source} → ${args.destination} (${entries.length} entries)` };
+}
+
+interface RecoveryRecord { path: string; removed_at: string; }
+const RECOVERY_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
+
+async function recoveryRoot(cwd: string, create = false): Promise<string> {
+  const root = path.join(await fs.realpath(cwd), RECOVERY_DIR);
+  if (create) await fs.mkdir(root, { mode: 0o700 }).catch((err: NodeJS.ErrnoException) => {
+    if (err.code !== 'EEXIST') throw err;
+  });
+  const stat = await fs.lstat(root);
+  if (!stat.isDirectory() || stat.isSymbolicLink()) throw new Error('recovery storage must be a real directory');
+  if (stat.mode & 0o077) throw new Error('recovery storage must be private (directory mode 0700)');
+  if (create) {
+    await fs.writeFile(path.join(root, '.gitignore'), '*\n', { flag: 'wx', mode: 0o600 }).catch((err: NodeJS.ErrnoException) => {
+      if (err.code !== 'EEXIST') throw err;
+    });
+  }
+  return root;
+}
+
+async function recoveryEntry(root: string, id: unknown): Promise<{ entry: string; record: RecoveryRecord }> {
+  if (typeof id !== 'string' || !RECOVERY_ID.test(id)) throw new Error('invalid recovery_id — use list_removed');
+  const entry = path.join(root, id);
+  if (!(await fs.lstat(entry)).isDirectory()) throw new Error('invalid recovery entry');
+  const file = await fs.open(path.join(entry, 'record.json'), constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  let record: RecoveryRecord;
+  try {
+    const stat = await file.stat();
+    if (!stat.isFile() || stat.size > 4096) throw new Error('invalid recovery record');
+    const buffer = Buffer.alloc(4097);
+    const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+    if (bytesRead > 4096) throw new Error('invalid recovery record');
+    const parsed: unknown = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
+    if (!parsed || typeof parsed !== 'object' || !('path' in parsed) || typeof parsed.path !== 'string' ||
+        !('removed_at' in parsed) || typeof parsed.removed_at !== 'string') throw new Error('invalid recovery record');
+    record = { path: parsed.path, removed_at: parsed.removed_at };
+  } finally {
+    await file.close();
+  }
+  await fs.lstat(path.join(entry, 'item'));
+  return { entry, record };
+}
+
+async function execRemovePath(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const abs = await mutablePath(cwd, args.path);
+  await inspectTree(abs);
+  const root = await recoveryRoot(cwd, true);
+  const id = randomUUID();
+  const entry = path.join(root, id);
+  await fs.mkdir(entry, { mode: 0o700 });
+  const record = { path: path.relative(await fs.realpath(cwd), abs), removed_at: new Date().toISOString() };
+  try {
+    const json = JSON.stringify(record);
+    if (Buffer.byteLength(json) > 4096) throw new Error('original path is too long for a recovery record');
+    await fs.writeFile(path.join(entry, 'record.json'), json, { flag: 'wx', mode: 0o600 });
+    await fs.rename(abs, path.join(entry, 'item'));
+  } catch (err) {
+    await fs.unlink(path.join(entry, 'record.json')).catch(() => {});
+    await fs.rmdir(entry).catch(() => {});
+    throw err;
+  }
+  return { toolCallId: '', content: JSON.stringify({ removed: record.path, recovery_id: id, hint: 'use restore_file to recover; no automatic purge' }) };
+}
+
+async function execListRemoved(cwd: string): Promise<ToolResult> {
+  const root = await recoveryRoot(cwd).catch((err: NodeJS.ErrnoException) => {
+    if (err.code === 'ENOENT') return null;
+    throw err;
+  });
+  if (!root) return { toolCallId: '', content: JSON.stringify({ items: [], capped: false }) };
+  const records: { recovery_id: string; path: string; removed_at: string }[] = [];
+  const dir = await fs.opendir(root);
+  let seen = 0, capped = false;
+  for await (const entry of dir) {
+    if (++seen > MAX_TREE_ENTRIES || records.length >= MAX_LIST_ENTRIES) { capped = true; break; }
+    if (!entry.isDirectory() || !RECOVERY_ID.test(entry.name)) continue;
+    try {
+      const { record } = await recoveryEntry(root, entry.name);
+      records.push({ recovery_id: entry.name, ...record });
+    } catch { /* Incomplete or tampered records are not restorable listings. */ }
+  }
+  return { toolCallId: '', content: JSON.stringify({ items: records, capped }) };
+}
+
+async function execRestoreFile(cwd: string, args: Record<string, unknown>): Promise<ToolResult> {
+  const root = await recoveryRoot(cwd);
+  const { entry, record } = await recoveryEntry(root, args.recovery_id);
+  const destination = await mutablePath(cwd, args.destination ?? record.path);
+  await requireMissing(destination);
+  await inspectTree(path.join(entry, 'item'));
+  await fs.mkdir(path.dirname(destination), { recursive: true });
+  await fs.rename(path.join(entry, 'item'), destination);
+  await fs.unlink(path.join(entry, 'record.json')).catch(() => {});
+  await fs.rmdir(entry).catch(() => {});
+  return { toolCallId: '', content: `restored ${args.recovery_id} → ${path.relative(await fs.realpath(cwd), destination)}` };
+}
+
+export interface PreparedCommand { command: string; cwd: string; timeoutMs: number; }
+export interface CommandApproval extends PreparedCommand { kind?: 'explicit' | 'auto' | 'absolute'; }
+
+export async function prepareCommand(cwd: string, args: Record<string, unknown>, redactValues: string[] = [], unrestricted = false): Promise<PreparedCommand> {
+  const command = validateCommand(args.command, args.timeout_ms, redactValues);
+  const rawCwd = args.cwd;
+  if (typeof rawCwd === 'string' && redactValues.some((value) => value && rawCwd.includes(value))) {
+    throw new Error('command cwd contains a protected credential');
+  }
+  const abs = await toolPath(cwd, args.cwd === undefined ? '.' : args.cwd, unrestricted);
+  if (!(await fs.stat(abs)).isDirectory()) throw new Error('command cwd must be an existing directory');
+  return { ...command, cwd: await fs.realpath(abs) };
+}
+
+export interface ToolExecutionOptions {
+  signal?: AbortSignal;
+  redactValues?: string[];
+  commandApproval?: CommandApproval; // exact explicit, guarded-auto or absolute authorization
+  autoEnabled?: () => boolean; // checked when queued execution actually starts
+  absoluteAccess?: boolean; // host-only file/cwd capability, never a tool argument
+  absoluteEnabled?: () => boolean; // required live authorization at queued execution start
+  onStart?: () => void;
+}
+
+const mutationTails = new Map<string, Promise<void>>();
+
+/** Execute a tool. Commands require an approval snapshot; failures become error results. */
+export async function executeTool(call: ToolCall, cwd: string, options: ToolExecutionOptions = {}): Promise<ToolResult> {
+  const def = toolByName.get(call.name);
+  const result = (): Promise<ToolResult> => absoluteAccess.run(options.absoluteAccess === true, async () => {
+    if (!def) throw new Error(`unknown tool: ${call.name}`);
+    options.signal?.throwIfAborted(); // also checked when serialized execution actually starts
+    if ((options.absoluteAccess === true || options.commandApproval?.kind === 'absolute') && !options.absoluteEnabled?.()) {
+      throw new Error('absolute authorization revoked — request approval again');
+    }
+    if (call.argumentsInvalid) throw new Error('invalid tool arguments');
+    switch (call.name) {
+      case 'run_command': {
+        const approved = options.commandApproval;
+        if (!approved) throw new Error('terminal commands require separate explicit approval or guarded-auto authorization');
+        const current = await prepareCommand(cwd, call.arguments, options.redactValues, options.absoluteAccess === true);
+        if (current.command !== approved.command || current.cwd !== approved.cwd || current.timeoutMs !== approved.timeoutMs) {
+          throw new Error('terminal command changed after approval — request approval again');
+        }
+        if (approved.kind === 'auto') {
+          if (!options.autoEnabled?.()) throw new Error('auto authorization revoked — request approval again');
+          const decision = await commandPolicy(current.command, current.cwd);
+          if (!decision.auto || !options.autoEnabled?.()) throw new Error('auto authorization no longer eligible — request approval again');
+        }
+        if ((approved.kind === 'absolute' || options.absoluteAccess === true) && !options.absoluteEnabled?.()) {
+          throw new Error('absolute authorization revoked — request approval again');
+        }
+        options.signal?.throwIfAborted();
+        options.onStart?.();
+        const command = await executeCommand({ ...current, signal: options.signal, redactValues: options.redactValues });
+        return { toolCallId: '', content: JSON.stringify(command), isError: command.status === 'completed' ? undefined : true };
+      }
+      case 'read_file':
+        return await execReadFile(cwd, call.arguments);
+      case 'write_file':
+        return await execWriteFile(cwd, call.arguments);
+      case 'edit_file':
+        return await execEditFile(cwd, call.arguments);
+      case 'list_dir':
+        return await execListDir(cwd, call.arguments);
+      case 'grep':
+        return await execGrep(cwd, call.arguments);
+      case 'read_files':
+        return await execReadFiles(cwd, call.arguments);
+      case 'file_info':
+        return await execFileInfo(cwd, call.arguments);
+      case 'find_files':
+        return await execFindFiles(cwd, call.arguments);
+      case 'make_dir':
+        return await execMakeDir(cwd, call.arguments);
+      case 'copy_path':
+        return await execTransfer(cwd, call.arguments, false);
+      case 'move_path':
+        return await execTransfer(cwd, call.arguments, true);
+      case 'remove_path':
+        return await execRemovePath(cwd, call.arguments);
+      case 'list_removed':
+        return await execListRemoved(cwd);
+      case 'restore_file':
+        return await execRestoreFile(cwd, call.arguments);
+      default:
+        throw new Error(`unknown tool: ${call.name}`);
+    }
+  });
+  try {
+    let r: ToolResult;
+    if (def?.requiresApproval) {
+      // Keep parallel batches from racing one another's mutations in the same project.
+      const key = await fs.realpath(cwd);
+      const task = (mutationTails.get(key) ?? Promise.resolve()).then(result);
+      const tail = task.then(() => {}, () => {});
+      mutationTails.set(key, tail);
+      try { r = await task; }
+      finally { if (mutationTails.get(key) === tail) mutationTails.delete(key); }
+    } else {
+      r = await result();
+    }
+    r.toolCallId = call.id;
+    if (options.absoluteAccess === true) {
+      // Drive-wide reads must not put the known router credential into history.
+      for (const value of options.redactValues ?? []) if (value) r.content = r.content.replaceAll(value, '[REDACTED]');
+    }
+    return r;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return { toolCallId: call.id, content: call.name === 'run_command' || options.absoluteAccess === true ? sanitizeCommandOutput(message, options.redactValues) : message, isError: true };
+  }
+}
+
+export function toolRequiresApproval(name: string): boolean {
+  return toolByName.get(name)?.requiresApproval ?? false;
+}