aether-code 0.42.0 → 0.43.0

package/src/tools.js

@@ -1,1288 +1,1288 @@
-// Tool implementations + JSON-schema definitions.
-//
-// Safety model:
-//   - read_file, list_dir, search_files: auto-execute (read-only)
-//   - write_file, edit_file: show diff, require y/n confirmation (or --yes flag)
-//   - run_shell: show command, require y/n confirmation (or --yes flag)
-//
-// Path safety: every path is resolved against `cwd` and rejected if it
-// escapes `cwd` — unless the user explicitly passes --unsafe-paths.
-
-import fs from "node:fs";
-import path from "node:path";
-import readline from "node:readline";
-import { spawn } from "node:child_process";
-import { c } from "./render.js";
-import { promptChoice } from "./menu.js";
-import { unifiedDiff, summarizeWrite } from "./diff.js";
-import { getConfig } from "./config.js";
-import { getVersion } from "./version.js";
-
-/* ─────────────────────── Tool definitions (sent to model) ─────────────────────── */
-
-export const TOOL_DEFINITIONS = [
-  {
-    type: "function",
-    function: {
-      name: "read_file",
-      description:
-        "Read the contents of a file as UTF-8 text. Returns the file contents or an error if the file doesn't exist.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Path relative to the working directory, or absolute." },
-        },
-        required: ["path"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "list_dir",
-      description:
-        "List the entries in a directory. Returns an array of {name, type: 'file'|'dir', size?: number}. Hidden files (starting with .) are excluded by default.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Directory path." },
-          include_hidden: { type: "boolean", description: "Include dotfiles. Default: false." },
-        },
-        required: ["path"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "search_files",
-      description:
-        "Recursively search for a regex pattern across files in a directory. Returns matching file paths and the matching line. Limited to 50 results.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "Directory to search." },
-          pattern: { type: "string", description: "JavaScript-style regex (without slashes)." },
-          glob: { type: "string", description: "Optional file-name glob filter, e.g. '*.ts'." },
-        },
-        required: ["path", "pattern"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "glob_files",
-      description:
-        "Find files by path pattern (no content search). Returns matching file paths sorted by most-recently-modified. Use this to locate files by name/extension/location, e.g. '**/*.ts', 'src/**/*.test.js', 'package.json'. Faster and clearer than search_files when you only need to find files, not grep their contents.",
-      parameters: {
-        type: "object",
-        properties: {
-          pattern: { type: "string", description: "Glob pattern. Supports ** (any depth), * (within a path segment), ?. e.g. 'src/**/*.js'." },
-          path: { type: "string", description: "Directory to search from. Default: the working directory." },
-        },
-        required: ["pattern"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "write_file",
-      description:
-        "Create or completely overwrite a file with the given content. The user will be shown a diff and may decline. If the parent directory doesn't exist, it will be created.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "File path." },
-          content: { type: "string", description: "Full file content to write." },
-        },
-        required: ["path", "content"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "edit_file",
-      description:
-        "Replace occurrences of `find` with `replace` in an existing file. Use this for targeted edits instead of rewriting whole files. By default replaces exactly one occurrence and fails if `find` is missing or appears more than once. Set `replace_all: true` to replace every occurrence.",
-      parameters: {
-        type: "object",
-        properties: {
-          path: { type: "string", description: "File path." },
-          find: { type: "string", description: "Exact text to replace. Must be unique unless replace_all is true." },
-          replace: { type: "string", description: "Text to substitute in." },
-          replace_all: { type: "boolean", description: "Replace ALL occurrences instead of requiring a unique match. Default: false." },
-        },
-        required: ["path", "find", "replace"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "run_shell",
-      description:
-        "Run a shell command and return its stdout, stderr, and exit code. The user will be shown the command and may decline. Used for builds, tests, package installs, git operations, etc.",
-      parameters: {
-        type: "object",
-        properties: {
-          command: { type: "string", description: "The shell command to run." },
-          cwd: { type: "string", description: "Optional working directory (relative or absolute)." },
-        },
-        required: ["command"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "web_search",
-      description:
-        "Search the live web for a query and return a JSON array of {title, url, snippet} results. Use this to find current docs, recent libraries, API references, or anything that may have changed since training. ALWAYS prefer this over guessing at library APIs. Cost: ~3–8 credits per call.",
-      parameters: {
-        type: "object",
-        properties: {
-          query: { type: "string", description: "Plain-language search query." },
-          max_results: { type: "number", description: "How many results to return (1–10, default 5)." },
-        },
-        required: ["query"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "web_fetch",
-      description:
-        "Fetch a URL and return its content as plain text (HTML scripts/styles stripped, tags removed, entities decoded). Use this after web_search to read the actual docs page. NEVER pass a URL you didn't get from a real source — only http:// or https:// is allowed. Caps response at 50 KB of text.",
-      parameters: {
-        type: "object",
-        properties: {
-          url: { type: "string", description: "Full http(s) URL to fetch." },
-        },
-        required: ["url"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "todo_write",
-      description:
-        "Replace the current todo list with a new state. Use this at the start of any task with 3+ steps to plan upfront, then call again to mark items 'in_progress' as you start them and 'completed' as you finish. Visible progress for the user; structural discipline for you. Status must be one of: 'pending', 'in_progress', 'completed'. Max 30 items per list.",
-      parameters: {
-        type: "object",
-        properties: {
-          todos: {
-            type: "array",
-            description: "Full replacement list (latest-wins semantics).",
-            items: {
-              type: "object",
-              properties: {
-                content: { type: "string", description: "Short imperative phrase, e.g. 'wire endpoint into UI'." },
-                status: {
-                  type: "string",
-                  enum: ["pending", "in_progress", "completed"],
-                  description: "Task status.",
-                },
-              },
-              required: ["content", "status"],
-            },
-          },
-        },
-        required: ["todos"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "ask_user",
-      description:
-        "Ask the user a single multiple-choice question and wait for their answer. Use this ONLY when the request is genuinely ambiguous AND the answer materially changes what you build — e.g. which platform/framework/language, the scope, or an irreversible decision. Ask BEFORE building when a wrong assumption would waste real work. Give 2–5 concrete options, each with a short description; put the best default first. Do NOT use it for trivial choices, things you can infer, or to confirm permission to act — just build when the task is clear.",
-      parameters: {
-        type: "object",
-        properties: {
-          question: { type: "string", description: "The single, focused question to ask." },
-          options: {
-            type: "array",
-            description: "2–5 options. Each is {label, description}. Best default first.",
-            items: {
-              type: "object",
-              properties: {
-                label: { type: "string", description: "Short option label." },
-                description: { type: "string", description: "One-line explanation of this option." },
-              },
-              required: ["label"],
-            },
-          },
-        },
-        required: ["question", "options"],
-      },
-    },
-  },
-  /* ─────────────────────── Git tools ─────────────────────── */
-  {
-    type: "function",
-    function: {
-      name: "git_status",
-      description:
-        "Show the working tree status — staged, unstaged, and untracked files. Auto-executes (read-only). Use this before committing to see what's changed.",
-      parameters: {
-        type: "object",
-        properties: {},
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_diff",
-      description:
-        "Show a unified diff of changes. By default shows unstaged changes. Set staged=true for staged changes, or pass base/head for branch comparisons (e.g. base='main' head='HEAD'). Optionally limit to specific file(s).",
-      parameters: {
-        type: "object",
-        properties: {
-          staged: { type: "boolean", description: "Show staged (--cached) diff instead of unstaged. Default: false." },
-          base: { type: "string", description: "Base ref for comparison (e.g. 'main', 'HEAD~3'). When set, shows diff between base and head." },
-          head: { type: "string", description: "Head ref for comparison. Default: 'HEAD' when base is set." },
-          files: {
-            type: "array",
-            description: "Limit diff to these file paths.",
-            items: { type: "string" },
-          },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_log",
-      description:
-        "Show recent commit history with hash, author, date, and message. Defaults to 15 commits. Use this to understand what's been done recently, find commit hashes, or check the commit style before committing.",
-      parameters: {
-        type: "object",
-        properties: {
-          count: { type: "number", description: "Number of commits to show (1-50). Default: 15." },
-          oneline: { type: "boolean", description: "Compact one-line format. Default: false." },
-          file: { type: "string", description: "Show only commits that touched this file." },
-          branch: { type: "string", description: "Show commits on this branch instead of HEAD." },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_commit",
-      description:
-        "Stage files and create a commit. If no files are specified, stages all modified/new files (git add -A). The user will see what's being committed and confirm. Use git_status first to see what's changed, and git_log to match the commit message style.",
-      parameters: {
-        type: "object",
-        properties: {
-          message: { type: "string", description: "Commit message. Be concise — focus on WHY, not WHAT." },
-          files: {
-            type: "array",
-            description: "Specific files to stage. If omitted, stages everything (git add -A).",
-            items: { type: "string" },
-          },
-        },
-        required: ["message"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_branch",
-      description:
-        "Create and/or switch to a branch. If the branch exists, switches to it. If it doesn't, creates it from the current HEAD (or from 'base' if specified) and switches to it.",
-      parameters: {
-        type: "object",
-        properties: {
-          name: { type: "string", description: "Branch name to create or switch to." },
-          base: { type: "string", description: "Create the branch from this ref instead of HEAD." },
-        },
-        required: ["name"],
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_push",
-      description:
-        "Push the current branch to the remote. Sets upstream tracking (-u origin) on first push. The user will confirm before pushing.",
-      parameters: {
-        type: "object",
-        properties: {
-          force: { type: "boolean", description: "Force push (--force-with-lease). Use only when explicitly asked. Default: false." },
-        },
-      },
-    },
-  },
-  {
-    type: "function",
-    function: {
-      name: "git_create_pr",
-      description:
-        "Create a GitHub pull request using the `gh` CLI. Requires `gh` to be installed and authenticated. Pushes the branch first if needed. The user will confirm before creating.",
-      parameters: {
-        type: "object",
-        properties: {
-          title: { type: "string", description: "PR title. Keep under 72 chars." },
-          body: { type: "string", description: "PR body/description. Markdown supported." },
-          base: { type: "string", description: "Target branch to merge into. Default: repo default (usually main)." },
-          draft: { type: "boolean", description: "Create as a draft PR. Default: false." },
-        },
-        required: ["title", "body"],
-      },
-    },
-  },
-];
-
-/* ─────────────────────── Argument validation ─────────────────────── */
-
-const TOOL_SCHEMAS = Object.fromEntries(
-  TOOL_DEFINITIONS.map((t) => [t.function.name, t.function.parameters]),
-);
-
-function typeMatches(val, t) {
-  switch (t) {
-    case "string": return typeof val === "string";
-    case "number": return typeof val === "number";
-    case "integer": return typeof val === "number" && Number.isInteger(val);
-    case "boolean": return typeof val === "boolean";
-    case "object": return typeof val === "object" && val !== null && !Array.isArray(val);
-    case "array": return Array.isArray(val);
-    default: return true;
-  }
-}
-
-/**
- * Validate parsed tool arguments against the tool's JSON schema BEFORE the
- * handler runs. Returns an error string the model can act on, or null if valid.
- * Catches malformed/partial args from the model that would otherwise surface as
- * cryptic downstream errors.
- */
-export function validateToolArgs(name, args) {
-  const schema = TOOL_SCHEMAS[name];
-  if (!schema) return `Unknown tool: ${name}`;
-  if (typeof args !== "object" || args === null || Array.isArray(args)) {
-    return `Arguments for ${name} must be a JSON object.`;
-  }
-  for (const req of schema.required ?? []) {
-    if (args[req] === undefined || args[req] === null) {
-      return `Missing required argument "${req}" for ${name}.`;
-    }
-  }
-  for (const [key, val] of Object.entries(args)) {
-    const prop = schema.properties?.[key];
-    if (!prop || val === undefined || val === null) continue;
-    if (prop.type && !typeMatches(val, prop.type)) {
-      return `Argument "${key}" for ${name} must be of type ${prop.type}.`;
-    }
-  }
-  return null;
-}
-
-/* ─────────────────────── Glob + ignore helpers ─────────────────────── */
-
-const ALWAYS_SKIP = new Set([".git", "node_modules", "dist"]);
-const MAX_SEARCH_MATCHES = 200;
-const MAX_GLOB_RESULTS = 300;
-
-// Convert a glob ('**', '*', '?') to an anchored regex over a POSIX-style
-// relative path. ** spans directory separators; * does not.
-export function globToRegExp(glob) {
-  let re = "";
-  let braceDepth = 0;
-  for (let i = 0; i < glob.length; i++) {
-    const ch = glob[i];
-    if (ch === "*") {
-      if (glob[i + 1] === "*") {
-        re += ".*";
-        i++;
-        if (glob[i + 1] === "/") i++; // collapse '**/' so it can also match zero dirs
-      } else {
-        re += "[^/]*";
-      }
-    } else if (ch === "?") {
-      re += "[^/]";
-    } else if (ch === "{") {
-      // Brace expansion: {js,ts} -> (js|ts). Common in .gitignore (*.{js,ts});
-      // treating it literally silently failed to ignore those files.
-      re += "(";
-      braceDepth++;
-    } else if (ch === "}" && braceDepth > 0) {
-      re += ")";
-      braceDepth--;
-    } else if (ch === "," && braceDepth > 0) {
-      re += "|";
-    } else if ("\\^$+.()|{}[]".includes(ch)) {
-      re += "\\" + ch;
-    } else {
-      re += ch;
-    }
-  }
-  return new RegExp("^" + re + "$");
-}
-
-// Parse a .gitignore at `root` into a matcher. Pragmatic subset of gitignore
-// semantics: blank/comment lines ignored; trailing '/' = directory-only;
-// leading '/' = root-anchored; '*'/'?' globs supported.
-function loadIgnore(root) {
-  let lines = [];
-  try { lines = fs.readFileSync(path.join(root, ".gitignore"), "utf8").split("\n"); } catch { /* none */ }
-  const rules = [];
-  for (const raw of lines) {
-    const line = raw.trim();
-    if (!line || line.startsWith("#")) continue;
-    let pat = line;
-    const dirOnly = pat.endsWith("/");
-    if (dirOnly) pat = pat.slice(0, -1);
-    const anchored = pat.startsWith("/");
-    if (anchored) pat = pat.slice(1);
-    rules.push({ re: globToRegExp(pat), anchored, dirOnly, base: !pat.includes("/") });
-  }
-  return (relPath, isDir) => {
-    const norm = relPath.split(path.sep).join("/");
-    const baseName = norm.split("/").pop();
-    for (const r of rules) {
-      if (r.dirOnly && !isDir) continue;
-      if (r.base) { if (r.re.test(baseName)) return true; }
-      else if (r.anchored) { if (r.re.test(norm)) return true; }
-      else if (r.re.test(norm) || r.re.test(baseName)) return true;
-    }
-    return false;
-  };
-}
-
-/* ─────────────────────── Helpers ─────────────────────── */
-
-function resolveSafe(rel, opts) {
-  const abs = path.isAbsolute(rel) ? path.normalize(rel) : path.resolve(opts.cwd, rel);
-  if (!opts.unsafePaths) {
-    const cwd = path.resolve(opts.cwd);
-    // Use path.relative (not startsWith) so Windows drive-relative inputs like
-    // "C:evil.txt" — which path.isAbsolute() reports as NON-absolute and
-    // path.resolve() may anchor to a drive's own cwd outside the project — are
-    // caught. A path is inside cwd only if its relative form doesn't climb out
-    // (no leading "..") and isn't itself absolute (different drive/root).
-    const relToCwd = path.relative(cwd, abs);
-    const escapes = relToCwd === ".." || relToCwd.startsWith(".." + path.sep) || path.isAbsolute(relToCwd);
-    if (abs !== cwd && escapes) {
-      throw new Error(
-        `Refusing to touch path outside cwd: ${abs}\n  Run with --unsafe-paths if you really mean this.`,
-      );
-    }
-  }
-  return abs;
-}
-
-function ask(question) {
-  if (!process.stdin.isTTY) {
-    return Promise.resolve("n"); // can't prompt in non-TTY; default no
-  }
-  return new Promise((resolve) => {
-    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(question, (answer) => {
-      rl.close();
-      resolve(answer.trim().toLowerCase());
-    });
-  });
-}
-
-async function confirm(question, autoYes) {
-  if (autoYes) return true;
-  const ans = await ask(`${question} ${c.dim("[y/N]: ")}`);
-  return ans === "y" || ans === "yes";
-}
-
-/* ─────────────────────── Implementations ─────────────────────── */
-
-export async function executeTool(call, opts) {
-  let args;
-  try {
-    args = JSON.parse(call.function.arguments || "{}");
-  } catch (e) {
-    return { ok: false, output: `Invalid JSON arguments: ${e.message}` };
-  }
-
-  const name = call.function.name;
-  const validationError = validateToolArgs(name, args);
-  if (validationError) {
-    return { ok: false, output: validationError };
-  }
-  const handlers = {
-    read_file: () => readFile(args, opts),
-    list_dir: () => listDir(args, opts),
-    search_files: () => searchFiles(args, opts),
-    glob_files: () => globFiles(args, opts),
-    write_file: () => writeFile(args, opts),
-    edit_file: () => editFile(args, opts),
-    run_shell: () => runShell(args, opts),
-    web_search: () => webSearch(args, opts),
-    web_fetch: () => webFetch(args, opts),
-    todo_write: () => todoWrite(args, opts),
-    ask_user: () => askUser(args, opts),
-    git_status: () => gitStatus(args, opts),
-    git_diff: () => gitDiff(args, opts),
-    git_log: () => gitLog(args, opts),
-    git_commit: () => gitCommit(args, opts),
-    git_branch: () => gitBranch(args, opts),
-    git_push: () => gitPush(args, opts),
-    git_create_pr: () => gitCreatePr(args, opts),
-  };
-  const fn = handlers[name];
-  if (!fn) {
-    return { ok: false, output: `Unknown tool: ${name}` };
-  }
-  try {
-    return await fn();
-  } catch (e) {
-    return { ok: false, output: `${name} failed: ${e.message}` };
-  }
-}
-
-// Ask the user a multiple-choice question and block on their answer. Not a
-// permission gate — it runs even in skip-permissions mode, because the model is
-// explicitly requesting input. In a non-TTY the menu auto-picks the first
-// option so scripted runs don't hang.
-async function askUser(args, _opts) {
-  const options = Array.isArray(args.options) ? args.options : [];
-  if (options.length === 0) {
-    return { ok: false, output: "ask_user requires a non-empty options array" };
-  }
-  const choice = await promptChoice({ question: String(args.question || "Which option?"), options });
-  if (!choice) {
-    return { ok: true, output: "The user cancelled the question. Proceed with your best judgment." };
-  }
-  const extra = choice.description ? ` (${choice.description})` : "";
-  return { ok: true, output: `The user chose: ${choice.label}${extra}` };
-}
-
-function readFile(args, opts) {
-  if (typeof args.path !== "string") return { ok: false, output: "path is required" };
-  const abs = resolveSafe(args.path, opts);
-  let stat;
-  try { stat = fs.statSync(abs); } catch (e) {
-    return { ok: false, output: `Cannot access ${args.path}: ${e.code || e.message}` };
-  }
-  if (stat.isDirectory()) return { ok: false, output: `${args.path} is a directory, not a file` };
-  // Block non-regular files (named pipes, sockets, devices) — reading them can
-  // hang forever (no timeout on readFileSync).
-  if (!stat.isFile()) return { ok: false, output: `${args.path} is not a regular file.` };
-  if (stat.size > 1_000_000) {
-    return { ok: false, output: `File too large (${stat.size} bytes). Aether refuses to read >1MB at once.` };
-  }
-  try {
-    return { ok: true, output: fs.readFileSync(abs, "utf8") };
-  } catch (e) {
-    return { ok: false, output: `Cannot read ${args.path}: ${e.code || e.message}` };
-  }
-}
-
-function listDir(args, opts) {
-  if (typeof args.path !== "string") return { ok: false, output: "path is required" };
-  const abs = resolveSafe(args.path, opts);
-  const entries = fs.readdirSync(abs, { withFileTypes: true });
-  const results = [];
-  for (const e of entries) {
-    if (!args.include_hidden && e.name.startsWith(".")) continue;
-    if (e.name === "node_modules" || e.name === ".git" || e.name === "dist") continue;
-    let size = undefined;
-    if (e.isFile()) {
-      try { size = fs.statSync(path.join(abs, e.name)).size; } catch { /* skip */ }
-    }
-    results.push({
-      name: e.name,
-      type: e.isDirectory() ? "dir" : e.isFile() ? "file" : "other",
-      size,
-    });
-  }
-  results.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1));
-  return { ok: true, output: JSON.stringify(results, null, 2) };
-}
-
-function searchFiles(args, opts) {
-  if (typeof args.path !== "string" || typeof args.pattern !== "string") {
-    return { ok: false, output: "path and pattern are required" };
-  }
-  let regex;
-  try { regex = new RegExp(args.pattern); } catch (e) {
-    return { ok: false, output: `Invalid regex: ${e.message}` };
-  }
-  const root = resolveSafe(args.path, opts);
-  const isIgnored = loadIgnore(path.resolve(opts.cwd));
-  const matches = [];
-  const globRe = args.glob ? globToRegExp(args.glob) : null;
-  let truncated = false;
-
-  function walk(dir) {
-    if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
-    let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    for (const e of entries) {
-      if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
-      if (e.name.startsWith(".") || ALWAYS_SKIP.has(e.name)) continue;
-      const full = path.join(dir, e.name);
-      const rel = path.relative(opts.cwd, full);
-      if (isIgnored(rel, e.isDirectory())) continue;
-      if (e.isDirectory()) {
-        walk(full);
-      } else if (e.isFile()) {
-        if (globRe && !globRe.test(e.name)) continue;
-        let content;
-        try {
-          const stat = fs.statSync(full);
-          if (stat.size > 500_000) continue;
-          content = fs.readFileSync(full, "utf8");
-        } catch { continue; }
-        const lines = content.split("\n");
-        for (let i = 0; i < lines.length; i++) {
-          // Skip very long lines: the pattern is model-supplied and a
-          // pathological regex on a long line can backtrack catastrophically
-          // (ReDoS) and freeze the single-threaded process.
-          if (lines[i].length > 2000) continue;
-          if (regex.test(lines[i])) {
-            matches.push({ file: rel, line: i + 1, text: lines[i].slice(0, 300) });
-            if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
-          }
-        }
-      }
-    }
-  }
-  walk(root);
-  const payload = { matches };
-  if (truncated) {
-    payload.truncated = true;
-    payload.note = `Showing the first ${MAX_SEARCH_MATCHES} matches — refine the pattern or pass a 'glob' filter to narrow.`;
-  }
-  return { ok: true, output: JSON.stringify(payload, null, 2) };
-}
-
-function globFiles(args, opts) {
-  if (typeof args.pattern !== "string") return { ok: false, output: "pattern is required" };
-  const root = resolveSafe(typeof args.path === "string" ? args.path : ".", opts);
-  const re = globToRegExp(args.pattern);
-  const isIgnored = loadIgnore(path.resolve(opts.cwd));
-  const found = [];
-  let truncated = false;
-
-  function walk(dir) {
-    if (found.length >= MAX_GLOB_RESULTS) { truncated = true; return; }
-    let entries;
-    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
-    for (const e of entries) {
-      if (found.length >= MAX_GLOB_RESULTS) { truncated = true; return; }
-      if (e.name.startsWith(".") || ALWAYS_SKIP.has(e.name)) continue;
-      const full = path.join(dir, e.name);
-      const rel = path.relative(opts.cwd, full);
-      if (isIgnored(rel, e.isDirectory())) continue;
-      if (e.isDirectory()) {
-        walk(full);
-      } else if (e.isFile()) {
-        const relToRoot = path.relative(root, full).split(path.sep).join("/");
-        if (re.test(relToRoot)) {
-          let mtime = 0;
-          try { mtime = fs.statSync(full).mtimeMs; } catch { /* ignore */ }
-          found.push({ path: rel, mtime });
-        }
-      }
-    }
-  }
-  walk(root);
-  found.sort((a, b) => b.mtime - a.mtime); // most-recently-modified first
-  const payload = { files: found.map((f) => f.path) };
-  if (truncated) {
-    payload.truncated = true;
-    payload.note = `Showing the first ${MAX_GLOB_RESULTS} files — narrow the pattern.`;
-  }
-  return { ok: true, output: JSON.stringify(payload, null, 2) };
-}
-
-async function writeFile(args, opts) {
-  if (typeof args.path !== "string" || typeof args.content !== "string") {
-    return { ok: false, output: "path and content are required" };
-  }
-  const abs = resolveSafe(args.path, opts);
-  const exists = fs.existsSync(abs);
-  const oldContent = exists ? fs.readFileSync(abs, "utf8") : null;
-  if (exists && oldContent === args.content) {
-    return { ok: true, output: `(no change — file already matches)` };
-  }
-  // Show diff + confirm (the "● write <file>" label already spaced this block)
-  console.log(summarizeWrite(oldContent, args.content, path.relative(opts.cwd, abs)));
-  console.log(unifiedDiff(oldContent ?? "", args.content, path.relative(opts.cwd, abs)));
-  const approved = await confirm(c.yellow("Apply this write?"), opts.autoYes);
-  if (!approved) {
-    return { ok: false, output: "User declined the write." };
-  }
-  fs.mkdirSync(path.dirname(abs), { recursive: true });
-  fs.writeFileSync(abs, args.content, "utf8");
-  return { ok: true, output: `Wrote ${args.content.length} bytes to ${path.relative(opts.cwd, abs)}` };
-}
-
-async function editFile(args, opts) {
-  if (typeof args.path !== "string" || typeof args.find !== "string" || typeof args.replace !== "string") {
-    return { ok: false, output: "path, find, replace are required" };
-  }
-  const abs = resolveSafe(args.path, opts);
-  if (!fs.existsSync(abs)) {
-    return {
-      ok: false,
-      output: `File not found: ${args.path}. It doesn't exist yet — use write_file to CREATE it (edit_file only modifies existing files). Do not retry edit_file on this path.`,
-    };
-  }
-  const oldContent = fs.readFileSync(abs, "utf8");
-  const occurrences = oldContent.split(args.find).length - 1;
-  if (occurrences === 0) {
-    return { ok: false, output: `\`find\` text not found in ${args.path}. Tip: read the file first to copy exact characters.` };
-  }
-  if (!args.replace_all && occurrences > 1) {
-    return {
-      ok: false,
-      output: `\`find\` text appears ${occurrences} times — must be unique. Add more context to disambiguate, or set replace_all: true to replace all ${occurrences}.`,
-    };
-  }
-  // split/join for BOTH paths: String.replace(str, str) would interpret special
-  // patterns in the replacement ($&, $`, $', $$) and silently corrupt code that
-  // contains them (regex, jQuery $, template strings). split/join is literal.
-  // On the single-edit path occurrences === 1, so it's equivalent + safe.
-  const newContent = oldContent.split(args.find).join(args.replace);
-  const rel = path.relative(opts.cwd, abs);
-  console.log(c.dim(`edit ${rel}${args.replace_all ? ` (${occurrences} occurrences)` : ""}`));
-  console.log(unifiedDiff(oldContent, newContent, rel));
-  const approved = await confirm(c.yellow("Apply this edit?"), opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the edit." };
-  fs.writeFileSync(abs, newContent, "utf8");
-  return { ok: true, output: `Edited ${rel}${args.replace_all && occurrences > 1 ? ` (${occurrences} replacements)` : ""}` };
-}
-
-/* ─────────────────────── Web tools ─────────────────────── */
-
-async function webSearch(args, opts) {
-  void opts;
-  if (typeof args.query !== "string") return { ok: false, output: "query is required" };
-  const { apiKey, baseUrl } = getConfig();
-  if (!apiKey) {
-    return { ok: false, output: "Web search requires AETHER_API_KEY. Set it and try again." };
-  }
-  const max = Number.isInteger(args.max_results) ? Math.min(10, Math.max(1, args.max_results)) : 5;
-  const maxRetries = 2;
-  const baseDelay = 500;
-  let res;
-  for (let attempt = 0; attempt <= maxRetries; attempt++) {
-    try {
-      res = await fetch(`${baseUrl}/api/v1/web-search`, {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${apiKey}`,
-          "User-Agent": `aether-code/${getVersion()}`,
-        },
-        body: JSON.stringify({ query: args.query, max_results: max }),
-      });
-      if (res.status >= 500 && attempt < maxRetries) {
-        res.body?.cancel().catch(() => {});
-        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-        continue;
-      }
-      break;
-    } catch (e) {
-      if (attempt < maxRetries) {
-        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
-        continue;
-      }
-      return { ok: false, output: `web_search network error: ${e.message}` };
-    }
-  }
-  let data = null;
-  try { data = await res.json(); } catch { /* non-JSON */ }
-  if (!res.ok) {
-    return { ok: false, output: data?.error || `web_search HTTP ${res.status}` };
-  }
-  return { ok: true, output: JSON.stringify(data.results ?? [], null, 2) };
-}
-
-// Bounded fetch with a fixed timeout + size cap. Strips scripts/styles, removes
-// tags, decodes common HTML entities. Not a full HTML parser; good enough for
-// reading docs pages, GitHub READMEs, MDN, Stack Overflow answers, etc.
-// SSRF guard: refuse loopback / link-local / private hosts so web_fetch can't
-// be steered (directly or via a redirect) at localhost or cloud-metadata
-// (169.254.169.254) or an internal service.
-function isBlockedHost(hostname) {
-  const h = (hostname || "").toLowerCase().replace(/^\[|\]$/g, "");
-  if (!h || h === "localhost" || h === "0.0.0.0" || h === "::1" || h === "::") return true;
-  if (h.endsWith(".localhost") || h.endsWith(".internal") || h.endsWith(".local")) return true;
-  if (/^127\./.test(h)) return true;                       // loopback
-  if (/^10\./.test(h)) return true;                        // private A
-  if (/^192\.168\./.test(h)) return true;                  // private C
-  if (/^172\.(1[6-9]|2\d|3[01])\./.test(h)) return true;   // private B
-  if (/^169\.254\./.test(h)) return true;                  // link-local incl. cloud metadata
-  if (/^(fe80:|fc|fd|::ffff:)/.test(h)) return true;       // IPv6 link-local / ULA / mapped
-  return false;
-}
-
-async function webFetch(args, opts) {
-  void opts;
-  if (typeof args.url !== "string") return { ok: false, output: "url is required" };
-  if (!/^https?:\/\//i.test(args.url)) {
-    return { ok: false, output: "Only http:// and https:// URLs are allowed." };
-  }
-  let initialHost;
-  try { initialHost = new URL(args.url).hostname; } catch { return { ok: false, output: "Invalid URL." }; }
-  if (isBlockedHost(initialHost)) {
-    return { ok: false, output: "web_fetch blocked: refusing to fetch a private/internal/loopback address." };
-  }
-  const controller = new AbortController();
-  const timeout = setTimeout(() => controller.abort(), 15_000);
-  let res;
-  try {
-    res = await fetch(args.url, {
-      signal: controller.signal,
-      redirect: "follow",
-      headers: {
-        // Looking like a normal browser dodges many anti-bot pages.
-        "User-Agent":
-          `Mozilla/5.0 (compatible; aether-code/${getVersion()}) Gecko/20100101 Firefox/130.0`,
-        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
-        "Accept-Language": "en-US,en;q=0.9",
-      },
-    });
-  } catch (e) {
-    clearTimeout(timeout);
-    return { ok: false, output: `web_fetch error: ${e.name === "AbortError" ? "timed out after 15s" : e.message}` };
-  }
-  clearTimeout(timeout);
-  // Re-check the FINAL url after any redirects — a public URL can 302 to an
-  // internal target, which the initial-URL check wouldn't catch.
-  try {
-    if (isBlockedHost(new URL(res.url).hostname)) {
-      res.body?.cancel().catch(() => {});
-      return { ok: false, output: "web_fetch blocked: redirect to a private/internal address." };
-    }
-  } catch { /* res.url unparseable — fall through */ }
-  if (!res.ok) {
-    return { ok: false, output: `web_fetch HTTP ${res.status} ${res.statusText}` };
-  }
-  // Cap at 2 MB of raw HTML before stripping — page might be huge.
-  const reader = res.body?.getReader();
-  if (!reader) return { ok: false, output: "Response had no body." };
-  const chunks = [];
-  let total = 0;
-  while (true) {
-    const { value, done } = await reader.read();
-    if (done) break;
-    total += value.length;
-    if (total > 2_000_000) {
-      reader.cancel();
-      break;
-    }
-    chunks.push(value);
-  }
-  const html = new TextDecoder("utf-8", { fatal: false }).decode(
-    Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))),
-  );
-  const text = htmlToText(html);
-  // Final cap on what we hand to the model so a single fetch doesn't blow the context.
-  const capped = text.length > 50_000 ? text.slice(0, 50_000) + "\n…(truncated; page was longer)" : text;
-  return { ok: true, output: capped };
-}
-
-export function htmlToText(html) {
-  let s = html;
-  // Drop script/style blocks entirely.
-  s = s.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ");
-  s = s.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ");
-  s = s.replace(/<noscript\b[^<]*(?:(?!<\/noscript>)<[^<]*)*<\/noscript>/gi, " ");
-  // Preserve paragraph + heading breaks.
-  s = s.replace(/<\/(p|div|h[1-6]|li|tr|br)\s*>/gi, "\n");
-  s = s.replace(/<br\s*\/?>/gi, "\n");
-  // Strip remaining tags.
-  s = s.replace(/<[^>]+>/g, "");
-  // Decode common HTML entities (covers ~95% of real-world cases).
-  const entities = {
-    "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'",
-    "&apos;": "'", "&nbsp;": " ", "&mdash;": "—", "&ndash;": "–",
-    "&hellip;": "…", "&copy;": "©", "&reg;": "®", "&trade;": "™",
-  };
-  for (const [ent, ch] of Object.entries(entities)) {
-    s = s.split(ent).join(ch);
-  }
-  s = s.replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)));
-  s = s.replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCharCode(parseInt(n, 16)));
-  // Collapse whitespace.
-  s = s.replace(/[ \t]+/g, " ");
-  s = s.replace(/\n\s*\n\s*\n+/g, "\n\n");
-  return s.trim();
-}
-
-const CATASTROPHIC_CMD_RE = new RegExp(
-  [
-    String.raw`rm\s+-(r|f|rf|fr)\w*\s+[/~](?!\S*node_modules)(?!\S*dist)(?!\S*\.next)(?!\S*build)`,
-    String.raw`del\s+/[sfq]+\s+[cC]:\\`,
-    String.raw`format\s+[a-zA-Z]:`,
-    String.raw`mkfs\.`,
-    String.raw`dd\s+.*of=/dev/[sh]d`,
-    String.raw`:\(\)\s*\{\s*:\|:`,
-    String.raw`>\s*/dev/[sh]d`,
-    String.raw`rd\s+/[sq]+\s+[cC]:\\`,
-  ].join("|"),
-);
-
-async function runShell(args, opts) {
-  if (typeof args.command !== "string") return { ok: false, output: "command is required" };
-  const cwd = args.cwd ? resolveSafe(args.cwd, opts) : opts.cwd;
-  console.log(c.yellow("$ ") + c.bold(args.command) + (args.cwd ? c.dim(`  (cwd: ${args.cwd})`) : ""));
-  const forceReview = CATASTROPHIC_CMD_RE.test(args.command);
-  if (forceReview) {
-    console.log(c.red(c.bold("  ⚠ DESTRUCTIVE COMMAND DETECTED")) + c.gray(" — requires manual confirmation"));
-  }
-  const approved = await confirm(c.yellow("Run this command?"), forceReview ? false : opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the command." };
-
-  return new Promise((resolve) => {
-    const child = spawn(args.command, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let killed = false;
-    const timeout = setTimeout(() => {
-      killed = true;
-      child.kill("SIGTERM");
-    }, 120_000); // 2-minute hard cap per command
-
-    child.stdout.on("data", (d) => {
-      const s = d.toString();
-      stdout += s;
-      if (stdout.length < 80_000) process.stdout.write(c.dim(s));
-    });
-    child.stderr.on("data", (d) => {
-      const s = d.toString();
-      stderr += s;
-      if (stderr.length < 80_000) process.stderr.write(c.dim(s));
-    });
-    child.on("close", (code) => {
-      clearTimeout(timeout);
-      // Truncate huge outputs before sending back to the model
-      const truncate = (t) => (t.length > 20_000 ? t.slice(0, 20_000) + "\n…(truncated)" : t);
-      const out = JSON.stringify(
-        {
-          exit_code: code,
-          killed,
-          stdout: truncate(stdout),
-          stderr: truncate(stderr),
-        },
-        null,
-        2,
-      );
-      resolve({ ok: code === 0 && !killed, output: out });
-    });
-  });
-}
-
-/* ─────────────────────── Git tools ─────────────────────── */
-
-function runGit(gitArgs, cwd, timeoutMs = 30_000) {
-  return new Promise((resolve) => {
-    const child = spawn("git", gitArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    let killed = false;
-    const timer = setTimeout(() => { killed = true; child.kill("SIGTERM"); }, timeoutMs);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      const truncate = (t) => (t.length > 30_000 ? t.slice(0, 30_000) + "\n…(truncated)" : t);
-      resolve({ code, killed, stdout: truncate(stdout), stderr: truncate(stderr) });
-    });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ code: 1, killed: false, stdout: "", stderr: `git spawn error: ${err.message}` });
-    });
-  });
-}
-
-async function gitStatus(_args, opts) {
-  const r = await runGit(["status", "--short", "--branch", "-u"], opts.cwd);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git status failed" };
-  const lines = r.stdout.trim().split("\n");
-  const branchLine = lines[0] || "";
-  const files = lines.slice(1).filter((l) => l.trim());
-  const staged = [];
-  const unstaged = [];
-  const untracked = [];
-  for (const line of files) {
-    const x = line[0];
-    const y = line[1];
-    const name = line.slice(3);
-    if (x === "?") { untracked.push(name); continue; }
-    if (x !== " " && x !== "?") staged.push({ status: x, file: name });
-    if (y !== " " && y !== "?") unstaged.push({ status: y, file: name });
-  }
-  const result = {
-    branch: branchLine.replace(/^## /, ""),
-    staged,
-    unstaged,
-    untracked,
-    clean: staged.length === 0 && unstaged.length === 0 && untracked.length === 0,
-  };
-  return { ok: true, output: JSON.stringify(result, null, 2) };
-}
-
-async function gitDiff(args, opts) {
-  const gitArgs = ["diff", "--stat", "--patch"];
-  if (args.staged) gitArgs.push("--cached");
-  if (args.base) {
-    const head = args.head || "HEAD";
-    gitArgs.length = 0;
-    gitArgs.push("diff", args.base + "..." + head, "--stat", "--patch");
-  }
-  if (Array.isArray(args.files) && args.files.length > 0) {
-    gitArgs.push("--");
-    for (const f of args.files) gitArgs.push(f);
-  }
-  const r = await runGit(gitArgs, opts.cwd, 60_000);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git diff failed" };
-  if (!r.stdout.trim()) return { ok: true, output: "(no changes)" };
-  return { ok: true, output: r.stdout };
-}
-
-async function gitLog(args, opts) {
-  const count = Math.min(50, Math.max(1, args.count ?? 15));
-  const gitArgs = ["log", `-${count}`];
-  if (args.oneline) {
-    gitArgs.push("--oneline");
-  } else {
-    gitArgs.push("--format=%h %an (%ar)%n  %s%n");
-  }
-  if (args.branch) gitArgs.push(args.branch);
-  if (args.file) { gitArgs.push("--"); gitArgs.push(args.file); }
-  const r = await runGit(gitArgs, opts.cwd);
-  if (r.code !== 0) return { ok: false, output: r.stderr || "git log failed" };
-  if (!r.stdout.trim()) return { ok: true, output: "(no commits)" };
-  return { ok: true, output: r.stdout };
-}
-
-async function gitCommit(args, opts) {
-  if (typeof args.message !== "string" || !args.message.trim()) {
-    return { ok: false, output: "commit message is required" };
-  }
-  // Stage files
-  const filesToStage = Array.isArray(args.files) && args.files.length > 0 ? args.files : null;
-  if (filesToStage) {
-    const addR = await runGit(["add", "--", ...filesToStage], opts.cwd);
-    if (addR.code !== 0) return { ok: false, output: `git add failed: ${addR.stderr}` };
-  } else {
-    const addR = await runGit(["add", "-A"], opts.cwd);
-    if (addR.code !== 0) return { ok: false, output: `git add -A failed: ${addR.stderr}` };
-  }
-  // Show what's staged
-  const staged = await runGit(["diff", "--cached", "--stat"], opts.cwd);
-  if (!staged.stdout.trim()) {
-    return { ok: false, output: "Nothing to commit — no staged changes after git add." };
-  }
-  console.log(c.dim(staged.stdout));
-  console.log(c.cyan("commit message: ") + c.bold(args.message));
-  const approved = await confirm(c.yellow("Create this commit?"), opts.autoYes);
-  if (!approved) {
-    await runGit(["reset", "HEAD"], opts.cwd);
-    return { ok: false, output: "User declined the commit. Staged changes have been unstaged." };
-  }
-  const commitR = await runGit(["commit", "-m", args.message], opts.cwd);
-  if (commitR.code !== 0) return { ok: false, output: `git commit failed: ${commitR.stderr}` };
-  // Get the commit hash for confirmation
-  const hashR = await runGit(["rev-parse", "--short", "HEAD"], opts.cwd);
-  const hash = hashR.stdout.trim();
-  return { ok: true, output: `Committed ${hash}: ${args.message}\n${commitR.stdout}` };
-}
-
-async function gitBranch(args, opts) {
-  if (typeof args.name !== "string" || !args.name.trim()) {
-    return { ok: false, output: "branch name is required" };
-  }
-  // Check if branch exists
-  const checkR = await runGit(["rev-parse", "--verify", args.name], opts.cwd);
-  if (checkR.code === 0) {
-    // Branch exists, switch to it
-    const switchR = await runGit(["checkout", args.name], opts.cwd);
-    if (switchR.code !== 0) return { ok: false, output: `git checkout failed: ${switchR.stderr}` };
-    return { ok: true, output: `Switched to existing branch '${args.name}'` };
-  }
-  // Create new branch
-  const createArgs = ["checkout", "-b", args.name];
-  if (args.base) createArgs.push(args.base);
-  const createR = await runGit(createArgs, opts.cwd);
-  if (createR.code !== 0) return { ok: false, output: `git checkout -b failed: ${createR.stderr}` };
-  return { ok: true, output: `Created and switched to new branch '${args.name}'${args.base ? ` from ${args.base}` : ""}` };
-}
-
-async function gitPush(args, opts) {
-  // Get current branch name
-  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
-  if (branchR.code !== 0) return { ok: false, output: `Cannot determine current branch: ${branchR.stderr}` };
-  const branch = branchR.stdout.trim();
-  if (!branch || branch === "HEAD") {
-    return { ok: false, output: "Cannot push — HEAD is detached. Checkout a branch first." };
-  }
-  const pushArgs = ["push", "-u", "origin", branch];
-  if (args.force) pushArgs.splice(1, 0, "--force-with-lease");
-  console.log(c.yellow("$ ") + c.bold(`git ${pushArgs.join(" ")}`));
-  const approved = await confirm(c.yellow(`Push '${branch}' to origin?`), opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the push." };
-  const r = await runGit(pushArgs, opts.cwd, 60_000);
-  if (r.code !== 0) return { ok: false, output: `git push failed: ${r.stderr}` };
-  return { ok: true, output: `Pushed '${branch}' to origin.\n${r.stderr}${r.stdout}`.trim() };
-}
-
-async function gitCreatePr(args, opts) {
-  if (typeof args.title !== "string" || !args.title.trim()) {
-    return { ok: false, output: "PR title is required" };
-  }
-  if (typeof args.body !== "string") {
-    return { ok: false, output: "PR body is required" };
-  }
-  // Check if gh CLI is available
-  const ghCheck = await runGit(["--version"], opts.cwd);
-  void ghCheck;
-  const ghVerify = new Promise((resolve) => {
-    const child = spawn("gh", ["--version"], { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let out = "";
-    child.stdout.on("data", (d) => { out += d.toString(); });
-    child.on("close", (code) => resolve({ code, stdout: out }));
-    child.on("error", () => resolve({ code: 1, stdout: "" }));
-  });
-  const ghResult = await ghVerify;
-  if (ghResult.code !== 0) {
-    return { ok: false, output: "GitHub CLI (gh) is not installed or not in PATH. Install it: https://cli.github.com" };
-  }
-  // Push branch first if needed
-  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
-  const branch = branchR.stdout.trim();
-  const trackR = await runGit(["config", "--get", `branch.${branch}.remote`], opts.cwd);
-  if (trackR.code !== 0 || !trackR.stdout.trim()) {
-    console.log(c.gray(`Branch '${branch}' has no remote — pushing first...`));
-    const pushR = await runGit(["push", "-u", "origin", branch], opts.cwd, 60_000);
-    if (pushR.code !== 0) return { ok: false, output: `Failed to push branch: ${pushR.stderr}` };
-    console.log(c.gray("Pushed."));
-  }
-  // Build gh pr create command
-  console.log(c.cyan("PR title: ") + c.bold(args.title));
-  const bodyPreview = args.body.length > 200 ? args.body.slice(0, 197) + "..." : args.body;
-  console.log(c.gray(bodyPreview));
-  if (args.base) console.log(c.gray(`base: ${args.base}`));
-  if (args.draft) console.log(c.gray("(draft PR)"));
-  const approved = await confirm(c.yellow("Create this pull request?"), opts.autoYes);
-  if (!approved) return { ok: false, output: "User declined the PR." };
-  const ghArgs = ["pr", "create", "--title", args.title, "--body", args.body];
-  if (args.base) { ghArgs.push("--base"); ghArgs.push(args.base); }
-  if (args.draft) ghArgs.push("--draft");
-  return new Promise((resolve) => {
-    const child = spawn("gh", ghArgs, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
-    let stdout = "";
-    let stderr = "";
-    const timer = setTimeout(() => child.kill("SIGTERM"), 30_000);
-    child.stdout.on("data", (d) => { stdout += d.toString(); });
-    child.stderr.on("data", (d) => { stderr += d.toString(); });
-    child.on("close", (code) => {
-      clearTimeout(timer);
-      if (code !== 0) {
-        resolve({ ok: false, output: `gh pr create failed (exit ${code}): ${stderr || stdout}` });
-      } else {
-        const prUrl = stdout.trim();
-        resolve({ ok: true, output: `Pull request created: ${prUrl}\n${stderr}`.trim() });
-      }
-    });
-    child.on("error", (err) => {
-      clearTimeout(timer);
-      resolve({ ok: false, output: `gh spawn error: ${err.message}` });
-    });
-  });
-}
-
-/* ─────────────────────── todo_write ─────────────────────── */
-
-// Module-level singleton holding the current todo list for this CLI session.
-// Latest-wins: each todo_write call replaces the entire list. The model
-// passes the full new state every time, mirroring what Claude Code's
-// TodoWrite does. Simpler than incremental ops; gives the model full
-// control over ordering and renames.
-const VALID_TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
-const MAX_TODOS = 30;
-let todoState = [];
-
-// Test-only escape hatches — exported so the test suite can reset state
-// between cases. Production code never touches these.
-export function __resetTodoState() {
-  todoState = [];
-}
-export function __getTodoState() {
-  return todoState.map((t) => ({ ...t }));
-}
-
-function todoWrite(args, opts) {
-  void opts;
-  if (!Array.isArray(args.todos)) {
-    return { ok: false, output: "todos must be an array" };
-  }
-  if (args.todos.length > MAX_TODOS) {
-    return {
-      ok: false,
-      output: `too many todos (${args.todos.length}) — max ${MAX_TODOS}. Keep the plan focused.`,
-    };
-  }
-  // Validate every item BEFORE mutating state — we don't want a partial write.
-  for (let i = 0; i < args.todos.length; i++) {
-    const t = args.todos[i];
-    if (!t || typeof t !== "object") {
-      return { ok: false, output: `todo[${i}] must be an object` };
-    }
-    if (typeof t.content !== "string" || t.content.trim().length === 0) {
-      return { ok: false, output: `todo[${i}] needs a non-empty content string` };
-    }
-    if (!VALID_TODO_STATUSES.has(t.status)) {
-      return {
-        ok: false,
-        output: `todo[${i}] invalid status: "${t.status}" — must be pending, in_progress, or completed`,
-      };
-    }
-  }
-  todoState = args.todos.map((t) => ({
-    content: t.content.trim(),
-    status: t.status,
-  }));
-  renderTodos(todoState);
-  const counts = { pending: 0, in_progress: 0, completed: 0 };
-  for (const t of todoState) counts[t.status]++;
-  return {
-    ok: true,
-    output: `Todos updated: ${counts.pending} pending, ${counts.in_progress} in_progress, ${counts.completed} completed.`,
-  };
-}
-
-function renderTodos(todos) {
-  if (!process.stdout.isTTY) return; // skip render in non-TTY (CI, piped, tests)
-  console.log("");
-  console.log(c.cyan("●") + " " + c.bold("Plan"));
-  for (const t of todos) {
-    const icon =
-      t.status === "completed"
-        ? c.green("●")
-        : t.status === "in_progress"
-          ? c.yellow("→")
-          : c.dim("·");
-    const text =
-      t.status === "completed"
-        ? c.dim(t.content)
-        : t.status === "in_progress"
-          ? c.bold(t.content)
-          : c.gray(t.content);
-    console.log(`  ${icon} ${text}`);
-  }
-  console.log("");
-}
+// Tool implementations + JSON-schema definitions.
+//
+// Safety model:
+//   - read_file, list_dir, search_files: auto-execute (read-only)
+//   - write_file, edit_file: show diff, require y/n confirmation (or --yes flag)
+//   - run_shell: show command, require y/n confirmation (or --yes flag)
+//
+// Path safety: every path is resolved against `cwd` and rejected if it
+// escapes `cwd` — unless the user explicitly passes --unsafe-paths.
+
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import { spawn } from "node:child_process";
+import { c } from "./render.js";
+import { promptChoice } from "./menu.js";
+import { unifiedDiff, summarizeWrite } from "./diff.js";
+import { getConfig } from "./config.js";
+import { getVersion } from "./version.js";
+
+/* ─────────────────────── Tool definitions (sent to model) ─────────────────────── */
+
+export const TOOL_DEFINITIONS = [
+  {
+    type: "function",
+    function: {
+      name: "read_file",
+      description:
+        "Read the contents of a file as UTF-8 text. Returns the file contents or an error if the file doesn't exist.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Path relative to the working directory, or absolute." },
+        },
+        required: ["path"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "list_dir",
+      description:
+        "List the entries in a directory. Returns an array of {name, type: 'file'|'dir', size?: number}. Hidden files (starting with .) are excluded by default.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Directory path." },
+          include_hidden: { type: "boolean", description: "Include dotfiles. Default: false." },
+        },
+        required: ["path"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "search_files",
+      description:
+        "Recursively search for a regex pattern across files in a directory. Returns matching file paths and the matching line. Limited to 50 results.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "Directory to search." },
+          pattern: { type: "string", description: "JavaScript-style regex (without slashes)." },
+          glob: { type: "string", description: "Optional file-name glob filter, e.g. '*.ts'." },
+        },
+        required: ["path", "pattern"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "glob_files",
+      description:
+        "Find files by path pattern (no content search). Returns matching file paths sorted by most-recently-modified. Use this to locate files by name/extension/location, e.g. '**/*.ts', 'src/**/*.test.js', 'package.json'. Faster and clearer than search_files when you only need to find files, not grep their contents.",
+      parameters: {
+        type: "object",
+        properties: {
+          pattern: { type: "string", description: "Glob pattern. Supports ** (any depth), * (within a path segment), ?. e.g. 'src/**/*.js'." },
+          path: { type: "string", description: "Directory to search from. Default: the working directory." },
+        },
+        required: ["pattern"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "write_file",
+      description:
+        "Create or completely overwrite a file with the given content. The user will be shown a diff and may decline. If the parent directory doesn't exist, it will be created.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "File path." },
+          content: { type: "string", description: "Full file content to write." },
+        },
+        required: ["path", "content"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "edit_file",
+      description:
+        "Replace occurrences of `find` with `replace` in an existing file. Use this for targeted edits instead of rewriting whole files. By default replaces exactly one occurrence and fails if `find` is missing or appears more than once. Set `replace_all: true` to replace every occurrence.",
+      parameters: {
+        type: "object",
+        properties: {
+          path: { type: "string", description: "File path." },
+          find: { type: "string", description: "Exact text to replace. Must be unique unless replace_all is true." },
+          replace: { type: "string", description: "Text to substitute in." },
+          replace_all: { type: "boolean", description: "Replace ALL occurrences instead of requiring a unique match. Default: false." },
+        },
+        required: ["path", "find", "replace"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "run_shell",
+      description:
+        "Run a shell command and return its stdout, stderr, and exit code. The user will be shown the command and may decline. Used for builds, tests, package installs, git operations, etc.",
+      parameters: {
+        type: "object",
+        properties: {
+          command: { type: "string", description: "The shell command to run." },
+          cwd: { type: "string", description: "Optional working directory (relative or absolute)." },
+        },
+        required: ["command"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "web_search",
+      description:
+        "Search the live web for a query and return a JSON array of {title, url, snippet} results. Use this to find current docs, recent libraries, API references, or anything that may have changed since training. ALWAYS prefer this over guessing at library APIs. Cost: ~3–8 credits per call.",
+      parameters: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "Plain-language search query." },
+          max_results: { type: "number", description: "How many results to return (1–10, default 5)." },
+        },
+        required: ["query"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "web_fetch",
+      description:
+        "Fetch a URL and return its content as plain text (HTML scripts/styles stripped, tags removed, entities decoded). Use this after web_search to read the actual docs page. NEVER pass a URL you didn't get from a real source — only http:// or https:// is allowed. Caps response at 50 KB of text.",
+      parameters: {
+        type: "object",
+        properties: {
+          url: { type: "string", description: "Full http(s) URL to fetch." },
+        },
+        required: ["url"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "todo_write",
+      description:
+        "Replace the current todo list with a new state. Use this at the start of any task with 3+ steps to plan upfront, then call again to mark items 'in_progress' as you start them and 'completed' as you finish. Visible progress for the user; structural discipline for you. Status must be one of: 'pending', 'in_progress', 'completed'. Max 30 items per list.",
+      parameters: {
+        type: "object",
+        properties: {
+          todos: {
+            type: "array",
+            description: "Full replacement list (latest-wins semantics).",
+            items: {
+              type: "object",
+              properties: {
+                content: { type: "string", description: "Short imperative phrase, e.g. 'wire endpoint into UI'." },
+                status: {
+                  type: "string",
+                  enum: ["pending", "in_progress", "completed"],
+                  description: "Task status.",
+                },
+              },
+              required: ["content", "status"],
+            },
+          },
+        },
+        required: ["todos"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "ask_user",
+      description:
+        "Ask the user a single multiple-choice question and wait for their answer. Use this ONLY when the request is genuinely ambiguous AND the answer materially changes what you build — e.g. which platform/framework/language, the scope, or an irreversible decision. Ask BEFORE building when a wrong assumption would waste real work. Give 2–5 concrete options, each with a short description; put the best default first. Do NOT use it for trivial choices, things you can infer, or to confirm permission to act — just build when the task is clear.",
+      parameters: {
+        type: "object",
+        properties: {
+          question: { type: "string", description: "The single, focused question to ask." },
+          options: {
+            type: "array",
+            description: "2–5 options. Each is {label, description}. Best default first.",
+            items: {
+              type: "object",
+              properties: {
+                label: { type: "string", description: "Short option label." },
+                description: { type: "string", description: "One-line explanation of this option." },
+              },
+              required: ["label"],
+            },
+          },
+        },
+        required: ["question", "options"],
+      },
+    },
+  },
+  /* ─────────────────────── Git tools ─────────────────────── */
+  {
+    type: "function",
+    function: {
+      name: "git_status",
+      description:
+        "Show the working tree status — staged, unstaged, and untracked files. Auto-executes (read-only). Use this before committing to see what's changed.",
+      parameters: {
+        type: "object",
+        properties: {},
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_diff",
+      description:
+        "Show a unified diff of changes. By default shows unstaged changes. Set staged=true for staged changes, or pass base/head for branch comparisons (e.g. base='main' head='HEAD'). Optionally limit to specific file(s).",
+      parameters: {
+        type: "object",
+        properties: {
+          staged: { type: "boolean", description: "Show staged (--cached) diff instead of unstaged. Default: false." },
+          base: { type: "string", description: "Base ref for comparison (e.g. 'main', 'HEAD~3'). When set, shows diff between base and head." },
+          head: { type: "string", description: "Head ref for comparison. Default: 'HEAD' when base is set." },
+          files: {
+            type: "array",
+            description: "Limit diff to these file paths.",
+            items: { type: "string" },
+          },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_log",
+      description:
+        "Show recent commit history with hash, author, date, and message. Defaults to 15 commits. Use this to understand what's been done recently, find commit hashes, or check the commit style before committing.",
+      parameters: {
+        type: "object",
+        properties: {
+          count: { type: "number", description: "Number of commits to show (1-50). Default: 15." },
+          oneline: { type: "boolean", description: "Compact one-line format. Default: false." },
+          file: { type: "string", description: "Show only commits that touched this file." },
+          branch: { type: "string", description: "Show commits on this branch instead of HEAD." },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_commit",
+      description:
+        "Stage files and create a commit. If no files are specified, stages all modified/new files (git add -A). The user will see what's being committed and confirm. Use git_status first to see what's changed, and git_log to match the commit message style.",
+      parameters: {
+        type: "object",
+        properties: {
+          message: { type: "string", description: "Commit message. Be concise — focus on WHY, not WHAT." },
+          files: {
+            type: "array",
+            description: "Specific files to stage. If omitted, stages everything (git add -A).",
+            items: { type: "string" },
+          },
+        },
+        required: ["message"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_branch",
+      description:
+        "Create and/or switch to a branch. If the branch exists, switches to it. If it doesn't, creates it from the current HEAD (or from 'base' if specified) and switches to it.",
+      parameters: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Branch name to create or switch to." },
+          base: { type: "string", description: "Create the branch from this ref instead of HEAD." },
+        },
+        required: ["name"],
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_push",
+      description:
+        "Push the current branch to the remote. Sets upstream tracking (-u origin) on first push. The user will confirm before pushing.",
+      parameters: {
+        type: "object",
+        properties: {
+          force: { type: "boolean", description: "Force push (--force-with-lease). Use only when explicitly asked. Default: false." },
+        },
+      },
+    },
+  },
+  {
+    type: "function",
+    function: {
+      name: "git_create_pr",
+      description:
+        "Create a GitHub pull request using the `gh` CLI. Requires `gh` to be installed and authenticated. Pushes the branch first if needed. The user will confirm before creating.",
+      parameters: {
+        type: "object",
+        properties: {
+          title: { type: "string", description: "PR title. Keep under 72 chars." },
+          body: { type: "string", description: "PR body/description. Markdown supported." },
+          base: { type: "string", description: "Target branch to merge into. Default: repo default (usually main)." },
+          draft: { type: "boolean", description: "Create as a draft PR. Default: false." },
+        },
+        required: ["title", "body"],
+      },
+    },
+  },
+];
+
+/* ─────────────────────── Argument validation ─────────────────────── */
+
+const TOOL_SCHEMAS = Object.fromEntries(
+  TOOL_DEFINITIONS.map((t) => [t.function.name, t.function.parameters]),
+);
+
+function typeMatches(val, t) {
+  switch (t) {
+    case "string": return typeof val === "string";
+    case "number": return typeof val === "number";
+    case "integer": return typeof val === "number" && Number.isInteger(val);
+    case "boolean": return typeof val === "boolean";
+    case "object": return typeof val === "object" && val !== null && !Array.isArray(val);
+    case "array": return Array.isArray(val);
+    default: return true;
+  }
+}
+
+/**
+ * Validate parsed tool arguments against the tool's JSON schema BEFORE the
+ * handler runs. Returns an error string the model can act on, or null if valid.
+ * Catches malformed/partial args from the model that would otherwise surface as
+ * cryptic downstream errors.
+ */
+export function validateToolArgs(name, args) {
+  const schema = TOOL_SCHEMAS[name];
+  if (!schema) return `Unknown tool: ${name}`;
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `Arguments for ${name} must be a JSON object.`;
+  }
+  for (const req of schema.required ?? []) {
+    if (args[req] === undefined || args[req] === null) {
+      return `Missing required argument "${req}" for ${name}.`;
+    }
+  }
+  for (const [key, val] of Object.entries(args)) {
+    const prop = schema.properties?.[key];
+    if (!prop || val === undefined || val === null) continue;
+    if (prop.type && !typeMatches(val, prop.type)) {
+      return `Argument "${key}" for ${name} must be of type ${prop.type}.`;
+    }
+  }
+  return null;
+}
+
+/* ─────────────────────── Glob + ignore helpers ─────────────────────── */
+
+const ALWAYS_SKIP = new Set([".git", "node_modules", "dist"]);
+const MAX_SEARCH_MATCHES = 200;
+const MAX_GLOB_RESULTS = 300;
+
+// Convert a glob ('**', '*', '?') to an anchored regex over a POSIX-style
+// relative path. ** spans directory separators; * does not.
+export function globToRegExp(glob) {
+  let re = "";
+  let braceDepth = 0;
+  for (let i = 0; i < glob.length; i++) {
+    const ch = glob[i];
+    if (ch === "*") {
+      if (glob[i + 1] === "*") {
+        re += ".*";
+        i++;
+        if (glob[i + 1] === "/") i++; // collapse '**/' so it can also match zero dirs
+      } else {
+        re += "[^/]*";
+      }
+    } else if (ch === "?") {
+      re += "[^/]";
+    } else if (ch === "{") {
+      // Brace expansion: {js,ts} -> (js|ts). Common in .gitignore (*.{js,ts});
+      // treating it literally silently failed to ignore those files.
+      re += "(";
+      braceDepth++;
+    } else if (ch === "}" && braceDepth > 0) {
+      re += ")";
+      braceDepth--;
+    } else if (ch === "," && braceDepth > 0) {
+      re += "|";
+    } else if ("\\^$+.()|{}[]".includes(ch)) {
+      re += "\\" + ch;
+    } else {
+      re += ch;
+    }
+  }
+  return new RegExp("^" + re + "$");
+}
+
+// Parse a .gitignore at `root` into a matcher. Pragmatic subset of gitignore
+// semantics: blank/comment lines ignored; trailing '/' = directory-only;
+// leading '/' = root-anchored; '*'/'?' globs supported.
+function loadIgnore(root) {
+  let lines = [];
+  try { lines = fs.readFileSync(path.join(root, ".gitignore"), "utf8").split("\n"); } catch { /* none */ }
+  const rules = [];
+  for (const raw of lines) {
+    const line = raw.trim();
+    if (!line || line.startsWith("#")) continue;
+    let pat = line;
+    const dirOnly = pat.endsWith("/");
+    if (dirOnly) pat = pat.slice(0, -1);
+    const anchored = pat.startsWith("/");
+    if (anchored) pat = pat.slice(1);
+    rules.push({ re: globToRegExp(pat), anchored, dirOnly, base: !pat.includes("/") });
+  }
+  return (relPath, isDir) => {
+    const norm = relPath.split(path.sep).join("/");
+    const baseName = norm.split("/").pop();
+    for (const r of rules) {
+      if (r.dirOnly && !isDir) continue;
+      if (r.base) { if (r.re.test(baseName)) return true; }
+      else if (r.anchored) { if (r.re.test(norm)) return true; }
+      else if (r.re.test(norm) || r.re.test(baseName)) return true;
+    }
+    return false;
+  };
+}
+
+/* ─────────────────────── Helpers ─────────────────────── */
+
+function resolveSafe(rel, opts) {
+  const abs = path.isAbsolute(rel) ? path.normalize(rel) : path.resolve(opts.cwd, rel);
+  if (!opts.unsafePaths) {
+    const cwd = path.resolve(opts.cwd);
+    // Use path.relative (not startsWith) so Windows drive-relative inputs like
+    // "C:evil.txt" — which path.isAbsolute() reports as NON-absolute and
+    // path.resolve() may anchor to a drive's own cwd outside the project — are
+    // caught. A path is inside cwd only if its relative form doesn't climb out
+    // (no leading "..") and isn't itself absolute (different drive/root).
+    const relToCwd = path.relative(cwd, abs);
+    const escapes = relToCwd === ".." || relToCwd.startsWith(".." + path.sep) || path.isAbsolute(relToCwd);
+    if (abs !== cwd && escapes) {
+      throw new Error(
+        `Refusing to touch path outside cwd: ${abs}\n  Run with --unsafe-paths if you really mean this.`,
+      );
+    }
+  }
+  return abs;
+}
+
+function ask(question) {
+  if (!process.stdin.isTTY) {
+    return Promise.resolve("n"); // can't prompt in non-TTY; default no
+  }
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+async function confirm(question, autoYes) {
+  if (autoYes) return true;
+  const ans = await ask(`${question} ${c.dim("[y/N]: ")}`);
+  return ans === "y" || ans === "yes";
+}
+
+/* ─────────────────────── Implementations ─────────────────────── */
+
+export async function executeTool(call, opts) {
+  let args;
+  try {
+    args = JSON.parse(call.function.arguments || "{}");
+  } catch (e) {
+    return { ok: false, output: `Invalid JSON arguments: ${e.message}` };
+  }
+
+  const name = call.function.name;
+  const validationError = validateToolArgs(name, args);
+  if (validationError) {
+    return { ok: false, output: validationError };
+  }
+  const handlers = {
+    read_file: () => readFile(args, opts),
+    list_dir: () => listDir(args, opts),
+    search_files: () => searchFiles(args, opts),
+    glob_files: () => globFiles(args, opts),
+    write_file: () => writeFile(args, opts),
+    edit_file: () => editFile(args, opts),
+    run_shell: () => runShell(args, opts),
+    web_search: () => webSearch(args, opts),
+    web_fetch: () => webFetch(args, opts),
+    todo_write: () => todoWrite(args, opts),
+    ask_user: () => askUser(args, opts),
+    git_status: () => gitStatus(args, opts),
+    git_diff: () => gitDiff(args, opts),
+    git_log: () => gitLog(args, opts),
+    git_commit: () => gitCommit(args, opts),
+    git_branch: () => gitBranch(args, opts),
+    git_push: () => gitPush(args, opts),
+    git_create_pr: () => gitCreatePr(args, opts),
+  };
+  const fn = handlers[name];
+  if (!fn) {
+    return { ok: false, output: `Unknown tool: ${name}` };
+  }
+  try {
+    return await fn();
+  } catch (e) {
+    return { ok: false, output: `${name} failed: ${e.message}` };
+  }
+}
+
+// Ask the user a multiple-choice question and block on their answer. Not a
+// permission gate — it runs even in skip-permissions mode, because the model is
+// explicitly requesting input. In a non-TTY the menu auto-picks the first
+// option so scripted runs don't hang.
+async function askUser(args, _opts) {
+  const options = Array.isArray(args.options) ? args.options : [];
+  if (options.length === 0) {
+    return { ok: false, output: "ask_user requires a non-empty options array" };
+  }
+  const choice = await promptChoice({ question: String(args.question || "Which option?"), options });
+  if (!choice) {
+    return { ok: true, output: "The user cancelled the question. Proceed with your best judgment." };
+  }
+  const extra = choice.description ? ` (${choice.description})` : "";
+  return { ok: true, output: `The user chose: ${choice.label}${extra}` };
+}
+
+function readFile(args, opts) {
+  if (typeof args.path !== "string") return { ok: false, output: "path is required" };
+  const abs = resolveSafe(args.path, opts);
+  let stat;
+  try { stat = fs.statSync(abs); } catch (e) {
+    return { ok: false, output: `Cannot access ${args.path}: ${e.code || e.message}` };
+  }
+  if (stat.isDirectory()) return { ok: false, output: `${args.path} is a directory, not a file` };
+  // Block non-regular files (named pipes, sockets, devices) — reading them can
+  // hang forever (no timeout on readFileSync).
+  if (!stat.isFile()) return { ok: false, output: `${args.path} is not a regular file.` };
+  if (stat.size > 1_000_000) {
+    return { ok: false, output: `File too large (${stat.size} bytes). Aether refuses to read >1MB at once.` };
+  }
+  try {
+    return { ok: true, output: fs.readFileSync(abs, "utf8") };
+  } catch (e) {
+    return { ok: false, output: `Cannot read ${args.path}: ${e.code || e.message}` };
+  }
+}
+
+function listDir(args, opts) {
+  if (typeof args.path !== "string") return { ok: false, output: "path is required" };
+  const abs = resolveSafe(args.path, opts);
+  const entries = fs.readdirSync(abs, { withFileTypes: true });
+  const results = [];
+  for (const e of entries) {
+    if (!args.include_hidden && e.name.startsWith(".")) continue;
+    if (e.name === "node_modules" || e.name === ".git" || e.name === "dist") continue;
+    let size = undefined;
+    if (e.isFile()) {
+      try { size = fs.statSync(path.join(abs, e.name)).size; } catch { /* skip */ }
+    }
+    results.push({
+      name: e.name,
+      type: e.isDirectory() ? "dir" : e.isFile() ? "file" : "other",
+      size,
+    });
+  }
+  results.sort((a, b) => (a.type === b.type ? a.name.localeCompare(b.name) : a.type === "dir" ? -1 : 1));
+  return { ok: true, output: JSON.stringify(results, null, 2) };
+}
+
+function searchFiles(args, opts) {
+  if (typeof args.path !== "string" || typeof args.pattern !== "string") {
+    return { ok: false, output: "path and pattern are required" };
+  }
+  let regex;
+  try { regex = new RegExp(args.pattern); } catch (e) {
+    return { ok: false, output: `Invalid regex: ${e.message}` };
+  }
+  const root = resolveSafe(args.path, opts);
+  const isIgnored = loadIgnore(path.resolve(opts.cwd));
+  const matches = [];
+  const globRe = args.glob ? globToRegExp(args.glob) : null;
+  let truncated = false;
+
+  function walk(dir) {
+    if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
+      if (e.name.startsWith(".") || ALWAYS_SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const rel = path.relative(opts.cwd, full);
+      if (isIgnored(rel, e.isDirectory())) continue;
+      if (e.isDirectory()) {
+        walk(full);
+      } else if (e.isFile()) {
+        if (globRe && !globRe.test(e.name)) continue;
+        let content;
+        try {
+          const stat = fs.statSync(full);
+          if (stat.size > 500_000) continue;
+          content = fs.readFileSync(full, "utf8");
+        } catch { continue; }
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          // Skip very long lines: the pattern is model-supplied and a
+          // pathological regex on a long line can backtrack catastrophically
+          // (ReDoS) and freeze the single-threaded process.
+          if (lines[i].length > 2000) continue;
+          if (regex.test(lines[i])) {
+            matches.push({ file: rel, line: i + 1, text: lines[i].slice(0, 300) });
+            if (matches.length >= MAX_SEARCH_MATCHES) { truncated = true; return; }
+          }
+        }
+      }
+    }
+  }
+  walk(root);
+  const payload = { matches };
+  if (truncated) {
+    payload.truncated = true;
+    payload.note = `Showing the first ${MAX_SEARCH_MATCHES} matches — refine the pattern or pass a 'glob' filter to narrow.`;
+  }
+  return { ok: true, output: JSON.stringify(payload, null, 2) };
+}
+
+function globFiles(args, opts) {
+  if (typeof args.pattern !== "string") return { ok: false, output: "pattern is required" };
+  const root = resolveSafe(typeof args.path === "string" ? args.path : ".", opts);
+  const re = globToRegExp(args.pattern);
+  const isIgnored = loadIgnore(path.resolve(opts.cwd));
+  const found = [];
+  let truncated = false;
+
+  function walk(dir) {
+    if (found.length >= MAX_GLOB_RESULTS) { truncated = true; return; }
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (found.length >= MAX_GLOB_RESULTS) { truncated = true; return; }
+      if (e.name.startsWith(".") || ALWAYS_SKIP.has(e.name)) continue;
+      const full = path.join(dir, e.name);
+      const rel = path.relative(opts.cwd, full);
+      if (isIgnored(rel, e.isDirectory())) continue;
+      if (e.isDirectory()) {
+        walk(full);
+      } else if (e.isFile()) {
+        const relToRoot = path.relative(root, full).split(path.sep).join("/");
+        if (re.test(relToRoot)) {
+          let mtime = 0;
+          try { mtime = fs.statSync(full).mtimeMs; } catch { /* ignore */ }
+          found.push({ path: rel, mtime });
+        }
+      }
+    }
+  }
+  walk(root);
+  found.sort((a, b) => b.mtime - a.mtime); // most-recently-modified first
+  const payload = { files: found.map((f) => f.path) };
+  if (truncated) {
+    payload.truncated = true;
+    payload.note = `Showing the first ${MAX_GLOB_RESULTS} files — narrow the pattern.`;
+  }
+  return { ok: true, output: JSON.stringify(payload, null, 2) };
+}
+
+async function writeFile(args, opts) {
+  if (typeof args.path !== "string" || typeof args.content !== "string") {
+    return { ok: false, output: "path and content are required" };
+  }
+  const abs = resolveSafe(args.path, opts);
+  const exists = fs.existsSync(abs);
+  const oldContent = exists ? fs.readFileSync(abs, "utf8") : null;
+  if (exists && oldContent === args.content) {
+    return { ok: true, output: `(no change — file already matches)` };
+  }
+  // Show diff + confirm (the "● write <file>" label already spaced this block)
+  console.log(summarizeWrite(oldContent, args.content, path.relative(opts.cwd, abs)));
+  console.log(unifiedDiff(oldContent ?? "", args.content, path.relative(opts.cwd, abs)));
+  const approved = await confirm(c.yellow("Apply this write?"), opts.autoYes);
+  if (!approved) {
+    return { ok: false, output: "User declined the write." };
+  }
+  fs.mkdirSync(path.dirname(abs), { recursive: true });
+  fs.writeFileSync(abs, args.content, "utf8");
+  return { ok: true, output: `Wrote ${args.content.length} bytes to ${path.relative(opts.cwd, abs)}` };
+}
+
+async function editFile(args, opts) {
+  if (typeof args.path !== "string" || typeof args.find !== "string" || typeof args.replace !== "string") {
+    return { ok: false, output: "path, find, replace are required" };
+  }
+  const abs = resolveSafe(args.path, opts);
+  if (!fs.existsSync(abs)) {
+    return {
+      ok: false,
+      output: `File not found: ${args.path}. It doesn't exist yet — use write_file to CREATE it (edit_file only modifies existing files). Do not retry edit_file on this path.`,
+    };
+  }
+  const oldContent = fs.readFileSync(abs, "utf8");
+  const occurrences = oldContent.split(args.find).length - 1;
+  if (occurrences === 0) {
+    return { ok: false, output: `\`find\` text not found in ${args.path}. Tip: read the file first to copy exact characters.` };
+  }
+  if (!args.replace_all && occurrences > 1) {
+    return {
+      ok: false,
+      output: `\`find\` text appears ${occurrences} times — must be unique. Add more context to disambiguate, or set replace_all: true to replace all ${occurrences}.`,
+    };
+  }
+  // split/join for BOTH paths: String.replace(str, str) would interpret special
+  // patterns in the replacement ($&, $`, $', $$) and silently corrupt code that
+  // contains them (regex, jQuery $, template strings). split/join is literal.
+  // On the single-edit path occurrences === 1, so it's equivalent + safe.
+  const newContent = oldContent.split(args.find).join(args.replace);
+  const rel = path.relative(opts.cwd, abs);
+  console.log(c.dim(`edit ${rel}${args.replace_all ? ` (${occurrences} occurrences)` : ""}`));
+  console.log(unifiedDiff(oldContent, newContent, rel));
+  const approved = await confirm(c.yellow("Apply this edit?"), opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the edit." };
+  fs.writeFileSync(abs, newContent, "utf8");
+  return { ok: true, output: `Edited ${rel}${args.replace_all && occurrences > 1 ? ` (${occurrences} replacements)` : ""}` };
+}
+
+/* ─────────────────────── Web tools ─────────────────────── */
+
+async function webSearch(args, opts) {
+  void opts;
+  if (typeof args.query !== "string") return { ok: false, output: "query is required" };
+  const { apiKey, baseUrl } = getConfig();
+  if (!apiKey) {
+    return { ok: false, output: "Web search requires AETHER_API_KEY. Set it and try again." };
+  }
+  const max = Number.isInteger(args.max_results) ? Math.min(10, Math.max(1, args.max_results)) : 5;
+  const maxRetries = 2;
+  const baseDelay = 500;
+  let res;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      res = await fetch(`${baseUrl}/api/v1/web-search`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${apiKey}`,
+          "User-Agent": `aether-code/${getVersion()}`,
+        },
+        body: JSON.stringify({ query: args.query, max_results: max }),
+      });
+      if (res.status >= 500 && attempt < maxRetries) {
+        res.body?.cancel().catch(() => {});
+        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
+        continue;
+      }
+      break;
+    } catch (e) {
+      if (attempt < maxRetries) {
+        await new Promise((r) => setTimeout(r, baseDelay * 2 ** attempt));
+        continue;
+      }
+      return { ok: false, output: `web_search network error: ${e.message}` };
+    }
+  }
+  let data = null;
+  try { data = await res.json(); } catch { /* non-JSON */ }
+  if (!res.ok) {
+    return { ok: false, output: data?.error || `web_search HTTP ${res.status}` };
+  }
+  return { ok: true, output: JSON.stringify(data.results ?? [], null, 2) };
+}
+
+// Bounded fetch with a fixed timeout + size cap. Strips scripts/styles, removes
+// tags, decodes common HTML entities. Not a full HTML parser; good enough for
+// reading docs pages, GitHub READMEs, MDN, Stack Overflow answers, etc.
+// SSRF guard: refuse loopback / link-local / private hosts so web_fetch can't
+// be steered (directly or via a redirect) at localhost or cloud-metadata
+// (169.254.169.254) or an internal service.
+function isBlockedHost(hostname) {
+  const h = (hostname || "").toLowerCase().replace(/^\[|\]$/g, "");
+  if (!h || h === "localhost" || h === "0.0.0.0" || h === "::1" || h === "::") return true;
+  if (h.endsWith(".localhost") || h.endsWith(".internal") || h.endsWith(".local")) return true;
+  if (/^127\./.test(h)) return true;                       // loopback
+  if (/^10\./.test(h)) return true;                        // private A
+  if (/^192\.168\./.test(h)) return true;                  // private C
+  if (/^172\.(1[6-9]|2\d|3[01])\./.test(h)) return true;   // private B
+  if (/^169\.254\./.test(h)) return true;                  // link-local incl. cloud metadata
+  if (/^(fe80:|fc|fd|::ffff:)/.test(h)) return true;       // IPv6 link-local / ULA / mapped
+  return false;
+}
+
+async function webFetch(args, opts) {
+  void opts;
+  if (typeof args.url !== "string") return { ok: false, output: "url is required" };
+  if (!/^https?:\/\//i.test(args.url)) {
+    return { ok: false, output: "Only http:// and https:// URLs are allowed." };
+  }
+  let initialHost;
+  try { initialHost = new URL(args.url).hostname; } catch { return { ok: false, output: "Invalid URL." }; }
+  if (isBlockedHost(initialHost)) {
+    return { ok: false, output: "web_fetch blocked: refusing to fetch a private/internal/loopback address." };
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), 15_000);
+  let res;
+  try {
+    res = await fetch(args.url, {
+      signal: controller.signal,
+      redirect: "follow",
+      headers: {
+        // Looking like a normal browser dodges many anti-bot pages.
+        "User-Agent":
+          `Mozilla/5.0 (compatible; aether-code/${getVersion()}) Gecko/20100101 Firefox/130.0`,
+        Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8",
+        "Accept-Language": "en-US,en;q=0.9",
+      },
+    });
+  } catch (e) {
+    clearTimeout(timeout);
+    return { ok: false, output: `web_fetch error: ${e.name === "AbortError" ? "timed out after 15s" : e.message}` };
+  }
+  clearTimeout(timeout);
+  // Re-check the FINAL url after any redirects — a public URL can 302 to an
+  // internal target, which the initial-URL check wouldn't catch.
+  try {
+    if (isBlockedHost(new URL(res.url).hostname)) {
+      res.body?.cancel().catch(() => {});
+      return { ok: false, output: "web_fetch blocked: redirect to a private/internal address." };
+    }
+  } catch { /* res.url unparseable — fall through */ }
+  if (!res.ok) {
+    return { ok: false, output: `web_fetch HTTP ${res.status} ${res.statusText}` };
+  }
+  // Cap at 2 MB of raw HTML before stripping — page might be huge.
+  const reader = res.body?.getReader();
+  if (!reader) return { ok: false, output: "Response had no body." };
+  const chunks = [];
+  let total = 0;
+  while (true) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    total += value.length;
+    if (total > 2_000_000) {
+      reader.cancel();
+      break;
+    }
+    chunks.push(value);
+  }
+  const html = new TextDecoder("utf-8", { fatal: false }).decode(
+    Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength))),
+  );
+  const text = htmlToText(html);
+  // Final cap on what we hand to the model so a single fetch doesn't blow the context.
+  const capped = text.length > 50_000 ? text.slice(0, 50_000) + "\n…(truncated; page was longer)" : text;
+  return { ok: true, output: capped };
+}
+
+export function htmlToText(html) {
+  let s = html;
+  // Drop script/style blocks entirely.
+  s = s.replace(/<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, " ");
+  s = s.replace(/<style\b[^<]*(?:(?!<\/style>)<[^<]*)*<\/style>/gi, " ");
+  s = s.replace(/<noscript\b[^<]*(?:(?!<\/noscript>)<[^<]*)*<\/noscript>/gi, " ");
+  // Preserve paragraph + heading breaks.
+  s = s.replace(/<\/(p|div|h[1-6]|li|tr|br)\s*>/gi, "\n");
+  s = s.replace(/<br\s*\/?>/gi, "\n");
+  // Strip remaining tags.
+  s = s.replace(/<[^>]+>/g, "");
+  // Decode common HTML entities (covers ~95% of real-world cases).
+  const entities = {
+    "&amp;": "&", "&lt;": "<", "&gt;": ">", "&quot;": '"', "&#39;": "'",
+    "&apos;": "'", "&nbsp;": " ", "&mdash;": "—", "&ndash;": "–",
+    "&hellip;": "…", "&copy;": "©", "&reg;": "®", "&trade;": "™",
+  };
+  for (const [ent, ch] of Object.entries(entities)) {
+    s = s.split(ent).join(ch);
+  }
+  s = s.replace(/&#(\d+);/g, (_, n) => String.fromCharCode(parseInt(n, 10)));
+  s = s.replace(/&#x([0-9a-f]+);/gi, (_, n) => String.fromCharCode(parseInt(n, 16)));
+  // Collapse whitespace.
+  s = s.replace(/[ \t]+/g, " ");
+  s = s.replace(/\n\s*\n\s*\n+/g, "\n\n");
+  return s.trim();
+}
+
+const CATASTROPHIC_CMD_RE = new RegExp(
+  [
+    String.raw`rm\s+-(r|f|rf|fr)\w*\s+[/~](?!\S*node_modules)(?!\S*dist)(?!\S*\.next)(?!\S*build)`,
+    String.raw`del\s+/[sfq]+\s+[cC]:\\`,
+    String.raw`format\s+[a-zA-Z]:`,
+    String.raw`mkfs\.`,
+    String.raw`dd\s+.*of=/dev/[sh]d`,
+    String.raw`:\(\)\s*\{\s*:\|:`,
+    String.raw`>\s*/dev/[sh]d`,
+    String.raw`rd\s+/[sq]+\s+[cC]:\\`,
+  ].join("|"),
+);
+
+async function runShell(args, opts) {
+  if (typeof args.command !== "string") return { ok: false, output: "command is required" };
+  const cwd = args.cwd ? resolveSafe(args.cwd, opts) : opts.cwd;
+  console.log(c.yellow("$ ") + c.bold(args.command) + (args.cwd ? c.dim(`  (cwd: ${args.cwd})`) : ""));
+  const forceReview = CATASTROPHIC_CMD_RE.test(args.command);
+  if (forceReview) {
+    console.log(c.red(c.bold("  ⚠ DESTRUCTIVE COMMAND DETECTED")) + c.gray(" — requires manual confirmation"));
+  }
+  const approved = await confirm(c.yellow("Run this command?"), forceReview ? false : opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the command." };
+
+  return new Promise((resolve) => {
+    const child = spawn(args.command, [], { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const timeout = setTimeout(() => {
+      killed = true;
+      child.kill("SIGTERM");
+    }, 120_000); // 2-minute hard cap per command
+
+    child.stdout.on("data", (d) => {
+      const s = d.toString();
+      stdout += s;
+      if (stdout.length < 80_000) process.stdout.write(c.dim(s));
+    });
+    child.stderr.on("data", (d) => {
+      const s = d.toString();
+      stderr += s;
+      if (stderr.length < 80_000) process.stderr.write(c.dim(s));
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      // Truncate huge outputs before sending back to the model
+      const truncate = (t) => (t.length > 20_000 ? t.slice(0, 20_000) + "\n…(truncated)" : t);
+      const out = JSON.stringify(
+        {
+          exit_code: code,
+          killed,
+          stdout: truncate(stdout),
+          stderr: truncate(stderr),
+        },
+        null,
+        2,
+      );
+      resolve({ ok: code === 0 && !killed, output: out });
+    });
+  });
+}
+
+/* ─────────────────────── Git tools ─────────────────────── */
+
+function runGit(gitArgs, cwd, timeoutMs = 30_000) {
+  return new Promise((resolve) => {
+    const child = spawn("git", gitArgs, { cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+    const timer = setTimeout(() => { killed = true; child.kill("SIGTERM"); }, timeoutMs);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const truncate = (t) => (t.length > 30_000 ? t.slice(0, 30_000) + "\n…(truncated)" : t);
+      resolve({ code, killed, stdout: truncate(stdout), stderr: truncate(stderr) });
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ code: 1, killed: false, stdout: "", stderr: `git spawn error: ${err.message}` });
+    });
+  });
+}
+
+async function gitStatus(_args, opts) {
+  const r = await runGit(["status", "--short", "--branch", "-u"], opts.cwd);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git status failed" };
+  const lines = r.stdout.trim().split("\n");
+  const branchLine = lines[0] || "";
+  const files = lines.slice(1).filter((l) => l.trim());
+  const staged = [];
+  const unstaged = [];
+  const untracked = [];
+  for (const line of files) {
+    const x = line[0];
+    const y = line[1];
+    const name = line.slice(3);
+    if (x === "?") { untracked.push(name); continue; }
+    if (x !== " " && x !== "?") staged.push({ status: x, file: name });
+    if (y !== " " && y !== "?") unstaged.push({ status: y, file: name });
+  }
+  const result = {
+    branch: branchLine.replace(/^## /, ""),
+    staged,
+    unstaged,
+    untracked,
+    clean: staged.length === 0 && unstaged.length === 0 && untracked.length === 0,
+  };
+  return { ok: true, output: JSON.stringify(result, null, 2) };
+}
+
+async function gitDiff(args, opts) {
+  const gitArgs = ["diff", "--stat", "--patch"];
+  if (args.staged) gitArgs.push("--cached");
+  if (args.base) {
+    const head = args.head || "HEAD";
+    gitArgs.length = 0;
+    gitArgs.push("diff", args.base + "..." + head, "--stat", "--patch");
+  }
+  if (Array.isArray(args.files) && args.files.length > 0) {
+    gitArgs.push("--");
+    for (const f of args.files) gitArgs.push(f);
+  }
+  const r = await runGit(gitArgs, opts.cwd, 60_000);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git diff failed" };
+  if (!r.stdout.trim()) return { ok: true, output: "(no changes)" };
+  return { ok: true, output: r.stdout };
+}
+
+async function gitLog(args, opts) {
+  const count = Math.min(50, Math.max(1, args.count ?? 15));
+  const gitArgs = ["log", `-${count}`];
+  if (args.oneline) {
+    gitArgs.push("--oneline");
+  } else {
+    gitArgs.push("--format=%h %an (%ar)%n  %s%n");
+  }
+  if (args.branch) gitArgs.push(args.branch);
+  if (args.file) { gitArgs.push("--"); gitArgs.push(args.file); }
+  const r = await runGit(gitArgs, opts.cwd);
+  if (r.code !== 0) return { ok: false, output: r.stderr || "git log failed" };
+  if (!r.stdout.trim()) return { ok: true, output: "(no commits)" };
+  return { ok: true, output: r.stdout };
+}
+
+async function gitCommit(args, opts) {
+  if (typeof args.message !== "string" || !args.message.trim()) {
+    return { ok: false, output: "commit message is required" };
+  }
+  // Stage files
+  const filesToStage = Array.isArray(args.files) && args.files.length > 0 ? args.files : null;
+  if (filesToStage) {
+    const addR = await runGit(["add", "--", ...filesToStage], opts.cwd);
+    if (addR.code !== 0) return { ok: false, output: `git add failed: ${addR.stderr}` };
+  } else {
+    const addR = await runGit(["add", "-A"], opts.cwd);
+    if (addR.code !== 0) return { ok: false, output: `git add -A failed: ${addR.stderr}` };
+  }
+  // Show what's staged
+  const staged = await runGit(["diff", "--cached", "--stat"], opts.cwd);
+  if (!staged.stdout.trim()) {
+    return { ok: false, output: "Nothing to commit — no staged changes after git add." };
+  }
+  console.log(c.dim(staged.stdout));
+  console.log(c.cyan("commit message: ") + c.bold(args.message));
+  const approved = await confirm(c.yellow("Create this commit?"), opts.autoYes);
+  if (!approved) {
+    await runGit(["reset", "HEAD"], opts.cwd);
+    return { ok: false, output: "User declined the commit. Staged changes have been unstaged." };
+  }
+  const commitR = await runGit(["commit", "-m", args.message], opts.cwd);
+  if (commitR.code !== 0) return { ok: false, output: `git commit failed: ${commitR.stderr}` };
+  // Get the commit hash for confirmation
+  const hashR = await runGit(["rev-parse", "--short", "HEAD"], opts.cwd);
+  const hash = hashR.stdout.trim();
+  return { ok: true, output: `Committed ${hash}: ${args.message}\n${commitR.stdout}` };
+}
+
+async function gitBranch(args, opts) {
+  if (typeof args.name !== "string" || !args.name.trim()) {
+    return { ok: false, output: "branch name is required" };
+  }
+  // Check if branch exists
+  const checkR = await runGit(["rev-parse", "--verify", args.name], opts.cwd);
+  if (checkR.code === 0) {
+    // Branch exists, switch to it
+    const switchR = await runGit(["checkout", args.name], opts.cwd);
+    if (switchR.code !== 0) return { ok: false, output: `git checkout failed: ${switchR.stderr}` };
+    return { ok: true, output: `Switched to existing branch '${args.name}'` };
+  }
+  // Create new branch
+  const createArgs = ["checkout", "-b", args.name];
+  if (args.base) createArgs.push(args.base);
+  const createR = await runGit(createArgs, opts.cwd);
+  if (createR.code !== 0) return { ok: false, output: `git checkout -b failed: ${createR.stderr}` };
+  return { ok: true, output: `Created and switched to new branch '${args.name}'${args.base ? ` from ${args.base}` : ""}` };
+}
+
+async function gitPush(args, opts) {
+  // Get current branch name
+  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
+  if (branchR.code !== 0) return { ok: false, output: `Cannot determine current branch: ${branchR.stderr}` };
+  const branch = branchR.stdout.trim();
+  if (!branch || branch === "HEAD") {
+    return { ok: false, output: "Cannot push — HEAD is detached. Checkout a branch first." };
+  }
+  const pushArgs = ["push", "-u", "origin", branch];
+  if (args.force) pushArgs.splice(1, 0, "--force-with-lease");
+  console.log(c.yellow("$ ") + c.bold(`git ${pushArgs.join(" ")}`));
+  const approved = await confirm(c.yellow(`Push '${branch}' to origin?`), opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the push." };
+  const r = await runGit(pushArgs, opts.cwd, 60_000);
+  if (r.code !== 0) return { ok: false, output: `git push failed: ${r.stderr}` };
+  return { ok: true, output: `Pushed '${branch}' to origin.\n${r.stderr}${r.stdout}`.trim() };
+}
+
+async function gitCreatePr(args, opts) {
+  if (typeof args.title !== "string" || !args.title.trim()) {
+    return { ok: false, output: "PR title is required" };
+  }
+  if (typeof args.body !== "string") {
+    return { ok: false, output: "PR body is required" };
+  }
+  // Check if gh CLI is available
+  const ghCheck = await runGit(["--version"], opts.cwd);
+  void ghCheck;
+  const ghVerify = new Promise((resolve) => {
+    const child = spawn("gh", ["--version"], { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let out = "";
+    child.stdout.on("data", (d) => { out += d.toString(); });
+    child.on("close", (code) => resolve({ code, stdout: out }));
+    child.on("error", () => resolve({ code: 1, stdout: "" }));
+  });
+  const ghResult = await ghVerify;
+  if (ghResult.code !== 0) {
+    return { ok: false, output: "GitHub CLI (gh) is not installed or not in PATH. Install it: https://cli.github.com" };
+  }
+  // Push branch first if needed
+  const branchR = await runGit(["rev-parse", "--abbrev-ref", "HEAD"], opts.cwd);
+  const branch = branchR.stdout.trim();
+  const trackR = await runGit(["config", "--get", `branch.${branch}.remote`], opts.cwd);
+  if (trackR.code !== 0 || !trackR.stdout.trim()) {
+    console.log(c.gray(`Branch '${branch}' has no remote — pushing first...`));
+    const pushR = await runGit(["push", "-u", "origin", branch], opts.cwd, 60_000);
+    if (pushR.code !== 0) return { ok: false, output: `Failed to push branch: ${pushR.stderr}` };
+    console.log(c.gray("Pushed."));
+  }
+  // Build gh pr create command
+  console.log(c.cyan("PR title: ") + c.bold(args.title));
+  const bodyPreview = args.body.length > 200 ? args.body.slice(0, 197) + "..." : args.body;
+  console.log(c.gray(bodyPreview));
+  if (args.base) console.log(c.gray(`base: ${args.base}`));
+  if (args.draft) console.log(c.gray("(draft PR)"));
+  const approved = await confirm(c.yellow("Create this pull request?"), opts.autoYes);
+  if (!approved) return { ok: false, output: "User declined the PR." };
+  const ghArgs = ["pr", "create", "--title", args.title, "--body", args.body];
+  if (args.base) { ghArgs.push("--base"); ghArgs.push(args.base); }
+  if (args.draft) ghArgs.push("--draft");
+  return new Promise((resolve) => {
+    const child = spawn("gh", ghArgs, { cwd: opts.cwd, stdio: ["ignore", "pipe", "pipe"] });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => child.kill("SIGTERM"), 30_000);
+    child.stdout.on("data", (d) => { stdout += d.toString(); });
+    child.stderr.on("data", (d) => { stderr += d.toString(); });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      if (code !== 0) {
+        resolve({ ok: false, output: `gh pr create failed (exit ${code}): ${stderr || stdout}` });
+      } else {
+        const prUrl = stdout.trim();
+        resolve({ ok: true, output: `Pull request created: ${prUrl}\n${stderr}`.trim() });
+      }
+    });
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, output: `gh spawn error: ${err.message}` });
+    });
+  });
+}
+
+/* ─────────────────────── todo_write ─────────────────────── */
+
+// Module-level singleton holding the current todo list for this CLI session.
+// Latest-wins: each todo_write call replaces the entire list. The model
+// passes the full new state every time, mirroring what Claude Code's
+// TodoWrite does. Simpler than incremental ops; gives the model full
+// control over ordering and renames.
+const VALID_TODO_STATUSES = new Set(["pending", "in_progress", "completed"]);
+const MAX_TODOS = 30;
+let todoState = [];
+
+// Test-only escape hatches — exported so the test suite can reset state
+// between cases. Production code never touches these.
+export function __resetTodoState() {
+  todoState = [];
+}
+export function __getTodoState() {
+  return todoState.map((t) => ({ ...t }));
+}
+
+function todoWrite(args, opts) {
+  void opts;
+  if (!Array.isArray(args.todos)) {
+    return { ok: false, output: "todos must be an array" };
+  }
+  if (args.todos.length > MAX_TODOS) {
+    return {
+      ok: false,
+      output: `too many todos (${args.todos.length}) — max ${MAX_TODOS}. Keep the plan focused.`,
+    };
+  }
+  // Validate every item BEFORE mutating state — we don't want a partial write.
+  for (let i = 0; i < args.todos.length; i++) {
+    const t = args.todos[i];
+    if (!t || typeof t !== "object") {
+      return { ok: false, output: `todo[${i}] must be an object` };
+    }
+    if (typeof t.content !== "string" || t.content.trim().length === 0) {
+      return { ok: false, output: `todo[${i}] needs a non-empty content string` };
+    }
+    if (!VALID_TODO_STATUSES.has(t.status)) {
+      return {
+        ok: false,
+        output: `todo[${i}] invalid status: "${t.status}" — must be pending, in_progress, or completed`,
+      };
+    }
+  }
+  todoState = args.todos.map((t) => ({
+    content: t.content.trim(),
+    status: t.status,
+  }));
+  renderTodos(todoState);
+  const counts = { pending: 0, in_progress: 0, completed: 0 };
+  for (const t of todoState) counts[t.status]++;
+  return {
+    ok: true,
+    output: `Todos updated: ${counts.pending} pending, ${counts.in_progress} in_progress, ${counts.completed} completed.`,
+  };
+}
+
+function renderTodos(todos) {
+  if (!process.stdout.isTTY) return; // skip render in non-TTY (CI, piped, tests)
+  console.log("");
+  console.log(c.cyan("●") + " " + c.bold("Plan"));
+  for (const t of todos) {
+    const icon =
+      t.status === "completed"
+        ? c.green("●")
+        : t.status === "in_progress"
+          ? c.yellow("→")
+          : c.dim("·");
+    const text =
+      t.status === "completed"
+        ? c.dim(t.content)
+        : t.status === "in_progress"
+          ? c.bold(t.content)
+          : c.gray(t.content);
+    console.log(`  ${icon} ${text}`);
+  }
+  console.log("");
+}