@wrongstack/tools 0.265.1 → 0.268.0

package/dist/builtin.js

@@ -1,6 +1,6 @@
 import { spawn, execFileSync, spawnSync } from 'node:child_process';
 import * as Core from '@wrongstack/core';
-import { buildChildEnv, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, isPrivateIPv4, isPrivateIPv6, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
+import { buildChildEnv, detectNewlineStyle, normalizeToLf, toStyle, atomicWrite, unifiedDiff, isPrivateIPv4, isPrivateIPv6, assessCommitSafety, compileGlob, expectDefined, recordPackageAction, detectPackageEcosystem, mutatePlan, clearPlan, getPlanTemplate, addPlanItem, deriveTodosFromPlanItem, removePlanItem, setPlanItemStatus, mutateTasks, formatTaskList, formatPlan, computeTaskItemProgress, loadPlan, savePlan, loadTasks, saveTasks, wstackGlobalRoot, resolveWstackPaths, truncate } from '@wrongstack/core';
 import * as fs from 'node:fs';
 import { statSync, mkdirSync, createWriteStream, writeFileSync } from 'node:fs';
 import * as fs14 from 'node:fs/promises';
@@ -763,8 +763,8 @@ async function* spawnStream(opts) {
   try {
     for (; ; ) {
       while (queue.length === 0) {
-        await new Promise((resolve7) => {
-          waiter = resolve7;
+        await new Promise((resolve6) => {
+          waiter = resolve6;
         });
       }
       const chunk = queue.shift();
@@ -1319,10 +1319,10 @@ var bashTool = {
         queue.push(c);
       }
     };
-    const next = () => new Promise((resolve7) => {
+    const next = () => new Promise((resolve6) => {
       const c = queue.shift();
-      if (c) resolve7(c);
-      else resolveNext = resolve7;
+      if (c) resolve6(c);
+      else resolveNext = resolve6;
     });
     let lastFlush = Date.now();
     const flush = () => {
@@ -3530,8 +3530,9 @@ async function loadGitignoreMatcher(projectRoot) {
 
 // src/codebase-index/indexer.ts
 var YIELD_EVERY_N = 50;
+var PARALLEL_BATCH = 20;
 function yieldEventLoop() {
-  return new Promise((resolve7) => setImmediate(resolve7));
+  return new Promise((resolve6) => setImmediate(resolve6));
 }
 function throwIfAborted(signal) {
   if (!signal?.aborted) return;
@@ -3663,97 +3664,108 @@ async function runIndexerWithStore(store, opts) {
   if (!force) {
     for (const meta of store.getAllFileMetas()) existingMeta.set(meta.file, meta);
   }
-  for (let fi = 0; fi < files.length; fi++) {
-    const file = expectDefined(files[fi]);
-    opts.onProgress?.(fi + 1, files.length);
-    if (fi > 0 && fi % YIELD_EVERY_N === 0) {
+  for (let batchStart = 0; batchStart < files.length; batchStart += PARALLEL_BATCH) {
+    const batchEnd = Math.min(batchStart + PARALLEL_BATCH, files.length);
+    const batchFiles = files.slice(batchStart, batchEnd);
+    opts.onProgress?.(batchEnd, files.length);
+    if (batchStart > 0 && batchStart % YIELD_EVERY_N === 0) {
       await yieldEventLoop();
       throwIfAborted(signal);
     }
-    let stat11;
-    try {
-      const statOpts = signal ? { signal } : {};
-      stat11 = await fs14.stat(file, statOpts);
-    } catch (e) {
-      if (isAbortError(e)) throw e;
-      store.deleteFile(file);
-      continue;
-    }
-    if (!stat11.isFile()) continue;
-    const lang = detectLang(file);
-    if (!lang) continue;
-    const meta = existingMeta.get(file);
-    if (!force && meta && meta.mtimeMs === Math.floor(stat11.mtimeMs)) {
-      langStats[lang] = (langStats[lang] ?? 0) + meta.symbolCount;
-      symbolsIndexed += meta.symbolCount;
-      filesIndexed++;
-      continue;
-    }
-    store.deleteRefsForFile(file);
-    store.deleteSymbolsForFile(file);
-    let content;
-    try {
-      content = await fs14.readFile(file, { encoding: "utf8", signal });
-    } catch (e) {
-      if (isAbortError(e)) throw e;
-      errors.push(`read error: ${file}: ${e instanceof Error ? e.message : String(e)}`);
-      continue;
-    }
-    let parsed;
-    try {
-      parsed = await parseFile(file, content, lang);
-    } catch (e) {
-      errors.push(`parse error: ${file}: ${e instanceof Error ? e.message : String(e)}`);
-      continue;
-    }
-    if (parsed.symbols.length === 0) {
-      store.upsertFile({
-        file,
-        lang,
-        mtimeMs: Math.floor(stat11.mtimeMs),
-        symbolCount: 0,
-        lastIndexed: Date.now()
-      });
-      filesIndexed++;
-      continue;
-    }
-    const nextId = store.getMaxSymbolId() + 1;
-    const symbolsWithIds = parsed.symbols.map((s, i) => ({ ...s, id: nextId + i }));
-    store.insertSymbols(symbolsWithIds, nextId);
-    const count = symbolsWithIds.length;
-    symbolsIndexed += count;
-    langStats[lang] = (langStats[lang] ?? 0) + count;
-    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);
+    const statOpts = signal ? { signal } : {};
+    const statReadParse = await Promise.allSettled(
+      batchFiles.map(async (file) => {
+        let stat11;
+        try {
+          stat11 = await fs14.stat(file, statOpts);
+        } catch (e) {
+          if (isAbortError(e)) throw e;
+          return { file, stat: null, lang: "", parsed: null, error: `stat error: ${e instanceof Error ? e.message : String(e)}` };
         }
-        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 });
-          }
+        if (!stat11.isFile()) return { file, stat: stat11, lang: "", parsed: null };
+        const lang = detectLang(file);
+        if (!lang) return { file, stat: stat11, lang: "", parsed: null };
+        let content;
+        try {
+          content = await fs14.readFile(file, { encoding: "utf8", signal });
+        } catch (e) {
+          if (isAbortError(e)) throw e;
+          return { file, stat: stat11, lang, parsed: null, error: `read error: ${e instanceof Error ? e.message : String(e)}` };
+        }
+        let parsed;
+        try {
+          parsed = await parseFile(file, content, lang);
+        } catch (e) {
+          return { file, stat: stat11, lang, parsed: null, error: `parse error: ${e instanceof Error ? e.message : String(e)}` };
         }
+        return { file, stat: stat11, lang, parsed, content };
+      })
+    );
+    for (let fi = 0; fi < statReadParse.length; fi++) {
+      const settled = statReadParse[fi];
+      const file = expectDefined(batchFiles[fi]);
+      if (settled.status === "rejected") {
+        const err = settled.reason;
+        if (err instanceof Error && isAbortError(err)) throw err;
+        errors.push(`batch error: ${file}: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+      const result = settled.value;
+      if (result.error) {
+        if (result.stat) store.deleteFile(file);
+        if (result.error.includes("error:")) errors.push(result.error);
+        continue;
       }
-      if (batch.length > 0) {
-        store.insertRefsBatch(batch);
+      const { stat: stat11, lang, parsed } = result;
+      if (!lang || !parsed) {
+        if (lang) {
+          store.upsertFile({ file, lang, mtimeMs: Math.floor(stat11.mtimeMs), symbolCount: 0, lastIndexed: Date.now() });
+          filesIndexed++;
+        }
+        continue;
       }
+      const meta = existingMeta.get(file);
+      if (!force && meta && meta.mtimeMs === Math.floor(stat11.mtimeMs)) {
+        langStats[lang] = (langStats[lang] ?? 0) + meta.symbolCount;
+        symbolsIndexed += meta.symbolCount;
+        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() });
+        filesIndexed++;
+        continue;
+      }
+      const nextId = store.getMaxSymbolId() + 1;
+      const symbolsWithIds = parsed.symbols.map((s, i) => ({ ...s, id: nextId + i }));
+      store.insertSymbols(symbolsWithIds, nextId);
+      const count = symbolsWithIds.length;
+      symbolsIndexed += count;
+      langStats[lang] = (langStats[lang] ?? 0) + count;
+      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);
+          }
+          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 });
+          }
+        }
+        if (batch.length > 0) store.insertRefsBatch(batch);
+      }
+      store.upsertFile({ file, lang, mtimeMs: Math.floor(stat11.mtimeMs), symbolCount: count, lastIndexed: Date.now() });
+      filesIndexed++;
     }
-    store.upsertFile({
-      file,
-      lang,
-      mtimeMs: Math.floor(stat11.mtimeMs),
-      symbolCount: count,
-      lastIndexed: Date.now()
-    });
-    filesIndexed++;
   }
   for (const [file_] of existingMeta) {
     try {
@@ -3920,7 +3932,7 @@ function terminateWorker(reason) {
 function callIndexOp(op, args, opts) {
   const w = ensureWorker();
   if (!w) return callInline(op, args, opts);
-  return new Promise((resolve7, reject) => {
+  return new Promise((resolve6, reject) => {
     const id = nextRpcId++;
     const timer = setTimeout(() => {
       pending.delete(id);
@@ -3943,7 +3955,7 @@ function callIndexOp(op, args, opts) {
     pending.set(id, {
       resolve: (v) => {
         cleanup();
-        resolve7(v);
+        resolve6(v);
       },
       reject: (e) => {
         cleanup();
@@ -4369,7 +4381,7 @@ function findGitDir(cwd) {
   return null;
 }
 function runGit(args, cwd, signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     const child = spawn("git", args, {
@@ -4385,8 +4397,8 @@ function runGit(args, cwd, signal) {
     child.stderr?.on("data", (c) => {
       stderr += c.toString();
     });
-    child.on("close", (code) => resolve7({ stdout, stderr, exitCode: code ?? 0 }));
-    child.on("error", (e) => resolve7({ stdout: "", stderr: e.message, exitCode: 1 }));
+    child.on("close", (code) => resolve6({ stdout, stderr, exitCode: code ?? 0 }));
+    child.on("error", (e) => resolve6({ stdout: "", stderr: e.message, exitCode: 1 }));
   });
 }
 async function fileDiff(input, ctx, _signal) {
@@ -4571,8 +4583,8 @@ function processFile(content, absPath, _style, _overwrite, target) {
 var editTool = {
   name: "edit",
   category: "Filesystem",
-  description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It requires that you have previously called `read` on the file in the current session. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
-  usageHint: "MANDATORY WORKFLOW:\n1. Call `read` on the target file first (in the same conversation).\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nThis tool is much safer than `write` for existing files because it works against the last-read version.",
+  description: "Perform a precise, surgical text replacement in a file. This is the preferred tool for modifying existing code. It works best after a prior `read`, but can auto-read the current file when the replacement is still unambiguous. Fails safely if the `old_string` appears more than once unless `replace_all` is set.",
+  usageHint: "RECOMMENDED WORKFLOW:\n1. Prefer calling `read` on the target file first when planning an edit.\n2. Use a sufficiently unique `old_string` (include surrounding lines/context if needed).\n3. If the string appears multiple times and you want to change all of them, set `replace_all: true`.\n4. `new_string` must be the exact replacement text.\n\nIf no prior read is recorded, the tool auto-reads the current file and only applies the edit after the same ambiguity checks pass.",
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
@@ -4601,9 +4613,7 @@ var editTool = {
       throw err;
     });
     if (!stat11.isFile()) throw new Error(`edit: "${input.path}" is not a regular file`);
-    if (!ctx.hasRead(absPath)) {
-      throw new Error(`edit: file "${input.path}" was not read in this session. Read it first.`);
-    }
+    const autoRead = !ctx.hasRead(absPath);
     const original = await fs14.readFile(absPath, "utf8");
     const updated = await fs14.stat(absPath);
     const mtimeTolerance = process.platform === "win32" ? 2e3 : 1;
@@ -4611,15 +4621,21 @@ var editTool = {
     if (lastReadMtime !== void 0 && updated.mtimeMs > lastReadMtime + mtimeTolerance) {
       throw new Error(`edit: file "${input.path}" was modified externally. Re-read it first.`);
     }
+    if (autoRead && updated.mtimeMs > stat11.mtimeMs + mtimeTolerance) {
+      throw new Error(`edit: file "${input.path}" changed while being auto-read. Retry the edit.`);
+    }
+    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);
     const fileLf = normalizeToLf(original);
     const oldLf = normalizeToLf(input.old_string);
     const newLf = normalizeToLf(input.new_string);
     if (oldLf === newLf) {
+      if (autoRead) ctx.recordRead(absPath, updated.mtimeMs);
       return {
         path: absPath,
         replacements: 0,
-        diff: "(no-op: old and new are identical)"
+        diff: "(no-op: old and new are identical)",
+        note: autoReadNote
       };
     }
     let count = 0;
@@ -4660,7 +4676,8 @@ var editTool = {
     return {
       path: absPath,
       replacements: input.replace_all ? count : 1,
-      diff
+      diff,
+      note: autoReadNote
     };
   }
 };
@@ -4872,26 +4889,26 @@ var execTool = {
         allowed: false
       };
     }
-    const requestedCwd = input.cwd ? path3.resolve(ctx.projectRoot, input.cwd) : ctx.cwd;
-    const rel = path3.relative(ctx.projectRoot, requestedCwd);
-    if (rel.startsWith("..") || path3.isAbsolute(rel)) {
+    let cwd;
+    try {
+      cwd = input.cwd ? await safeResolveReal(input.cwd, ctx) : await safeResolveReal(ctx.cwd, ctx);
+    } catch {
       return {
         command: cmd,
         args,
         stdout: "",
-        stderr: `cwd "${input.cwd}" resolves outside project root`,
+        stderr: `cwd "${input.cwd ?? ctx.cwd}" resolves outside project root`,
         exitCode: 1,
         truncated: false,
         allowed: false
       };
     }
-    const cwd = requestedCwd;
     const signal = opts.signal;
     return runCommand(cmd, args, cwd, timeout, signal, ctx.session?.id);
   }
 };
 function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     let killed = false;
@@ -4946,7 +4963,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       const exitCode = killed ? 124 : code ?? 1;
       registry.afterCall(durationMs, exitCode !== 0);
       const spooled = spool.finalize();
-      resolve7({
+      resolve6({
         command: cmd,
         args,
         stdout: normalizeCommandOutput(stdout) + (spooled ? spoolNote(spooled) : ""),
@@ -4962,7 +4979,7 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
       if (typeof pid === "number") registry.unregister(pid);
       registry.afterCall(Date.now() - startedAt, true);
       spool.finalize();
-      resolve7({
+      resolve6({
         command: cmd,
         args,
         stdout: normalizeCommandOutput(stdout),
@@ -5336,7 +5353,7 @@ var gitTool = {
   name: "git",
   category: "Git",
   description: "Safe wrapper around common git operations. Supports status, log, diff, commit, branch, checkout, stash, push, pull, fetch, reset, worktree, etc. This is the preferred way to interact with git instead of using the raw `bash` or `exec` tools.",
-  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
+  usageHint: "ALWAYS prefer this tool over raw shell git commands.\n\nKey fields:\n- `command`: one of the supported subcommands (status, log, diff, commit, etc.)\n- Use `message` only for commit operations.\n- Use `files` array for operations that take paths (status, diff, add, etc.).\n- Non-mutating commands (status, log, diff, branch, fetch) are still permission:confirm for safety.\n- For `commit` in a possibly-shared working tree, pass an explicit `files` list scoped to what YOU changed. A bare commit (no `files`) includes ALL staged changes and may capture another agent's half-done work. Heed the `warning` field on the result.\nNever pass raw git flags through `args` for dangerous operations \u2014 use the structured fields.",
   permission: "confirm",
   icon: "git",
   // Conservative: any of these may mutate. The non-mutating commands
@@ -5425,6 +5442,22 @@ var gitTool = {
       };
     }
     const args = buildArgs(input);
+    let safetyWarning;
+    if (input.command === "commit") {
+      try {
+        const report = await assessCommitSafety({
+          cwd: ctx.cwd,
+          projectRoot: ctx.projectRoot,
+          sessionId: ctx.session?.id,
+          signal: opts.signal
+        });
+        if (report.warning) {
+          const scopeNote = input.files ? "" : "\nNote: this commit has no explicit `files` list, so it will include ALL staged changes. Pass `files` to scope the commit to only what you changed.";
+          safetyWarning = report.warning + scopeNote;
+        }
+      } catch {
+      }
+    }
     let stagedDiff;
     if (input.command === "commit" && !input.dry_run) {
       try {
@@ -5438,6 +5471,7 @@ var gitTool = {
     }
     const result = await runGit2(args, gitDir, opts.signal);
     if (stagedDiff !== void 0) result.diff = stagedDiff;
+    if (safetyWarning !== void 0) result.warning = safetyWarning;
     return result;
   }
 };
@@ -5549,7 +5583,7 @@ function buildArgs(input) {
   }
 }
 function runGit2(args, cwd, signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     const child = spawn("git", args, {
@@ -5570,7 +5604,7 @@ function runGit2(args, cwd, signal) {
       }
     });
     child.on("error", (err) => {
-      resolve7({
+      resolve6({
         command: args[0],
         stdout: normalizeCommandOutput(stdout),
         stderr: err.message,
@@ -5579,7 +5613,7 @@ function runGit2(args, cwd, signal) {
       });
     });
     child.on("close", (code) => {
-      resolve7({
+      resolve6({
         command: args[0],
         stdout: normalizeCommandOutput(stdout),
         stderr: normalizeCommandOutput(stderr),
@@ -5802,13 +5836,13 @@ var grepTool = {
   }
 };
 async function detectRg(signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     try {
       const p = spawn("rg", ["--version"], { env: buildChildEnv(), stdio: "ignore", signal, windowsHide: true });
-      p.on("error", () => resolve7(false));
-      p.on("close", (code) => resolve7(code === 0));
+      p.on("error", () => resolve6(false));
+      p.on("close", (code) => resolve6(code === 0));
     } catch {
-      resolve7(false);
+      resolve6(false);
     }
   });
 }
@@ -6223,8 +6257,8 @@ var jsonTool = {
     };
   }
 };
-function query(data, path21) {
-  const parts = path21.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
+function query(data, path20) {
+  const parts = path20.replace(/\[(\d+)\]/g, ".$1").split(".").filter(Boolean);
   let current = data;
   for (const part of parts) {
     if (current === null || current === void 0) return void 0;
@@ -6450,7 +6484,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
     };
   }
   args.push("--timestamps", service);
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     const MAX = 2e5;
@@ -6466,7 +6500,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
       if (settled) return;
       settled = true;
       clearTimeout(timer);
-      resolve7(result);
+      resolve6(result);
     };
     const child = spawn("docker", args, { cwd, signal, env: buildChildEnv(), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     const timer = setTimeout(() => {
@@ -6501,7 +6535,7 @@ async function dockerLogs(service, lines, filterRe, cwd, signal, since) {
 }
 var DOCKER_LOGS_TIMEOUT_MS = 3e3;
 var MAX_TAIL_LINES = 1e5;
-async function fileLogs(path21, lines, filterRe, stream) {
+async function fileLogs(path20, lines, filterRe, stream) {
   const { createInterface } = await import('node:readline');
   const { createReadStream } = await import('node:fs');
   const entries = [];
@@ -6510,7 +6544,7 @@ async function fileLogs(path21, lines, filterRe, stream) {
   let writeIdx = 0;
   let totalLines = 0;
   const rl = createInterface({
-    input: createReadStream(path21),
+    input: createReadStream(path20),
     crlfDelay: Number.POSITIVE_INFINITY
   });
   for await (const line of rl) {
@@ -6531,7 +6565,7 @@ async function fileLogs(path21, lines, filterRe, stream) {
     if (parsed) entries.push(parsed);
   }
   return {
-    source: path21,
+    source: path20,
     entries,
     total: entries.length,
     truncated: totalLines > effLines,
@@ -6589,12 +6623,15 @@ var outdatedTool = {
   // fixed four sibling tools (mcp_control, shellcheck, shellcheck_scan,
   // web_search) but missed this one; applying the same contract here.
   mutating: true,
-  // Capability is just "network" — the tool only hits the package
+  // Capability is outbound network — the tool only hits the package
   // registry over HTTP, never touches the filesystem or runs shell.
+  // Use the canonical `net.outbound` capability (not the non-existent
+  // `network` string) so the subagent allowlist recognises it and
+  // permits read-only registry lookups under a director.
   // The H7 invariant test requires this array to be non-empty for
   // any mutating:true tool (meta-tools whitelisted). See
   // tests/permission-mutating-invariant.test.ts:92.
-  capabilities: ["network"],
+  capabilities: ["net.outbound"],
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -6625,7 +6662,7 @@ var outdatedTool = {
   }
 };
 function runOutdated(manager, args, cwd, signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     const MAX = 1e5;
@@ -6641,10 +6678,10 @@ function runOutdated(manager, args, cwd, signal) {
     });
     child.on("close", (code) => {
       const result = parseOutdatedOutput(stdout, code ?? 0);
-      resolve7(result);
+      resolve6(result);
     });
     child.on("error", (e) => {
-      resolve7({
+      resolve6({
         exit_code: 1,
         packages: [],
         total: 0,
@@ -6778,7 +6815,7 @@ function stripPathComponents(p, strip) {
   return parts.slice(strip).join("/");
 }
 function runPatch(args, cwd, signal) {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     let stdout = "";
     let stderr = "";
     const env = { ...buildChildEnv(), LANG: "C", LC_ALL: "C" };
@@ -6789,8 +6826,8 @@ function runPatch(args, cwd, signal) {
     child.stderr?.on("data", (c) => {
       stderr += c.toString();
     });
-    child.on("close", (code) => resolve7({ exitCode: code ?? 1, stdout, stderr }));
-    child.on("error", (e) => resolve7({ exitCode: 1, stdout: "", stderr: e.message }));
+    child.on("close", (code) => resolve6({ exitCode: code ?? 1, stdout, stderr }));
+    child.on("error", (e) => resolve6({ exitCode: 1, stdout: "", stderr: e.message }));
   });
 }
 function extractPatchedFiles(output) {
@@ -7087,6 +7124,11 @@ var readTool = {
       limit: {
         type: "integer",
         description: "Maximum number of lines to return (default is 2000)."
+      },
+      mode: {
+        type: "string",
+        enum: ["content", "summary"],
+        description: "Return full line-numbered content (default) or a compact file summary with imports/exports/symbols."
       }
     },
     required: ["path"]
@@ -7100,14 +7142,27 @@ var readTool = {
     } 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(err)}`
-      );
+      throw new Error(`read: failed to stat "${input.path}": ${toErrorMessage(err)}`);
     }
     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})`);
     }
+    const offset = Math.max(1, input.offset ?? 1);
+    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    const prior = getReadRangeRecord(ctx, absPath);
+    const requestedEnd = prior ? Math.min(offset + limit - 1, prior.totalLines) : offset + limit - 1;
+    if (input.mode !== "summary" && limit > 0 && prior && coversRange(prior, stat11.mtimeMs, offset, requestedEnd)) {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      return {
+        text: `[unchanged since previous read: "${input.path}" mtime=${Math.round(stat11.mtimeMs)}; requested lines ${offset}-${requestedEnd} were already shown. Use offset/limit for a new range if needed.]`,
+        total_lines: prior.totalLines,
+        encoding: "utf8",
+        truncated: requestedEnd < prior.totalLines,
+        cached: true,
+        note: "Repeated read suppressed to save tokens."
+      };
+    }
     const buf = await fs14.readFile(absPath);
     if (isBinaryBuffer(buf)) {
       throw new Error(`read: "${input.path}" appears to be binary`);
@@ -7115,17 +7170,38 @@ var readTool = {
     const text = buf.toString("utf8");
     const allLines = text.split(/\r\n|\r|\n/);
     const total = allLines.length;
-    const offset = Math.max(1, input.offset ?? 1);
-    const limit = Math.max(0, Math.min(input.limit ?? 2e3, 5e3));
+    if (input.mode === "summary") {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, Math.min(total, 200));
+      return {
+        text: summarizeFile(input.path, stat11.size, allLines),
+        total_lines: total,
+        encoding: "utf8",
+        truncated: total > 200,
+        note: "Summary mode returned compact structure instead of full file content."
+      };
+    }
     if (limit === 0) {
       ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, 1, 0);
       return { text: "", total_lines: total, encoding: "utf8", truncated: total > 0 };
     }
+    if (offset > total) {
+      ctx.recordRead(absPath, stat11.mtimeMs);
+      rememberReadRange(ctx, absPath, stat11.mtimeMs, total, total + 1, total + 1);
+      return {
+        text: `[offset ${offset} is past end of file "${input.path}" \u2014 file has ${total} line(s). Do not retry this offset.]`,
+        total_lines: total,
+        encoding: "utf8",
+        truncated: false
+      };
+    }
     const slice = allLines.slice(offset - 1, offset - 1 + limit);
     const truncated = offset - 1 + slice.length < total;
     const width = String(offset + slice.length - 1).length;
     const numbered = slice.map((line, i) => `${String(offset + i).padStart(width, " ")}\u2192${line}`).join("\n");
     ctx.recordRead(absPath, stat11.mtimeMs);
+    rememberReadRange(ctx, absPath, stat11.mtimeMs, total, offset, offset + slice.length - 1);
     return {
       text: numbered,
       total_lines: total,
@@ -7134,6 +7210,62 @@ var readTool = {
     };
   }
 };
+var READ_RANGES_META_KEY = "tools.read.ranges.v1";
+function getReadRanges(ctx) {
+  const existing = ctx.meta[READ_RANGES_META_KEY];
+  if (existing && typeof existing === "object" && !Array.isArray(existing)) {
+    return existing;
+  }
+  const next = {};
+  ctx.meta[READ_RANGES_META_KEY] = next;
+  return next;
+}
+function getReadRangeRecord(ctx, absPath) {
+  return getReadRanges(ctx)[absPath];
+}
+function rememberReadRange(ctx, absPath, mtimeMs, totalLines, start, end) {
+  if (end < start) return;
+  const ranges = getReadRanges(ctx);
+  const prior = ranges[absPath];
+  const nextRanges = prior && Math.abs(prior.mtimeMs - mtimeMs) <= 1 ? prior.ranges.slice() : [];
+  nextRanges.push({ start, end });
+  ranges[absPath] = {
+    mtimeMs,
+    totalLines,
+    ranges: mergeRanges(nextRanges)
+  };
+}
+function coversRange(record, mtimeMs, start, end) {
+  if (Math.abs(record.mtimeMs - mtimeMs) > 1) return false;
+  return record.ranges.some((range) => range.start <= start && range.end >= end);
+}
+function mergeRanges(ranges) {
+  const sorted = ranges.slice().sort((a, b) => a.start - b.start);
+  const merged = [];
+  for (const range of sorted) {
+    const last = merged[merged.length - 1];
+    if (!last || range.start > last.end + 1) {
+      merged.push({ ...range });
+      continue;
+    }
+    last.end = Math.max(last.end, range.end);
+  }
+  return merged;
+}
+function summarizeFile(filePath, bytes, lines) {
+  const interesting = lines.map((line, index) => ({ line: line.trim(), number: index + 1 })).filter(
+    ({ line }) => /^(import\s|export\s|class\s|interface\s|type\s|function\s|const\s+\w+\s*=|let\s+\w+\s*=|var\s+\w+\s*=|def\s+|async\s+function\s)/.test(
+      line
+    )
+  ).slice(0, 80).map(({ line, number }) => `${number}: ${line}`);
+  return [
+    `summary: ${filePath}`,
+    `bytes=${bytes}`,
+    `total_lines=${lines.length}`,
+    interesting.length > 0 ? `symbols/imports:
+${interesting.join("\n")}` : "symbols/imports: (none detected)"
+  ].join("\n");
+}
 var DEFAULT_IGNORE4 = ["node_modules", ".git", "dist", "build", ".next", "coverage"];
 var replaceTool = {
   name: "replace",
@@ -7270,13 +7402,13 @@ async function globFiles(pattern, base, extraGlob) {
   return await globNative(pattern, base, extraGlob);
 }
 function checkRg() {
-  return new Promise((resolve7) => {
+  return new Promise((resolve6) => {
     try {
       const p = spawn("rg", ["--version"], { env: buildChildEnv(), stdio: "ignore", windowsHide: true });
-      p.on("error", () => resolve7(false));
-      p.on("close", (code) => resolve7(code === 0));
+      p.on("error", () => resolve6(false));
+      p.on("close", (code) => resolve6(code === 0));
     } catch {
-      resolve7(false);
+      resolve6(false);
     }
   });
 }
@@ -7293,10 +7425,10 @@ function spawnRgFind(pattern, base) {
     buf += chunk.toString();
   });
   return {
-    promise: new Promise((resolve7, reject) => {
+    promise: new Promise((resolve6, reject) => {
       child.on("error", reject);
       child.on("close", () => {
-        resolve7(buf.split("\n").filter(Boolean));
+        resolve6(buf.split("\n").filter(Boolean));
       });
     })
   };