@semalt-ai/code 1.8.5 → 1.20.0

package/lib/tool_registry.js

@@ -0,0 +1,2862 @@
+'use strict';
+
+// ---------------------------------------------------------------------------
+// Runtime tool registry — one registration per tool.
+// ---------------------------------------------------------------------------
+//
+// This is the single place that owns, per tool, EVERYTHING needed to recover,
+// gate, and run a call — for BOTH transport paths:
+//
+//   * parseXml(text)        — XML/tag path (the ~25 regexes once inlined in
+//                             extractToolCalls now live next to their tool).
+//   * fromParams(params)    — native function-calling path (was mapInvokeToCall).
+//   * permission(ctx, args) — the gate descriptor (was the describePermission
+//                             switch). Returns null for ungated read-only ops.
+//   * execute(ctx, args, opts) — the operation (was the agentExecFile branch).
+//
+// Both transports resolve to the SAME entry and produce the SAME [action, ...args]
+// tuple, and dispatch (agentExecFile / describePermission in lib/tools.js) is a
+// registry lookup keyed on the tool's canonical action.
+//
+// `ctx` is a dependency bag built once by createToolExecutor (lib/tools.js) and
+// passed in at call time. It carries the factory-scoped collaborators (colors,
+// permissionManager, getConfig) and the tools.js-internal helpers (isPathSafe,
+// the sandbox/secret guards, _log, …). Passing them in — rather than requiring
+// lib/tools.js here — is what keeps this module free of the tools.js ↔ registry
+// require cycle. Executor/permission bodies were moved VERBATIM from agentExecFile
+// / describePermission; the `const { … } = ctx` preamble re-binds the same names
+// so the bodies below are unchanged.
+//
+// Adding a tool is now ONE registration object here + its TOOL_SPECS schema + its
+// TAG_REGISTRY classification. The first two are asserted in lockstep by the
+// load-time parity check in lib/constants.js (which also requires execute +
+// permission on every non-wrapper entry).
+//
+// IMPORTANT — parse ORDER: extractToolCalls runs entries in array order; the
+// per-format ordering is pinned by test/extract-tool-calls.test.js.
+
+const fs = require('fs');
+const fsp = require('fs/promises');
+const path = require('path');
+const os = require('os');
+const http = require('http');
+const https = require('https');
+const { spawnSync } = require('child_process');
+const { extractContent, capToTokens, defaultEstimate, markupEstimate, MARKUP_CHARS_PER_TOKEN, classifyContentType } = require('./web-extract');
+const { summarizeWebContent } = require('./web-summarize');
+
+// Resolve the User-Agent for the fetch tools (Task W.3 Part 2). A fixed,
+// realistic browser UA defeats SIMPLE UA-based bot-blocking (sites that 403/406
+// an empty/curl-like UA). Operator-overridable via config.web.user_agent;
+// deliberately NOT model-selectable — the agent does not control how the tool
+// presents itself to the outside, so there is no UA parameter in the tool spec.
+// Reads the already-normalized config (getConfig() returns web.user_agent set to
+// the override or the default) but falls back defensively to DEFAULT_USER_AGENT
+// for any partially-built config. The constant is required LAZILY because
+// constants.js requires this module at load time (circular dep) — a top-level
+// destructure would capture `undefined`; by call time constants is fully loaded.
+function _resolveUserAgent(cfg) {
+  const web = cfg && cfg.web && typeof cfg.web === 'object' ? cfg.web : {};
+  const ua = typeof web.user_agent === 'string' ? web.user_agent.trim() : '';
+  if (ua) return ua;
+  return require('./constants').DEFAULT_USER_AGENT;
+}
+
+// http_get per-call options (Task W.1 / W.1b). The agent may override the global
+// web-fetch behavior for a single fetch via a three-level `mode` enum:
+//   mode="summarized" (default) → extract → Markdown → secondary-LLM summary.
+//   mode="extracted"            → extract → Markdown, NO summary (exact snippets).
+//   mode="raw"                  → bypass extraction entirely; return the ORIGINAL
+//       fetched HTML/content (token-capped, fenced) — for analyzing a page's
+//       markup/CSS/JS/structure, the one task extraction destroys.
+//   intent="…"                  → the reason for fetching, focusing the summary.
+// Deprecated boolean aliases (kept for back-compat): summarize="false" and
+// raw="true" both map to `extracted`. Precedence: an explicit `mode` always
+// beats the legacy booleans; with neither, the global config default applies.
+const WEB_FETCH_MODES = ['summarized', 'extracted', 'raw'];
+
+function _httpGetBool(v) {
+  if (v == null) return undefined;
+  const s = String(v).trim().toLowerCase();
+  if (s === 'true' || s === '1' || s === 'yes' || s === 'on') return true;
+  if (s === 'false' || s === '0' || s === 'no' || s === 'off') return false;
+  return undefined;
+}
+
+// Normalize a `mode` value to one of WEB_FETCH_MODES, or undefined if unknown.
+function _httpGetMode(v) {
+  if (v == null) return undefined;
+  const s = String(v).trim().toLowerCase();
+  return WEB_FETCH_MODES.includes(s) ? s : undefined;
+}
+
+// Map a legacy boolean pair to a mode (explicit `mode` is resolved by the caller
+// first and takes precedence). summarize=false / raw=true → extracted.
+function _legacyBoolsToMode(summarize, raw) {
+  if (summarize !== undefined) return summarize ? 'summarized' : 'extracted';
+  if (raw !== undefined) return raw ? 'extracted' : 'summarized';
+  return undefined;
+}
+
+// Validate + normalize a URL for the fetch tools (http_get / download).
+//
+// `new URL(...)` — and `http.get`/`https.get`'s own internal parse — throws
+// SYNCHRONOUSLY for a malformed URL, before any request starts. That throw
+// happens OUTSIDE the request-level `.on('error')` handlers (which only catch
+// async network failures: EHOSTUNREACH, DNS, timeout, …), so a bad URL would
+// escape the executor as an uncaught exception and crash the whole session
+// instead of becoming a recoverable tool error. The model routinely produces
+// malformed/guessed URLs (invented domains, non-ASCII hosts, stray chars), so
+// every fetch must validate up front and turn ANY bad input into a clean tool
+// error in the SAME `{ error, error_code }` shape the network-failure path
+// returns — so the agent handles it identically to EHOSTUNREACH/timeout.
+//
+// Returns `{ url }` (the normalized href) on success, or `{ error, error_code }`
+// on failure. Only http/https schemes are allowed; everything else (file:, ftp:,
+// javascript:, data:, …) is refused (these parse cleanly but must never be
+// fetched). `base` (optional) resolves a relative URL — used for redirect
+// `Location` headers, which are often relative.
+function _validateFetchUrl(raw, base) {
+  if (typeof raw !== 'string') {
+    return {
+      error: `Invalid URL: expected a string, got ${raw === null ? 'null' : typeof raw}`,
+      error_code: 'ERR_INVALID_URL',
+    };
+  }
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return { error: 'Invalid URL: empty URL', error_code: 'ERR_INVALID_URL' };
+  }
+  let parsed;
+  try {
+    parsed = base ? new URL(trimmed, base) : new URL(trimmed);
+  } catch (err) {
+    return { error: `Invalid URL: ${err.message}`, error_code: 'ERR_INVALID_URL' };
+  }
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+    return {
+      error: `Invalid URL: unsupported protocol "${parsed.protocol}" (only http and https are allowed)`,
+      error_code: 'ERR_INVALID_PROTOCOL',
+    };
+  }
+  return { url: parsed.href };
+}
+
+function _httpGetOpts(attrStr) {
+  const s = String(attrStr || '');
+  const get = (name) => {
+    const m = s.match(new RegExp(`${name}="([^"]*)"`)) || s.match(new RegExp(`${name}='([^']*)'`));
+    return m ? m[1] : undefined;
+  };
+  const opts = {};
+  const mode = _httpGetMode(get('mode'));
+  if (mode) opts.mode = mode;
+  else {
+    const legacy = _legacyBoolsToMode(_httpGetBool(get('summarize')), _httpGetBool(get('raw')));
+    if (legacy) opts.mode = legacy;
+  }
+  const intent = get('intent');
+  if (intent != null && intent !== '') opts.intent = intent;
+  return opts;
+}
+
+function _httpGetOptsFromParams(p) {
+  const opts = {};
+  const mode = _httpGetMode(p.mode);
+  if (mode) opts.mode = mode;
+  else {
+    const summarize = typeof p.summarize === 'boolean' ? p.summarize : undefined;
+    const raw = typeof p.raw === 'boolean' ? p.raw : undefined;
+    const legacy = _legacyBoolsToMode(summarize, raw);
+    if (legacy) opts.mode = legacy;
+  }
+  if (typeof p.intent === 'string' && p.intent.trim()) opts.intent = p.intent.trim();
+  return opts;
+}
+
+// web_search per-call options (Task W.2b). Only `count` today — bounded so a
+// huge value never leaves the client; the backend clamps further. Returns
+// `undefined` for a missing/invalid/zero count so the backend default applies.
+const _WEB_SEARCH_MAX_COUNT = 10;
+function _clampSearchCount(v) {
+  if (v == null || v === '') return undefined;
+  const n = parseInt(v, 10);
+  if (!Number.isFinite(n) || n <= 0) return undefined;
+  return Math.min(n, _WEB_SEARCH_MAX_COUNT);
+}
+
+function _webSearchOpts(attrStr) {
+  const s = String(attrStr || '');
+  const m = s.match(/count="([^"]*)"/) || s.match(/count='([^']*)'/);
+  const count = _clampSearchCount(m ? m[1] : undefined);
+  return count ? { count } : {};
+}
+
+function _webSearchOptsFromParams(p) {
+  const count = _clampSearchCount(p && p.count);
+  return count ? { count } : {};
+}
+
+// The web-fetch pipeline (Task W.1 / W.1b), shared by http_get's execute. Turns
+// a fetched body into the content that enters the main context. The `mode` enum
+// selects the depth of processing:
+//   raw        → bypass extraction ENTIRELY; return the ORIGINAL fetched content
+//                (token-capped). For analyzing a page's HTML/CSS/JS/structure —
+//                the one task extraction destroys (Task W.1b).
+//   extracted  → extract main content → Markdown (HTML only; json/text/markdown
+//                pass through untouched so they are never mangled), token-cap it,
+//                NO secondary summary.
+//   summarized → as `extracted`, then summarize via a secondary cheap LLM call —
+//                only the summary enters context; the extracted full text never
+//                does.
+// Context protection (token-cap via web.max_content_tokens) applies in EVERY
+// mode, including raw (raw HTML is token-heavier, so it matters more, not less).
+// Containment: a summarizer failure falls back to the capped extracted Markdown,
+// NEVER the raw page. Network-free here (the LLM call is the injected webChat).
+async function processWebContent({
+  rawBody, contentType, url, statusCode, totalBytes, transferCapped,
+  mode, intent, summaryModel, maxContentTokens, webChat, signal,
+}) {
+  // RAW mode (Task W.1b): the original content is returned with NO extraction —
+  // no Readability, no Turndown, no summary. Context protection still holds: cap
+  // to the token budget with the standard truncation notice. The untrusted fence
+  // is applied by the caller (lib/agent.js) for raw exactly as for every mode.
+  if (mode === 'raw') {
+    const kind = classifyContentType(contentType, url, rawBody);
+    // Raw HTML/markup tokenizes denser than prose, so char/4 over-admits markup
+    // (Task W.4 Part 2). Use the markup-aware estimate + matching char budget for
+    // markup; JSON/text raw bodies stay on the prose estimate (unchanged).
+    const isMarkup = kind === 'html';
+    const capped = isMarkup
+      ? capToTokens(rawBody, maxContentTokens, markupEstimate, MARKUP_CHARS_PER_TOKEN)
+      : capToTokens(rawBody, maxContentTokens, defaultEstimate);
+    return {
+      status_code: statusCode,
+      bytes: totalBytes,
+      kind,
+      mode: 'raw',
+      extracted: false,
+      summarized: false,
+      content_tokens: capped.tokens,
+      content_truncated: capped.truncated,
+      transfer_capped: !!transferCapped,
+      body: capped.text,
+    };
+  }
+
+  const { kind, markdown, title, extracted } = extractContent({ body: rawBody, contentType, url });
+  const capped = capToTokens(markdown, maxContentTokens, defaultEstimate);
+  const base = {
+    status_code: statusCode,
+    bytes: totalBytes,
+    kind,
+    mode,
+    title: title || undefined,
+    extracted,
+    content_tokens: capped.tokens,
+    content_truncated: capped.truncated,
+    transfer_capped: !!transferCapped,
+  };
+  // Summarize ONLY HTML — JSON/plain text/Markdown pass through verbatim so
+  // structured data is never smoothed over. Requires mode==='summarized'
+  // AND an available LLM call. Otherwise return the capped extracted Markdown.
+  const summarizable = kind === 'html' && capped.text.trim().length > 0;
+  if (mode === 'summarized' && summarizable && typeof webChat === 'function') {
+    try {
+      const summary = await summarizeWebContent({
+        markdown: capped.text, intent, chat: webChat, model: summaryModel, signal,
+      });
+      return { ...base, body: summary, summarized: true };
+    } catch (err) {
+      // Summary errored/timed out → degrade to the capped extracted Markdown,
+      // never the raw HTML.
+      return { ...base, body: capped.text, summarized: false, summary_error: err.message };
+    }
+  }
+  return { ...base, body: capped.text, summarized: false };
+}
+
+// ── XML parse helpers (moved from lib/tools.js) ────────────────────────────
+
+function _matchDual(text, template) {
+  const results = [];
+  for (const q of ['"', "'"]) {
+    const re = new RegExp(template.replace(/Q/g, q), 'g');
+    for (const m of text.matchAll(re)) results.push(m);
+  }
+  return results;
+}
+
+// 1-based starting line numbers of every literal occurrence of `needle` in
+// `data`. Used by replace_in_file's uniqueness guard to tell the model WHERE the
+// ambiguous matches are so it can add disambiguating context. Capped so a needle
+// that matches hundreds of times doesn't produce a giant error string.
+function _literalOccurrenceLines(data, needle, cap = 10) {
+  const lines = [];
+  let from = 0;
+  let idx;
+  while ((idx = data.indexOf(needle, from)) !== -1) {
+    lines.push(data.slice(0, idx).split('\n').length);
+    from = idx + needle.length;
+    if (lines.length >= cap) break;
+  }
+  return lines;
+}
+
+function _unwrapInnerTag(inner) {
+  if (inner == null) return inner;
+  const trimmed = String(inner).trim();
+  const m = trimmed.match(/^<(\w+)(?:\s[^>]*)?>([\s\S]*)<\/\1>$/);
+  if (!m) return inner;
+  return m[2].trim();
+}
+
+// read_file pagination rail (Task W.7). Parses both forms in one pass and
+// resolves the optional start_line/end_line/show_line_numbers attributes onto the
+// tuple ['read', path, startLine|null, endLine|null, showLineNumbers]. Absent
+// range → null (parity with fromParams), so the formatter's defaults apply. Path
+// comes from the `path` attr or the inline body (the historical two forms).
+function _parseReadTag(text) {
+  const out = [];
+  const re = /<read_file\b([^>]*?)(?:\/>|>([\s\S]*?)<\/read_file>)/g;
+  for (const m of text.matchAll(re)) {
+    const attrStr = m[1] || '';
+    const body = m[2] != null ? m[2] : '';
+    const attr = (k) => {
+      const mm = attrStr.match(new RegExp(`${k}="([^"]*)"`)) || attrStr.match(new RegExp(`${k}='([^']*)'`));
+      return mm ? mm[1] : null;
+    };
+    const num = (v) => { if (v == null) return null; const n = parseInt(v, 10); return Number.isFinite(n) ? n : null; };
+    let p = attr('path');
+    if (p == null) { const b = _unwrapInnerTag(body).trim(); p = b || null; }
+    if (p == null) continue;
+    const sln = attr('show_line_numbers');
+    out.push(['read', p, num(attr('start_line')), num(attr('end_line')),
+      sln === 'true' || sln === '1' || sln === 'yes']);
+  }
+  return out;
+}
+
+function _inline(text, tagAlternation, action, extraArgs = []) {
+  const re = new RegExp(`<(?:${tagAlternation})>([\\s\\S]*?)<\\/(?:${tagAlternation})>`, 'g');
+  const out = [];
+  for (const m of text.matchAll(re)) out.push([action, _unwrapInnerTag(m[1]).trim(), ...extraArgs]);
+  return out;
+}
+
+// The full ctx destructure, reused at the top of every execute/permission so the
+// moved bodies see the same free names they had inside the createToolExecutor
+// closure. Unused names in any given body are harmless.
+//   const CTX = (ctx) => ... (we inline the destructure literally for clarity)
+
+// ── write/append share one body in agentExecFile; keep that sharing here ────
+async function _execWriteAppend(ctx, action, args, options) {
+  const signal = (options && options.signal) || null; // eslint-disable-line no-unused-vars
+  const [arg0 = null, arg1 = null] = args;
+  const { _log, logToolCall, isPathSafe, isProtectedConfigPath, _sandboxError, _protectedConfigWriteError, _dryRun, _skippedOps, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+
+  const filePath = arg0;
+  const content = arg1;
+  const tag = action === 'write' ? 'write_file' : 'append_file';
+
+  const blocked = permissionManager.readonlyBlock(tag);
+  if (blocked) {
+    logToolCall(tag, { path: filePath, content }, false, 'denied');
+    return blocked;
+  }
+
+  if (isProtectedConfigPath(filePath)) {
+    logToolCall(tag, { path: filePath }, false, 'denied');
+    return _protectedConfigWriteError(filePath);
+  }
+
+  if (!isPathSafe(filePath)) {
+    logToolCall(tag, { path: filePath }, false, 'denied');
+    return _sandboxError(filePath);
+  }
+
+  if (_dryRun) {
+    const verb = action === 'write' ? 'write' : 'append';
+    _skippedOps.push({ category: 'file', symbol: '✎', desc: `${verb} ${filePath}` });
+    logToolCall(tag, { path: filePath }, false, 'dry-run');
+    return { status: 'dry-run', message: 'dry-run: write skipped', path: filePath };
+  }
+
+  try {
+    // Capture prior content so the diff can render at EXECUTION time (the agent
+    // loop hands _diffBefore/_diffAfter to onToolEnd). Non-existent file → '' →
+    // the diff renders as a new file. Cheap relative to the write itself.
+    let before = '';
+    try { before = await fsp.readFile(filePath, 'utf8'); } catch {}
+    const after = action === 'write' ? (content || '') : (before + (content || ''));
+    const dir = path.dirname(filePath);
+    if (dir && dir !== '.') await fsp.mkdir(dir, { recursive: true });
+    if (action === 'write') await fsp.writeFile(filePath, content || '');
+    else await fsp.appendFile(filePath, content || '');
+    const verb = action === 'write' ? 'Wrote' : 'Appended to';
+    _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}${verb} ${filePath}${RST}`);
+    logToolCall(tag, { path: filePath, content }, true, 'ok');
+    return { status: 'ok', path: filePath, bytes: (content || '').length, _diffBefore: before, _diffAfter: after };
+  } catch (error) {
+    _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+    logToolCall(tag, { path: filePath, content }, true, 'error');
+    return { error: error.message };
+  }
+}
+
+async function _permWriteAppend(ctx, action, args) {
+  const { _dryRun, renderDiff, writer } = ctx;
+  const _uiActive = ctx._uiActive;
+  const filePath = args[0];
+  const content = args[1];
+  const tag = action === 'write' ? 'write_file' : 'append_file';
+
+  // The full diff is rendered at EXECUTION time (the agent loop's onToolEnd),
+  // decoupled from this modal — so an auto-approved write shows its diff just
+  // like a manually-approved one, and the diff is shown exactly once. The modal
+  // therefore carries only a compact description, NOT the diff. The one path
+  // without an execution-time renderer (headless / oneshot, !_uiActive) still
+  // surfaces the diff here so a write is never silent there.
+  if (!_uiActive && !_dryRun) {
+    let existing = '';
+    try { existing = await fsp.readFile(filePath, 'utf8'); } catch {}
+    const finalContent = action === 'write' ? (content || '') : (existing + (content || ''));
+    writer.scrollback(renderDiff(existing, finalContent, filePath));
+  }
+
+  if (_dryRun) return null;
+
+  let desc = `${action === 'write' ? 'Write' : 'Append to'} ${filePath}`;
+  if (content) desc += ` (${content.length} chars)`;
+  return { actionType: 'file', description: desc, tag };
+}
+
+// ── grep / glob (Task 2.1) ─────────────────────────────────────────────────
+//
+// Canonical search semantics. The pure-Node implementation is the REFERENCE;
+// ripgrep is invoked with a flag set chosen to reproduce it byte-for-byte (the
+// equivalence is pinned by test/grep-glob.test.js):
+//   * recurse from baseDir
+//   * always skip directories named node_modules or .git
+//   * skip hidden entries (names beginning with ".")
+//   * honor a .gitignore in baseDir if present (common-subset rules below)
+//   * skip binary files (a NUL byte in the first 8 KB)
+//   * emit one record per matching LINE: { file, line, text }, sorted by
+//     (file, line); file is baseDir-relative POSIX. Output never carries the
+//     engine identity, so rg and Node results are deep-equal.
+
+const GREP_MAX_MATCHES = 1000;
+const GLOB_MAX_FILES = 5000;
+const GREP_SKIP_DIRS = new Set(['node_modules', '.git']);
+const BINARY_SNIFF_BYTES = 8192;
+
+// grep output modes (Task W.5), Claude-Code-style. The model selects one via the
+// `output_mode` parameter; the mode is shaped at serialization time
+// (lib/agent.js formatFileResult) from the same engine result:
+//   * content            — file:line:text per match (default; "show me the lines")
+//   * files_with_matches — unique file paths only ("which files")
+//   * count              — match counts per file + total ("how many")
+const GREP_OUTPUT_MODES = ['content', 'files_with_matches', 'count'];
+function _normGrepMode(m) {
+  return GREP_OUTPUT_MODES.includes(m) ? m : 'content';
+}
+// head_limit / offset normalization (Task W.5). A positive integer bounds /
+// skips results; anything else falls back (limit → default, offset → 0).
+function _normHeadLimit(v, dflt) {
+  const n = typeof v === 'number' ? v : parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : dflt;
+}
+function _normOffset(v) {
+  const n = typeof v === 'number' ? v : parseInt(v, 10);
+  return Number.isFinite(n) && n > 0 ? Math.floor(n) : 0;
+}
+
+// ripgrep detection, performed once and cached. SEMALT_NO_RG forces the Node
+// fallback; SEMALT_RG_BIN points at an alternate binary (both used by tests).
+let _rgChecked = false;
+let _rgBin = null;
+function _detectRipgrep() {
+  if (_rgChecked) return _rgBin;
+  _rgChecked = true;
+  if (process.env.SEMALT_NO_RG) { _rgBin = null; return _rgBin; }
+  const bin = process.env.SEMALT_RG_BIN || 'rg';
+  try {
+    const r = spawnSync(bin, ['--version'], { encoding: 'utf8' });
+    if (r && r.status === 0) _rgBin = bin;
+  } catch { /* rg not on PATH */ }
+  return _rgBin;
+}
+
+function _toPosix(p) { return p.split(path.sep).join('/'); }
+
+// Glob → anchored RegExp. Mirrors the search_files conversion so the two file
+// matchers agree: * → one path segment, ** → any depth.
+function _globToRegExp(glob) {
+  let s = glob.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+  s = s.replace(/\*\*/g, '\x00');
+  s = s.replace(/\*/g, '[^/]*');
+  s = s.replace(/\x00\//g, '(?:.*/)?');
+  s = s.replace(/\x00/g, '.*');
+  return new RegExp(`^${s}$`);
+}
+
+// .gitignore, common subset: blank/comment lines; basename globs (no slash,
+// matched at any depth); anchored path globs (a slash anywhere but trailing);
+// dir-only (trailing slash); negation (!). Only the baseDir .gitignore is read
+// (no nested files). Last matching rule wins.
+function _loadGitignore(baseDir) {
+  let txt;
+  try { txt = fs.readFileSync(path.join(baseDir, '.gitignore'), 'utf8'); }
+  catch { return []; }
+  const rules = [];
+  for (let line of txt.split('\n')) {
+    line = line.replace(/\r$/, '').replace(/^\s+|\s+$/g, '');
+    if (!line || line.startsWith('#')) continue;
+    let negate = false;
+    if (line.startsWith('!')) { negate = true; line = line.slice(1); }
+    let dirOnly = false;
+    if (line.endsWith('/')) { dirOnly = true; line = line.slice(0, -1); }
+    let anchored = false;
+    if (line.startsWith('/')) { anchored = true; line = line.slice(1); }
+    if (!line) continue;
+    rules.push({ negate, dirOnly, anchored: anchored || line.includes('/'), re: _globToRegExp(line) });
+  }
+  return rules;
+}
+
+// rel: baseDir-relative POSIX path of the entry; name: its basename.
+function _gitignored(rules, rel, name, isDir) {
+  let ignored = false;
+  for (const r of rules) {
+    if (r.dirOnly && !isDir) continue;
+    if (r.re.test(r.anchored ? rel : name)) ignored = !r.negate;
+  }
+  return ignored;
+}
+
+function _isBinaryBuf(buf) {
+  const n = Math.min(buf.length, BINARY_SNIFF_BYTES);
+  for (let i = 0; i < n; i++) if (buf[i] === 0) return true;
+  return false;
+}
+
+// Iterative DFS over baseDir applying the canonical skip rules; calls
+// onFile(rel, name, absPath) for each surviving file. Honors an abort signal
+// between entries. Returns false if aborted, true otherwise.
+function _walkTree(baseDir, { rules = [], signal = null, onFile }) {
+  const stack = [{ dir: baseDir, rel: '' }];
+  while (stack.length) {
+    if (signal && signal.aborted) return false;
+    const { dir, rel } = stack.pop();
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); }
+    catch { continue; }
+    for (const e of entries) {
+      const name = e.name;
+      if (name.startsWith('.')) continue; // hidden
+      const isDir = e.isDirectory();
+      const childRel = rel ? `${rel}/${name}` : name;
+      if (isDir) {
+        if (GREP_SKIP_DIRS.has(name)) continue;
+        if (rules.length && _gitignored(rules, childRel, name, true)) continue;
+        stack.push({ dir: path.join(dir, name), rel: childRel });
+        continue;
+      }
+      if (!e.isFile()) continue; // symlinks / sockets / etc.
+      if (rules.length && _gitignored(rules, childRel, name, false)) continue;
+      onFile(childRel, name, path.join(dir, name));
+    }
+  }
+  return true;
+}
+
+function _grepNode({ pattern, pathGlob, ignoreCase, baseDir, signal }) {
+  let re;
+  try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); }
+  catch (err) { return { error: `Invalid regex pattern: ${err.message}` }; }
+  const rules = _loadGitignore(baseDir);
+  const pf = pathGlob ? _globToRegExp(pathGlob) : null;
+  const pfBasename = pathGlob && !pathGlob.includes('/');
+  const matches = [];
+  const ok = _walkTree(baseDir, {
+    rules,
+    signal,
+    onFile: (rel, name, abs) => {
+      if (pf && !pf.test(pfBasename ? name : rel)) return;
+      let buf;
+      try { buf = fs.readFileSync(abs); } catch { return; }
+      if (_isBinaryBuf(buf)) return;
+      const data = buf.toString('utf8');
+      const lines = data.split('\n');
+      // A trailing newline terminates the last line; drop the phantom empty
+      // element split() produces so line counting matches ripgrep.
+      if (data.endsWith('\n')) lines.pop();
+      const posix = _toPosix(rel);
+      for (let i = 0; i < lines.length; i++) {
+        if (re.test(lines[i])) matches.push({ file: posix, line: i + 1, text: lines[i] });
+      }
+    },
+  });
+  if (!ok) return { aborted: true };
+  return { matches };
+}
+
+function _grepRg({ pattern, pathGlob, ignoreCase, baseDir, signal }) {
+  if (signal && signal.aborted) return { aborted: true };
+  const bin = _detectRipgrep() || process.env.SEMALT_RG_BIN || 'rg';
+  // These flags make rg honor the baseDir .gitignore without a git repo while
+  // ignoring parent/global/.ignore files, and unconditionally drop node_modules
+  // — exactly the canonical Node semantics above. Hidden entries and binary
+  // files are skipped by rg's defaults.
+  const args = ['--json', '--no-require-git', '--no-ignore-parent', '--no-ignore-global', '--no-ignore-dot', '-g', '!node_modules'];
+  if (ignoreCase) args.push('-i');
+  if (pathGlob) args.push('-g', pathGlob);
+  args.push('--regexp', pattern, '--', '.');
+  const r = spawnSync(bin, args, { cwd: baseDir, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  if (r.error) return { error: r.error.message };
+  if (r.status === 2) return { error: (r.stderr || 'ripgrep error').trim() };
+  // status 0 = matches, 1 = no matches — both are success.
+  const matches = [];
+  if (r.stdout) {
+    for (const ln of r.stdout.split('\n')) {
+      if (!ln) continue;
+      let obj;
+      try { obj = JSON.parse(ln); } catch { continue; }
+      if (obj.type !== 'match') continue;
+      const d = obj.data;
+      if (!d.lines || typeof d.lines.text !== 'string') continue; // non-UTF8 line
+      let file = d.path && d.path.text ? d.path.text : '';
+      if (file.startsWith('./')) file = file.slice(2);
+      let text = d.lines.text;
+      if (text.endsWith('\n')) text = text.slice(0, -1);
+      matches.push({ file: _toPosix(file), line: d.line_number, text });
+    }
+  }
+  return { matches };
+}
+
+function _finalizeGrep(raw, pattern) {
+  if (!raw || raw.error || raw.aborted) return raw || { error: 'grep failed' };
+  const matches = raw.matches.slice().sort((a, b) =>
+    (a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line));
+  let truncated = false;
+  if (matches.length > GREP_MAX_MATCHES) { matches.length = GREP_MAX_MATCHES; truncated = true; }
+  const out = { matches, pattern, count: matches.length };
+  if (truncated) out.truncated = true;
+  return out;
+}
+
+// Resolve the grep `path` argument into a concrete search plan. `path` is no
+// longer a glob-only filter: it may denote an existing FILE (search just that
+// file, like search_in_file), an existing DIRECTORY (use it as the walk root),
+// or — when it is NOT an existing filesystem path — a GLOB filter applied to the
+// cwd walk (the legacy behavior, preserved for callers like `path="*.js"`). A
+// `path` that is a literal that does not exist falls into the glob branch and
+// simply matches zero candidate files; the wrapper's safety net then turns that
+// into a clear diagnostic instead of a silent {count:0}. Relative paths resolve
+// against the process cwd (statSync semantics), matching read_file/search_in_file.
+function _resolveGrepPath(pathArg) {
+  if (pathArg == null || pathArg === '') return { mode: 'none', baseDir: '.', pathGlob: null };
+  let st = null;
+  try { st = fs.statSync(pathArg); } catch { st = null; }
+  if (st && st.isFile()) return { mode: 'file', file: pathArg, display: pathArg };
+  if (st && st.isDirectory()) return { mode: 'dir', baseDir: pathArg, pathGlob: null };
+  return { mode: 'glob', baseDir: '.', pathGlob: pathArg };
+}
+
+// Grep a single explicit file (FILE-target mode). Engine-independent — an
+// explicitly named file is read directly (like search_in_file), which also means
+// it is searched even if .gitignore'd, since the model asked for THIS file. Binary
+// files yield no matches. Returns the same { matches:[{file,line,text}] } shape as
+// _grepNode so it flows through _finalizeGrep identically.
+function _grepFile({ pattern, ignoreCase, file, display, signal }) {
+  let re;
+  try { re = new RegExp(pattern, ignoreCase ? 'i' : ''); }
+  catch (err) { return { error: `Invalid regex pattern: ${err.message}` }; }
+  if (signal && signal.aborted) return { aborted: true };
+  let buf;
+  try { buf = fs.readFileSync(file); } catch (err) { return { error: err.message }; }
+  if (_isBinaryBuf(buf)) return { matches: [] };
+  const data = buf.toString('utf8');
+  const lines = data.split('\n');
+  if (data.endsWith('\n')) lines.pop();
+  const posix = _toPosix(display);
+  const matches = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (re.test(lines[i])) matches.push({ file: posix, line: i + 1, text: lines[i] });
+  }
+  return { matches };
+}
+
+// Does the walk root contain ANY file grep would consider searching (passing the
+// gitignore + skip-dir + pathGlob filters)? Used ONLY by the safety net, and only
+// when a result came back empty — it answers "was there anything to search at
+// all?" so a glob that matched real files (true negative) is never demoted to an
+// error. Deliberately does NOT read file contents (no binary sniff): over-counting
+// errs toward returning {count:0}, the safe direction. Short-circuits on first hit.
+function _grepHasCandidate({ baseDir, pathGlob, signal }) {
+  const rules = _loadGitignore(baseDir);
+  const pf = pathGlob ? _globToRegExp(pathGlob) : null;
+  const pfBasename = pathGlob && !pathGlob.includes('/');
+  let found = false;
+  _walkTree(baseDir, {
+    rules,
+    signal,
+    onFile: (rel, name) => {
+      if (found) return;
+      if (pf && !pf.test(pfBasename ? name : rel)) return;
+      found = true;
+    },
+  });
+  return found;
+}
+
+// engine: 'auto' (rg if available, else Node), 'rg', or 'node'. Exported for
+// the parity tests, which drive both engines and assert deep equality.
+//
+// `path` (when supplied) is the path-aware target: it is resolved via
+// _resolveGrepPath into a FILE read / DIRECTORY walk root / GLOB filter, and feeds
+// BOTH engines identically (FILE mode is a direct read, trivially engine-agnostic).
+// The legacy `pathGlob`/`baseDir` params are still honored directly for callers
+// that pre-resolve (the parity tests). The safety net fires ONLY on the `path`
+// pathway, so existing pathGlob/baseDir callers are byte-for-byte unaffected.
+function _grepSearch({ pattern, path: pathArg = null, pathGlob = null, ignoreCase = false, baseDir = '.', engine = 'auto', signal = null }) {
+  if (typeof pattern !== 'string' || pattern === '') return { error: 'grep: pattern is required' };
+  const pathSupplied = pathArg != null && pathArg !== '';
+  if (pathSupplied) {
+    const plan = _resolveGrepPath(pathArg);
+    if (plan.mode === 'file') {
+      const raw = _grepFile({ pattern, ignoreCase, file: plan.file, display: plan.display, signal });
+      if (raw && (raw.error || raw.aborted)) return raw;
+      return _finalizeGrep(raw, pattern); // an existing file with 0 hits is a true negative, not an error
+    }
+    baseDir = plan.baseDir;
+    pathGlob = plan.pathGlob;
+  }
+  const useRg = engine === 'rg' || (engine === 'auto' && !!_detectRipgrep());
+  let raw;
+  if (useRg) {
+    raw = _grepRg({ pattern, pathGlob, ignoreCase, baseDir, signal });
+    if (raw && raw.error && engine === 'auto') {
+      raw = _grepNode({ pattern, pathGlob, ignoreCase, baseDir, signal });
+    }
+  } else {
+    raw = _grepNode({ pattern, pathGlob, ignoreCase, baseDir, signal });
+  }
+  if (raw && (raw.error || raw.aborted)) return raw;
+  const out = _finalizeGrep(raw, pattern);
+  // Safety net (FIX 2): a `path` was supplied but there was NOTHING to search
+  // (path doesn't exist, or the glob/dir matched zero candidate files). Surface a
+  // diagnostic instead of a silent {count:0} that reads as "pattern absent". Gated
+  // strictly on zero CANDIDATE FILES — a glob that matched real files where the
+  // pattern just isn't present still returns {count:0} (a true negative).
+  if (out && !out.error && out.count === 0 && pathSupplied
+      && !_grepHasCandidate({ baseDir, pathGlob, signal })) {
+    return { error: `grep: path "${pathArg}" did not resolve to any file within the search root ${baseDir}` };
+  }
+  return out;
+}
+
+function _globSearch({ pattern, baseDir = '.', signal = null }) {
+  if (typeof pattern !== 'string' || pattern === '') return { error: 'glob: pattern is required' };
+  const re = _globToRegExp(pattern);
+  const byBasename = !pattern.includes('/');
+  const files = [];
+  let truncated = false;
+  // glob does not apply .gitignore (only node_modules/.git/hidden are skipped).
+  const ok = _walkTree(baseDir, {
+    rules: [],
+    signal,
+    onFile: (rel, name, abs) => {
+      if (truncated) return;
+      if (!re.test(byBasename ? name : rel)) return;
+      let st;
+      try { st = fs.statSync(abs); } catch { return; }
+      files.push({ path: _toPosix(rel), size: st.size, mtime: st.mtime.toISOString() });
+      if (files.length >= GLOB_MAX_FILES) truncated = true;
+    },
+  });
+  if (!ok) return { aborted: true };
+  files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
+  const out = { files, pattern, dir: baseDir, count: files.length };
+  if (truncated) out.truncated = true;
+  return out;
+}
+
+// Shared XML parser for the attribute-or-inline <grep>/<glob> tags.
+function _parseSearchTag(text, tag) {
+  const out = [];
+  const re = new RegExp(`<${tag}\\b([^>]*?)(?:\\/>|>([\\s\\S]*?)<\\/${tag}>)`, 'g');
+  for (const m of text.matchAll(re)) {
+    const attrStr = m[1] || '';
+    const body = m[2] != null ? m[2] : '';
+    const attr = (k) => {
+      const mm = attrStr.match(new RegExp(`${k}="([^"]*)"`)) || attrStr.match(new RegExp(`${k}='([^']*)'`));
+      return mm ? mm[1] : null;
+    };
+    let pattern = attr('pattern');
+    if (pattern == null) { const b = body.trim(); pattern = b || null; }
+    if (pattern == null) continue;
+    if (tag === 'grep') {
+      const ic = attr('ignore_case');
+      out.push(['grep', pattern, attr('path') || null, ic === 'true' || ic === '1' || ic === 'yes',
+        attr('output_mode') || null, attr('head_limit'), attr('offset')]);
+    } else {
+      out.push(['glob', pattern, attr('path') || attr('dir') || '.', attr('head_limit'), attr('offset')]);
+    }
+  }
+  return out;
+}
+
+// ── Native git tools (Task 5.1) ────────────────────────────────────────────
+//
+// First-class git operations: structured results for the common verbs, the long
+// tail left to the (sandboxed) generic shell. Every git tool shells out through
+// ctx.agentExecShell — the SAME sandbox + deny-list chokepoint as <shell> — so it
+// gets NO privileged path around confinement (constraint #5). Read-only tools
+// (status/diff/log, and the list ops of branch/worktree) return a null permission
+// descriptor; mutating tools (add/commit/branch-create/checkout/worktree-add+remove)
+// require approval, honor --readonly via permissionManager.readonlyBlock, and are
+// subject to the per-pattern rules + deny-list. Checkpoints (Task 4.3) snapshot
+// FILE-TOOL mutations only — git operations are NOT reversible via /rewind, and
+// git_checkout can discard uncommitted work that checkpoints never captured.
+
+// Shell-quote one argument so the command string we hand to agentExecShell is
+// safe regardless of metacharacters in branch names / paths / commit messages.
+// Platform-aware: cmd.exe double-quote convention on Windows, POSIX single-quote
+// elsewhere. The deny-list + sandbox remain the security boundary; this only
+// prevents accidental word-splitting of the structured arguments.
+function _shQuote(arg) {
+  const s = String(arg == null ? '' : arg);
+  if (process.platform === 'win32') return '"' + s.replace(/"/g, '""') + '"';
+  return "'" + s.replace(/'/g, "'\\''") + "'";
+}
+
+function _gitCommand(argv) {
+  return 'git ' + argv.map(_shQuote).join(' ');
+}
+
+// Run a git invocation through the shared shell chokepoint and return the raw
+// shell result ({ exit_code, stdout, stderr, blocked, sandbox }).
+function _runGit(ctx, argv, options) {
+  return ctx.agentExecShell(_gitCommand(argv), options || {});
+}
+
+// Map a failed git invocation to a structured { error } — degrading gracefully
+// for the "not a repo" and "git absent" cases rather than surfacing raw noise.
+function _gitFailure(res) {
+  if (res && res.blocked) return { error: (res.stderr || 'git command blocked').trim() };
+  const err = (res && res.stderr ? res.stderr : '').trim();
+  const combined = (err + '\n' + (res && res.stdout ? res.stdout : '')).toLowerCase();
+  if (/not a git repository/.test(combined)) {
+    return { error: 'Not a git repository. Run this inside a git working tree.' };
+  }
+  if ((res && res.exit_code === 127) || /command not found|not recognized as an internal|no such file or directory/.test(combined)) {
+    return { error: 'git is not installed or not found on PATH.' };
+  }
+  return { error: err || (res && res.stdout ? res.stdout.trim() : '') || `git exited with code ${res ? res.exit_code : '?'}` };
+}
+
+function _gitLog(ctx, action, args, status) {
+  try { ctx.logToolCall(action, { args }, status !== 'error', status); } catch { /* audit best-effort */ }
+}
+
+// Parse the `## …` branch header of `git status --porcelain=v1 --branch`.
+function _parseStatusBranch(header) {
+  let h = String(header).replace(/^##\s*/, '');
+  if (h.startsWith('No commits yet on ')) return h.slice('No commits yet on '.length).trim();
+  if (h.startsWith('HEAD ')) return 'HEAD (detached)';
+  const dots = h.indexOf('...');
+  if (dots !== -1) h = h.slice(0, dots);
+  const sp = h.indexOf(' ');
+  if (sp !== -1) h = h.slice(0, sp);
+  return h.trim();
+}
+
+// Parse a unified diff into { files: [{ file, additions, deletions, hunks }] }.
+function _parseDiff(raw) {
+  const files = [];
+  let cur = null;
+  let hunk = null;
+  for (const line of String(raw).split('\n')) {
+    if (line.startsWith('diff --git ')) {
+      cur = { file: null, additions: 0, deletions: 0, hunks: [] };
+      hunk = null;
+      files.push(cur);
+      const m = line.match(/ b\/(.+)$/);
+      if (m) cur.file = m[1];
+      continue;
+    }
+    if (!cur) continue;
+    if (line.startsWith('+++ b/')) { cur.file = line.slice(6); continue; }
+    if (line.startsWith('--- ') || line.startsWith('+++ ')) continue;
+    if (line.startsWith('@@')) {
+      hunk = { header: line, lines: [] };
+      cur.hunks.push(hunk);
+      continue;
+    }
+    if (!hunk) continue;
+    hunk.lines.push(line);
+    if (line.startsWith('+')) cur.additions++;
+    else if (line.startsWith('-')) cur.deletions++;
+  }
+  return files;
+}
+
+// Parse `git worktree list --porcelain` into [{ path, head, branch }].
+function _parseWorktrees(raw) {
+  const out = [];
+  let cur = null;
+  for (const line of String(raw).split('\n')) {
+    if (line.startsWith('worktree ')) {
+      cur = { path: line.slice('worktree '.length), head: null, branch: null };
+      out.push(cur);
+    } else if (cur && line.startsWith('HEAD ')) {
+      cur.head = line.slice('HEAD '.length);
+    } else if (cur && line.startsWith('branch ')) {
+      cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    } else if (cur && line === 'detached') {
+      cur.branch = '(detached)';
+    }
+  }
+  return out;
+}
+
+// XML attribute extractor (dual-quote) + a small typed-attr parser shared by the
+// git tags. `spec` = { str: [...], bool: [...], num: [...], inline: 'key'? }.
+function _gitAttr(attrStr, key) {
+  const m = attrStr.match(new RegExp(`${key}="([^"]*)"`)) || attrStr.match(new RegExp(`${key}='([^']*)'`));
+  return m ? m[1] : null;
+}
+function _gitTruthy(v) { return v === 'true' || v === '1' || v === 'yes' || v === ''; }
+function _parseGitTag(text, tag, spec) {
+  const out = [];
+  const re = new RegExp(`<${tag}\\b([^>]*?)(?:\\/>|>([\\s\\S]*?)<\\/${tag}>)`, 'g');
+  for (const m of text.matchAll(re)) {
+    const attrStr = m[1] || '';
+    const body = m[2] != null ? m[2] : '';
+    const opts = {};
+    for (const k of spec.str || []) { const v = _gitAttr(attrStr, k); if (v != null) opts[k] = v; }
+    for (const k of spec.bool || []) { const v = _gitAttr(attrStr, k); if (v != null) opts[k] = _gitTruthy(v); }
+    for (const k of spec.num || []) {
+      const v = _gitAttr(attrStr, k);
+      if (v != null && v !== '') { const n = parseInt(v, 10); if (!Number.isNaN(n)) opts[k] = n; }
+    }
+    if (spec.inline) { const b = body.trim(); if (b && opts[spec.inline] == null) opts[spec.inline] = b; }
+    out.push([tag, opts]);
+  }
+  return out;
+}
+
+const GIT_TOOL_REGISTRY = [
+  {
+    tool: 'git_status',
+    specNames: ['git_status'],
+    tags: ['git_status'],
+    parseXml: (text) => _parseGitTag(text, 'git_status', {}),
+    fromParams: () => ['git_status', {}],
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const res = await _runGit(ctx, ['status', '--porcelain=v1', '--branch'], options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_status', args, 'error'); return _gitFailure(res); }
+      const staged = [];
+      const unstaged = [];
+      const untracked = [];
+      let branch = null;
+      for (const line of res.stdout.split('\n')) {
+        if (!line) continue;
+        if (line.startsWith('## ')) { branch = _parseStatusBranch(line); continue; }
+        const x = line[0];
+        const y = line[1];
+        const p = line.slice(3);
+        if (line.startsWith('??')) { untracked.push(p); continue; }
+        if (x && x !== ' ' && x !== '?') staged.push({ path: p, status: x });
+        if (y && y !== ' ' && y !== '?') unstaged.push({ path: p, status: y });
+      }
+      const clean = staged.length === 0 && unstaged.length === 0 && untracked.length === 0;
+      const summary = `On branch ${branch || '(unknown)'} — ${clean ? 'clean' : `staged: ${staged.length}, unstaged: ${unstaged.length}, untracked: ${untracked.length}`}`;
+      _gitLog(ctx, 'git_status', args, 'ok');
+      return { status: 'ok', branch, staged, unstaged, untracked, clean, summary };
+    },
+  },
+  {
+    tool: 'git_diff',
+    specNames: ['git_diff'],
+    tags: ['git_diff'],
+    parseXml: (text) => _parseGitTag(text, 'git_diff', { str: ['path'], bool: ['staged'] }),
+    fromParams: (p) => ['git_diff', { ...((p.staged || p.cached) ? { staged: true } : {}), ...(p.path ? { path: String(p.path) } : {}) }],
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const argv = ['diff'];
+      if (o.staged) argv.push('--cached');
+      if (o.path) argv.push('--', String(o.path));
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_diff', args, 'error'); return _gitFailure(res); }
+      const files = _parseDiff(res.stdout);
+      const additions = files.reduce((s, f) => s + f.additions, 0);
+      const deletions = files.reduce((s, f) => s + f.deletions, 0);
+      const summary = files.length
+        ? `${files.length} file(s) changed, +${additions} -${deletions}`
+        : 'No changes';
+      _gitLog(ctx, 'git_diff', args, 'ok');
+      return { status: 'ok', staged: !!o.staged, files, additions, deletions, raw: res.stdout, summary };
+    },
+  },
+  {
+    tool: 'git_log',
+    specNames: ['git_log'],
+    tags: ['git_log'],
+    parseXml: (text) => _parseGitTag(text, 'git_log', { str: ['path'], num: ['count'] }),
+    fromParams: (p) => {
+      const count = Number.isInteger(p.count) ? p.count : (p.count != null && p.count !== '' ? parseInt(p.count, 10) : undefined);
+      return ['git_log', { ...(count ? { count } : {}), ...(p.path ? { path: String(p.path) } : {}) }];
+    },
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const count = Number.isInteger(o.count) && o.count > 0 ? o.count : 20;
+      const SEP = '\x1f';
+      const argv = ['log', '-n', String(count), `--pretty=format:%H${SEP}%an${SEP}%ae${SEP}%ad${SEP}%s`, '--date=iso'];
+      if (o.path) argv.push('--', String(o.path));
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) {
+        const combined = `${res.stderr || ''}\n${res.stdout || ''}`.toLowerCase();
+        // A fresh repo with no commits is a valid empty result, not an error.
+        if (/does not have any commits yet|bad default revision|unknown revision|ambiguous argument 'head'/.test(combined)) {
+          _gitLog(ctx, 'git_log', args, 'ok');
+          return { status: 'ok', commits: [], count: 0, summary: 'No commits yet' };
+        }
+        _gitLog(ctx, 'git_log', args, 'error');
+        return _gitFailure(res);
+      }
+      const commits = [];
+      for (const line of res.stdout.split('\n')) {
+        if (!line) continue;
+        const [hash, author, email, date, ...rest] = line.split(SEP);
+        commits.push({ hash, short: (hash || '').slice(0, 7), author, email, date, subject: rest.join(SEP) });
+      }
+      _gitLog(ctx, 'git_log', args, 'ok');
+      return { status: 'ok', commits, count: commits.length, summary: `${commits.length} commit(s)` };
+    },
+  },
+  {
+    tool: 'git_add',
+    specNames: ['git_add'],
+    tags: ['git_add'],
+    parseXml: (text) => _parseGitTag(text, 'git_add', { str: ['paths'], bool: ['all'] }),
+    fromParams: (p) => ['git_add', { ...(p.paths != null ? { paths: p.paths } : {}), ...(p.all ? { all: true } : {}) }],
+    permission: () => ({ actionType: 'git', description: 'git add (stage changes)', tag: 'git_add' }),
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const blocked = ctx.permissionManager.readonlyBlock('git_add');
+      if (blocked) { _gitLog(ctx, 'git_add', args, 'error'); return blocked; }
+      let paths = [];
+      if (Array.isArray(o.paths)) paths = o.paths.map(String).filter(Boolean);
+      else if (typeof o.paths === 'string' && o.paths.trim()) paths = o.paths.trim().split(/\s+/);
+      if (!o.all && paths.length === 0) {
+        _gitLog(ctx, 'git_add', args, 'error');
+        return { error: 'git_add requires `paths` (one or more files) or `all: true`.' };
+      }
+      const argv = o.all ? ['add', '-A'] : ['add', '--', ...paths];
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_add', args, 'error'); return _gitFailure(res); }
+      const added = o.all ? ['-A (all)'] : paths;
+      _gitLog(ctx, 'git_add', args, 'ok');
+      return { status: 'ok', added, summary: `Staged ${o.all ? 'all changes' : paths.join(', ')}` };
+    },
+  },
+  {
+    tool: 'git_commit',
+    specNames: ['git_commit'],
+    tags: ['git_commit'],
+    parseXml: (text) => _parseGitTag(text, 'git_commit', { str: ['message'], bool: ['all'], inline: 'message' }),
+    fromParams: (p) => ['git_commit', { message: p.message != null ? String(p.message) : '', ...(p.all ? { all: true } : {}) }],
+    permission: () => ({ actionType: 'git', description: 'git commit', tag: 'git_commit' }),
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const blocked = ctx.permissionManager.readonlyBlock('git_commit');
+      if (blocked) { _gitLog(ctx, 'git_commit', args, 'error'); return blocked; }
+      const message = (o.message == null ? '' : String(o.message)).trim();
+      if (!message) {
+        _gitLog(ctx, 'git_commit', args, 'error');
+        return { error: 'git_commit requires a non-empty commit message.' };
+      }
+      const argv = ['commit', '-m', message];
+      if (o.all) argv.push('-a');
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_commit', args, 'error'); return _gitFailure(res); }
+      const hashRes = await _runGit(ctx, ['rev-parse', 'HEAD'], options);
+      const branchRes = await _runGit(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], options);
+      const hash = (hashRes.stdout || '').trim();
+      const branch = (branchRes.stdout || '').trim();
+      _gitLog(ctx, 'git_commit', args, 'ok');
+      return { status: 'ok', hash, short: hash.slice(0, 7), branch, summary: `Committed ${hash.slice(0, 7)} on ${branch}` };
+    },
+  },
+  {
+    tool: 'git_branch',
+    specNames: ['git_branch'],
+    tags: ['git_branch'],
+    parseXml: (text) => _parseGitTag(text, 'git_branch', { str: ['name'], bool: ['delete', 'force'] }),
+    fromParams: (p) => ['git_branch', { ...(p.name ? { name: String(p.name) } : {}), ...((p.delete || p.remove) ? { delete: true } : {}), ...(p.force ? { force: true } : {}) }],
+    // op-dependent: listing branches is read-only (null); create/delete is mutating.
+    permission: (ctx, args) => {
+      const o = args[0] || {};
+      if (!o.name) return null;
+      return { actionType: 'git', description: `git branch ${o.delete ? 'delete' : 'create'} ${o.name}`, tag: 'git_branch' };
+    },
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      if (!o.name) {
+        const res = await _runGit(ctx, ['branch', '--no-color'], options);
+        if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_branch', args, 'error'); return _gitFailure(res); }
+        const branches = [];
+        let current = null;
+        for (const line of res.stdout.split('\n')) {
+          if (!line.trim()) continue;
+          const isCurrent = line.startsWith('*');
+          const name = line.replace(/^\*?\s+/, '').trim();
+          if (!name || name.startsWith('(')) continue; // skip "(HEAD detached …)"
+          if (isCurrent) current = name;
+          branches.push({ name, current: isCurrent });
+        }
+        _gitLog(ctx, 'git_branch', args, 'ok');
+        return { status: 'ok', branches, current, summary: `${branches.length} branch(es), on ${current || '(detached)'}` };
+      }
+      const blocked = ctx.permissionManager.readonlyBlock('git_branch');
+      if (blocked) { _gitLog(ctx, 'git_branch', args, 'error'); return blocked; }
+      const argv = o.delete ? ['branch', o.force ? '-D' : '-d', String(o.name)] : ['branch', String(o.name)];
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_branch', args, 'error'); return _gitFailure(res); }
+      _gitLog(ctx, 'git_branch', args, 'ok');
+      return o.delete
+        ? { status: 'ok', deleted: String(o.name), summary: `Deleted branch ${o.name}` }
+        : { status: 'ok', created: String(o.name), summary: `Created branch ${o.name}` };
+    },
+  },
+  {
+    tool: 'git_checkout',
+    specNames: ['git_checkout'],
+    tags: ['git_checkout'],
+    parseXml: (text) => _parseGitTag(text, 'git_checkout', { str: ['name'], bool: ['create', 'force'] }),
+    fromParams: (p) => ['git_checkout', { name: p.name != null ? String(p.name) : '', ...(p.create ? { create: true } : {}), ...(p.force ? { force: true } : {}) }],
+    permission: (ctx, args) => {
+      const o = args[0] || {};
+      // Destructive-git ↔ checkpoint honesty: a checkout can discard uncommitted
+      // working-tree changes that checkpoints never snapshot (not rewindable).
+      return { actionType: 'git', description: `git checkout ${o.create ? '-b ' : ''}${o.name || ''} (may discard uncommitted changes — NOT recoverable via /rewind)`, tag: 'git_checkout' };
+    },
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const blocked = ctx.permissionManager.readonlyBlock('git_checkout');
+      if (blocked) { _gitLog(ctx, 'git_checkout', args, 'error'); return blocked; }
+      const name = (o.name == null ? '' : String(o.name)).trim();
+      if (!name) { _gitLog(ctx, 'git_checkout', args, 'error'); return { error: 'git_checkout requires a target `name` (branch or ref).' }; }
+      const argv = ['checkout'];
+      if (o.force) argv.push('-f');
+      if (o.create) argv.push('-b');
+      argv.push(name);
+      const res = await _runGit(ctx, argv, options);
+      if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_checkout', args, 'error'); return _gitFailure(res); }
+      const branchRes = await _runGit(ctx, ['rev-parse', '--abbrev-ref', 'HEAD'], options);
+      const branch = (branchRes.stdout || '').trim() || name;
+      _gitLog(ctx, 'git_checkout', args, 'ok');
+      return { status: 'ok', branch, created: !!o.create, summary: `Switched to ${branch}` };
+    },
+  },
+  {
+    tool: 'git_worktree',
+    specNames: ['git_worktree'],
+    tags: ['git_worktree'],
+    parseXml: (text) => _parseGitTag(text, 'git_worktree', { str: ['op', 'path', 'branch'], bool: ['force'] }),
+    fromParams: (p) => ['git_worktree', { op: p.op || 'list', ...(p.path ? { path: String(p.path) } : {}), ...(p.branch ? { branch: String(p.branch) } : {}), ...(p.force ? { force: true } : {}) }],
+    // op-dependent: list is read-only (null); add/remove are mutating.
+    permission: (ctx, args) => {
+      const o = args[0] || {};
+      const op = o.op || 'list';
+      if (op === 'list') return null;
+      return { actionType: 'git', description: `git worktree ${op} ${o.path || ''}`, tag: 'git_worktree' };
+    },
+    execute: async (ctx, args, options) => {
+      const o = args[0] || {};
+      const op = o.op || 'list';
+      if (op === 'list') {
+        const res = await _runGit(ctx, ['worktree', 'list', '--porcelain'], options);
+        if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_worktree', args, 'error'); return _gitFailure(res); }
+        const worktrees = _parseWorktrees(res.stdout);
+        _gitLog(ctx, 'git_worktree', args, 'ok');
+        return { status: 'ok', op: 'list', worktrees, summary: `${worktrees.length} worktree(s)` };
+      }
+      const blocked = ctx.permissionManager.readonlyBlock('git_worktree');
+      if (blocked) { _gitLog(ctx, 'git_worktree', args, 'error'); return blocked; }
+      if (op === 'add') {
+        if (!o.path) { _gitLog(ctx, 'git_worktree', args, 'error'); return { error: 'git_worktree add requires a `path`.' }; }
+        const argv = ['worktree', 'add'];
+        if (o.branch) argv.push('-b', String(o.branch));
+        argv.push(String(o.path));
+        const res = await _runGit(ctx, argv, options);
+        if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_worktree', args, 'error'); return _gitFailure(res); }
+        _gitLog(ctx, 'git_worktree', args, 'ok');
+        return { status: 'ok', op: 'add', path: String(o.path), branch: o.branch ? String(o.branch) : null, summary: `Added worktree at ${o.path}` };
+      }
+      if (op === 'remove') {
+        if (!o.path) { _gitLog(ctx, 'git_worktree', args, 'error'); return { error: 'git_worktree remove requires a `path`.' }; }
+        const argv = ['worktree', 'remove'];
+        if (o.force) argv.push('--force');
+        argv.push(String(o.path));
+        const res = await _runGit(ctx, argv, options);
+        if (res.blocked || res.exit_code !== 0) { _gitLog(ctx, 'git_worktree', args, 'error'); return _gitFailure(res); }
+        _gitLog(ctx, 'git_worktree', args, 'ok');
+        return { status: 'ok', op: 'remove', path: String(o.path), summary: `Removed worktree at ${o.path}` };
+      }
+      _gitLog(ctx, 'git_worktree', args, 'error');
+      return { error: `git_worktree: unknown op "${op}" (expected list | add | remove).` };
+    },
+  },
+];
+
+const TOOL_REGISTRY = [
+  {
+    tool: 'shell',
+    specNames: ['exec', 'shell'],
+    tags: ['exec', 'shell', 'run_command', 'run'],
+    parseXml: (text) => _inline(text, 'shell|exec|run_command|run', 'shell'),
+    fromParams: (p) => (p.command ? ['shell', p.command] : null),
+    // shell is executed through agentExecShell (deny-list chokepoint), not the
+    // agentExecFile dispatch — this execute exists for registry completeness.
+    execute: (ctx, args, options) => ctx.agentExecShell(args[0], options || {}),
+    permission: (ctx, args) => ({ actionType: 'shell', description: args[0] || '', tag: 'exec' }),
+  },
+  {
+    tool: 'read',
+    specNames: ['read_file'],
+    tags: ['read_file'],
+    parseXml: (text) => _parseReadTag(text),
+    fromParams: (p) => (p.path
+      ? ['read', p.path, p.start_line ?? null, p.end_line ?? null, !!p.show_line_numbers]
+      : null),
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, getConfig, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      if (isProtectedSecretPath(filePath)) {
+        logToolCall('read_file', { path: filePath }, false, 'denied');
+        return _secretReadError(filePath);
+      }
+      const startedAt = Date.now();
+      const stat = await fsp.stat(filePath).catch(() => null);
+      if (stat) {
+        const cfg = getConfig ? getConfig() : {};
+        // Byte BACKSTOP only (Task W.7). Pagination (formatReadResult) is now the
+        // primary context bound — a large line-readable file paginates rather than
+        // hard-refusing. This ceiling (default 50 MB) just rules out slurping a
+        // multi-GB file whole into memory; an operator can lower max_file_size_kb
+        // to hard-refuse smaller files.
+        const defKb = require('./constants').DEFAULT_READ_MAX_FILE_KB;
+        const maxKb = cfg.max_file_size_kb || defKb;
+        const maxBytes = maxKb * 1024;
+        if (stat.size > maxBytes) {
+          const kb = (stat.size / 1024).toFixed(0);
+          logToolCall('read_file', { path: filePath }, false, 'error');
+          return { error: `File too large: ${kb} KB exceeds max_file_size_kb=${maxKb}` };
+        }
+      }
+      if (signal && signal.aborted) {
+        logToolCall('read_file', { path: filePath }, true, 'aborted');
+        return { aborted: true, elapsed_s: Math.max(0, Math.round((Date.now() - startedAt) / 1000)) };
+      }
+      try {
+        const data = await fsp.readFile(filePath, { encoding: 'utf8', signal: signal || undefined });
+        const lines = data.split('\n').length;
+        if (lines > 10) {
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Read ${filePath} (${lines} lines, ${data.length} chars)${RST}`);
+        } else {
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Read ${filePath}${RST}`);
+        }
+        logToolCall('read_file', { path: filePath }, true, 'ok');
+        return { content: data, path: filePath, bytes: Buffer.byteLength(data, 'utf8') };
+      } catch (error) {
+        if (error && (error.name === 'AbortError' || error.code === 'ABORT_ERR')) {
+          logToolCall('read_file', { path: filePath }, true, 'aborted');
+          return { aborted: true, elapsed_s: Math.max(0, Math.round((Date.now() - startedAt) / 1000)) };
+        }
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('read_file', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'view_image',
+    specNames: ['view_image'],
+    tags: ['view_image'],
+    // Both XML forms accepted: the attribute form `<view_image path="…"/>` and
+    // the inline form `<view_image>PATH</view_image>` (like read_file/download).
+    parseXml: (text) => {
+      const out = [];
+      for (const m of _matchDual(text, '<view_image\\s+path=Q([^Q]+)Q\\s*(?:><\\/view_image>|\\/>)')) {
+        out.push(['view_image', m[1]]);
+      }
+      for (const m of text.matchAll(/<view_image>([\s\S]*?)<\/view_image>/g)) {
+        out.push(['view_image', _unwrapInnerTag(m[1]).trim()]);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.path ? ['view_image', String(p.path)] : null),
+    // Read-only: a local file read, so no permission gate (parity with read_file /
+    // grep, permission: () => null). Path safety + the size cap are enforced by
+    // readImage (via isPathSafe) inside execute, exactly as the /image command does.
+    permission: () => null,
+    // Stage a LOCAL image into vision context. Reuses readImage — the SAME encoder
+    // the /image slash command uses (read through isPathSafe, size-capped, magic-byte
+    // media-type detect, base64). The returned `image` record is collected by the
+    // agent loop and attached to the tool-result message's `images[]`, so api.js
+    // buildProviderMessages turns it into a provider image block on the next turn.
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isPathSafe, getConfig, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      try {
+        const { readImage } = require('./images');
+        const cfg = getConfig ? getConfig() : {};
+        const img = readImage(filePath, { maxBytes: cfg.image_max_bytes, isPathSafe });
+        const kb = Math.max(1, Math.round(img.bytes / 1024));
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Viewing image ${filePath} (${img.media_type}, ${kb} KB)${RST}`);
+        logToolCall('view_image', { path: filePath }, true, 'ok');
+        // `image` carries the base64 bytes for staging; it never enters the
+        // model-facing text (formatFileResult builds a short confirmation line).
+        return { status: 'ok', path: filePath, media_type: img.media_type, bytes: img.bytes, image: img };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('view_image', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'write',
+    specNames: ['write_file', 'create_file'],
+    tags: ['write_file', 'create_file'],
+    parseXml: (text) => {
+      const out = [];
+      // QUIRK: attribute-form content (m[2]) is captured RAW — not trimmed —
+      // unlike inline-tag bodies which go through _unwrapInnerTag().trim().
+      // Preserved deliberately; pinned by test/extract-tool-calls.test.js
+      // ("QUIRK: attribute-form content is NOT trimmed (unlike inline tags)").
+      // Any change to this is out of scope for the tool-registry refactor.
+      for (const m of _matchDual(text, '<write_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/write_file>')) out.push(['write', m[1], m[2]]);
+      for (const m of _matchDual(text, '<create_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/create_file>')) out.push(['write', m[1], m[2]]);
+      return out;
+    },
+    fromParams: (p) => (p.path ? ['write', p.path, p.content != null ? p.content : ''] : null),
+    permission: (ctx, args) => _permWriteAppend(ctx, 'write', args),
+    execute: (ctx, args, options) => _execWriteAppend(ctx, 'write', args, options),
+  },
+  {
+    tool: 'append',
+    specNames: ['append_file'],
+    tags: ['append_file'],
+    // QUIRK: as with write_file, append content is captured raw (not trimmed).
+    parseXml: (text) => _matchDual(text, '<append_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/append_file>').map((m) => ['append', m[1], m[2]]),
+    fromParams: (p) => (p.path ? ['append', p.path, p.content != null ? p.content : ''] : null),
+    permission: (ctx, args) => _permWriteAppend(ctx, 'append', args),
+    execute: (ctx, args, options) => _execWriteAppend(ctx, 'append', args, options),
+  },
+  {
+    tool: 'list_dir',
+    specNames: ['list_dir'],
+    tags: ['list_dir'],
+    parseXml: (text) => _inline(text, 'list_dir', 'list_dir'),
+    fromParams: (p) => ['list_dir', p.path || '.'],
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const dirPath = arg0;
+      try {
+        const entries = await fsp.readdir(dirPath, { withFileTypes: true });
+        const items = entries.map((e) => {
+          if (e.isSymbolicLink()) return `[L] ${e.name}`;
+          if (e.isDirectory()) return `[D] ${e.name}`;
+          return `[F] ${e.name}`;
+        });
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Listed ${dirPath} (${items.length} items)${RST}`);
+        logToolCall('list_dir', { path: dirPath }, true, 'ok');
+        return { items, path: dirPath };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('list_dir', { path: dirPath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'search_files',
+    specNames: ['search_files'],
+    tags: ['search_files'],
+    parseXml: (text) => {
+      const out = _inline(text, 'search_files', 'search_files', ['.']);
+      for (const m of _matchDual(text, '<search_files\\s+pattern=Q([^Q]+)Q(?:\\s+dir=Q([^Q]*)Q)?\\s*(?:><\\/search_files>|\\/>)')) {
+        out.push(['search_files', m[1], m[2] || '.']);
+      }
+      return out;
+    },
+    fromParams: (p) => ['search_files', p.pattern || '*', p.dir || '.'],
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const pattern = arg0;
+      const searchDir = arg1 || '.';
+      const startedAt = Date.now();
+      try {
+        let regStr = pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+        regStr = regStr.replace(/\*\*/g, '\x00');
+        regStr = regStr.replace(/\*/g, '[^/]*');
+        regStr = regStr.replace(/\x00\//g, '(?:.*/)?');
+        regStr = regStr.replace(/\x00/g, '.*');
+        const regex = new RegExp(`^${regStr}$`);
+        const matchName = !pattern.includes('/');
+        const files = [];
+        async function walk(dir, rel) {
+          if (signal && signal.aborted) return;
+          let entries;
+          try { entries = await fsp.readdir(dir, { withFileTypes: true }); } catch { return; }
+          for (const entry of entries) {
+            if (signal && signal.aborted) return;
+            const relPath = rel ? `${rel}/${entry.name}` : entry.name;
+            if (regex.test(matchName ? entry.name : relPath)) files.push(relPath);
+            if (entry.isDirectory()) await walk(path.join(dir, entry.name), relPath);
+          }
+        }
+        await walk(searchDir, '');
+        if (signal && signal.aborted) {
+          logToolCall('search_files', { pattern, dir: searchDir }, true, 'aborted');
+          return { aborted: true, elapsed_s: Math.max(0, Math.round((Date.now() - startedAt) / 1000)) };
+        }
+        files.sort();
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Found ${files.length} file(s) matching "${pattern}"${RST}`);
+        logToolCall('search_files', { pattern, dir: searchDir }, true, 'ok');
+        return { files, pattern, dir: searchDir };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('search_files', { pattern, dir: searchDir }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'grep',
+    specNames: ['grep'],
+    tags: ['grep'],
+    parseXml: (text) => _parseSearchTag(text, 'grep'),
+    fromParams: (p) => (p.pattern
+      ? ['grep', p.pattern, p.path || null, !!p.ignore_case, p.output_mode || null, p.head_limit ?? null, p.offset ?? null]
+      : null),
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [pattern = null, pathArg = null, ignoreCase = false, outputMode = null, headLimit, offset] = args;
+      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      // Path-as-target now reads files directly, so apply the SAME secret-file read
+      // guard read_file/search_in_file use (the OS sandbox remains the outer
+      // confinement; this just refuses the credential/history files by name).
+      if (pathArg != null && pathArg !== '' && isProtectedSecretPath(pathArg)) {
+        logToolCall('grep', { pattern, path: pathArg }, false, 'denied');
+        return _secretReadError(pathArg);
+      }
+      const res = _grepSearch({ pattern, path: pathArg, ignoreCase, engine: 'auto', signal });
+      if (res.aborted) { logToolCall('grep', { pattern }, true, 'aborted'); return res; }
+      if (res.error) {
+        _log(`  ${FG_RED}✗ ${res.error}${RST}`);
+        logToolCall('grep', { pattern }, true, 'error');
+        return res;
+      }
+      // Shape the serialization controls onto the result (Task W.5). The engine
+      // returns the full (engine-capped) match set; output_mode + head_limit +
+      // offset bound what reaches the model in formatFileResult (lib/agent.js).
+      res.output_mode = _normGrepMode(outputMode);
+      res.head_limit = _normHeadLimit(headLimit, require('./constants').DEFAULT_GREP_HEAD_LIMIT);
+      res.offset = _normOffset(offset);
+      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}grep "${pattern}" — ${res.count} match(es)${RST}`);
+      logToolCall('grep', { pattern, path: pathArg }, true, 'ok');
+      return res;
+    },
+  },
+  {
+    tool: 'glob',
+    specNames: ['glob'],
+    tags: ['glob'],
+    parseXml: (text) => _parseSearchTag(text, 'glob'),
+    fromParams: (p) => (p.pattern ? ['glob', p.pattern, p.path || p.dir || '.', p.head_limit ?? null, p.offset ?? null] : null),
+    permission: () => null,
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [pattern = null, base = '.', headLimit, offset] = args;
+      const { _log, logToolCall, isPathSafe, _sandboxError, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      if (!isPathSafe(base)) {
+        logToolCall('glob', { pattern, dir: base }, false, 'denied');
+        return _sandboxError(base);
+      }
+      const res = _globSearch({ pattern, baseDir: base, signal });
+      if (res.aborted) { logToolCall('glob', { pattern }, true, 'aborted'); return res; }
+      if (res.error) {
+        _log(`  ${FG_RED}✗ ${res.error}${RST}`);
+        logToolCall('glob', { pattern }, true, 'error');
+        return res;
+      }
+      // head_limit + offset bound the file list that reaches the model (Task W.5);
+      // the engine returns the full (engine-capped) list, serialized in formatFileResult.
+      res.head_limit = _normHeadLimit(headLimit, require('./constants').DEFAULT_GLOB_HEAD_LIMIT);
+      res.offset = _normOffset(offset);
+      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}glob "${pattern}" — ${res.count} file(s)${RST}`);
+      logToolCall('glob', { pattern, dir: base }, true, 'ok');
+      return res;
+    },
+  },
+  {
+    tool: 'delete_file',
+    specNames: ['delete_file'],
+    tags: ['delete_file'],
+    parseXml: (text) => _inline(text, 'delete_file', 'delete_file'),
+    fromParams: (p) => (p.path ? ['delete_file', p.path] : null),
+    permission: (ctx, args) => {
+      const { _log, FG_YELLOW, BOLD, RST } = ctx;
+      const filePath = args[0];
+      _log(`  ${FG_YELLOW}${BOLD}⚠ Deleting: ${filePath}${RST}`);
+      return { actionType: 'file', description: `Delete ${filePath}`, tag: 'delete_file' };
+    },
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isPathSafe, _sandboxError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      const blocked = permissionManager.readonlyBlock('delete_file');
+      if (blocked) {
+        logToolCall('delete_file', { path: filePath }, false, 'denied');
+        return blocked;
+      }
+      if (!isPathSafe(filePath)) {
+        logToolCall('delete_file', { path: filePath }, false, 'denied');
+        return _sandboxError(filePath);
+      }
+      try {
+        await fsp.unlink(filePath);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Deleted ${filePath}${RST}`);
+        logToolCall('delete_file', { path: filePath }, true, 'ok');
+        return { status: 'ok', path: filePath };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('delete_file', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'make_dir',
+    specNames: ['make_dir'],
+    tags: ['make_dir'],
+    parseXml: (text) => _inline(text, 'make_dir', 'make_dir'),
+    fromParams: (p) => (p.path ? ['make_dir', p.path] : null),
+    permission: (ctx, args) => ({ actionType: 'file', description: `Create directory ${args[0]}`, tag: 'make_dir' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isPathSafe, _sandboxError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const dirPath = arg0;
+      const blocked = permissionManager.readonlyBlock('make_dir');
+      if (blocked) {
+        logToolCall('make_dir', { path: dirPath }, false, 'denied');
+        return blocked;
+      }
+      if (!isPathSafe(dirPath)) {
+        logToolCall('make_dir', { path: dirPath }, false, 'denied');
+        return _sandboxError(dirPath);
+      }
+      try {
+        await fsp.mkdir(dirPath, { recursive: true });
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Created directory ${dirPath}${RST}`);
+        logToolCall('make_dir', { path: dirPath }, true, 'ok');
+        return { status: 'ok', path: dirPath };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('make_dir', { path: dirPath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'remove_dir',
+    specNames: ['remove_dir'],
+    tags: ['remove_dir'],
+    parseXml: (text) => _inline(text, 'remove_dir', 'remove_dir'),
+    fromParams: (p) => (p.path ? ['remove_dir', p.path] : null),
+    permission: (ctx, args) => ({ actionType: 'file', description: `Remove directory ${args[0]}`, tag: 'remove_dir' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, isPathSafe, _sandboxError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const dirPath = arg0;
+      const blocked = permissionManager.readonlyBlock('remove_dir');
+      if (blocked) {
+        logToolCall('remove_dir', { path: dirPath }, false, 'denied');
+        return blocked;
+      }
+      if (!isPathSafe(dirPath)) {
+        logToolCall('remove_dir', { path: dirPath }, false, 'denied');
+        return _sandboxError(dirPath);
+      }
+      try {
+        await fsp.rm(dirPath, { recursive: true, force: true });
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Removed directory ${dirPath}${RST}`);
+        logToolCall('remove_dir', { path: dirPath }, true, 'ok');
+        return { status: 'ok', path: dirPath };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('remove_dir', { path: dirPath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'move_file',
+    specNames: ['move_file'],
+    tags: ['move_file'],
+    parseXml: (text) => _matchDual(text, '<move_file\\s+src=Q([^Q]+)Q\\s+dst=Q([^Q]+)Q\\s*(?:><\\/move_file>|\\/>)').map((m) => ['move_file', m[1], m[2]]),
+    fromParams: (p) => (p.src && p.dst ? ['move_file', p.src, p.dst] : null),
+    permission: (ctx, args) => {
+      const { _log, FG_YELLOW, BOLD, RST } = ctx;
+      const src = args[0];
+      const dst = args[1];
+      _log(`  ${FG_YELLOW}${BOLD}⚠ Moving: ${src} → ${dst}${RST}`);
+      return { actionType: 'file', description: `Move ${src} to ${dst}`, tag: 'move_file' };
+    },
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, isPathSafe, isProtectedSecretPath, isProtectedConfigPath, _sandboxError, _secretReadError, _protectedConfigWriteError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const src = arg0;
+      const dst = arg1;
+      const blocked = permissionManager.readonlyBlock('move_file');
+      if (blocked) {
+        logToolCall('move_file', { src, dst }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedSecretPath(src)) {
+        logToolCall('move_file', { src, dst }, false, 'denied');
+        return _secretReadError(src);
+      }
+      if (isProtectedConfigPath(dst)) {
+        logToolCall('move_file', { src, dst }, false, 'denied');
+        return _protectedConfigWriteError(dst);
+      }
+      if (!isPathSafe(dst)) {
+        logToolCall('move_file', { src, dst }, false, 'denied');
+        return _sandboxError(dst);
+      }
+      try {
+        const dstDir = path.dirname(dst);
+        if (dstDir && dstDir !== '.') await fsp.mkdir(dstDir, { recursive: true });
+        try {
+          await fsp.rename(src, dst);
+        } catch (renameErr) {
+          if (renameErr.code !== 'EXDEV') throw renameErr;
+          await fsp.cp(src, dst, { recursive: true });
+          await fsp.rm(src, { recursive: true, force: true });
+        }
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Moved ${src} → ${dst}${RST}`);
+        logToolCall('move_file', { src, dst }, true, 'ok');
+        return { status: 'ok', src, dst };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('move_file', { src, dst }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'copy_file',
+    specNames: ['copy_file'],
+    tags: ['copy_file'],
+    parseXml: (text) => _matchDual(text, '<copy_file\\s+src=Q([^Q]+)Q\\s+dst=Q([^Q]+)Q\\s*(?:><\\/copy_file>|\\/>)').map((m) => ['copy_file', m[1], m[2]]),
+    fromParams: (p) => (p.src && p.dst ? ['copy_file', p.src, p.dst] : null),
+    permission: (ctx, args) => ({ actionType: 'file', description: `Copy ${args[0]} to ${args[1]}`, tag: 'copy_file' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, isPathSafe, isProtectedSecretPath, isProtectedConfigPath, _sandboxError, _secretReadError, _protectedConfigWriteError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const src = arg0;
+      const dst = arg1;
+      const blocked = permissionManager.readonlyBlock('copy_file');
+      if (blocked) {
+        logToolCall('copy_file', { src, dst }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedSecretPath(src)) {
+        logToolCall('copy_file', { src, dst }, false, 'denied');
+        return _secretReadError(src);
+      }
+      if (isProtectedConfigPath(dst)) {
+        logToolCall('copy_file', { src, dst }, false, 'denied');
+        return _protectedConfigWriteError(dst);
+      }
+      if (!isPathSafe(dst)) {
+        logToolCall('copy_file', { src, dst }, false, 'denied');
+        return _sandboxError(dst);
+      }
+      try {
+        const dstDir = path.dirname(dst);
+        if (dstDir && dstDir !== '.') await fsp.mkdir(dstDir, { recursive: true });
+        await fsp.cp(src, dst, { recursive: true });
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Copied ${src} → ${dst}${RST}`);
+        logToolCall('copy_file', { src, dst }, true, 'ok');
+        return { status: 'ok', src, dst };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('copy_file', { src, dst }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'edit_file',
+    specNames: ['edit_file'],
+    tags: ['edit_file'],
+    // Optional `end_line` (W.5 trailing-arg discipline: absent → the 4-element
+    // single-line tuple, byte-for-byte the prior behavior). When present, lines
+    // `line..end_line` are replaced wholesale by the content — a regex-free way
+    // to swap a block, pairing with read_file's start_line/end_line + line
+    // numbers (read a numbered slice, then replace that exact range).
+    parseXml: (text) => _matchDual(text, '<edit_file\\s+path=Q([^Q]+)Q\\s+line=Q(\\d+)Q(?:\\s+end_line=Q(\\d+)Q)?>([\\s\\S]*?)<\\/edit_file>').map((m) => {
+      const call = ['edit_file', m[1], parseInt(m[2], 10), m[4]];
+      if (m[3] != null) call.push(parseInt(m[3], 10));
+      return call;
+    }),
+    fromParams: (p) => {
+      if (!(p.path && p.line !== undefined)) return null;
+      const call = ['edit_file', p.path, parseInt(p.line, 10), p.content != null ? p.content : ''];
+      if (p.end_line != null) call.push(parseInt(p.end_line, 10));
+      return call;
+    },
+    permission: (ctx, args) => ({ actionType: 'file', description: args[4] != null ? `Edit lines ${args[1]}-${args[4]} in ${args[0]}` : `Edit line ${args[1]} in ${args[0]}`, tag: 'edit_file' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null, arg2 = null, arg3] = args;
+      const { _log, logToolCall, isProtectedConfigPath, _protectedConfigWriteError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      const lineNum = arg1;
+      const newContent = arg2;
+      const endLine = arg3; // undefined → single-line edit (unchanged)
+      const blocked = permissionManager.readonlyBlock('edit_file');
+      if (blocked) {
+        logToolCall('edit_file', { path: filePath, line: lineNum }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedConfigPath(filePath)) {
+        logToolCall('edit_file', { path: filePath, line: lineNum }, false, 'denied');
+        return _protectedConfigWriteError(filePath);
+      }
+      try {
+        const data = await fsp.readFile(filePath, 'utf8');
+        const lines = data.split('\n');
+        if (lineNum < 1 || lineNum > lines.length) {
+          logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
+          return { error: `Line ${lineNum} out of range (file has ${lines.length} lines)` };
+        }
+        if (endLine == null) {
+          // Single-line replace — exactly the prior behavior (no regression).
+          lines[lineNum - 1] = newContent;
+          const after = lines.join('\n');
+          await fsp.writeFile(filePath, after);
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited line ${lineNum} in ${filePath}${RST}`);
+          logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'ok');
+          // _diffBefore/_diffAfter feed the execution-time diff renderer (onToolEnd).
+          return { status: 'ok', path: filePath, line: lineNum, _diffBefore: data, _diffAfter: after };
+        }
+        // Line-range replace: swap lines lineNum..endLine for newContent (which
+        // may itself be multi-line). No regex involved → no ReDoS surface.
+        if (endLine < lineNum || endLine > lines.length) {
+          logToolCall('edit_file', { path: filePath, line: lineNum, end_line: endLine }, true, 'error');
+          return { error: `Line range ${lineNum}-${endLine} out of range (file has ${lines.length} lines)` };
+        }
+        lines.splice(lineNum - 1, endLine - lineNum + 1, ...newContent.split('\n'));
+        const afterRange = lines.join('\n');
+        await fsp.writeFile(filePath, afterRange);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Edited lines ${lineNum}-${endLine} in ${filePath}${RST}`);
+        logToolCall('edit_file', { path: filePath, line: lineNum, end_line: endLine }, true, 'ok');
+        return { status: 'ok', path: filePath, line: lineNum, end_line: endLine, _diffBefore: data, _diffAfter: afterRange };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('edit_file', { path: filePath, line: lineNum }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'search_in_file',
+    specNames: ['search_in_file'],
+    tags: ['search_in_file'],
+    parseXml: (text) => _matchDual(text, '<search_in_file\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/search_in_file>').map((m) => ['search_in_file', m[1], m[2].trim()]),
+    fromParams: (p) => (p.path && p.pattern ? ['search_in_file', p.path, p.pattern] : null),
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, isProtectedSecretPath, _secretReadError, _checkRegexSafety, _isLiteralPattern, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      const pattern = arg1;
+      if (isProtectedSecretPath(filePath)) {
+        logToolCall('search_in_file', { path: filePath, pattern }, false, 'denied');
+        return _secretReadError(filePath);
+      }
+      try {
+        const data = await fsp.readFile(filePath, 'utf8');
+        const guardErr = _checkRegexSafety(pattern, data);
+        if (guardErr) {
+          logToolCall('search_in_file', { path: filePath, pattern }, true, 'error');
+          return guardErr;
+        }
+        // A metacharacter-free pattern is matched literally (substring) — same
+        // line results as a regex for plain text, but unbounded by length so a
+        // long pasted block can be located. Genuine regexes still compile.
+        const isLiteral = _isLiteralPattern(pattern);
+        const test = isLiteral ? (content) => content.includes(pattern) : ((regex) => (content) => regex.test(content))(new RegExp(pattern));
+        const matches = data.split('\n')
+          .map((content, idx) => test(content) ? { line: idx + 1, content } : null)
+          .filter(Boolean);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Found ${matches.length} match(es) in ${filePath}${RST}`);
+        logToolCall('search_in_file', { path: filePath, pattern }, true, 'ok');
+        return { matches, path: filePath };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('search_in_file', { path: filePath, pattern }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'replace_in_file',
+    specNames: ['replace_in_file'],
+    tags: ['replace_in_file'],
+    // LITERAL by default (Claude Code Edit model): the search text is matched
+    // VERBATIM, byte-for-byte, no matter what regex-special chars it contains —
+    // so a copied code block with ( ) { } . [ ] just works. Regex is opt-in via
+    // `regex="true"`. Matching must be UNIQUE: 0 matches → error (no-op masked as
+    // success was the silent-corruption trap), >1 matches → error unless
+    // `replace_all="true"`. Inline body = regex flags (only meaningful with
+    // regex="true"). Attr-based parse (like read_file) so the optional flags
+    // appear in any order.
+    parseXml: (text) => {
+      const out = [];
+      const re = /<replace_in_file\b([^>]*?)>([\s\S]*?)<\/replace_in_file>/g;
+      for (const m of text.matchAll(re)) {
+        const attrStr = m[1] || '';
+        const body = m[2] != null ? m[2] : '';
+        const attr = (k) => {
+          const mm = attrStr.match(new RegExp(`${k}="([^"]*)"`)) || attrStr.match(new RegExp(`${k}='([^']*)'`));
+          return mm ? mm[1] : null;
+        };
+        const p = attr('path');
+        const search = attr('search');
+        if (p == null || search == null) continue;
+        const replace = attr('replace') != null ? attr('replace') : '';
+        out.push(['replace_in_file', p, search, replace, body.trim(), attr('regex') === 'true', attr('replace_all') === 'true']);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.path && p.search !== undefined ? ['replace_in_file', p.path, p.search, p.replace != null ? p.replace : '', p.flags || '', p.regex === true || p.regex === 'true', p.replace_all === true || p.replace_all === 'true'] : null),
+    permission: (ctx, args) => ({ actionType: 'file', description: `Replace in ${args[0]}`, tag: 'replace_in_file' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null, arg2 = null, arg3 = null, arg4 = false, arg5 = false] = args;
+      const { _log, logToolCall, isProtectedConfigPath, _protectedConfigWriteError, _checkRegexSafety, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      const searchStr = arg1;
+      const replaceStr = arg2;
+      const flags = arg3 || '';
+      const useRegex = arg4 === true;
+      const replaceAll = arg5 === true;
+      const blocked = permissionManager.readonlyBlock('replace_in_file');
+      if (blocked) {
+        logToolCall('replace_in_file', { path: filePath, search: searchStr }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedConfigPath(filePath)) {
+        logToolCall('replace_in_file', { path: filePath, search: searchStr }, false, 'denied');
+        return _protectedConfigWriteError(filePath);
+      }
+      try {
+        const data = await fsp.readFile(filePath, 'utf8');
+        if (searchStr == null || searchStr === '') {
+          logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+          return { error: 'replace_in_file: search string is empty — nothing to match.' };
+        }
+        let newData;
+        let count;
+        let remaining; // post-replace occurrences of the search string in newData
+        if (!useRegex) {
+          // LITERAL path (default): O(dataLen) substring match — no regex
+          // compiled, so a long block is matched verbatim with no ReDoS surface
+          // and no length bound. The replacement is raw text (no $1/$& handling).
+          const parts = data.split(searchStr);
+          count = parts.length - 1;
+          // ---- Uniqueness / occurrence guard (BEFORE writing) ----
+          if (count === 0) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: search string not found in ${filePath} — file unchanged. Verify exact text including whitespace/indentation.` };
+          }
+          if (count > 1 && !replaceAll) {
+            const lines = _literalOccurrenceLines(data, searchStr);
+            const at = lines.length ? ` (matches start at line${lines.length > 1 ? 's' : ''} ${lines.join(', ')}${count > lines.length ? ', …' : ''})` : '';
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: found ${count} matches but replace_all is not set${at}. Add surrounding context to uniquely identify ONE occurrence, or set replace_all:true to replace all ${count}.` };
+          }
+          if (replaceAll) {
+            newData = parts.join(replaceStr);
+          } else {
+            // count === 1: replace the single occurrence.
+            const idx = data.indexOf(searchStr);
+            newData = data.slice(0, idx) + replaceStr + data.slice(idx + searchStr.length);
+            count = 1;
+          }
+          remaining = newData.split(searchStr).length - 1;
+        } else {
+          // REGEX path (opt-in via regex:true): ReDoS guard applies. `g` flag OR
+          // replace_all replaces all; otherwise the match must be unique.
+          const guardErr = _checkRegexSafety(searchStr, data, false);
+          if (guardErr) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return guardErr;
+          }
+          const safeFlags = flags.replace(/[^gimsuy]/g, '');
+          const globalFlags = safeFlags.replace('g', '') + 'g';
+          const isGlobal = safeFlags.includes('g') || replaceAll;
+          count = (data.match(new RegExp(searchStr, globalFlags)) || []).length;
+          // ---- Uniqueness / occurrence guard (BEFORE writing) ----
+          if (count === 0) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: pattern not found in ${filePath} — file unchanged. Verify the regex (or drop regex:true to match literally).` };
+          }
+          if (count > 1 && !isGlobal) {
+            logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+            return { error: `replace_in_file: pattern matched ${count} times but neither the "g" flag nor replace_all is set. Refine the pattern to match ONE occurrence, or set replace_all:true to replace all ${count}.` };
+          }
+          const regex = new RegExp(searchStr, (isGlobal ? globalFlags : safeFlags.replace('g', '')) || undefined);
+          newData = data.replace(regex, replaceStr);
+          count = isGlobal ? count : 1;
+          remaining = (newData.match(new RegExp(searchStr, globalFlags)) || []).length;
+        }
+        await fsp.writeFile(filePath, newData);
+        const result = { status: 'ok', path: filePath, count, _diffBefore: data, _diffAfter: newData };
+        // POST-REPLACE VERIFICATION: if the search string still appears (e.g. the
+        // replacement contains it, or matches overlapped), surface a warning
+        // instead of reporting clean success.
+        if (remaining > 0) {
+          result.warning = `replace_in_file: replaced ${count} occurrence(s), but the search string still appears ${remaining} time(s) in ${filePath} (the replacement may contain the search text, or matches overlapped).`;
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath} (${remaining} still present)${RST}`);
+        } else {
+          _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Replaced ${count} occurrence(s) in ${filePath}${RST}`);
+        }
+        logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'ok');
+        // _diffBefore/_diffAfter feed the execution-time diff renderer (onToolEnd).
+        return result;
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('replace_in_file', { path: filePath, search: searchStr }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'download',
+    specNames: ['download'],
+    tags: ['download'],
+    // Optional `path` destination (Pre-Task 4.0b). Both the attribute form
+    // (`<download path="dest">URL</download>`) and the plain form
+    // (`<download>URL</download>`, defaulting to the CWD) are accepted.
+    parseXml: (text) => {
+      const out = [];
+      for (const m of _matchDual(text, '<download\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/download>')) {
+        out.push(['download', _unwrapInnerTag(m[2]).trim(), m[1]]);
+      }
+      for (const m of text.matchAll(/<download>([\s\S]*?)<\/download>/g)) {
+        out.push(['download', _unwrapInnerTag(m[1]).trim()]);
+      }
+      return out;
+    },
+    fromParams: (p) => {
+      if (!p.url) return null;
+      const dest = p.path || p.dest;
+      return dest ? ['download', p.url, dest] : ['download', p.url];
+    },
+    permission: (ctx, args) => ({ actionType: 'net', description: `Download ${args[0]}`, tag: 'download' }),
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [arg0 = null, arg1 = null] = args;
+      const {
+        _log, logToolCall, _dryRun, _skippedOps,
+        isPathSafe, _sandboxError, isProtectedSecretPath, _secretReadError,
+        isProtectedConfigPath, _protectedConfigWriteError,
+        permissionManager, getConfig,
+        FG_GREEN, FG_GRAY, FG_RED, RST,
+      } = ctx;
+      const url = arg0;
+      const dest = arg1 || null;
+      if (_dryRun) {
+        _skippedOps.push({ category: 'net', symbol: '↓', desc: `download ${url}` });
+        logToolCall('download', { url }, false, 'dry-run');
+        return { status: 'dry-run', message: 'dry-run: network call skipped' };
+      }
+      // Validate/normalize the URL BEFORE building the request or resolving a
+      // destination — a malformed URL (or non-http(s) scheme, empty, non-string)
+      // is a clean tool error, never an uncaught throw out of the executor.
+      const validatedDlUrl = _validateFetchUrl(url);
+      if (validatedDlUrl.error) {
+        _log(`  ${FG_RED}✗ ${validatedDlUrl.error}${RST}`);
+        logToolCall('download', { url }, true, 'error');
+        return validatedDlUrl;
+      }
+      const normalizedDlUrl = validatedDlUrl.url;
+      // Resolve the destination: an explicit path (relative → CWD, or absolute),
+      // otherwise the URL basename into the CWD (historical default).
+      let outPath;
+      if (dest) {
+        outPath = path.resolve(dest);
+      } else {
+        let fileName;
+        try {
+          fileName = path.basename(new URL(normalizedDlUrl).pathname) || 'download';
+        } catch {
+          fileName = 'download';
+        }
+        outPath = path.join(process.cwd(), fileName);
+      }
+      // Confinement (Pre-Task 4.0b): download is a write path and must honor the
+      // same guards as every other mutating file tool — --readonly, the
+      // secret-file guard, and isPathSafe (CWD confinement / --allow-anywhere).
+      const blocked = permissionManager.readonlyBlock('download');
+      if (blocked) {
+        logToolCall('download', { url, path: outPath }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedSecretPath(outPath)) {
+        logToolCall('download', { url, path: outPath }, false, 'denied');
+        return _secretReadError(outPath);
+      }
+      if (isProtectedConfigPath(outPath)) {
+        logToolCall('download', { url, path: outPath }, false, 'denied');
+        return _protectedConfigWriteError(outPath);
+      }
+      if (!isPathSafe(outPath)) {
+        logToolCall('download', { url, path: outPath }, false, 'denied');
+        return _sandboxError(outPath);
+      }
+      const cfg = getConfig ? getConfig() : {};
+      const maxBytes = Math.max(1024, cfg.download_max_bytes || 104857600);
+      const userAgent = _resolveUserAgent(cfg);
+      const startedAt = Date.now();
+      return new Promise((resolve) => {
+        let abortedByUser = false;
+        let cappedExceeded = false;
+        let onAbort = null;
+        let activeReq = null;
+        let activeFile = null;
+        const detachAbort = () => {
+          if (onAbort && signal) {
+            try { signal.removeEventListener('abort', onAbort); } catch {}
+            onAbort = null;
+          }
+        };
+        const finishAborted = () => {
+          fs.unlink(outPath, () => {});
+          logToolCall('download', { url }, true, 'aborted');
+          resolve({ aborted: true, elapsed_s: Math.max(0, Math.round((Date.now() - startedAt) / 1000)) });
+        };
+        if (signal) {
+          if (signal.aborted) {
+            abortedByUser = true;
+            finishAborted();
+            return;
+          }
+          onAbort = () => {
+            abortedByUser = true;
+            try { if (activeReq) activeReq.destroy(new Error('Aborted')); } catch {}
+            try { if (activeFile) activeFile.destroy(); } catch {}
+          };
+          signal.addEventListener('abort', onAbort, { once: true });
+        }
+
+        function doDownload(target, redirectsLeft) {
+          const proto = target.startsWith('https') ? https : http;
+          let req;
+          try {
+            req = proto.get(target, { headers: { 'User-Agent': userAgent } }, (res) => {
+            if ([301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0 && res.headers.location) {
+              res.resume();
+              // A redirect Location may be relative or malformed — resolve +
+              // validate it against the current target rather than throwing.
+              const nextUrl = _validateFetchUrl(res.headers.location, target);
+              if (nextUrl.error) {
+                detachAbort();
+                _log(`  ${FG_RED}✗ ${nextUrl.error}${RST}`);
+                logToolCall('download', { url: target }, true, 'error');
+                return resolve(nextUrl);
+              }
+              return doDownload(nextUrl.url, redirectsLeft - 1);
+            }
+            if (res.statusCode >= 400) {
+              res.resume();
+              const msg = `HTTP ${res.statusCode}`;
+              detachAbort();
+              _log(`  ${FG_RED}✗ ${msg}${RST}`);
+              logToolCall('download', { url }, true, 'error');
+              return resolve({ error: msg });
+            }
+            const file = fs.createWriteStream(outPath);
+            activeFile = file;
+            let downloadedBytes = 0;
+            // Manual stream (instead of res.pipe) so we can enforce the byte cap
+            // mid-flight: on exceeding it, abort the request, destroy the file,
+            // remove the partial artifact, and resolve once cleanup completes so
+            // no truncated file is ever left behind.
+            res.on('data', (chunk) => {
+              if (cappedExceeded || abortedByUser) return;
+              downloadedBytes += chunk.length;
+              if (downloadedBytes > maxBytes) {
+                cappedExceeded = true;
+                try { if (activeReq) activeReq.destroy(); } catch {}
+                try { res.destroy(); } catch {}
+                detachAbort();
+                const msg = `Download aborted: exceeded byte cap (${maxBytes} bytes)`;
+                file.destroy();
+                file.once('close', () => {
+                  fs.unlink(outPath, () => {
+                    _log(`  ${FG_RED}✗ ${msg}${RST}`);
+                    logToolCall('download', { url, path: outPath }, true, 'error');
+                    resolve({ error: msg, capped: true, bytes: downloadedBytes });
+                  });
+                });
+                return;
+              }
+              if (!file.write(chunk)) {
+                res.pause();
+                file.once('drain', () => { if (!cappedExceeded && !abortedByUser) res.resume(); });
+              }
+            });
+            res.on('end', () => {
+              if (cappedExceeded || abortedByUser) return;
+              file.end();
+            });
+            res.on('error', (err) => {
+              if (cappedExceeded) return;
+              if (abortedByUser) { detachAbort(); finishAborted(); return; }
+              file.destroy();
+              fs.unlink(outPath, () => {});
+              detachAbort();
+              _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+              logToolCall('download', { url }, true, 'error');
+              resolve({ error: err.message });
+            });
+            file.on('finish', () => {
+              if (cappedExceeded || abortedByUser) return;
+              file.close();
+              detachAbort();
+              _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Downloaded to ${outPath}${RST}`);
+              logToolCall('download', { url }, true, 'ok');
+              resolve({ status: 'ok', path: outPath, bytes: downloadedBytes });
+            });
+            file.on('error', (err) => {
+              if (cappedExceeded) return;
+              if (abortedByUser) {
+                detachAbort();
+                finishAborted();
+                return;
+              }
+              fs.unlink(outPath, () => {});
+              detachAbort();
+              _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+              logToolCall('download', { url }, true, 'error');
+              resolve({ error: err.message });
+            });
+            });
+          } catch (err) {
+            // Defense-in-depth: the URL is validated before we get here, but any
+            // synchronous throw from proto.get must still become a tool error.
+            detachAbort();
+            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+            logToolCall('download', { url: target }, true, 'error');
+            resolve({ error: `Invalid URL: ${err.message}`, error_code: err.code || 'ERR_INVALID_URL' });
+            return;
+          }
+          activeReq = req;
+          req.on('error', (err) => {
+            if (cappedExceeded) return;
+            if (abortedByUser) {
+              detachAbort();
+              finishAborted();
+              return;
+            }
+            fs.unlink(outPath, () => {});
+            detachAbort();
+            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+            logToolCall('download', { url }, true, 'error');
+            resolve({ error: err.message });
+          });
+          req.setTimeout(120000, () => {
+            req.destroy();
+            fs.unlink(outPath, () => {});
+            detachAbort();
+            logToolCall('download', { url }, true, 'error');
+            resolve({ error: 'Request timeout' });
+          });
+        }
+        doDownload(normalizedDlUrl, 5);
+      });
+    },
+  },
+  {
+    tool: 'upload',
+    specNames: ['upload'],
+    tags: ['upload'],
+    // QUIRK: upload content (base64) is captured raw (not trimmed), like write.
+    parseXml: (text) => _matchDual(text, '<upload\\s+path=Q([^Q]+)Q>([\\s\\S]*?)<\\/upload>').map((m) => ['upload', m[1], m[2]]),
+    fromParams: (p) => (p.path ? ['upload', p.path, p.content != null ? p.content : ''] : null),
+    permission: (ctx, args) => ({ actionType: 'file', description: `Upload to ${args[0]}`, tag: 'upload' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, isPathSafe, isProtectedConfigPath, _sandboxError, _protectedConfigWriteError, permissionManager, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      const encodedContent = arg1 || '';
+      const blocked = permissionManager.readonlyBlock('upload');
+      if (blocked) {
+        logToolCall('upload', { path: filePath }, false, 'denied');
+        return blocked;
+      }
+      if (isProtectedConfigPath(filePath)) {
+        logToolCall('upload', { path: filePath }, false, 'denied');
+        return _protectedConfigWriteError(filePath);
+      }
+      if (!isPathSafe(filePath)) {
+        logToolCall('upload', { path: filePath }, false, 'denied');
+        return _sandboxError(filePath);
+      }
+      try {
+        const dir = path.dirname(filePath);
+        if (dir && dir !== '.') await fsp.mkdir(dir, { recursive: true });
+        const buffer = Buffer.from(encodedContent.trim(), 'base64');
+        await fsp.writeFile(filePath, buffer);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Uploaded ${buffer.length} bytes to ${filePath}${RST}`);
+        logToolCall('upload', { path: filePath }, true, 'ok');
+        return { status: 'ok', path: filePath, bytes: buffer.length };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('upload', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'file_stat',
+    specNames: ['file_stat'],
+    tags: ['file_stat'],
+    parseXml: (text) => _inline(text, 'file_stat', 'file_stat'),
+    fromParams: (p) => (p.path ? ['file_stat', p.path] : null),
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const filePath = arg0;
+      try {
+        const stat = await fsp.stat(filePath);
+        const type = stat.isDirectory() ? 'directory' : stat.isSymbolicLink() ? 'symlink' : 'file';
+        const size_kb = (stat.size / 1024).toFixed(2);
+        const mode = '0o' + stat.mode.toString(8);
+        const mtime = stat.mtime.toISOString();
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Stat ${filePath}${RST}`);
+        logToolCall('file_stat', { path: filePath }, true, 'ok');
+        return { path: filePath, size_kb, mtime, type, mode };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('file_stat', { path: filePath }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'http_get',
+    specNames: ['http_get'],
+    tags: ['http_get'],
+    parseXml: (text) => {
+      const out = [];
+      for (const m of text.matchAll(/<http_get\b([^>]*?)(?:><\/http_get>|\/>)/g)) {
+        const attrStr = m[1];
+        const urlMatch = attrStr.match(/url="([^"]+)"/) || attrStr.match(/url='([^']+)'/);
+        if (urlMatch) out.push(['http_get', urlMatch[1], _httpGetOpts(attrStr)]);
+      }
+      for (const m of text.matchAll(/<http_get>([\s\S]*?)<\/http_get>/g)) {
+        const inner = m[1].trim();
+        if (!inner) continue;
+        const urlAttr = inner.match(/url="([^"]+)"/) || inner.match(/url='([^']+)'/);
+        out.push(['http_get', urlAttr ? urlAttr[1] : _unwrapInnerTag(inner).trim(), _httpGetOpts(inner)]);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.url ? ['http_get', p.url, _httpGetOptsFromParams(p)] : null),
+    permission: (ctx, args) => ({ actionType: 'net', description: `HTTP GET ${args[0]}`, tag: 'http_get' }),
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [arg0 = null, callOpts = {}] = args;
+      const { _log, logToolCall, _dryRun, _skippedOps, getConfig, webChat, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const url = arg0;
+      if (_dryRun) {
+        _skippedOps.push({ category: 'net', symbol: '↓', desc: `GET ${url}` });
+        logToolCall('http_get', { url }, false, 'dry-run');
+        return { status: 'dry-run', message: 'dry-run: network call skipped' };
+      }
+      // Validate/normalize the URL BEFORE constructing any request. A malformed
+      // URL (or a non-http(s) scheme, empty/whitespace, non-string) is a clean
+      // tool error the agent can recover from — never an uncaught throw out of
+      // the executor. Same shape as the request-error path below.
+      const validatedUrl = _validateFetchUrl(url);
+      if (validatedUrl.error) {
+        _log(`  ${FG_RED}✗ ${validatedUrl.error}${RST}`);
+        logToolCall('http_get', { url }, true, 'error');
+        return validatedUrl;
+      }
+      const normalizedUrl = validatedUrl.url;
+      const httpCfg = getConfig ? getConfig() : {};
+      const reqTimeoutMs = Math.max(15000, httpCfg.request_timeout_ms || 15000);
+      // Byte cap is now ONLY a transfer/disk guard — the context-protection
+      // mechanism is the post-extraction TOKEN budget (web.max_content_tokens).
+      const maxBytes = Math.max(1024, httpCfg.http_fetch_max_bytes || 262144);
+      const userAgent = _resolveUserAgent(httpCfg);
+      const webCfg = (httpCfg.web && typeof httpCfg.web === 'object') ? httpCfg.web : {};
+      const maxContentTokens = Number.isFinite(webCfg.max_content_tokens) && webCfg.max_content_tokens > 0
+        ? webCfg.max_content_tokens : 6000;
+      const summaryModel = typeof webCfg.summary_model === 'string' && webCfg.summary_model.trim()
+        ? webCfg.summary_model.trim() : undefined;
+      // Resolve the web-fetch mode (Task W.1b). Precedence: an explicit per-call
+      // `mode` (the canonical enum the parser emits) beats the deprecated legacy
+      // booleans (summarize/raw — which may still arrive directly on callOpts from
+      // older callers), which beat the global config default (web.summarize mapped
+      // to summarized/extracted). Summary needs an injected LLM call (webChat);
+      // without one (headless/oneshot without an api client) the summarized branch
+      // degrades to extracted Markdown, never the raw page.
+      const mode = (callOpts && WEB_FETCH_MODES.includes(callOpts.mode) && callOpts.mode)
+        || _legacyBoolsToMode(
+          typeof (callOpts && callOpts.summarize) === 'boolean' ? callOpts.summarize : undefined,
+          typeof (callOpts && callOpts.raw) === 'boolean' ? callOpts.raw : undefined,
+        )
+        || (webCfg.summarize !== false ? 'summarized' : 'extracted');
+      const intent = callOpts && typeof callOpts.intent === 'string' ? callOpts.intent : '';
+      const startedAt = Date.now();
+      return new Promise((resolve) => {
+        let abortedByUser = false;
+        let onAbort = null;
+        let activeReq = null;
+        const detachAbort = () => {
+          if (onAbort && signal) {
+            try { signal.removeEventListener('abort', onAbort); } catch {}
+            onAbort = null;
+          }
+        };
+        const finishAborted = () => {
+          logToolCall('http_get', { url }, true, 'aborted');
+          resolve({ aborted: true, elapsed_s: Math.max(0, Math.round((Date.now() - startedAt) / 1000)) });
+        };
+        if (signal) {
+          if (signal.aborted) {
+            abortedByUser = true;
+            finishAborted();
+            return;
+          }
+          onAbort = () => {
+            abortedByUser = true;
+            try { if (activeReq) activeReq.destroy(new Error('Aborted')); } catch {}
+          };
+          signal.addEventListener('abort', onAbort, { once: true });
+        }
+
+        function doGet(target, redirectsLeft) {
+          const proto = target.startsWith('https') ? https : http;
+          let req;
+          try {
+            req = proto.get(target, { headers: { 'User-Agent': userAgent } }, (res) => {
+            if ([301, 302, 303, 307, 308].includes(res.statusCode) && redirectsLeft > 0 && res.headers.location) {
+              res.resume();
+              // A redirect Location may be relative or malformed — resolve it
+              // against the current target and validate, so a bad redirect is a
+              // clean tool error rather than a synchronous throw in this callback.
+              const nextUrl = _validateFetchUrl(res.headers.location, target);
+              if (nextUrl.error) {
+                detachAbort();
+                _log(`  ${FG_RED}✗ ${nextUrl.error}${RST}`);
+                logToolCall('http_get', { url: target }, true, 'error');
+                return resolve(nextUrl);
+              }
+              return doGet(nextUrl.url, redirectsLeft - 1);
+            }
+            const bufs = [];
+            let totalBytes = 0;
+            let capped = false;
+            res.on('data', (chunk) => {
+              totalBytes += chunk.length;
+              if (!capped) {
+                if (totalBytes <= maxBytes) {
+                  bufs.push(chunk);
+                } else {
+                  const keep = maxBytes - (totalBytes - chunk.length);
+                  if (keep > 0) bufs.push(chunk.slice(0, keep));
+                  capped = true;
+                }
+              }
+            });
+            res.on('end', () => {
+              if (abortedByUser) return;
+              detachAbort();
+              const kept = Buffer.concat(bufs);
+              const keptBytes = kept.length;
+              const rawBody = kept.toString('utf8');
+              const contentType = res.headers && res.headers['content-type'];
+              const statusCode = res.statusCode;
+              _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}HTTP GET ${target} (${statusCode}, ${totalBytes} bytes${capped ? `, transfer-capped to ${keptBytes}` : ''})${RST}`);
+              logToolCall('http_get', { url: target }, true, statusCode < 400 ? 'ok' : 'error');
+              // Stage 1+2+3: extract main content → Markdown → (optional) summary.
+              // The RAW page never enters the main context — only the processed
+              // result does. Fully contained: any pipeline error degrades to the
+              // capped extracted Markdown (and as a last resort the crude-stripped
+              // text), NEVER the raw HTML.
+              (async () => {
+                let result;
+                try {
+                  result = await processWebContent({
+                    rawBody, contentType, url: target, statusCode,
+                    totalBytes, transferCapped: capped,
+                    mode, intent, summaryModel, maxContentTokens,
+                    webChat, signal,
+                  });
+                } catch (err) {
+                  // Defensive: extraction itself should not throw, but if it does,
+                  // fall back to a crude tag-strip rather than dumping raw HTML.
+                  const { stripTagsCrude } = require('./web-extract');
+                  const safe = capToTokens(stripTagsCrude(rawBody), maxContentTokens, defaultEstimate);
+                  result = { status_code: statusCode, body: safe.text, bytes: totalBytes,
+                    kind: 'text', extracted: false, summarized: false, processing_error: err.message };
+                }
+                resolve(result);
+              })();
+            });
+            });
+          } catch (err) {
+            // Defense-in-depth: the URL is validated before we get here, but any
+            // synchronous throw from proto.get must still become a tool error,
+            // never escape the executor.
+            detachAbort();
+            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+            logToolCall('http_get', { url: target }, true, 'error');
+            resolve({ error: `Invalid URL: ${err.message}`, error_code: err.code || 'ERR_INVALID_URL' });
+            return;
+          }
+          activeReq = req;
+          req.on('error', (err) => {
+            if (abortedByUser) {
+              detachAbort();
+              finishAborted();
+              return;
+            }
+            detachAbort();
+            _log(`  ${FG_RED}✗ ${err.message}${RST}`);
+            logToolCall('http_get', { url: target }, true, 'error');
+            resolve({ error: err.message, error_code: err.code });
+          });
+          req.setTimeout(reqTimeoutMs, () => {
+            req.destroy();
+            detachAbort();
+            logToolCall('http_get', { url: target }, true, 'error');
+            resolve({ error: 'Request timeout', error_code: 'ETIMEDOUT' });
+          });
+        }
+        doGet(normalizedUrl, 5);
+      });
+    },
+  },
+  {
+    // Web search (Task W.2b). Calls the backend POST /api/search via the
+    // injected ctx.webSearch (api client's dashboardSearch → SearXNG) and
+    // returns a COMPACT { title, url, snippet } list — never page content
+    // (that is http_get's job). The spec steers the model to read the snippets,
+    // pick the relevant result(s), and fetch only those with http_get, instead
+    // of blindly multi-fetching. The backend is on another machine and may be
+    // down/unreachable/erroring — every failure mode is caught and surfaced as a
+    // clean tool error; NOTHING throws out of the executor (the http_get-fix
+    // lesson). Results are untrusted external content, fenced in lib/agent.js.
+    tool: 'web_search',
+    specNames: ['web_search'],
+    tags: ['web_search'],
+    parseXml: (text) => {
+      const out = [];
+      for (const m of text.matchAll(/<web_search\b([^>]*?)(?:><\/web_search>|\/>)/g)) {
+        const attrStr = m[1];
+        const qMatch = attrStr.match(/query="([^"]*)"/) || attrStr.match(/query='([^']*)'/);
+        if (qMatch) out.push(['web_search', qMatch[1], _webSearchOpts(attrStr)]);
+      }
+      for (const m of text.matchAll(/<web_search>([\s\S]*?)<\/web_search>/g)) {
+        const inner = m[1].trim();
+        if (!inner) continue;
+        const qAttr = inner.match(/query="([^"]*)"/) || inner.match(/query='([^']*)'/);
+        out.push(['web_search', qAttr ? qAttr[1] : inner, _webSearchOpts(inner)]);
+      }
+      return out;
+    },
+    fromParams: (p) => (p.query ? ['web_search', String(p.query), _webSearchOptsFromParams(p)] : null),
+    // A network read like http_get — same descriptor shape (net, gated; not a
+    // privileged path). Performs no mutation.
+    permission: (ctx, args) => ({ actionType: 'net', description: `Web search: ${args[0]}`, tag: 'web_search' }),
+    execute: async (ctx, args, options) => {
+      const signal = (options && options.signal) || null;
+      const [arg0 = '', callOpts = {}] = args;
+      const { _log, logToolCall, _dryRun, _skippedOps, webSearch, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const query = typeof arg0 === 'string' ? arg0.trim() : '';
+      if (!query) {
+        logToolCall('web_search', { query: arg0 }, true, 'error');
+        return { error: 'web search unavailable: empty query' };
+      }
+      if (_dryRun) {
+        _skippedOps.push({ category: 'net', symbol: '⌕', desc: `search ${query}` });
+        logToolCall('web_search', { query }, false, 'dry-run');
+        return { status: 'dry-run', message: 'dry-run: web search skipped' };
+      }
+      if (typeof webSearch !== 'function') {
+        logToolCall('web_search', { query }, true, 'error');
+        return { error: 'web search unavailable: no backend client configured (available in interactive chat / the SDK with dashboard auth)' };
+      }
+      // Bound count BEFORE the backend call; the backend clamps further but a
+      // huge value should never leave the client. An invalid/zero count is
+      // dropped so the backend default applies.
+      const count = _clampSearchCount(callOpts && callOpts.count);
+      const limit = count || 10;
+      try {
+        const resp = await webSearch(query, count ? { count, signal } : { signal });
+        const raw = resp && Array.isArray(resp.results) ? resp.results : [];
+        const results = raw.slice(0, limit).map((r) => ({
+          title: r && typeof r.title === 'string' ? r.title : '',
+          url: r && typeof r.url === 'string' ? r.url : '',
+          snippet: r && typeof r.snippet === 'string' ? r.snippet : '',
+        }));
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}web search "${query}" (${results.length} result${results.length === 1 ? '' : 's'})${RST}`);
+        logToolCall('web_search', { query }, true, 'ok');
+        return { query, count: results.length, results };
+      } catch (err) {
+        const reason = (err && err.message) ? err.message : String(err || 'unknown error');
+        _log(`  ${FG_RED}✗ web search unavailable: ${reason}${RST}`);
+        logToolCall('web_search', { query }, true, 'error');
+        return { error: `web search unavailable: ${reason}` };
+      }
+    },
+  },
+  {
+    tool: 'ask_user',
+    specNames: ['ask_user'],
+    tags: ['ask_user'],
+    parseXml: (text) => _matchDual(text, '<ask_user\\s+question=Q([^Q]+)Q\\s*(?:><\\/ask_user>|\\/>)').map((m) => ['ask_user', m[1]]),
+    fromParams: (p) => (p.question ? ['ask_user', p.question] : null),
+    // No permission descriptor: ask_user has no system side effects — it only
+    // prompts the interactive user, which IS the interaction. A separate "may I
+    // ask you?" gate would be pure friction (a double prompt before the real
+    // question/menu). A null descriptor also makes it available during plan mode
+    // (the plan-mode gate withholds only effectful tools, i.e. non-null
+    // descriptors), so the agent can ask clarifying questions while planning.
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, _parseAskMenu, permissionManager, writer, FG_YELLOW, FG_GRAY, RST, DIM } = ctx;
+      const question = arg0;
+      // Display-only split: the menu gets ONLY the numbered options; the modal
+      // header gets ONLY the prose prompt (no duplication). The model-facing
+      // result below still carries the FULL original `question` (agent.js builds
+      // "User answered \"<question>\": <answer>" from it). Edge: a question with
+      // no prose before the numbers yields an empty prompt — fall back to the raw
+      // question so the modal never renders an empty header.
+      const { prompt, options } = _parseAskMenu(question);
+      if (options.length >= 2) {
+        const selected = await permissionManager.captureSelect({ prompt: prompt || question, options });
+        logToolCall('ask_user', { question }, true, 'ok');
+        return { question, answer: selected || options[0] };
+      }
+      if (!process.stdout.isTTY || process.stdin.isRaw) {
+        writer.scrollback(`\n  ${FG_YELLOW}?${RST} ${question}\n  ${DIM}[auto-answering 'y']${RST}`);
+        logToolCall('ask_user', { question }, true, 'ok');
+        return { question, answer: 'y' };
+      }
+      process.stdout.write(`\n  ${FG_YELLOW}?${RST} ${question}\n  ${FG_GRAY}>${RST} `);
+      const buf = Buffer.alloc(4096);
+      let input = '';
+      while (true) {
+        const n = fs.readSync(0, buf, 0, 1);
+        if (n === 0) break;
+        const ch = buf[0];
+        if (ch === 0x0a) break;
+        if (ch === 0x0d) continue;
+        input += String.fromCharCode(ch);
+      }
+      _log();
+      logToolCall('ask_user', { question }, true, 'ok');
+      return { question, answer: input };
+    },
+  },
+  {
+    tool: 'store_memory',
+    specNames: ['store_memory'],
+    tags: ['store_memory'],
+    // QUIRK: store_memory value is captured raw (not trimmed), like write.
+    parseXml: (text) => _matchDual(text, '<store_memory\\s+key=Q([^Q]+)Q>([\\s\\S]*?)<\\/store_memory>').map((m) => ['store_memory', m[1], m[2]]),
+    fromParams: (p) => (p.key ? ['store_memory', p.key, p.value != null ? p.value : ''] : null),
+    permission: (ctx, args) => ({ actionType: 'memory', description: `Store memory: ${args[0]}`, tag: 'store_memory' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, MEMORY_PATH, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const key = arg0;
+      const value = arg1 || '';
+      try {
+        let mem = {};
+        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
+        mem[key] = value;
+        await fsp.mkdir(path.dirname(MEMORY_PATH), { recursive: true });
+        await fsp.writeFile(MEMORY_PATH, JSON.stringify(mem, null, 2));
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Stored memory: ${key}${RST}`);
+        logToolCall('store_memory', { key }, true, 'ok');
+        return { status: 'ok', key };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('store_memory', { key }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'recall_memory',
+    specNames: ['recall_memory'],
+    tags: ['recall_memory'],
+    parseXml: (text) => _matchDual(text, '<recall_memory\\s+key=Q([^Q]+)Q\\s*(?:><\\/recall_memory>|\\/>)').map((m) => ['recall_memory', m[1]]),
+    fromParams: (p) => (p.key ? ['recall_memory', p.key] : null),
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, MEMORY_PATH, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      const key = arg0;
+      try {
+        let mem = {};
+        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
+        const found = key in mem;
+        const value = found ? mem[key] : null;
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Recalled memory: ${key}${RST}`);
+        logToolCall('recall_memory', { key }, true, 'ok');
+        return { key, value, found };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('recall_memory', { key }, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'list_memories',
+    specNames: ['list_memories'],
+    tags: ['list_memories'],
+    parseXml: (text) => [...text.matchAll(/<list_memories\s*(?:><\/list_memories>|\/>)/g)].map(() => ['list_memories']),
+    fromParams: () => ['list_memories'],
+    permission: () => null,
+    execute: async (ctx) => {
+      const { _log, logToolCall, MEMORY_PATH, FG_GREEN, FG_GRAY, FG_RED, RST } = ctx;
+      try {
+        let mem = {};
+        try { mem = JSON.parse(await fsp.readFile(MEMORY_PATH, 'utf8')); } catch {}
+        const keys = Object.keys(mem);
+        _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Listed ${keys.length} memory key(s)${RST}`);
+        logToolCall('list_memories', {}, true, 'ok');
+        return { keys };
+      } catch (error) {
+        _log(`  ${FG_RED}✗ ${error.message}${RST}`);
+        logToolCall('list_memories', {}, true, 'error');
+        return { error: error.message };
+      }
+    },
+  },
+  {
+    tool: 'get_env',
+    specNames: ['get_env'],
+    tags: ['get_env'],
+    parseXml: (text) => _inline(text, 'get_env', 'get_env'),
+    fromParams: (p) => (p.name ? ['get_env', p.name] : null),
+    permission: () => null,
+    execute: async (ctx, args) => {
+      const [arg0 = null] = args;
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, RST } = ctx;
+      const varName = arg0;
+      const value = process.env[varName];
+      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Got env ${varName}${RST}`);
+      logToolCall('get_env', { name: varName }, true, 'ok');
+      return { name: varName, value: value !== undefined ? value : null };
+    },
+  },
+  {
+    tool: 'set_env',
+    specNames: ['set_env'],
+    tags: ['set_env'],
+    parseXml: (text) => _matchDual(text, '<set_env\\s+name=Q([^Q]+)Q\\s+value=Q([^Q]*)Q\\s*(?:><\\/set_env>|\\/>)').map((m) => ['set_env', m[1], m[2]]),
+    fromParams: (p) => (p.name ? ['set_env', p.name, p.value != null ? p.value : ''] : null),
+    permission: (ctx, args) => ({ actionType: 'env', description: `Set env ${args[0]}=${args[1] || ''}`, tag: 'set_env' }),
+    execute: async (ctx, args) => {
+      const [arg0 = null, arg1 = null] = args;
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, RST } = ctx;
+      const varName = arg0;
+      const value = arg1 || '';
+      process.env[varName] = value;
+      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}Set env ${varName}${RST}`);
+      logToolCall('set_env', { name: varName }, true, 'ok');
+      return { status: 'ok', name: varName };
+    },
+  },
+  {
+    tool: 'system_info',
+    specNames: ['system_info'],
+    tags: ['system_info'],
+    parseXml: (text) => [...text.matchAll(/<system_info\s*(?:><\/system_info>|\/>)/g)].map(() => ['system_info']),
+    fromParams: () => ['system_info'],
+    permission: () => null,
+    execute: async (ctx) => {
+      const { _log, logToolCall, FG_GREEN, FG_GRAY, RST } = ctx;
+      const info = {
+        platform: os.platform(),
+        arch: os.arch(),
+        hostname: os.hostname(),
+        user: process.env.USER || process.env.USERNAME || '',
+        total_mem_mb: Math.round(os.totalmem() / 1024 / 1024),
+        free_mem_mb: Math.round(os.freemem() / 1024 / 1024),
+        node_version: process.version,
+        cwd: process.cwd(),
+      };
+      _log(`  ${FG_GREEN}✓${RST} ${FG_GRAY}System info: ${info.platform}/${info.arch}${RST}`);
+      logToolCall('system_info', {}, true, 'ok');
+      return info;
+    },
+  },
+  ...GIT_TOOL_REGISTRY,
+];
+
+// name (TOOL_SPECS key / native function name) → registry entry.
+const _byName = new Map();
+// canonical action (tuple[0]) → registry entry, for executor / permission dispatch.
+const _byAction = new Map();
+for (const entry of TOOL_REGISTRY) {
+  for (const n of entry.specNames) _byName.set(n.toLowerCase(), entry);
+  _byAction.set(entry.tool, entry);
+}
+
+// ── Dynamic (runtime-registered) tools — MCP, Task 3.3 ─────────────────────
+//
+// Tools discovered at runtime (MCP servers) are registered here, SEPARATE from
+// the static TOOL_REGISTRY array above. This separation is deliberate: the
+// load-time parity check in lib/constants.js validates only the static set
+// (TAG_REGISTRY ↔ TOOL_SPECS ↔ TOOL_REGISTRY), and it runs once at module load,
+// before any MCP server has connected. Keeping dynamic tools out of that array
+// means MCP tools never break the parity invariant.
+//
+// Dispatch (entryForAction) and native mapping (fromInvoke) consult this map
+// AFTER the static one, so a dynamic tool can never shadow a built-in. Each
+// entry has the same shape as a static one — { tool, fromParams, execute,
+// permission, parseXml?, spec? } — so it dispatches through the agent loop
+// identically. `spec` (an OpenAI-format { description, parameters }) is surfaced
+// to the native function-calling `tools` array via dynamicToolSpecs().
+const _dynamic = new Map(); // canonical name (== entry.tool) → entry
+
+function _lookupDynamic(name) {
+  if (name == null) return null;
+  return _dynamic.get(name) || _dynamic.get(String(name).toLowerCase()) || null;
+}
+
+function registerDynamicTool(entry) {
+  if (!entry || typeof entry.tool !== 'string' || !entry.tool) {
+    throw new Error('registerDynamicTool: entry.tool (canonical name) is required');
+  }
+  if (typeof entry.execute !== 'function') {
+    throw new Error(`registerDynamicTool(${entry.tool}): execute() is required`);
+  }
+  if (typeof entry.fromParams !== 'function') {
+    throw new Error(`registerDynamicTool(${entry.tool}): fromParams() is required`);
+  }
+  if (typeof entry.permission !== 'function') {
+    throw new Error(`registerDynamicTool(${entry.tool}): permission() is required`);
+  }
+  _dynamic.set(entry.tool, entry);
+}
+
+function unregisterDynamicTool(name) {
+  return _dynamic.delete(name);
+}
+
+function clearDynamicTools() {
+  _dynamic.clear();
+}
+
+function dynamicToolEntries() {
+  return [..._dynamic.values()];
+}
+
+// { name → { description, parameters } } for every dynamic tool that carries a
+// spec. Merged into the native function-calling tools array in lib/api.js.
+function dynamicToolSpecs() {
+  const out = {};
+  for (const e of _dynamic.values()) {
+    if (e.spec) out[e.tool] = e.spec;
+  }
+  return out;
+}
+
+function fromInvoke(toolName, params) {
+  const entry = _byName.get((toolName || '').toLowerCase()) || _lookupDynamic(toolName);
+  if (!entry) return null;
+  return entry.fromParams(params || {});
+}
+
+function entryForAction(action) {
+  return _byAction.get(action) || _lookupDynamic(action) || null;
+}
+
+// Static (load-time-parity-checked) tool names only — MUST NOT include dynamic
+// tools, or the lib/constants.js parity assertion would see phantom entries.
+function registryToolNames() {
+  return [..._byName.keys()];
+}
+
+module.exports = {
+  TOOL_REGISTRY,
+  fromInvoke,
+  entryForAction,
+  registryToolNames,
+  // Dynamic (runtime) tool registry — MCP (Task 3.3).
+  registerDynamicTool,
+  unregisterDynamicTool,
+  clearDynamicTools,
+  dynamicToolEntries,
+  dynamicToolSpecs,
+  // Exported for the grep/glob characterization + parity tests (Task 2.1).
+  // The execute() bodies above use these same functions; tests drive both
+  // engines explicitly to prove rg- and Node-path outputs are identical.
+  _grepSearch,
+  _globSearch,
+  _detectRipgrep,
+  // Path-aware grep target resolution + single-file grep (file/dir/glob path
+  // semantics + the unresolvable-path safety net). Exported for focused tests.
+  _resolveGrepPath,
+  _grepFile,
+  _grepHasCandidate,
+  // grep output modes + bound normalizers (Task W.5).
+  GREP_OUTPUT_MODES,
+  _normGrepMode,
+  _normHeadLimit,
+  _normOffset,
+  // Exported for the web-fetch mode-resolution tests (Task W.1b).
+  _httpGetOpts,
+  _httpGetOptsFromParams,
+  processWebContent,
+  WEB_FETCH_MODES,
+  // Exported for the URL-validation tests (fetch-url-validation.test.js).
+  _validateFetchUrl,
+};