@wrongstack/tools 0.275.1 → 0.276.3

package/dist/pack.js

@@ -1,6 +1,6 @@
 import { spawn, execFileSync } from 'node:child_process';
 import * as Core from '@wrongstack/core';
-import { buildChildEnv, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { buildChildEnv, getDesignKitLoader, isDesignStack, loadActiveKit, applyTokenOverrides, setActiveKit, recordKitChoice, recordOverrides, setDesignOverrides, materializeTokens, runDesignVerify, ToolValidationError, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, ToolError, FetchError, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, deepMerge, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, FsError, toErrorMessage as toErrorMessage$2, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import * as fs from 'node:fs';
 import { statSync, mkdirSync, createWriteStream } from 'node:fs';
 import * as fs2 from 'node:fs/promises';
@@ -833,8 +833,8 @@ async function* spawnStream(opts) {
   try {
     for (; ; ) {
       while (queue.length === 0) {
-        await new Promise((resolve6) => {
-          waiter = resolve6;
+        await new Promise((resolve7) => {
+          waiter = resolve7;
         });
       }
       const chunk = queue.shift();
@@ -2133,10 +2133,10 @@ var bashTool = {
         queue.push(c);
       }
     };
-    const next = () => new Promise((resolve6) => {
+    const next = () => new Promise((resolve7) => {
       const c = queue.shift();
-      if (c) resolve6(c);
-      else resolveNext = resolve6;
+      if (c) resolve7(c);
+      else resolveNext = resolve7;
     });
     let lastFlush = Date.now();
     const flush = () => {
@@ -2536,8 +2536,8 @@ var Bm25Index = class {
   df;
   N;
   safeAvgLen;
-  score(query2, filter) {
-    const qTokens = tokenise(query2);
+  score(query, filter) {
+    const qTokens = tokenise(query);
     if (qTokens.length === 0) return [];
     const results = [];
     for (const doc of this.documents) {
@@ -2860,7 +2860,7 @@ var IndexStore = class {
     );
   }
   // ─── Search ──────────────────────────────────────────────────────────────────
-  search(query2, filter) {
+  search(query, filter) {
     const conditions = [];
     const values = [];
     let effectiveKind = filter?.kind;
@@ -2884,8 +2884,8 @@ var IndexStore = class {
       conditions.push("file LIKE ?");
       values.push(`%${filter.file}%`);
     }
-    if (query2.trim()) {
-      const tokens = query2.toLowerCase().split(/\s+/).filter(Boolean);
+    if (query.trim()) {
+      const tokens = query.toLowerCase().split(/\s+/).filter(Boolean);
       const tokenConds = tokens.map(() => "text LIKE ?");
       conditions.push(`(${tokenConds.join(" OR ")})`);
       for (const t of tokens) values.push(`%${t}%`);
@@ -2919,10 +2919,10 @@ var IndexStore = class {
    * `LIKE '%tok%'` recall for the common symbol-search shapes ("user" finds
    * "users", camelCase-split text makes "complex" find "complexOperation").
    */
-  searchRanked(query2, filter, limit) {
-    const tokens = tokenise(query2);
+  searchRanked(query, filter, limit) {
+    const tokens = tokenise(query);
     if (tokens.length === 0 || !this.ftsAvailable) {
-      return this.searchRankedFallback(query2, filter, limit);
+      return this.searchRankedFallback(query, filter, limit);
     }
     let effectiveKind = filter?.kind;
     if (filter?.lspKind !== void 0) {
@@ -2979,19 +2979,19 @@ var IndexStore = class {
     };
   }
   /** Legacy ranked path: LIKE candidates + in-process BM25 + JS snippets. */
-  searchRankedFallback(query2, filter, limit) {
-    const candidates = this.search(query2, filter);
+  searchRankedFallback(query, filter, limit) {
+    const candidates = this.search(query, filter);
     if (candidates.length === 0) return { results: [], total: 0 };
-    if (!query2.trim()) {
+    if (!query.trim()) {
       return { results: candidates.slice(0, limit), total: candidates.length };
     }
     const candidateById = new Map(candidates.map((c) => [c.id, c]));
     const bm25 = buildBm25Index(
       candidates.map((c) => ({ id: c.id, text: buildIndexableText(c.name, c.signature, c.docComment) }))
     );
-    const scored = bm25.score(query2, (id) => candidateById.has(id));
+    const scored = bm25.score(query, (id) => candidateById.has(id));
     scored.sort((a, b) => b.score - a.score);
-    const qTokens = tokenise(query2);
+    const qTokens = tokenise(query);
     const results = scored.slice(0, limit).map(({ id, score }) => {
       const c = expectDefined(candidateById.get(id));
       return { ...c, score, snippet: bm25.extractSnippet(id, qTokens) };
@@ -3102,6 +3102,104 @@ var IndexStore = class {
       }
     });
   }
+  /**
+   * Commit a batch of file-level symbol/refs/upserts in a single transaction.
+   *
+   * Used by the indexer to amortize SQLite commit overhead across many files.
+   * Before this, the indexer issued one transaction per file (BEGIN IMMEDIATE
+   * for symbols, plus per-file deletes and an upsertFile call), so a 20-file
+   * parallel batch cost ~5+ transactions × 20 files = 100+ commits. With
+   * this entry point we do exactly one BEGIN/COMMIT per parallel batch.
+   *
+   * Each entry must already be a fully-parsed FileSymbols (symbols + refs).
+   * The caller is responsible for the per-file prefix accounting
+   * (refsByLine → flat list with `fromId` populated). `deleteForFiles` lets
+   * the caller clear stale symbols/refs for any files being re-indexed before
+   * the inserts run (required to keep refs → symbols FK invariants).
+   *
+   * Returns the symbols back with their assigned `id` (same shape as
+   * {@link insertSymbols}) so callers can build final per-file results.
+   */
+  commitBatch(entries, options = {}) {
+    if (entries.length === 0 && (options.deleteForFiles?.length ?? 0) === 0) {
+      return [];
+    }
+    return this.runWithRetry(() => {
+      this.db.exec("BEGIN IMMEDIATE");
+      try {
+        if (options.deleteForFiles && options.deleteForFiles.length > 0) {
+          const placeholders = options.deleteForFiles.map(() => "?").join(",");
+          if (this.ftsAvailable) {
+            this.db.prepare(
+              `DELETE FROM symbols_fts WHERE rowid IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
+            ).run(...options.deleteForFiles);
+          }
+          this.db.prepare(
+            `DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file IN (${placeholders}))`
+          ).run(...options.deleteForFiles);
+          this.db.prepare(`DELETE FROM symbols WHERE file IN (${placeholders})`).run(...options.deleteForFiles);
+        }
+        const maxRows = this.db.prepare("SELECT MAX(id) AS m FROM symbols").all();
+        let nextId = (maxRows[0]?.m ?? 0) + 1;
+        const symStmt = this.db.prepare(
+          `INSERT INTO symbols(id, lang, kind, name, file, line, col, signature, doc_comment, scope, text, file_fk)
+           VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`
+        );
+        const ftsStmt = this.ftsAvailable ? this.db.prepare("INSERT INTO symbols_fts(rowid, text) VALUES (?, ?)") : null;
+        const allInserted = [];
+        const refsToInsert = [];
+        for (const entry of entries) {
+          for (const s of entry.symbols) {
+            const id = nextId++;
+            symStmt.run(
+              id,
+              s.lang,
+              s.kind,
+              s.name,
+              s.file,
+              s.line,
+              s.col,
+              s.signature,
+              s.docComment,
+              s.scope,
+              s.text,
+              s.file
+            );
+            ftsStmt?.run(id, buildIndexableText(s.name, s.signature, s.docComment));
+            allInserted.push({ ...s, id });
+          }
+          for (const r of entry.refs) refsToInsert.push(r);
+        }
+        if (refsToInsert.length > 0) {
+          const refStmt = this.db.prepare(
+            `INSERT INTO refs(from_id, to_name, to_id, call_type, line)
+             VALUES (?, ?, ?, ?, ?)`
+          );
+          for (const ref of refsToInsert) {
+            refStmt.run(ref.fromId, ref.toName, ref.toId ?? null, ref.callType, ref.line);
+          }
+        }
+        const upsertStmt = this.db.prepare(
+          `INSERT INTO files(file, lang, mtime_ms, symbol_count, last_indexed)
+           VALUES (?, ?, ?, ?, ?)
+           ON CONFLICT(file) DO UPDATE SET
+             lang = excluded.lang,
+             mtime_ms = excluded.mtime_ms,
+             symbol_count = excluded.symbol_count,
+             last_indexed = excluded.last_indexed`
+        );
+        const now = Date.now();
+        for (const entry of entries) {
+          upsertStmt.run(entry.file, entry.lang, entry.mtimeMs, entry.symbolCount, now);
+        }
+        this.db.exec("COMMIT");
+        return allInserted;
+      } catch (err) {
+        this.db.exec("ROLLBACK");
+        throw err;
+      }
+    });
+  }
   /**
    * Delete all refs whose source symbols are in a given file.
    * Used when re-indexing a file to clear stale refs.
@@ -3618,8 +3716,8 @@ async function syncGoParse(filePath, content, lang) {
     proc.stdin?.write(content);
     proc.stdin?.end();
     const { code } = await Promise.race([
-      new Promise((resolve6) => {
-        proc.on("close", (c) => resolve6({ code: c }));
+      new Promise((resolve7) => {
+        proc.on("close", (c) => resolve7({ code: c }));
       }),
       new Promise(
         (_, reject) => setTimeout(() => {
@@ -3881,8 +3979,8 @@ async function syncPyParse(filePath, content, lang) {
       stdout += chunk.toString();
     });
     const { code } = await Promise.race([
-      new Promise((resolve6) => {
-        proc.on("close", (c) => resolve6({ code: c }));
+      new Promise((resolve7) => {
+        proc.on("close", (c) => resolve7({ code: c }));
       }),
       new Promise(
         (_, reject) => setTimeout(() => {
@@ -3967,8 +4065,8 @@ async function tryNativeParse(file, content) {
       stdout += chunk.toString();
     });
     const { code } = await Promise.race([
-      new Promise((resolve6) => {
-        proc.on("close", (c) => resolve6({ code: c }));
+      new Promise((resolve7) => {
+        proc.on("close", (c) => resolve7({ code: c }));
       }),
       new Promise(
         (_, reject) => setTimeout(() => {
@@ -4458,7 +4556,7 @@ async function loadGitignoreMatcher(projectRoot) {
 var YIELD_EVERY_N = 50;
 var PARALLEL_BATCH = 20;
 function yieldEventLoop() {
-  return new Promise((resolve6) => setImmediate(resolve6));
+  return new Promise((resolve7) => setImmediate(resolve7));
 }
 function throwIfAborted(signal) {
   if (!signal?.aborted) return;
@@ -4633,6 +4731,8 @@ async function runIndexerWithStore(store, opts) {
         return { file, stat: stat11, lang, parsed, content };
       })
     );
+    const batchEntries = [];
+    const deleteForFiles = [];
     for (let fi = 0; fi < statReadParse.length; fi++) {
       const settled = statReadParse[fi];
       const file = expectDefined(batchFiles[fi]);
@@ -4657,43 +4757,116 @@ async function runIndexerWithStore(store, opts) {
       }
       if (!lang || !parsed) {
         if (lang) {
-          store.upsertFile({ file, lang, mtimeMs: Math.floor(stat11.mtimeMs), symbolCount: 0, lastIndexed: Date.now() });
+          store.upsertFile({
+            file,
+            lang,
+            mtimeMs: Math.floor(stat11.mtimeMs),
+            symbolCount: 0,
+            lastIndexed: Date.now()
+          });
           filesIndexed++;
         }
         continue;
       }
-      store.deleteRefsForFile(file);
-      store.deleteSymbolsForFile(file);
       if (parsed.symbols.length === 0) {
-        store.upsertFile({ file, lang, mtimeMs: Math.floor(stat11.mtimeMs), symbolCount: 0, lastIndexed: Date.now() });
+        store.upsertFile({
+          file,
+          lang,
+          mtimeMs: Math.floor(stat11.mtimeMs),
+          symbolCount: 0,
+          lastIndexed: Date.now()
+        });
         filesIndexed++;
         continue;
       }
-      const symbolsWithIds = store.insertSymbols(parsed.symbols);
-      const count = symbolsWithIds.length;
-      symbolsIndexed += count;
-      langStats[lang] = (langStats[lang] ?? 0) + count;
+      const refs = [];
       if (parsed.refs && parsed.refs.length > 0) {
-        const refsByLine = /* @__PURE__ */ new Map();
-        for (const r of parsed.refs) {
-          let arr = refsByLine.get(r.line);
-          if (!arr) {
-            arr = [];
-            refsByLine.set(r.line, arr);
+        for (const r of parsed.refs) refs.push({ ...r, fromId: 0 });
+      }
+      batchEntries.push({
+        file,
+        lang,
+        symbols: parsed.symbols,
+        refs,
+        mtimeMs: Math.floor(stat11.mtimeMs),
+        symbolCount: parsed.symbols.length
+      });
+      deleteForFiles.push(file);
+    }
+    if (batchEntries.length > 0) {
+      try {
+        const inserted = store.commitBatch(batchEntries, { deleteForFiles });
+        let cursor = 0;
+        for (const entry of batchEntries) {
+          const count = entry.symbols.length;
+          const symbolsWithIds = inserted.slice(cursor, cursor + count);
+          cursor += count;
+          symbolsIndexed += count;
+          langStats[entry.lang] = (langStats[entry.lang] ?? 0) + count;
+          filesIndexed++;
+          if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
+            const refsByLine = /* @__PURE__ */ new Map();
+            for (let i = 0; i < symbolsWithIds.length; i++) {
+              const sym = symbolsWithIds[i];
+              let arr = refsByLine.get(sym.line);
+              if (!arr) {
+                arr = [];
+                refsByLine.set(sym.line, arr);
+              }
+              arr.push(i);
+            }
+            for (const ref of entry.refs) {
+              const indices = refsByLine.get(ref.line);
+              if (indices && indices.length > 0) {
+                const idx = indices.shift();
+                ref.fromId = symbolsWithIds[idx].id;
+              }
+            }
           }
-          arr.push(r);
         }
-        const batch = [];
-        for (const sym of symbolsWithIds) {
-          const symRefs = refsByLine.get(sym.line);
-          if (symRefs) {
-            for (const r of symRefs) batch.push({ ...r, fromId: sym.id });
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        errors.push(`commitBatch failed: ${message} \u2014 falling back to per-file writes`);
+        for (const entry of batchEntries) {
+          try {
+            store.deleteRefsForFile(entry.file);
+            store.deleteSymbolsForFile(entry.file);
+            const symbolsWithIds = store.insertSymbols(entry.symbols);
+            symbolsIndexed += symbolsWithIds.length;
+            langStats[entry.lang] = (langStats[entry.lang] ?? 0) + symbolsWithIds.length;
+            filesIndexed++;
+            if (entry.refs.length > 0 && symbolsWithIds.length > 0) {
+              const refsByLine = /* @__PURE__ */ new Map();
+              for (const sym of symbolsWithIds) {
+                let arr = refsByLine.get(sym.line);
+                if (!arr) {
+                  arr = [];
+                  refsByLine.set(sym.line, arr);
+                }
+                arr.push(sym);
+              }
+              const fallbackBatch = [];
+              for (const ref of entry.refs) {
+                const syms = refsByLine.get(ref.line);
+                if (syms && syms.length > 0) {
+                  const sym = syms.shift();
+                  fallbackBatch.push({ ...ref, fromId: sym.id });
+                }
+              }
+              if (fallbackBatch.length > 0) store.insertRefsBatch(fallbackBatch);
+            }
+            store.upsertFile({
+              file: entry.file,
+              lang: entry.lang,
+              mtimeMs: entry.mtimeMs,
+              symbolCount: entry.symbolCount,
+              lastIndexed: Date.now()
+            });
+          } catch (innerErr) {
+            errors.push(`fallback write failed: ${entry.file}: ${innerErr instanceof Error ? innerErr.message : String(innerErr)}`);
           }
         }
-        if (batch.length > 0) store.insertRefsBatch(batch);
       }
-      store.upsertFile({ file, lang, mtimeMs: Math.floor(stat11.mtimeMs), symbolCount: count, lastIndexed: Date.now() });
-      filesIndexed++;
     }
   }
   if (discoveredFiles) {
@@ -4861,7 +5034,7 @@ function terminateWorker(reason) {
 function callIndexOp(op, args, opts) {
   const w = ensureWorker();
   if (!w) return callInline(op, args, opts);
-  return new Promise((resolve6, reject) => {
+  return new Promise((resolve7, reject) => {
     const id = nextRpcId++;
     const timer = setTimeout(() => {
       pending.delete(id);
@@ -4884,7 +5057,7 @@ function callIndexOp(op, args, opts) {
     pending.set(id, {
       resolve: (v) => {
         cleanup();
-        resolve6(v);
+        resolve7(v);
       },
       reject: (e) => {
         cleanup();
@@ -5076,7 +5249,7 @@ var codebaseSearchTool = {
   name: "codebase-search",
   category: "Project",
   icon: "index",
-  description: "Semantic/keyword search over the indexed codebase symbols (functions, classes, interfaces, etc.). Uses BM25 ranking. Much more powerful and structured than raw `grep` for finding code by name or concept.",
+  description: "Search code symbols using a fast SQLite+BM25 index, with optional LSP fallback. Much more powerful and structured than raw `grep` for finding code by name or concept. Set `preferLsp: true` for live precision when the LSP plugin is active (supersedes codebase-lsp-search).",
   usageHint: "PREFERRED FOR CODE UNDERSTANDING:\n\n- Use when you need to find where something is defined or used by name.\n- `kind` filter is very useful (e.g. only functions or only interfaces).\n- Combine with `file` filter to scope to a specific directory or module.\nThis is generally better than `grep` when you are looking for symbols rather than arbitrary text patterns.",
   permission: "auto",
   mutating: false,
@@ -5110,6 +5283,10 @@ var codebaseSearchTool = {
         description: "Maximum results to return (default 20, max 100)",
         minimum: 1,
         maximum: 100
+      },
+      preferLsp: {
+        type: "boolean",
+        description: "Prefer live LSP results over the index. Index-only when the LSP plugin is not active. When the LSP plugin is active and this is true, results come from live workspaceSymbol queries."
       }
     },
     required: ["query"]
@@ -5374,7 +5551,14 @@ These win over kit tokens. Run \`design {action:"materialize"}\` to write them t
         kitId: active.kit,
         outPath: input.out
       });
-      const abs = path3.join(ctx.projectRoot, result.path);
+      const root = path3.resolve(ctx.projectRoot);
+      const abs = path3.resolve(path3.join(ctx.projectRoot, result.path));
+      const rel = path3.relative(root, abs);
+      if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+        throw new Error(
+          `design: materialize path "${result.path}" would escape the project root`
+        );
+      }
       let exists = false;
       try {
         await fs2.access(abs);
@@ -5533,7 +5717,7 @@ function findGitDir(cwd) {
   return null;
 }
 function runGit(args, cwd, signal) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     const child = spawn("git", args, {
@@ -5549,8 +5733,8 @@ function runGit(args, cwd, signal) {
     child.stderr?.on("data", (c) => {
       stderr += c.toString();
     });
-    child.on("close", (code) => resolve6({ stdout, stderr, exitCode: code ?? 0 }));
-    child.on("error", (e) => resolve6({ stdout: "", stderr: e.message, exitCode: 1 }));
+    child.on("close", (code) => resolve7({ stdout, stderr, exitCode: code ?? 0 }));
+    child.on("error", (e) => resolve7({ stdout: "", stderr: e.message, exitCode: 1 }));
   });
 }
 async function fileDiff(input, ctx, _signal) {
@@ -5589,8 +5773,8 @@ ${numbered}`;
 var documentTool = {
   name: "document",
   category: "Project",
-  description: "Preview documentation comments (JSDoc/TSDoc style) that would be generated for code symbols. Returns a list of candidates with status `skipped` \u2014 the tool is currently a read-only preview and does NOT write to files.",
-  usageHint: "USE FOR IMPROVING CODE DOCUMENTATION:\n\n- Good for adding missing docs to public APIs or complex functions.\n- Currently this is a PREVIEW-ONLY tool: it does not modify files.\n- Use the output to decide which symbols to document manually, or pass the candidates to `edit` / `patch`.\n- `overwrite`, `style`, and `target` parameters are accepted for future expansion but are ignored today.\nAlways review the proposed documentation before applying it \u2014 the model can hallucinate details.",
+  description: "DEPRECATED \u2014 use the `auto_doc` tool with `dryRun: true` instead. This tool is a read-only preview stub that returns `skipped` candidates without generating real docstrings.",
+  usageHint: "Deprecated: prefer `auto_doc` with `dryRun: true` for previewing, or `auto_doc` without dryRun for writing. This tool only lists undocumented symbols with placeholder comments \u2014 it does not generate real JSDoc/TSDoc.",
   permission: "auto",
   mutating: false,
   timeoutMs: 3e4,
@@ -5753,28 +5937,62 @@ var editTool = {
     required: ["path", "old_string", "new_string"]
   },
   async execute(input, ctx) {
-    if (!input?.path) throw new Error("edit: path is required");
-    if (input.old_string === void 0) throw new Error("edit: old_string is required");
-    if (input.new_string === void 0) throw new Error("edit: new_string is required");
-    if (input.old_string === "") throw new Error("edit: old_string cannot be empty");
+    if (!input?.path) {
+      throw new ToolValidationError({ message: "edit: path is required", field: "path" });
+    }
+    if (input.old_string === void 0) {
+      throw new ToolValidationError({
+        message: "edit: old_string is required",
+        field: "old_string"
+      });
+    }
+    if (input.new_string === void 0) {
+      throw new ToolValidationError({
+        message: "edit: new_string is required",
+        field: "new_string"
+      });
+    }
+    if (input.old_string === "") {
+      throw new ToolValidationError({
+        message: "edit: old_string cannot be empty",
+        field: "old_string"
+      });
+    }
     const absPath = await safeResolveReal(input.path, ctx);
     const stat11 = await fs2.stat(absPath).catch((err) => {
       if (err.code === "ENOENT") {
-        throw new Error(`edit: file "${input.path}" does not exist. Use \`write\` instead.`);
+        throw new ToolValidationError({
+          message: `edit: file "${input.path}" does not exist. Use \`write\` instead.`,
+          field: "path",
+          context: { exists: false }
+        });
       }
       throw err;
     });
-    if (!stat11.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
+    if (!stat11.isFile()) {
+      throw new ToolValidationError({
+        message: `edit: "${input.path}" is not a regular file`,
+        field: "path"
+      });
+    }
     const autoRead = !ctx.hasRead(absPath);
     const original = await fs2.readFile(absPath, "utf8");
     const updated = await fs2.stat(absPath);
     const mtimeTolerance = process.platform === "win32" ? 2e3 : 1;
     const lastReadMtime = ctx.lastReadMtime(absPath);
     if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
-      throw new Error(`edit: file "${input.path}" was modified externally. Re-read it first.`);
+      throw new ToolValidationError({
+        message: `edit: file "${input.path}" was modified externally. Re-read it first.`,
+        field: "path",
+        context: { reason: "external_modification" }
+      });
     }
     if (autoRead && updated.mtimeMs > stat11.mtimeMs + mtimeTolerance) {
-      throw new Error(`edit: file "${input.path}" changed while being auto-read. Retry the edit.`);
+      throw new ToolValidationError({
+        message: `edit: file "${input.path}" changed while being auto-read. Retry the edit.`,
+        field: "path",
+        context: { reason: "auto_read_race" }
+      });
     }
     const autoReadNote = autoRead ? `No prior read was recorded for "${input.path}"; edit auto-read the current file and applied the replacement only after the ambiguity checks passed.` : void 0;
     const style = detectNewlineStyle(original);
@@ -5800,15 +6018,18 @@ var editTool = {
     }
     if (count === 0) {
       const hint = findSimilarity(fileLf, oldLf);
-      throw new Error(
-        `edit: no match for old_string in "${input.path}".${hint ? ` Nearest match near line ${hint}.` : ""}`
-      );
+      throw new ToolValidationError({
+        message: `edit: no match for old_string in "${input.path}".${hint ? ` Nearest match near line ${hint}.` : ""}`,
+        field: "old_string"
+      });
     }
     if (count > 1 && !input.replace_all) {
       const lines = lineNumbersFor(fileLf, matches);
-      throw new Error(
-        `edit: old_string matched ${count} times in "${input.path}" (lines: ${lines.join(", ")}). Add more context to make it unique, or set replace_all: true.`
-      );
+      throw new ToolValidationError({
+        message: `edit: old_string matched ${count} times in "${input.path}" (lines: ${lines.join(", ")}). Add more context to make it unique, or set replace_all: true.`,
+        field: "old_string",
+        context: { occurrences: count }
+      });
     }
     const newFileLf = input.replace_all ? fileLf.split(oldLf).join(newLf) : fileLf.replace(oldLf, newLf);
     const newFile = toStyle(newFileLf, style);
@@ -6142,7 +6363,7 @@ var execTool = {
   }
 };
 function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -6150,7 +6371,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     const finish = (result) => {
       if (resolvedOnce.value) return;
       resolvedOnce.value = true;
-      resolve6(result);
+      resolve7(result);
     };
     const startedAt = Date.now();
     const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT2 });
@@ -6327,10 +6548,16 @@ async function guardedFetch(url, maxRedirects, signal, headers = {
   for (; ; ) {
     const parsed = new URL(currentUrl);
     if (parsed.protocol !== "https:" && parsed.protocol !== "http:") {
-      throw new Error(`fetch: redirect to unsupported protocol "${parsed.protocol}"`);
+      throw new ToolValidationError({
+        message: `fetch: redirect to unsupported protocol "${parsed.protocol}"`,
+        field: "url"
+      });
     }
     if (parsed.protocol === "http:" && !ALLOW_PRIVATE) {
-      throw new Error("fetch: redirect to http:// blocked (HTTPS required by default)");
+      throw new ToolValidationError({
+        message: "fetch: redirect to http:// blocked (HTTPS required by default)",
+        field: "url"
+      });
     }
     await assertNotPrivate(parsed.hostname);
     const init = {
@@ -6345,11 +6572,19 @@ async function guardedFetch(url, maxRedirects, signal, headers = {
     }
     redirectCount++;
     if (redirectCount > maxRedirects) {
-      throw new Error(`fetch: exceeded ${maxRedirects} redirects`);
+      throw new FetchError({
+        message: `fetch: exceeded ${maxRedirects} redirects`,
+        status: res.status,
+        context: { url: currentUrl, maxRedirects, redirectCount }
+      });
     }
     const location = res.headers.get("location");
     if (!location) {
-      throw new Error("fetch: redirect status with no location header");
+      throw new FetchError({
+        message: "fetch: redirect status with no location header",
+        status: res.status,
+        context: { url: currentUrl, redirectCount }
+      });
     }
     currentUrl = new URL(location, currentUrl).toString();
   }
@@ -6388,26 +6623,53 @@ var fetchTool = {
   async execute(input, ctx, opts) {
     let final;
     const executeStream = fetchTool.executeStream;
-    if (!executeStream) throw new Error("fetchTool: stream execution unavailable");
+    if (!executeStream) {
+      throw new ToolError({
+        message: "fetchTool: stream execution unavailable",
+        code: "TOOL_EXECUTION_FAILED",
+        toolName: "fetch"
+      });
+    }
     for await (const ev of executeStream(input, ctx, opts)) {
       if (ev.type === "final") final = ev.output;
     }
-    if (!final) throw new Error("fetch: stream ended without final event");
+    if (!final) {
+      throw new ToolError({
+        message: "fetch: stream ended without final event",
+        code: "TOOL_EXECUTION_FAILED",
+        toolName: "fetch"
+      });
+    }
     return final;
   },
   async *executeStream(input, ctx, opts) {
-    if (!input?.url) throw new Error("fetch: url is required");
+    if (!input?.url) {
+      throw new ToolValidationError({
+        message: "fetch: url is required",
+        field: "url"
+      });
+    }
     const u = new URL(input.url);
     if (u.protocol !== "https:" && u.protocol !== "http:") {
-      throw new Error(`fetch: unsupported protocol "${u.protocol}"`);
+      throw new ToolValidationError({
+        message: `fetch: unsupported protocol "${u.protocol}"`,
+        field: "url"
+      });
     }
     if (u.protocol === "http:" && !ALLOW_PRIVATE) {
-      throw new Error("fetch: http:// blocked (HTTPS required by default)");
+      throw new ToolValidationError({
+        message: "fetch: http:// blocked (HTTPS required by default)",
+        field: "url"
+      });
     }
     await assertNotPrivate(u.hostname);
     yield { type: "log", text: `GET ${input.url}` };
     const ctrl = new AbortController();
-    const timer = setTimeout(() => ctrl.abort(new Error("fetch timeout")), TIMEOUT_MS);
+    const timer = setTimeout(() => ctrl.abort(new ToolError({
+      message: "fetch timeout",
+      code: "TOOL_TIMEOUT",
+      toolName: "fetch"
+    })), TIMEOUT_MS);
     const combined = combineSignals([opts.signal, ctrl.signal]);
     try {
       let res;
@@ -6419,7 +6681,11 @@ var fetchTool = {
       }
       const ct = res.headers.get("content-type") ?? "application/octet-stream";
       if (/^image\/|^audio\/|^video\/|application\/octet-stream/.test(ct)) {
-        throw new Error(`fetch: refusing to read binary content-type "${ct}"`);
+        throw new FetchError({
+          message: `fetch: refusing to read binary content-type "${ct}"`,
+          status: res.status,
+          context: { url: res.url, contentType: ct }
+        });
       }
       yield {
         type: "log",
@@ -6484,16 +6750,25 @@ async function assertNotPrivate(hostname2) {
   if (ALLOW_PRIVATE) return;
   const host = hostname2.startsWith("[") && hostname2.endsWith("]") ? hostname2.slice(1, -1) : hostname2;
   if (host === "localhost" || host.endsWith(".localhost")) {
-    throw new Error("fetch: blocked localhost target");
+    throw new ToolValidationError({
+      message: "fetch: blocked localhost target",
+      field: "url"
+    });
   }
   const ipVersion = net.isIP(host);
   if (ipVersion === 4) {
     if (isPrivateIPv4(host)) {
-      throw new Error(`fetch: blocked private/loopback address "${host}"`);
+      throw new ToolValidationError({
+        message: `fetch: blocked private/loopback address "${host}"`,
+        field: "url"
+      });
     }
   } else if (ipVersion === 6) {
     if (isPrivateIPv6(host)) {
-      throw new Error(`fetch: blocked private/loopback address "${host}"`);
+      throw new ToolValidationError({
+        message: `fetch: blocked private/loopback address "${host}"`,
+        field: "url"
+      });
     }
   } else {
     try {
@@ -6501,7 +6776,10 @@ async function assertNotPrivate(hostname2) {
       for (const r of records) {
         const bad = r.family === 4 ? isPrivateIPv4(r.address) : isPrivateIPv6(r.address);
         if (bad) {
-          throw new Error(`fetch: resolved to private address ${r.address}`);
+          throw new ToolValidationError({
+            message: `fetch: resolved to private address ${r.address}`,
+            field: "url"
+          });
         }
       }
     } catch (err) {
@@ -6511,7 +6789,13 @@ async function assertNotPrivate(hostname2) {
 }
 function describeFetchError(err, url, timedOut) {
   if (timedOut) {
-    return new Error(`fetch: GET ${url} timed out after ${TIMEOUT_MS}ms`);
+    return new ToolError({
+      message: `fetch: GET ${url} timed out after ${TIMEOUT_MS}ms`,
+      code: "TOOL_TIMEOUT",
+      toolName: "fetch",
+      context: { url, timedOut: true, timeoutMs: TIMEOUT_MS },
+      cause: err
+    });
   }
   const parts = [];
   const seen = /* @__PURE__ */ new Set();
@@ -6524,7 +6808,15 @@ function describeFetchError(err, url, timedOut) {
     cur = cur.cause;
   }
   const detail = parts.length > 0 ? parts.join(" \u2192 ") : "fetch failed";
-  return new Error(`fetch: GET ${url} failed \u2014 ${detail}`);
+  return new FetchError({
+    message: `fetch: GET ${url} failed \u2014 ${detail}`,
+    status: 502,
+    context: { url, timedOut: false, transportErrors: parts },
+    // Preserve the original undici / DNS / TLS chain so callers can inspect
+    // it via `err.cause` and structured `instanceof` checks. The flattened
+    // text version stays in the message for human readability.
+    cause: err
+  });
 }
 function prettyJson(s) {
   try {
@@ -6872,7 +7164,7 @@ function buildArgs(input) {
   }
 }
 function runGit2(args, cwd, signal) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     const child = spawn("git", args, {
@@ -6893,7 +7185,7 @@ function runGit2(args, cwd, signal) {
       }
     });
     child.on("error", (err) => {
-      resolve6({
+      resolve7({
         command: args[0],
         stdout: normalizeCommandOutput(stdout),
         stderr: err.message,
@@ -6902,7 +7194,7 @@ function runGit2(args, cwd, signal) {
       });
     });
     child.on("close", (code) => {
-      resolve6({
+      resolve7({
         command: args[0],
         stdout: normalizeCommandOutput(stdout),
         stderr: normalizeCommandOutput(stderr),
@@ -6964,7 +7256,7 @@ var globTool = {
   },
   async execute(input, ctx) {
     if (!input?.pattern) throw new Error("glob: pattern is required");
-    const base = input.path ? safeResolve(input.path, ctx) : ctx.cwd;
+    const base = input.path ? await safeResolveReal(input.path, ctx) : ctx.cwd;
     const limit = Math.max(1, Math.min(input.limit ?? 1e3, 5e3));
     const ignored = await readGitignore(base);
     const re = compileGlob(input.pattern);
@@ -7019,8 +7311,12 @@ var globTool = {
           try {
             const st = await fs2.stat(full);
             if (st.isDirectory()) {
+              const real = await fs2.realpath(full);
+              await assertRealInsideRoot(real, ctx);
               subdirs.push({ full, rel });
             } else if (st.isFile()) {
+              const real = await fs2.realpath(full);
+              await assertRealInsideRoot(real, ctx);
               re.lastIndex = 0;
               const relMatch = re.test(rel);
               re.lastIndex = 0;
@@ -7158,13 +7454,21 @@ var grepTool = {
     return final;
   },
   async *executeStream(input, ctx, opts) {
-    if (!input?.pattern) throw new Error("grep: pattern is required");
+    if (!input?.pattern) {
+      throw new ToolValidationError({
+        message: "grep: pattern is required",
+        field: "pattern"
+      });
+    }
     const base = input.path ? safeResolve(input.path, ctx) : ctx.cwd;
     const mode = input.output_mode ?? "content";
     const limit = Math.max(1, Math.min(input.limit ?? 200, 2e3));
     const validation = compileUserRegex(input.pattern, input.case_insensitive ? "i" : "");
     if (!validation.ok) {
-      throw new Error(`grep: ${validation.reason}`);
+      throw new ToolValidationError({
+        message: `grep: ${validation.reason}`,
+        field: "pattern"
+      });
     }
     const rgAvailable = await detectRg(opts.signal);
     if (rgAvailable) {
@@ -7180,13 +7484,13 @@ var grepTool = {
   }
 };
 async function detectRg(signal) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     try {
       const p = spawn("rg", ["--version"], { env: buildChildEnv(), stdio: "ignore", signal, windowsHide: true });
-      p.on("error", () => resolve6(false));
-      p.on("close", (code) => resolve6(code === 0));
+      p.on("error", () => resolve7(false));
+      p.on("close", (code) => resolve7(code === 0));
     } catch {
-      resolve6(false);
+      resolve7(false);
     }
   });
 }
@@ -7320,7 +7624,10 @@ async function runNative(input, base, mode, limit, signal) {
   const flags = input.case_insensitive ? "i" : "";
   const compiled = compileUserRegex(input.pattern, flags);
   if (!compiled.ok) {
-    throw new Error(`grep: ${compiled.reason}`);
+    throw new ToolValidationError({
+      message: `grep: ${compiled.reason}`,
+      field: "pattern"
+    });
   }
   const re = compiled.regex;
   const globRe = input.glob ? compileGlob(input.glob) : null;
@@ -7477,6 +7784,10 @@ var installTool = {
       global: {
         type: "boolean",
         description: "Whether to perform a global install (use with caution)."
+      },
+      lifecycleScripts: {
+        type: "boolean",
+        description: "Opt in to running package lifecycle scripts (preinstall / install / postinstall / prepare / \u2026). Default: false \u2014 installs pass --ignore-scripts so a malicious package cannot execute arbitrary code at install time. Set true to opt back in to the legacy npm/pnpm/yarn default."
       }
     }
   },
@@ -7496,8 +7807,10 @@ var installTool = {
     yield { type: "log", text: `Resolving with ${pkgManager}\u2026`, data: { phase: "resolve" } };
     const save = input.save === "dev" ? "-D" : input.save === "optional" ? "-O" : "";
     const globalFlag = input.global ? ["-g"] : [];
+    const ignoreScripts = input.lifecycleScripts !== true;
     const args = [];
     if (input.dry_run) args.push("--dry-run");
+    if (ignoreScripts) args.push("--ignore-scripts");
     if (pkgManager === "pnpm") {
       if (save) args.push(save);
       args.push("add", ...globalFlag);
@@ -7592,8 +7905,8 @@ function resolveManifestPath(cwd, pkgManager) {
 var jsonTool = {
   name: "json",
   category: "Data",
-  description: "Parse, pretty-print, query, and convert between JSON, JSON5, and YAML. Supports simple path-based queries.",
-  usageHint: "VERY USEFUL FOR DATA INSPECTION:\n\n- Use on package.json, tsconfig, config files, or any structured data.\n- `query` lets you extract specific values without reading the whole file.\n- Great for validating that a file has the expected structure.\nPrefer this over raw `read` + manual parsing when dealing with configuration or data files.",
+  description: "Parse, pretty-print, query, validate, transform, and merge JSON/JSON5/YAML. Use `action` to select the operation: parse (default), query, validate, transform, or merge.",
+  usageHint: 'VERY USEFUL FOR DATA INSPECTION:\n\n- `action: "parse"` (default): read/pretty-print/convert JSON, JSON5, or YAML from `file` or `data`.\n- `action: "query"`: JMESPath-like query (`a.b[0].c`, `items[*].name`, filters, functions).\n- `action: "validate"`: validate data against a JSON Schema (`schema` param).\n- `action: "transform"`: chain multiple JMESPath transforms (`transforms` param).\n- `action: "merge"`: deep merge `base` and `patch` objects (`conflictResolution` param).\nPrefer this over raw `read` + manual parsing when dealing with configuration or data files.',
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
@@ -7602,69 +7915,420 @@ var jsonTool = {
   inputSchema: {
     type: "object",
     properties: {
-      file: { type: "string", description: "Path to JSON/JSON5/YAML file" },
-      data: { type: "string", description: "JSON/JSON5/YAML string (alternative to file)" },
-      query: {
+      action: {
         type: "string",
-        description: 'JMESPath-like query (e.g. "a.b[0].c" or "a[*].name")'
+        enum: ["parse", "query", "validate", "transform", "merge"],
+        description: "Operation (default: parse). parse=read/pretty-print, query=JMESPath, validate=schema, transform=chained queries, merge=deep merge."
       },
+      file: { type: "string", description: "Path to JSON/JSON5/YAML file (parse/query/validate)" },
+      data: { type: "string", description: "JSON/JSON5/YAML string (parse/query/validate, alternative to file)" },
       format: {
         type: "string",
         enum: ["json", "json5", "yaml"],
-        description: "Output format (default: json)"
+        description: "Output format for parse/query/transform (default: json)"
+      },
+      query: {
+        type: "string",
+        description: "JMESPath-like query expression (query action)"
+      },
+      transforms: {
+        type: "array",
+        items: { type: "string" },
+        description: "Ordered JMESPath query strings (transform action)"
+      },
+      schema: {
+        type: "object",
+        description: "JSON Schema to validate against (validate action)"
+      },
+      base: { description: "Base JSON object (merge action)" },
+      patch: { description: "Patch JSON object to merge in (merge action)" },
+      conflictResolution: {
+        type: "string",
+        enum: ["prefer-base", "prefer-patch"],
+        description: "Merge conflict resolution (default: prefer-patch)"
       },
       validate: {
         type: "boolean",
-        description: "Validate syntax only, no output (default: false)"
+        description: "Validate syntax only, no output (parse action, default: false)"
       }
     }
   },
-  async execute(input) {
-    const format = input.format ?? "json";
-    let parsed;
-    let raw;
-    if (input.file) {
-      try {
-        raw = await fs2.readFile(input.file, "utf8");
-      } catch {
-        return { data: null, formatted: "", type: "unknown", error: `Could not read file` };
-      }
-    } else if (input.data) {
-      raw = input.data;
-    } else {
-      return { data: null, formatted: "", type: "unknown", error: "Provide file or data" };
+  async execute(input, ctx) {
+    const action = input.action ?? "parse";
+    switch (action) {
+      case "query":
+        return executeQuery(input, ctx);
+      case "validate":
+        return executeValidate(input, ctx);
+      case "transform":
+        return executeTransform(input, ctx);
+      case "merge":
+        return executeMerge(input);
+      case "parse":
+      default:
+        return executeParse(input, ctx);
     }
+  }
+};
+async function executeParse(input, ctx) {
+  const format = input.format ?? "json";
+  let parsed;
+  let raw;
+  if (input.file) {
     try {
-      parsed = JSON.parse(raw);
-    } catch (e) {
-      return {
-        data: null,
-        formatted: "",
-        type: "unknown",
-        /* v8 ignore next -- JSON.parse only throws SyntaxError (an Error); the String(e) side is defensive. */
-        error: `Parse failed: ${e instanceof Error ? e.message : String(e)}`
-      };
-    }
-    if (input.validate) {
-      return {
-        data: parsed,
-        formatted: "valid",
-        type: Array.isArray(parsed) ? "array" : typeof parsed,
-        keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
-      };
+      raw = await fs2.readFile(await safeResolveReal(input.file, ctx), "utf8");
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "parse", error: "Could not read file" };
     }
-    const queryResult = input.query ? query(parsed, input.query) : void 0;
-    const formatted = formatOutput(queryResult ?? parsed, format);
+  } else if (input.data) {
+    raw = input.data;
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "parse", error: "Provide file or data" };
+  }
+  try {
+    parsed = JSON.parse(raw);
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "parse",
+      /* v8 ignore next -- JSON.parse only throws SyntaxError (an Error); the String(e) side is defensive. */
+      error: `Parse failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+  if (input.validate) {
     return {
       data: parsed,
-      formatted,
+      formatted: "valid",
       type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "parse",
+      keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
+    };
+  }
+  if (input.query) {
+    const queryResult = simpleQuery(parsed, input.query);
+    const formatted2 = formatOutput(queryResult, format);
+    return {
+      data: parsed,
+      formatted: formatted2,
+      type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "parse",
       keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0,
       query_result: queryResult
     };
   }
-};
-function query(data, path22) {
+  const formatted = formatOutput(parsed, format);
+  return {
+    data: parsed,
+    formatted,
+    type: Array.isArray(parsed) ? "array" : typeof parsed,
+    action: "parse",
+    keys: typeof parsed === "object" && parsed !== null ? Object.keys(parsed) : void 0
+  };
+}
+async function executeQuery(input, ctx) {
+  if (!input.query) {
+    return { data: null, formatted: "", type: "unknown", action: "query", error: "query is required for action: query" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs2.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "query", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "query", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "query", error: "Provide file or data" };
+  }
+  try {
+    const result = jmespathSearch(parsed, input.query);
+    const format = input.format ?? "json";
+    return {
+      data: parsed,
+      formatted: formatOutput(result, format),
+      type: result === null ? "null" : Array.isArray(result) ? "array" : typeof result,
+      action: "query",
+      query_result: result
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "query",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Query failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeValidate(input, ctx) {
+  if (!input.schema) {
+    return { data: null, formatted: "", type: "unknown", action: "validate", error: "schema is required for action: validate" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs2.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "validate", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "validate", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "validate", error: "Provide file or data" };
+  }
+  try {
+    const { valid, errors } = validateJsonSchema(parsed, input.schema);
+    return {
+      data: parsed,
+      formatted: valid ? "valid" : "invalid",
+      type: Array.isArray(parsed) ? "array" : typeof parsed,
+      action: "validate",
+      valid,
+      errors
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "validate",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Validation failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeTransform(input, ctx) {
+  if (!input.transforms || input.transforms.length === 0) {
+    return { data: null, formatted: "", type: "unknown", action: "transform", error: "transforms array is required for action: transform" };
+  }
+  let parsed;
+  if (input.file) {
+    try {
+      const raw = await fs2.readFile(await safeResolveReal(input.file, ctx), "utf8");
+      parsed = JSON.parse(raw);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "transform", error: "Could not read/parse file" };
+    }
+  } else if (input.data) {
+    try {
+      parsed = JSON.parse(input.data);
+    } catch {
+      return { data: null, formatted: "", type: "unknown", action: "transform", error: "Could not parse data string" };
+    }
+  } else {
+    return { data: null, formatted: "", type: "unknown", action: "transform", error: "Provide file or data" };
+  }
+  try {
+    let current = parsed;
+    const steps = [];
+    for (const t of input.transforms) {
+      current = jmespathSearch(current, t);
+      steps.push({ transform: t, result: current });
+    }
+    const format = input.format ?? "json";
+    return {
+      data: parsed,
+      formatted: formatOutput(current, format),
+      type: current === null ? "null" : Array.isArray(current) ? "array" : typeof current,
+      action: "transform",
+      result: current,
+      steps
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "transform",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Transform failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+async function executeMerge(input) {
+  if (input.base === void 0 || input.patch === void 0) {
+    return { data: null, formatted: "", type: "unknown", action: "merge", error: "base and patch are required for action: merge" };
+  }
+  const conflictResolution = input.conflictResolution ?? "prefer-patch";
+  try {
+    const result = deepMerge(input.base, input.patch, { conflictResolution });
+    const format = input.format ?? "json";
+    return {
+      data: result,
+      formatted: formatOutput(result, format),
+      type: result === null ? "null" : Array.isArray(result) ? "array" : typeof result,
+      action: "merge",
+      result
+    };
+  } catch (e) {
+    return {
+      data: null,
+      formatted: "",
+      type: "unknown",
+      action: "merge",
+      /* v8 ignore next -- defensive String(e) */
+      error: `Merge failed: ${e instanceof Error ? e.message : String(e)}`
+    };
+  }
+}
+function jmespathSearch(data, query) {
+  if (!query || query === "@") return data;
+  if (query === "$") return data;
+  const dotMatch = query.match(/^([a-zA-Z_][a-zA-Z0-9_]*)(?:\.(.+))?$/);
+  if (dotMatch) {
+    const key = dotMatch[1];
+    const rest = dotMatch[2];
+    const val = data?.[key];
+    if (rest === void 0) return val;
+    return jmespathSearch(val, rest);
+  }
+  const arrMatch = query.match(/^\[(\d+)\](?:\.(.+))?$/);
+  if (arrMatch) {
+    const idx = Number.parseInt(arrMatch[1], 10);
+    const rest = arrMatch[2];
+    const arr = data;
+    const val = arr?.[idx];
+    if (rest === void 0) return val;
+    return jmespathSearch(val, rest);
+  }
+  if (query === "[*]") {
+    if (Array.isArray(data)) {
+      return data;
+    }
+    return data;
+  }
+  const multiMatch = query.match(/^([a-zA-Z_][a-zA-Z0-9_]*)\[\*\](?:\.(.+))?$/);
+  if (multiMatch) {
+    const key = multiMatch[1];
+    const rest = multiMatch[2];
+    const arr = data?.[key];
+    if (!Array.isArray(arr)) return [];
+    if (rest === void 0) return arr;
+    return arr.map((item) => jmespathSearch(item, rest));
+  }
+  const filterMatch = query.match(/^\[\\?([a-zA-Z_][a-zA-Z0-9_]*)(==|!=|<|>|<=|>=)(`[^`]+`|'[^']*')\](?:\.(.+))?$/);
+  if (filterMatch) {
+    const field = filterMatch[1];
+    const op = filterMatch[2];
+    const rawVal = filterMatch[3];
+    const rest = filterMatch[4];
+    const cmpVal = JSON.parse(rawVal.slice(1, -1));
+    const arr = data;
+    if (!Array.isArray(arr)) return [];
+    const filtered = arr.filter((item) => {
+      const itemVal = item[field];
+      switch (op) {
+        case "==":
+          return itemVal === cmpVal;
+        case "!=":
+          return itemVal !== cmpVal;
+        case ">":
+          return Number(itemVal) > Number(cmpVal);
+        case "<":
+          return Number(itemVal) < Number(cmpVal);
+        case ">=":
+          return Number(itemVal) >= Number(cmpVal);
+        case "<=":
+          return Number(itemVal) <= Number(cmpVal);
+        /* v8 ignore next -- op is constrained to the six operators by the filter regex; default is unreachable. */
+        default:
+          return true;
+      }
+    });
+    if (rest === void 0) return filtered;
+    return filtered.map((item) => jmespathSearch(item, rest));
+  }
+  const fnMatch = query.match(/^(length|keys|values|type)\(@\)$/);
+  if (fnMatch) {
+    const fn = fnMatch[1];
+    switch (fn) {
+      case "length":
+        if (Array.isArray(data)) return data.length;
+        if (typeof data === "string") return data.length;
+        if (typeof data === "object" && data !== null) return Object.keys(data).length;
+        return 0;
+      case "keys":
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) return Object.keys(data);
+        return [];
+      case "values":
+        if (typeof data === "object" && data !== null && !Array.isArray(data)) return Object.values(data);
+        return [];
+      case "type":
+        if (data === null) return "null";
+        if (Array.isArray(data)) return "array";
+        return typeof data;
+      /* v8 ignore next 2 -- fn is constrained to the four names by the function regex; default is unreachable. */
+      default:
+        return null;
+    }
+  }
+  return null;
+}
+function validateJsonSchema(data, schema) {
+  const errors = [];
+  function check(value, s, path22) {
+    if (s["type"]) {
+      const expectedType = s["type"];
+      const actualType = Array.isArray(value) ? "array" : value === null ? "null" : typeof value;
+      if (expectedType === "integer") {
+        if (!Number.isInteger(value)) errors.push(`${path22}: expected integer, got ${actualType}`);
+      } else if (expectedType !== actualType) {
+        errors.push(`${path22}: expected ${expectedType}, got ${actualType}`);
+      }
+    }
+    if (typeof value === "string" && s["format"] === "uri" && value) {
+      try {
+        new URL(value);
+      } catch {
+        errors.push(`${path22}: not a valid URI`);
+      }
+    }
+    if (typeof value === "string" && s["pattern"]) {
+      const re = new RegExp(s["pattern"]);
+      if (!re.test(value)) errors.push(`${path22}: does not match pattern ${s["pattern"]}`);
+    }
+    if (typeof value === "string" && s["minLength"] !== void 0 && value.length < s["minLength"]) {
+      errors.push(`${path22}: string too short (min ${s["minLength"]})`);
+    }
+    if (typeof value === "string" && s["maxLength"] !== void 0 && value.length > s["maxLength"]) {
+      errors.push(`${path22}: string too long (max ${s["maxLength"]})`);
+    }
+    if (typeof value === "number" && s["minimum"] !== void 0 && value < s["minimum"]) {
+      errors.push(`${path22}: below minimum ${s["minimum"]}`);
+    }
+    if (typeof value === "number" && s["maximum"] !== void 0 && value > s["maximum"]) {
+      errors.push(`${path22}: above maximum ${s["maximum"]}`);
+    }
+    if (Array.isArray(value) && s["items"] && Array.isArray(s["items"])) {
+      for (let i = 0; i < value.length; i++) {
+        check(value[i], s["items"], `${path22}[${i}]`);
+      }
+    }
+    if (typeof value === "object" && value !== null && !Array.isArray(value) && s["properties"]) {
+      const props = s["properties"];
+      for (const [k, propSchema] of Object.entries(props)) {
+        check(value[k], propSchema, `${path22}.${k}`);
+      }
+    }
+  }
+  check(data, schema, "$");
+  return { valid: errors.length === 0, errors };
+}
+function simpleQuery(data, path22) {
   const parts = path22.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
@@ -7891,7 +8555,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
     };
   }
   args.push("--timestamps", service);
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     const MAX = 2e5;
@@ -7907,7 +8571,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      resolve6(result);
+      resolve7(result);
     };
     const child = spawn("docker", args, { cwd, signal, env: buildChildEnv(), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     const timer = setTimeout(() => {
@@ -8027,8 +8691,8 @@ var outdatedTool = {
   // read-only, but `outdated` makes outbound HTTP calls to the
   // registry. The 'confirm' permission routes the call through the
   // tool.confirm_needed flow on every invocation. M-1 originally
-  // fixed four sibling tools (mcp_control, shellcheck, shellcheck_scan,
-  // web_search) but missed this one; applying the same contract here.
+  // fixed four sibling tools (mcp_control, shellcheck, shellcheck (scan mode),
+  // search) but missed this one; applying the same contract here.
   mutating: true,
   // Capability is outbound network — the tool only hits the package
   // registry over HTTP, never touches the filesystem or runs shell.
@@ -8069,7 +8733,7 @@ var outdatedTool = {
   }
 };
 function runOutdated(manager, args, cwd, signal) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     const MAX = 1e5;
@@ -8086,10 +8750,10 @@ function runOutdated(manager, args, cwd, signal) {
     });
     child.on("close", (code) => {
       const result = parseOutdatedOutput(stdout, code ?? 0);
-      resolve6(result);
+      resolve7(result);
     });
     child.on("error", (e) => {
-      resolve6({
+      resolve7({
         exit_code: 1,
         packages: [],
         total: 0,
@@ -8223,7 +8887,7 @@ function stripPathComponents(p, strip) {
   return parts.slice(strip).join("/");
 }
 function runPatch(args, cwd, signal) {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     let stdout = "";
     let stderr = "";
     const env = { ...buildChildEnv(), LANG: "C", LC_ALL: "C" };
@@ -8234,8 +8898,8 @@ function runPatch(args, cwd, signal) {
     child.stderr?.on("data", (c) => {
       stderr += c.toString();
     });
-    child.on("close", (code) => resolve6({ exitCode: code ?? 1, stdout, stderr }));
-    child.on("error", (e) => resolve6({ exitCode: 1, stdout: "", stderr: e.message }));
+    child.on("close", (code) => resolve7({ exitCode: code ?? 1, stdout, stderr }));
+    child.on("error", (e) => resolve7({ exitCode: 1, stdout: "", stderr: e.message }));
   });
 }
 function extractPatchedFiles(output) {
@@ -8542,19 +9206,49 @@ var readTool = {
     required: ["path"]
   },
   async execute(input, ctx) {
-    if (!input?.path) throw new Error("read: path is required");
+    if (!input?.path) {
+      throw new ToolValidationError({
+        message: "read: path is required",
+        field: "path"
+      });
+    }
     const absPath = await safeResolveReal(input.path, ctx);
     let stat11;
     try {
       stat11 = await fs2.stat(absPath);
     } catch (err) {
       const code = err.code;
-      if (code === "ENOENT") throw new Error(`read: file not found "${input.path}"`);
-      throw new Error(`read: failed to stat "${input.path}": ${toErrorMessage$2(err)}`);
+      if (code === "ENOENT") {
+        throw new FsError({
+          message: `read: file not found "${input.path}"`,
+          code: "FS_READ_FAILED",
+          path: absPath,
+          context: { errno: "ENOENT" }
+        });
+      }
+      throw new FsError({
+        message: `read: failed to stat "${input.path}": ${toErrorMessage$2(err)}`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { errno: code },
+        cause: err
+      });
+    }
+    if (!stat11.isFile()) {
+      throw new FsError({
+        message: `read: "${input.path}" is not a regular file`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "not-a-regular-file" }
+      });
     }
-    if (!stat11.isFile()) throw new Error(`read: "${input.path}" is not a regular file`);
     if (stat11.size > MAX_BYTES2) {
-      throw new Error(`read: file too large (${stat11.size} bytes, limit ${MAX_BYTES2})`);
+      throw new FsError({
+        message: `read: file too large (${stat11.size} bytes, limit ${MAX_BYTES2})`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { size: stat11.size, limit: MAX_BYTES2, reason: "too-large" }
+      });
     }
     const offset = Math.max(1, input.offset ?? 1);
     const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
@@ -8678,8 +9372,8 @@ var DEFAULT_IGNORE4 = ["node_modules", ".git", "dist", "build", ".next", "covera
 var replaceTool = {
   name: "replace",
   category: "Transform",
-  description: "Perform a search-and-replace across multiple files using a regex pattern. This is a powerful bulk transformation tool. Always use `dry_run: true` first on anything non-trivial.",
-  usageHint: "DANGEROUS IF USED CARELESSLY \u2014 review the diff output carefully.\n\nRecommended workflow:\n1. Start with `dry_run: true` to see exactly what would change.\n2. Use a specific enough `pattern` (and `glob` / `files`) to avoid accidental broad changes.\n3. `replace_all` controls whether only the first match per file or all matches are replaced.\nThis tool is excellent for large-scale refactors (renaming, import updates, etc.) but must be used with caution.",
+  description: "Perform a search-and-replace across multiple files using a regex pattern. This is a powerful bulk transformation tool. Dry-run is ON by default \u2014 set `dry_run: false` to apply changes.",
+  usageHint: "DANGEROUS IF USED CARELESSLY \u2014 review the diff output carefully.\n\nRecommended workflow:\n1. Run without `dry_run: false` first to see exactly what would change (dry-run is the default).\n2. Review the diff output, then re-run with `dry_run: false` to apply.\n3. Use a specific enough `pattern` (and `glob` / `files`) to avoid accidental broad changes.\n4. `replace_all` controls whether only the first match per file or all matches are replaced.\nThis tool is excellent for large-scale refactors (renaming, import updates, etc.) but must be used with caution.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -8699,22 +9393,40 @@ var replaceTool = {
         type: "boolean",
         description: "Replace all occurrences in each file (default: true)"
       },
-      dry_run: { type: "boolean", description: "Preview changes without writing" }
+      dry_run: { type: "boolean", description: "Preview changes without writing (default: true)" }
     },
     required: ["pattern", "replacement", "files"]
   },
   async execute(input, ctx) {
-    if (!input?.pattern) throw new Error("replace: pattern is required");
-    if (input.replacement === void 0) throw new Error("replace: replacement is required");
-    if (!input?.files) throw new Error("replace: files is required");
+    if (!input?.pattern) {
+      throw new ToolValidationError({
+        message: "replace: pattern is required",
+        field: "pattern"
+      });
+    }
+    if (input.replacement === void 0) {
+      throw new ToolValidationError({
+        message: "replace: replacement is required",
+        field: "replacement"
+      });
+    }
+    if (!input?.files) {
+      throw new ToolValidationError({
+        message: "replace: files is required",
+        field: "files"
+      });
+    }
     const replaceAll = input.replace_all ?? true;
     const compiled = compileUserRegex(input.pattern, "g");
     if (!compiled.ok) {
-      throw new Error(`replace: ${compiled.reason}`);
+      throw new ToolValidationError({
+        message: `replace: ${compiled.reason}`,
+        field: "pattern"
+      });
     }
     const re = compiled.regex;
     const globRe = input.glob ? compileGlob(input.glob) : null;
-    const dryRun = input.dry_run ?? false;
+    const dryRun = input.dry_run ?? true;
     const filesInput = Array.isArray(input.files) ? input.files.join(",") : input.files;
     const fileList = await resolveFiles2(filesInput, ctx, globRe);
     const realRoot = await fs2.realpath(ctx.projectRoot).catch(() => ctx.projectRoot);
@@ -8810,13 +9522,13 @@ async function globFiles(pattern, base, extraGlob) {
   return await globNative(pattern, base, extraGlob);
 }
 function checkRg() {
-  return new Promise((resolve6) => {
+  return new Promise((resolve7) => {
     try {
       const p = spawn("rg", ["--version"], { env: buildChildEnv(), stdio: "ignore", windowsHide: true });
-      p.on("error", () => resolve6(false));
-      p.on("close", (code) => resolve6(code === 0));
+      p.on("error", () => resolve7(false));
+      p.on("close", (code) => resolve7(code === 0));
     } catch {
-      resolve6(false);
+      resolve7(false);
     }
   });
 }
@@ -8833,10 +9545,10 @@ function spawnRgFind(pattern, base) {
     buf += chunk.toString();
   });
   return {
-    promise: new Promise((resolve6, reject) => {
+    promise: new Promise((resolve7, reject) => {
       child.on("error", reject);
       child.on("close", () => {
-        resolve6(buf.split("\n").filter(Boolean));
+        resolve7(buf.split("\n").filter(Boolean));
       });
     })
   };
@@ -9063,11 +9775,13 @@ function substituteVars(content, name, vars) {
 var DEFAULT_NUM = 10;
 var MAX_RESULTS = 50;
 var TIMEOUT_MS3 = 15e3;
+var CACHE_TTL_MS = 3e5;
+var cache = /* @__PURE__ */ new Map();
 var searchTool = {
   name: "search",
   category: "Search",
-  description: "Perform a web search and return results with title, URL, and snippet. Use this when you need up-to-date external information that is not in the local codebase.",
-  usageHint: "Good for: API documentation, error messages, library usage examples, current best practices.\n\n- Prefer specific queries over very broad ones.\n- Results go through the guarded fetch system (same protections as the `fetch` tool).\n- This is often better than the model trying to recall outdated knowledge.",
+  description: "Perform a web search and return results with title, URL, and snippet. Use this when you need up-to-date external information that is not in the local codebase. Results are cached (5 min TTL) and deduplicated by URL.",
+  usageHint: "Good for: API documentation, error messages, library usage examples, current best practices.\n\n- Prefer specific queries over very broad ones.\n- Results go through the guarded fetch system (same protections as the `fetch` tool).\n- Supports duckduckgo (default), google, and bing sources.\n- Set `skip_cache: true` to force a fresh search.\n- This is often better than the model trying to recall outdated knowledge.",
   permission: "confirm",
   mutating: false,
   capabilities: ["net.outbound"],
@@ -9087,6 +9801,10 @@ var searchTool = {
         type: "string",
         enum: ["duckduckgo", "google", "bing"],
         description: "Search engine to use (default: duckduckgo)"
+      },
+      skip_cache: {
+        type: "boolean",
+        description: "Skip the in-memory cache and force a fresh search (default: false)"
       }
     },
     required: ["query"]
@@ -9102,57 +9820,135 @@ var searchTool = {
     return final;
   },
   async *executeStream(input, _ctx, opts) {
-    if (!input?.query) throw new Error("search: query is required");
+    if (!input?.query || input.query.trim() === "") {
+      throw new ToolValidationError({
+        message: "search: query is required and must be a non-empty string",
+        field: "query"
+      });
+    }
     const num = Math.max(1, Math.min(input.num_results ?? DEFAULT_NUM, MAX_RESULTS));
     const source = input.source ?? "duckduckgo";
+    const skipCache = input.skip_cache ?? false;
+    const cacheKey = `${source}:${input.query}`;
+    if (!skipCache) {
+      const entry = cache.get(cacheKey);
+      if (entry && Date.now() - entry.timestamp < CACHE_TTL_MS) {
+        const results = entry.results.map((r) => ({
+          title: r.title,
+          url: r.url,
+          snippet: r.snippet
+        }));
+        yield {
+          type: "log",
+          text: `Cache hit for "${input.query}" (${source})`,
+          data: { source, query: input.query, cached: true }
+        };
+        yield {
+          type: "partial_output",
+          text: `${results.length} cached results from ${source}`,
+          data: { count: results.length, cached: true }
+        };
+        yield {
+          type: "final",
+          output: {
+            query: input.query,
+            results: results.slice(0, num),
+            source,
+            truncated: results.length >= num,
+            cached: true
+          }
+        };
+        return;
+      }
+    }
     yield {
       type: "log",
       text: `Querying ${source} for "${input.query}"\u2026`,
-      data: { source, query: input.query }
+      data: { source, query: input.query, cached: false }
     };
-    let output;
+    let rawResults;
     switch (source) {
       case "duckduckgo":
-        output = await duckduckgoSearch(input.query, num, opts.signal);
+        rawResults = await duckduckgoSearch(input.query, num, opts.signal);
         break;
       case "google":
-        output = await googleSearch(input.query, num, opts.signal);
+        rawResults = await googleSearch(input.query, num, opts.signal);
         break;
       case "bing":
-        output = await bingSearch(input.query, num, opts.signal);
+        rawResults = await bingSearch(input.query, num, opts.signal);
         break;
       default:
-        throw new Error(`search: unknown source "${source}"`);
+        throw new ToolValidationError({
+          message: `search: unknown source "${source}"`,
+          field: "source"
+        });
     }
+    const seenUrls = /* @__PURE__ */ new Set();
+    const deduped = [];
+    for (const r of rawResults) {
+      const noQuery = r.url.split("?")[0] ?? r.url;
+      const normalized = noQuery.split("#")[0] ?? r.url;
+      if (!seenUrls.has(normalized) && r.url.startsWith("http")) {
+        seenUrls.add(normalized);
+        deduped.push(r);
+      }
+    }
+    const ranked = scoreResults(deduped, input.query);
+    const finalResults = ranked.slice(0, num);
+    cache.set(cacheKey, { results: ranked, timestamp: Date.now() });
+    pruneStaleCacheEntries();
     yield {
       type: "partial_output",
-      text: `${output.results.length} results from ${output.source}`,
-      data: { count: output.results.length }
+      text: `${finalResults.length} results from ${source}`,
+      data: { count: finalResults.length, cached: false }
+    };
+    yield {
+      type: "final",
+      output: {
+        query: input.query,
+        results: finalResults.map((r) => ({
+          title: r.title,
+          url: r.url,
+          snippet: r.snippet
+        })),
+        source,
+        truncated: finalResults.length >= num,
+        cached: false
+      }
     };
-    yield { type: "final", output };
   }
 };
-async function duckduckgoSearch(query2, num, signal) {
-  const encoded = encodeURIComponent(query2);
+function pruneStaleCacheEntries() {
+  const cutoff = Date.now() - CACHE_TTL_MS * 2;
+  for (const [key, entry] of cache.entries()) {
+    if (entry.timestamp < cutoff) cache.delete(key);
+  }
+}
+function scoreResults(results, query) {
+  const terms = query.toLowerCase().split(/\s+/).filter((t) => t.length > 0);
+  return results.map((r) => {
+    const titleLower = r.title.toLowerCase();
+    const snippetLower = r.snippet.toLowerCase();
+    let score = r.score;
+    for (const term of terms) {
+      if (titleLower.includes(term)) score += 2;
+      if (snippetLower.includes(term)) score += 1;
+    }
+    return { ...r, score };
+  }).sort((a, b) => b.score - a.score);
+}
+async function duckduckgoSearch(query, num, signal) {
+  const encoded = encodeURIComponent(query);
   const url = `https://lite.duckduckgo.com/lite/?q=${encoded}&kd=-1&kl=wt-wt`;
   try {
     const response = await fetchWithTimeout(url, signal, TIMEOUT_MS3);
     const html = await response.text();
-    const results = parseDuckDuckGo(html, num);
-    return {
-      query: query2,
-      results,
-      source: "duckduckgo",
-      truncated: results.length >= num
-    };
+    return parseDuckDuckGo(html, num);
   } catch (err) {
-    console.log(JSON.stringify({ level: "debug", event: "search_failed", query: query2, error: toErrorMessage$3(err) }));
-    return {
-      query: query2,
-      results: [{ title: "Search unavailable", url: "", snippet: "Could not reach DuckDuckGo" }],
-      source: "duckduckgo",
-      truncated: false
-    };
+    console.log(
+      JSON.stringify({ level: "debug", event: "search_failed", query, error: toErrorMessage$3(err) })
+    );
+    return [{ title: "Search unavailable", url: "https://duckduckgo.com/unavailable", snippet: "Could not reach DuckDuckGo", score: 0 }];
   }
 }
 function takeFrom(iter, max) {
@@ -9177,25 +9973,22 @@ function parseDuckDuckGo(html, num) {
   );
   for (let i = 0; i < linkMatches.length && i < num; i++) {
     const entry = linkMatches[i];
-    results.push({
-      title: entry?.title ?? "",
-      url: entry?.url ?? "",
-      snippet: snippetMatches[i] ?? ""
-    });
+    if (entry) {
+      results.push({
+        title: entry.title ?? "",
+        url: entry.url ?? "",
+        snippet: snippetMatches[i] ?? "",
+        score: 1
+      });
+    }
   }
   return results;
 }
-async function googleSearch(query2, num, signal) {
-  const encoded = encodeURIComponent(query2);
+async function googleSearch(query, num, signal) {
+  const encoded = encodeURIComponent(query);
   const url = `https://www.google.com/search?q=${encoded}&hl=en`;
   const html = await fetchWithTimeout(url, signal, TIMEOUT_MS3).then((r) => r.text()).catch(() => "");
-  const results = parseGoogleResults(html, num);
-  return {
-    query: query2,
-    results,
-    source: "google",
-    truncated: results.length >= num
-  };
+  return parseGoogleResults(html, num);
 }
 function parseGoogleResults(html, num) {
   const results = [];
@@ -9218,22 +10011,17 @@ function parseGoogleResults(html, num) {
     results.push({
       title: titles[i] ?? "",
       url: urls[i] ?? "",
-      snippet: snippets[i] ?? ""
+      snippet: snippets[i] ?? "",
+      score: 1
     });
   }
   return results;
 }
-async function bingSearch(query2, num, signal) {
-  const encoded = encodeURIComponent(query2);
+async function bingSearch(query, num, signal) {
+  const encoded = encodeURIComponent(query);
   const url = `https://www.bing.com/search?q=${encoded}`;
   const html = await fetchWithTimeout(url, signal, TIMEOUT_MS3).then((r) => r.text()).catch(() => "");
-  const results = parseBingResults(html, num);
-  return {
-    query: query2,
-    results,
-    source: "bing",
-    truncated: results.length >= num
-  };
+  return parseBingResults(html, num);
 }
 function parseBingResults(html, num) {
   const results = [];
@@ -9248,11 +10036,15 @@ function parseBingResults(html, num) {
     num
   );
   for (let i = 0; i < entries.length; i++) {
-    results.push({
-      title: entries[i]?.title ?? "",
-      url: entries[i]?.url ?? "",
-      snippet: snippets[i] ?? ""
-    });
+    const entry = entries[i];
+    if (entry) {
+      results.push({
+        title: entry.title ?? "",
+        url: entry.url ?? "",
+        snippet: snippets[i] ?? "",
+        score: 1
+      });
+    }
   }
   return results;
 }
@@ -9268,7 +10060,15 @@ async function fetchWithTimeout(url, signal, timeoutMs) {
     return res;
   } catch (e) {
     clearTimeout(timer);
-    throw e;
+    if (e instanceof FetchError) {
+      throw e;
+    }
+    throw new FetchError({
+      message: `search: failed to fetch ${url}`,
+      status: 0,
+      context: { url },
+      cause: e
+    });
   }
 }
 function anySignal(...signals) {
@@ -9332,15 +10132,15 @@ var setWorkingDirTool = {
     };
   }
 };
-function findTaskIndex(tasks, query2) {
-  const asNum = Number.parseInt(query2, 10);
+function findTaskIndex(tasks, query) {
+  const asNum = Number.parseInt(query, 10);
   if (!Number.isNaN(asNum)) {
     const idx = asNum - 1;
     if (tasks[idx]) return idx;
   }
-  const byId = tasks.findIndex((t) => t.id === query2);
+  const byId = tasks.findIndex((t) => t.id === query);
   if (byId >= 0) return byId;
-  const lower = query2.toLowerCase();
+  const lower = query.toLowerCase();
   return tasks.findIndex((t) => t.title.toLowerCase().includes(lower));
 }
 var taskTool = {
@@ -9964,8 +10764,8 @@ var todoTool = {
 var toolHelpTool = {
   name: "tool_help",
   category: "Meta",
-  description: "Get detailed help for one or more tools, including their full schema and usage guidance. This is the best way to understand exactly how to call a specific tool.",
-  usageHint: "USE WHEN YOU NEED PRECISE TOOL INFORMATION:\n\n- Call with a specific `tool` name when you want the full schema and current usageHint.\n- Omit `tool` (or use a broad query) to get an overview of available tools.\n- Different `format` options give you different levels of detail.\nThis tool is extremely valuable for self-correction when you are unsure about a tool's interface.",
+  description: "Get detailed help for a specific tool, including its full input schema and usage guidance. If you do not know which tool to use, search with `tool_search` first, then call this with the tool name.",
+  usageHint: "USE WHEN YOU NEED PRECISE TOOL INFORMATION:\n\n- Call with a specific `tool` name when you want the full schema and current usageHint.\n- Omit `tool` to get an overview of all available tools.\n- Different `format` options give you different levels of detail.\n- Tip: use `tool_search` to find the right tool name, then `tool_help` for the full schema.\nThis tool is extremely valuable for self-correction when you are unsure about a tool's interface.",
   permission: "auto",
   mutating: false,
   timeoutMs: 5e3,
@@ -10088,8 +10888,8 @@ function formatAllToolsMarkdown(tools) {
 var toolSearchTool = {
   name: "tool_search",
   category: "Meta",
-  description: "Search the catalog of available tools. Very useful when you are unsure which tool to use for a task.",
-  usageHint: "SELF-DISCOVERY TOOL:\n\n- Use when you need to find the right tool for a job.\n- `query` searches names and descriptions.\n- You can filter by `tags` (category), `permission`, or `mutating`.\nCall this before guessing tool names. It helps you discover the best tool for the current situation.",
+  description: "Search the catalog of available tools by name or description. Use this to discover which tool to use for a task. For the full schema and usage details of a specific tool, use `tool_help` instead.",
+  usageHint: "SELF-DISCOVERY TOOL:\n\n- Use when you need to find the right tool for a job.\n- `query` searches names and descriptions.\n- You can filter by `tags` (category), `permission`, or `mutating`.\n- Once you find the right tool name, use `tool_help` with that name for full schema details.\nCall this before guessing tool names. It helps you discover the best tool for the current situation.",
   permission: "auto",
   mutating: false,
   timeoutMs: 1e3,
@@ -10127,9 +10927,9 @@ var toolSearchTool = {
   async execute(input, ctx) {
     const limit = Math.min(input.limit ?? 20, 100);
     const tools = ctx.tools;
-    const query2 = input.query?.toLowerCase() ?? "";
+    const query = input.query?.toLowerCase() ?? "";
     const filtered = tools.filter((t) => {
-      if (query2 && !t.name.toLowerCase().includes(query2) && !t.description.toLowerCase().includes(query2)) {
+      if (query && !t.name.toLowerCase().includes(query) && !t.description.toLowerCase().includes(query)) {
         return false;
       }
       if (input.tags && input.tags.length > 0) {
@@ -10153,7 +10953,7 @@ var toolSearchTool = {
       mutating: t.mutating
     }));
     const totalAvailable = tools.length;
-    const hint = results.length === 0 && query2 ? `No tools matched "${input.query}". Use tool-help (without arguments) to see all ${totalAvailable} available tools.` : void 0;
+    const hint = results.length === 0 && query ? `No tools matched "${input.query}". Use tool-help (without arguments) to see all ${totalAvailable} available tools.` : void 0;
     return {
       tools: results,
       total: filtered.length,
@@ -10526,8 +11326,18 @@ var writeTool = {
     required: ["path", "content"]
   },
   async execute(input, ctx) {
-    if (!input?.path) throw new Error("write: path is required");
-    if (input.content === void 0) throw new Error("write: content is required");
+    if (!input?.path) {
+      throw new ToolValidationError({
+        message: "write: path is required",
+        field: "path"
+      });
+    }
+    if (input.content === void 0) {
+      throw new ToolValidationError({
+        message: "write: content is required",
+        field: "content"
+      });
+    }
     const absPath = await safeResolveReal(input.path, ctx);
     let existed = false;
     let prev = "";