@wrongstack/tools 0.264.0 → 0.267.0

package/dist/pack.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, loadTasks, emptyTaskFile, saveTasks, formatTaskList, formatPlan, mutateTasks, loadPlan, emptyPlan, savePlan, computeTaskItemProgress, 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';
@@ -142,6 +142,23 @@ var CircuitBreaker = class {
   lastSlowAt = null;
   /** Timestamp when the breaker was opened (for cooldown calculation). */
   openedAt = null;
+  /**
+   * Master enable flag. When false the breaker is bypassed: `beforeCall`
+   * always returns true and `afterCall` records nothing. The class itself
+   * defaults to enabled (so the standalone unit tests exercise tripping); the
+   * ProcessRegistry flips this off until the user opts in via `/settings`.
+   */
+  enabled = true;
+  /**
+   * Fired (best-effort) when the breaker transitions into the `open` state.
+   * The registry uses this to arm its auto kill/reset countdown.
+   */
+  onTrip;
+  /**
+   * Fired (best-effort) when the breaker returns to `closed` after having been
+   * open/half-open. The registry uses this to cancel a pending kill/reset.
+   */
+  onReset;
   constructor(config = {}) {
     this.maxConsecutiveFailures = config.maxConsecutiveFailures ?? DEFAULT_MAX_CONSECUTIVE_FAILURES;
     this.slowCallThresholdMs = config.slowCallThresholdMs ?? DEFAULT_SLOW_CALL_THRESHOLD_MS;
@@ -150,12 +167,22 @@ var CircuitBreaker = class {
     this.maxCallsPerWindow = config.maxCallsPerWindow ?? DEFAULT_MAX_CALLS_PER_WINDOW;
     this.cooldownMs = config.cooldownMs ?? DEFAULT_COOLDOWN_MS;
   }
+  /** Toggle the master enable. Disabling resets to a clean `closed` state. */
+  setEnabled(enabled) {
+    if (this.enabled === enabled) return;
+    this.enabled = enabled;
+    if (!enabled) this._reset();
+  }
+  get isEnabled() {
+    return this.enabled;
+  }
   /**
    * Returns true if the circuit allows a new call to proceed.
    * When false, callers should abort the tool call and return a
    * circuit-breaker error instead of spawning a process.
    */
   get canProceed() {
+    if (!this.enabled) return true;
     this._checkStateTransition();
     return this.state !== "open";
   }
@@ -191,7 +218,7 @@ var CircuitBreaker = class {
    *                  not affect breaker state.
    */
   beforeCall(bypass = false) {
-    if (bypass) return true;
+    if (bypass || !this.enabled) return true;
     this._checkStateTransition();
     if (this.state === "open") return false;
     return true;
@@ -206,7 +233,7 @@ var CircuitBreaker = class {
    *                  Use for background/fire-and-forget processes.
    */
   afterCall(durationMs, failed, bypass = false) {
-    if (bypass) return;
+    if (bypass || !this.enabled) return;
     const now = Date.now();
     if (this.state === "half-open") {
       if (failed) {
@@ -252,12 +279,23 @@ var CircuitBreaker = class {
     if (this.state === "open") return;
     this.state = "open";
     this.openedAt = Date.now();
+    try {
+      this.onTrip?.();
+    } catch {
+    }
   }
   _reset() {
+    const wasRecovering = this.state !== "closed";
     this.state = "closed";
     this.consecutiveFailures = 0;
     this.window = [];
     this.openedAt = null;
+    if (wasRecovering) {
+      try {
+        this.onReset?.();
+      } catch {
+      }
+    }
   }
   /** Transition from open → half-open when cooldown elapses. */
   _checkStateTransition() {
@@ -319,8 +357,21 @@ function killWin32Tree(pid) {
 var ProcessRegistryImpl = class {
   processes = /* @__PURE__ */ new Map();
   breaker;
+  /**
+   * Auto kill/reset config. When the breaker trips and `autoKillResetMs > 0`,
+   * a countdown is armed; on expiry all tracked processes are killed and the
+   * breaker is reset to closed (forced recovery). Zero means manual recovery
+   * only (`/kill reset`).
+   */
+  autoKillResetMs = 0;
+  autoKillTimer = null;
+  autoKillArmedAt = null;
+  breakerCountdownListeners = [];
   constructor(breakerConfig) {
     this.breaker = new CircuitBreaker(breakerConfig);
+    this.breaker.onTrip = () => this._armAutoKillReset();
+    this.breaker.onReset = () => this._cancelAutoKillReset();
+    this.breaker.setEnabled(false);
   }
   register(info) {
     this.processes.set(info.pid, { ...info, killed: false, protected: info.protected ?? false });
@@ -396,6 +447,90 @@ var ProcessRegistryImpl = class {
   forceBreakerReset() {
     this.breaker.forceReset();
   }
+  /**
+   * Configure circuit-breaker protection at runtime. Called from `/settings`
+   * (instant, all modes) and on TUI mount (applies persisted config).
+   *
+   * - `enabled` toggles whether the breaker gates `bash`/`exec`.
+   * - `autoKillResetMs` arms the auto kill/reset countdown when the breaker
+   *   trips (0 = manual recovery only).
+   *
+   * Re-applies cleanly on every call: cancels a pending countdown when the
+   * timeout is cleared or protection disabled, and re-arms if the breaker is
+   * currently open under the new settings.
+   */
+  setBreakerConfig(cfg) {
+    if (cfg.enabled !== void 0) this.breaker.setEnabled(cfg.enabled);
+    if (cfg.autoKillResetMs !== void 0) this.autoKillResetMs = Math.max(0, cfg.autoKillResetMs);
+    if (this.autoKillResetMs <= 0) {
+      this._cancelAutoKillReset();
+      return;
+    }
+    if (this.breaker.isEnabled && this.breaker.snapshot().state === "open") {
+      this._armAutoKillReset();
+    }
+  }
+  /**
+   * Live countdown to the next auto kill/reset, or null when nothing is armed.
+   * The TUI polls this on a 1s tick while armed so the statusline decrements.
+   */
+  getBreakerCountdown() {
+    if (this.autoKillArmedAt === null || this.autoKillResetMs <= 0) return null;
+    const elapsed = Date.now() - this.autoKillArmedAt;
+    return { remainingMs: Math.max(0, this.autoKillResetMs - elapsed), totalMs: this.autoKillResetMs };
+  }
+  /**
+   * Subscribe to countdown arm/cancel events. Returns an unsubscribe function.
+   * Use {@link getBreakerCountdown} for the live ticking value between events.
+   */
+  onBreakerCountdownChange(listener) {
+    this.breakerCountdownListeners.push(listener);
+    return () => {
+      this.breakerCountdownListeners = this.breakerCountdownListeners.filter((l) => l !== listener);
+    };
+  }
+  _emitBreakerCountdown() {
+    const snap = this.getBreakerCountdown();
+    for (const l of this.breakerCountdownListeners) {
+      try {
+        l(snap);
+      } catch {
+      }
+    }
+  }
+  /**
+   * Arm the auto kill/reset countdown. Idempotent: re-arming resets the window
+   * (a fresh trip after a failed half-open probe restarts the clock). No-op
+   * when protection is off or no timeout is configured.
+   */
+  _armAutoKillReset() {
+    if (this.autoKillResetMs <= 0 || !this.breaker.isEnabled) return;
+    this._clearAutoKillTimer();
+    this.autoKillArmedAt = Date.now();
+    this.autoKillTimer = setTimeout(() => {
+      this.autoKillTimer = null;
+      this.autoKillArmedAt = null;
+      this.killAll({ force: false });
+      this.breaker.forceReset();
+      this._emitBreakerCountdown();
+    }, this.autoKillResetMs);
+    this.autoKillTimer.unref?.();
+    this._emitBreakerCountdown();
+  }
+  _cancelAutoKillReset() {
+    const wasArmed = this.autoKillArmedAt !== null;
+    this._clearAutoKillTimer();
+    if (wasArmed) {
+      this.autoKillArmedAt = null;
+      this._emitBreakerCountdown();
+    }
+  }
+  _clearAutoKillTimer() {
+    if (this.autoKillTimer !== null) {
+      clearTimeout(this.autoKillTimer);
+      this.autoKillTimer = null;
+    }
+  }
   /** Kill a single process by PID.
    *
    *  On POSIX: sends SIGTERM to the *process group* (-pid) so that
@@ -534,8 +669,9 @@ async function* spawnStream(opts) {
   let pending2 = "";
   let error;
   const spool = createOutputSpool({ tool: opts.cmd, thresholdBytes: max });
-  const cmd = resolveWin32Command(opts.cmd);
-  const needsShell = isWin && (cmd.endsWith(".cmd") || cmd.endsWith(".bat"));
+  const resolved = resolveWin32Command(opts.cmd);
+  const needsShell = isWin && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
+  const cmd = needsShell ? opts.cmd : resolved;
   const child = spawn(cmd, opts.args, {
     cwd: opts.cwd,
     env: buildChildEnv(),
@@ -699,22 +835,29 @@ async function detectPackageManager(cwd) {
 function resolvePath(input, ctx) {
   return path3.isAbsolute(input) ? path3.normalize(input) : path3.resolve(ctx.workingDir ?? ctx.cwd, input);
 }
+function allowedRoots(ctx) {
+  return [path3.resolve(ctx.projectRoot), path3.resolve(Core.wstackGlobalRoot())];
+}
+function isInsideAny(target, roots) {
+  return roots.some((root) => {
+    const rel = path3.relative(root, target);
+    return rel === "" || !rel.startsWith("..") && !path3.isAbsolute(rel);
+  });
+}
 function ensureInsideRoot(absPath, ctx) {
-  if (ctx.allowOutsideProjectRoot) return path3.resolve(absPath);
-  const root = path3.resolve(ctx.projectRoot);
   const target = path3.resolve(absPath);
-  const rel = path3.relative(root, target);
-  if (rel.startsWith("..") || path3.isAbsolute(rel)) {
-    throw new Error(`Path "${absPath}" is outside project root "${root}"`);
-  }
-  return target;
+  if (ctx.allowOutsideProjectRoot) return target;
+  if (isInsideAny(target, allowedRoots(ctx))) return target;
+  throw new Error(`Path "${absPath}" is outside project root "${path3.resolve(ctx.projectRoot)}"`);
 }
 function safeResolve(input, ctx) {
   return ensureInsideRoot(resolvePath(input, ctx), ctx);
 }
 async function assertRealInsideRoot(absPath, ctx) {
   if (ctx.allowOutsideProjectRoot) return;
-  const realRoot = await fs14.realpath(ctx.projectRoot).catch(() => path3.resolve(ctx.projectRoot));
+  const realRoots = await Promise.all(
+    allowedRoots(ctx).map((r) => fs14.realpath(r).catch(() => path3.resolve(r)))
+  );
   let probe = absPath;
   for (; ; ) {
     let real;
@@ -729,13 +872,10 @@ async function assertRealInsideRoot(absPath, ctx) {
       }
       throw err;
     }
-    const rel = path3.relative(realRoot, real);
-    if (rel.startsWith("..") || path3.isAbsolute(rel)) {
-      throw new Error(
-        `Path "${absPath}" resolves through a symlink outside project root "${realRoot}"`
-      );
-    }
-    return;
+    if (isInsideAny(real, realRoots)) return;
+    throw new Error(
+      `Path "${absPath}" resolves through a symlink outside project root "${realRoots[0]}"`
+    );
   }
 }
 async function safeResolveReal(input, ctx) {
@@ -837,6 +977,7 @@ var auditTool = {
   permission: "confirm",
   mutating: false,
   capabilities: ["shell.restricted"],
+  icon: "package",
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -941,6 +1082,7 @@ var bashTool = {
   permission: "confirm",
   mutating: true,
   riskTier: "destructive",
+  icon: "terminal",
   // Trust rules match on the literal `command` string. Without subjectKey
   // the policy heuristic would have done the same here, but declaring it
   // explicitly removes the implicit cross-tool aliasing.
@@ -1281,6 +1423,7 @@ var batchToolUseTool = {
   mutating: true,
   timeoutMs: 12e4,
   capabilities: ["tool.mutate.any"],
+  icon: "meta",
   inputSchema: {
     type: "object",
     properties: {
@@ -2056,39 +2199,57 @@ var IndexStore = class {
       }
     });
   }
+  /**
+   * Bulk-insert refs for many source symbols in a single transaction.
+   *
+   * Unlike {@link insertRefs} this does NOT delete per source id — the caller
+   * (the indexer) has already cleared stale refs for the file via
+   * {@link deleteRefsForFile}, so the per-source DELETE would be redundant work
+   * repeated once per symbol. One transaction for the whole file instead of one
+   * per symbol turns an O(symbols) transaction count into O(1).
+   *
+   * Each ref's own {@link Ref.fromId} is used; pass an empty array to no-op.
+   */
+  insertRefsBatch(refs) {
+    if (refs.length === 0) return;
+    this.runWithRetry(() => {
+      const stmt = this.db.prepare(
+        `INSERT INTO refs(from_id, to_name, to_id, call_type, line)
+         VALUES (?, ?, ?, ?, ?)`
+      );
+      for (const ref of refs) {
+        stmt.run(ref.fromId, ref.toName, ref.toId ?? null, ref.callType, ref.line);
+      }
+    });
+  }
   /**
    * Delete all refs whose source symbols are in a given file.
    * Used when re-indexing a file to clear stale refs.
    */
   deleteRefsForFile(file) {
     this.runWithRetry(() => {
-      const ids = this.db.prepare(
-        "SELECT id FROM symbols WHERE file = ?"
-      ).all(file);
-      if (!ids.length) return;
-      const placeholders = ids.map(() => "?").join(",");
-      this.db.prepare(`DELETE FROM refs WHERE from_id IN (${placeholders})`).run(...ids.map((r) => r.id));
+      this.db.prepare(
+        "DELETE FROM refs WHERE from_id IN (SELECT id FROM symbols WHERE file = ?)"
+      ).run(file);
     });
   }
   /**
    * Resolve `to_name` → `to_id` for all refs that have a name but no id.
    * Call this after all symbols have been inserted to fill in cross-references.
+   *
+   * Single statement: the `to_name IN (SELECT name FROM symbols)` guard restricts
+   * the UPDATE to refs that will actually resolve, so `.changes` counts only refs
+   * that found a target — matching the previous per-row loop's return value.
    */
   resolveRefs() {
     return this.runWithRetry(() => {
-      const unresolved = this.db.prepare(
-        "SELECT id, to_name FROM refs WHERE to_id IS NULL AND to_name IS NOT NULL"
-      ).all();
-      let resolved = 0;
-      for (const row of unresolved) {
-        const target = this.db.prepare("SELECT id FROM symbols WHERE name = ? LIMIT 1").all(row.to_name);
-        const first = target[0];
-        if (first) {
-          this.db.prepare("UPDATE refs SET to_id = ? WHERE id = ?").run(first.id, row.id);
-          resolved++;
-        }
-      }
-      return resolved;
+      const result = this.db.prepare(
+        `UPDATE refs SET to_id = (
+           SELECT id FROM symbols WHERE name = refs.to_name LIMIT 1
+         ) WHERE to_id IS NULL AND to_name IS NOT NULL
+           AND to_name IN (SELECT name FROM symbols)`
+      ).run();
+      return result.changes ?? 0;
     });
   }
   /**
@@ -3563,14 +3724,27 @@ async function runIndexerWithStore(store, opts) {
     symbolsIndexed += count;
     langStats[lang] = (langStats[lang] ?? 0) + count;
     if (parsed.refs && parsed.refs.length > 0) {
-      for (let i = 0; i < symbolsWithIds.length; i++) {
-        const sym = expectDefined(symbolsWithIds[i]);
-        const symRefs = parsed.refs.filter((r) => r.line === sym.line);
-        if (symRefs.length > 0) {
-          const refsWithFromId = symRefs.map((r) => ({ ...r, fromId: sym.id }));
-          store.insertRefs(sym.id, refsWithFromId);
+      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,
@@ -3903,6 +4077,7 @@ async function codebaseIndexStats(args, opts = {}) {
 var codebaseIndexTool = {
   name: "codebase-index",
   category: "Project",
+  icon: "index",
   description: "Build or incrementally update the project-wide symbol index. This powers fast codebase search and understanding. By default it only processes files that have changed since the last indexing run.",
   usageHint: "IMPORTANT FOR LARGE CODEBASES:\n\n- First run (or after major changes): consider `force: true` for a clean rebuild.\n- Normal usage: call without arguments for fast incremental updates.\n- Use `langs` to restrict to specific languages if you only care about certain parts of the project.\nThis tool is relatively expensive \u2014 do not call it on every turn. Use it when the index is stale or before heavy codebase-search sessions.",
   permission: "confirm",
@@ -3959,6 +4134,7 @@ var codebaseIndexTool = {
 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.",
   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",
@@ -4047,6 +4223,7 @@ var codebaseSearchTool = {
 var codebaseStatsTool = {
   name: "codebase-stats",
   category: "Project",
+  icon: "index",
   description: "Return health and statistics about the current symbol index (total symbols, files, language/kind breakdown, size, last update). Useful to decide whether to re-index.",
   usageHint: "CALL BEFORE HEAVY CODEBASE-SEARCH WORK:\n\n- Use to see if the index is up-to-date or needs a refresh.\n- No arguments required.\n- Helps avoid wasting tokens on searches against a stale index.\nLightweight and safe to call frequently.",
   permission: "auto",
@@ -4107,6 +4284,7 @@ var diffTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  icon: "diff",
   timeoutMs: 1e4,
   inputSchema: {
     type: "object",
@@ -4253,6 +4431,7 @@ var documentTool = {
   mutating: false,
   timeoutMs: 3e4,
   capabilities: ["fs.read"],
+  icon: "document",
   inputSchema: {
     type: "object",
     properties: {
@@ -4392,11 +4571,12 @@ 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"],
+  icon: "edit",
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -4421,9 +4601,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;
@@ -4431,15 +4609,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;
@@ -4480,7 +4664,8 @@ var editTool = {
     return {
       path: absPath,
       replacements: input.replace_all ? count : 1,
-      diff
+      diff,
+      note: autoReadNote
     };
   }
 };
@@ -4619,6 +4804,7 @@ var execTool = {
   riskTier: "standard",
   timeoutMs: DEFAULT_TIMEOUT_MS2,
   capabilities: ["shell.restricted"],
+  icon: "terminal",
   inputSchema: {
     type: "object",
     properties: {
@@ -4718,7 +4904,8 @@ function runCommand(cmd, args, cwd, timeout, signal, sessionId) {
     const spool = createOutputSpool({ tool: `exec-${cmd}`, thresholdBytes: MAX_OUTPUT2 });
     const resolved = resolveWin32Command(cmd);
     const needsShell = isWin2 && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
-    const child = spawn(resolved, args, {
+    const spawnCmd = needsShell ? cmd : resolved;
+    const child = spawn(spawnCmd, args, {
       cwd,
       env: buildChildEnv(sessionId),
       stdio: ["ignore", "pipe", "pipe"],
@@ -4905,6 +5092,7 @@ var fetchTool = {
   permission: "confirm",
   mutating: false,
   capabilities: ["net.outbound"],
+  icon: "web",
   // Trust rules for fetch match on the literal URL — declare it explicitly
   // so a user can trust `https://api.example.com/*` without accidentally
   // matching that pattern on any other tool that happens to have a `url`
@@ -5054,6 +5242,7 @@ var formatTool = {
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write", "shell.exec"],
+  icon: "code",
   timeoutMs: 6e4,
   inputSchema: {
     type: "object",
@@ -5152,8 +5341,9 @@ 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
   // (status/log/diff/branch/fetch) are still gated on `permission: 'confirm'`
   // and `MUTATING_SUBCOMMANDS` is consulted at runtime for per-call checks.
@@ -5240,6 +5430,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 {
@@ -5253,6 +5459,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;
   }
 };
@@ -5413,6 +5620,7 @@ var globTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  icon: "folder",
   maxOutputBytes: 65536,
   timeoutMs: 5e3,
   inputSchema: {
@@ -5545,6 +5753,7 @@ var grepTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  icon: "search",
   maxOutputBytes: 131072,
   timeoutMs: 1e4,
   inputSchema: {
@@ -5831,6 +6040,7 @@ var installTool = {
   permission: "confirm",
   mutating: true,
   riskTier: "standard",
+  icon: "package",
   timeoutMs: 12e4,
   capabilities: ["package.install", "shell.restricted"],
   inputSchema: {
@@ -5969,6 +6179,7 @@ var jsonTool = {
   mutating: false,
   timeoutMs: 5e3,
   capabilities: ["fs.read"],
+  icon: "json",
   inputSchema: {
     type: "object",
     properties: {
@@ -6094,6 +6305,7 @@ var lintTool = {
   mutating: false,
   timeoutMs: 6e4,
   capabilities: ["shell.restricted"],
+  icon: "code",
   inputSchema: {
     type: "object",
     properties: {
@@ -6187,6 +6399,7 @@ var logsTool = {
   mutating: false,
   timeoutMs: 3e4,
   capabilities: ["shell.restricted"],
+  icon: "logs",
   inputSchema: {
     type: "object",
     properties: {
@@ -6388,6 +6601,7 @@ var outdatedTool = {
   description: "Check for outdated dependencies in the project. Reports current, wanted (semver range), and latest versions available.",
   usageHint: "MAINTENANCE & SECURITY TOOL:\n\n- Run periodically or before dependency-related work.\n- Helps surface packages that may need updates for security or features.\n- Hits the package registry over HTTP, so it is NOT purely local \u2014 flagged as mutating for the confirmation gate.\nUse the output to decide on upgrades. Prefer this over manual shell commands for dependency hygiene.",
   permission: "confirm",
+  icon: "package",
   // Network side-effecting (registry HTTP). Pairs with `mutating: true`
   // so the H7 invariant test (`no auto-permission tool declares
   // mutating: true`) passes — a tool claiming `'auto'` must be purely
@@ -6397,12 +6611,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",
@@ -6439,7 +6656,8 @@ function runOutdated(manager, args, cwd, signal) {
     const MAX = 1e5;
     const resolved = resolveWin32Command(manager);
     const needsShell = process.platform === "win32" && (resolved.endsWith(".cmd") || resolved.endsWith(".bat"));
-    const child = spawn(resolved, args, { cwd, signal, env: buildChildEnv(), stdio: ["ignore", "pipe", "pipe"], windowsHide: true, ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {} });
+    const spawnCmd = needsShell ? manager : resolved;
+    const child = spawn(spawnCmd, args, { cwd, signal, env: buildChildEnv(), stdio: ["ignore", "pipe", "pipe"], windowsHide: true, ...needsShell ? { shell: true, windowsVerbatimArguments: true } : {} });
     child.stdout?.on("data", (c) => {
       if (stdout.length < MAX) stdout += c.toString();
     });
@@ -6503,6 +6721,7 @@ var patchTool = {
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
+  icon: "edit",
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -6610,11 +6829,12 @@ function extractPatchedFiles(output) {
 var planTool = {
   name: "plan",
   category: "Session",
-  description: "Manage a persistent strategic plan for the current session. Unlike todos, plans are meant for higher-level, multi-phase approaches and survive across conversation resumptions. Use this to outline big-picture work, then promote concrete items into the todo list when ready to execute.",
-  usageHint: 'RECOMMENDED FOR COMPLEX, MULTI-PHASE WORK:\n\n- Start by creating a high-level plan with `action: "add"` or using templates (`template_use`).\n- Use `promote` to turn a plan item into actionable todos.\n- Use `taskify` to convert a plan item into a structured task (with type/priority/deps).\n- Keep plans at the "why and what" level, and todos at the "how and next step" level.\n- Common templates: "new-feature", "bug-fix", "refactor", "release", "security-audit".\n\nThis tool is excellent for maintaining long-term direction across many turns or even multiple sessions.',
+  description: 'Manage a session-persistent strategic plan. The plan is written to disk and survives conversation resumptions within the same session, but is isolated to this session \u2014 other sessions have their own separate plans. Unlike todos (which are per-turn and lost on restart), a plan tracks high-level progress across multiple turns. Use this to outline big-picture work, then promote concrete items into the todo list when ready to execute. By default plans are isolated to this session; use `scope: "project"` to store the plan in a shared project-level file visible to all sessions.',
+  usageHint: 'RECOMMENDED FOR COMPLEX, MULTI-PHASE WORK:\n\n- Start by creating a high-level plan with `action: "add"` or using templates (`template_use`).\n- Use `promote` to turn a plan item into actionable todos.\n- Use `taskify` to convert a plan item into a structured task (with type/priority/deps).\n- Keep plans at the "why and what" level, and todos at the "how and next step" level.\n- Common templates: "new-feature", "bug-fix", "refactor", "release", "security-audit".\n\nThis tool is excellent for maintaining long-term direction across many turns within a session. Plans survive resume but are not shared across separate sessions.\nUse `scope: "project"` to use a shared project-level plan file.',
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
+  icon: "plan",
   timeoutMs: 2e3,
   inputSchema: {
     type: "object",
@@ -6654,12 +6874,26 @@ var planTool = {
       template: {
         type: "string",
         description: "Template identifier when using action=template_use. Common values: new-feature, bug-fix, refactor, release, security-audit."
+      },
+      scope: {
+        type: "string",
+        enum: ["session", "project"],
+        description: 'Storage scope: "session" (default, isolated to this session) or "project" (shared across all sessions for this project).'
       }
     },
     required: ["action"]
   },
   async execute(input, ctx) {
-    const planPath = ctx.meta["plan.path"];
+    const sessionPlanPath = ctx.meta["plan.path"];
+    let planPath;
+    if (input.scope === "project") {
+      if (typeof sessionPlanPath === "string") {
+        const lastSep = Math.max(sessionPlanPath.lastIndexOf("/"), sessionPlanPath.lastIndexOf("\\"));
+        planPath = lastSep >= 0 ? sessionPlanPath.slice(0, lastSep + 1) + "backlog.plan.json" : "backlog.plan.json";
+      }
+    } else {
+      planPath = sessionPlanPath;
+    }
     if (typeof planPath !== "string" || !planPath) {
       return {
         ok: false,
@@ -6673,148 +6907,169 @@ var planTool = {
     let early = null;
     const taskifyMeta = { title: "", details: "" };
     let didTaskify = false;
-    const plan = await mutatePlan(planPath, sessionId, async (p) => {
-      switch (input.action) {
-        case "show":
-          break;
-        case "add": {
-          const title = input.title?.trim();
-          if (!title) {
-            early = mkResult(p, false, "add requires `title`.");
-            return p;
-          }
-          const { plan: updated } = addPlanItem(p, title, input.details?.trim() || void 0);
-          return updated;
-        }
-        case "start":
-        case "done": {
-          if (!input.target) {
-            early = mkResult(p, false, `${input.action} requires \`target\` (id|index|substring).`);
-            return p;
-          }
-          const next = setPlanItemStatus(
-            p,
-            input.target,
-            input.action === "start" ? "in_progress" : "done"
-          );
-          if (next === p) {
-            early = mkResult(p, false, `No plan item matched "${input.target}".`);
-            return p;
-          }
-          return next;
-        }
-        case "remove": {
-          if (!input.target) {
-            early = mkResult(p, false, "remove requires `target` (id|index|substring).");
-            return p;
-          }
-          const next = removePlanItem(p, input.target);
-          if (next === p) {
-            early = mkResult(p, false, `No plan item matched "${input.target}".`);
-            return p;
-          }
-          return next;
-        }
-        case "promote": {
-          if (!input.target) {
-            early = mkResult(p, false, `${input.action} requires \`target\` (id|index|substring).`);
-            return p;
-          }
-          const derived = deriveTodosFromPlanItem(p, input.target, input.subtasks);
-          if (!derived) {
-            early = mkResult(p, false, `No plan item matched "${input.target}".`);
-            return p;
+    let plan;
+    try {
+      plan = await mutatePlan(planPath, sessionId, async (p) => {
+        switch (input.action) {
+          case "show":
+            break;
+          case "add": {
+            const title = input.title?.trim();
+            if (!title) {
+              early = mkResult(p, false, "add requires `title`.");
+              return p;
+            }
+            const { plan: updated } = addPlanItem(p, title, input.details?.trim() || void 0);
+            return updated;
           }
-          ctx.state.replaceTodos(derived.todos);
-          early = mkResult(
-            derived.plan,
-            true,
-            `${input.action} ok \u2014 ${derived.todos.length} todo(s) created.`,
-            derived.todos
-          );
-          return derived.plan;
-        }
-        case "template_use": {
-          const templateName = input.template?.trim();
-          if (!templateName) {
-            early = mkResult(p, false, "template_use requires `template` name.");
-            return p;
+          case "start":
+          case "done": {
+            if (!input.target) {
+              early = mkResult(p, false, `${input.action} requires \`target\` (id|index|substring).`);
+              return p;
+            }
+            const next = setPlanItemStatus(
+              p,
+              input.target,
+              input.action === "start" ? "in_progress" : "done"
+            );
+            if (next === p) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            return next;
           }
-          const template = getPlanTemplate(templateName);
-          if (!template) {
-            early = mkResult(p, false, `Unknown template "${templateName}".`);
-            return p;
+          case "remove": {
+            if (!input.target) {
+              early = mkResult(p, false, "remove requires `target` (id|index|substring).");
+              return p;
+            }
+            const next = removePlanItem(p, input.target);
+            if (next === p) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            return next;
           }
-          let updated = p;
-          for (const item of template.items) {
-            ({ plan: updated } = addPlanItem(updated, item.title, item.details));
+          case "promote": {
+            if (!input.target) {
+              early = mkResult(p, false, `${input.action} requires \`target\` (id|index|substring).`);
+              return p;
+            }
+            const derived = deriveTodosFromPlanItem(p, input.target, input.subtasks);
+            if (!derived) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            ctx.state.replaceTodos(derived.todos);
+            early = mkResult(
+              derived.plan,
+              true,
+              `${input.action} ok \u2014 ${derived.todos.length} todo(s) created.`,
+              derived.todos
+            );
+            return derived.plan;
           }
-          early = mkResult(
-            updated,
-            true,
-            `Applied template "${template.name}" \u2014 ${template.items.length} items added.`
-          );
-          return updated;
-        }
-        case "clear":
-          return clearPlan(p);
-        case "taskify": {
-          if (!input.target) {
-            early = mkResult(p, false, "taskify requires `target` (plan item id|index|substring).");
-            return p;
+          case "template_use": {
+            const templateName = input.template?.trim();
+            if (!templateName) {
+              early = mkResult(p, false, "template_use requires `template` name.");
+              return p;
+            }
+            const template = getPlanTemplate(templateName);
+            if (!template) {
+              early = mkResult(p, false, `Unknown template "${templateName}".`);
+              return p;
+            }
+            let updated = p;
+            for (const item of template.items) {
+              ({ plan: updated } = addPlanItem(updated, item.title, item.details));
+            }
+            early = mkResult(
+              updated,
+              true,
+              `Applied template "${template.name}" \u2014 ${template.items.length} items added.`
+            );
+            return updated;
           }
-          let itemIdx = -1;
-          const asNum = Number.parseInt(input.target, 10);
-          if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= p.items.length) {
-            itemIdx = asNum - 1;
-          } else {
-            itemIdx = p.items.findIndex((it) => it.id === input.target);
-            if (itemIdx === -1) {
-              const lower = input.target.toLowerCase();
-              itemIdx = p.items.findIndex((it) => it.title.toLowerCase().includes(lower));
+          case "clear":
+            return clearPlan(p);
+          case "taskify": {
+            if (!input.target) {
+              early = mkResult(p, false, "taskify requires `target` (plan item id|index|substring).");
+              return p;
             }
+            let itemIdx = -1;
+            const asNum = Number.parseInt(input.target, 10);
+            if (!Number.isNaN(asNum) && asNum >= 1 && asNum <= p.items.length) {
+              itemIdx = asNum - 1;
+            } else {
+              itemIdx = p.items.findIndex((it) => it.id === input.target);
+              if (itemIdx === -1) {
+                const lower = input.target.toLowerCase();
+                itemIdx = p.items.findIndex((it) => it.title.toLowerCase().includes(lower));
+              }
+            }
+            if (itemIdx === -1 || !p.items[itemIdx]) {
+              early = mkResult(p, false, `No plan item matched "${input.target}".`);
+              return p;
+            }
+            const item = p.items[itemIdx];
+            taskifyMeta.title = item.title;
+            taskifyMeta.details = item.details ?? "";
+            didTaskify = true;
+            break;
           }
-          if (itemIdx === -1 || !p.items[itemIdx]) {
-            early = mkResult(p, false, `No plan item matched "${input.target}".`);
+          default:
+            early = mkResult(p, false, `Unknown action "${input.action}".`);
             return p;
-          }
-          const item = p.items[itemIdx];
-          taskifyMeta.title = item.title;
-          taskifyMeta.details = item.details ?? "";
-          didTaskify = true;
-          break;
         }
-        default:
-          early = mkResult(p, false, `Unknown action "${input.action}".`);
-          return p;
-      }
-      return p;
-    });
+        return p;
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        message: `Plan change not saved \u2014 ${err instanceof Error ? err.message : String(err)}`,
+        plan: "",
+        count: 0,
+        open: 0
+      };
+    }
     if (early) return early;
     if (didTaskify) {
-      const taskPath = ctx.meta["task.path"];
-      if (typeof taskPath !== "string" || !taskPath) {
+      const taskPathRaw = ctx.meta["task.path"];
+      if (typeof taskPathRaw !== "string" || !taskPathRaw) {
         return mkResult(plan, false, "Task storage path not configured \u2014 cannot taskify.");
       }
-      const taskFile = await loadTasks(taskPath) ?? emptyTaskFile(sessionId);
+      let taskPath = taskPathRaw;
+      if (input.scope === "project") {
+        const lastSep = Math.max(taskPath.lastIndexOf("/"), taskPath.lastIndexOf("\\"));
+        taskPath = lastSep >= 0 ? taskPath.slice(0, lastSep + 1) + "backlog.tasks.json" : "backlog.tasks.json";
+      }
       const now = (/* @__PURE__ */ new Date()).toISOString();
-      taskFile.tasks.push({
-        id: `task_${randomUUID()}`,
-        title: taskifyMeta.title,
-        description: taskifyMeta.details || void 0,
-        type: "feature",
-        priority: "medium",
-        status: "pending",
-        createdAt: now,
-        updatedAt: now
-      });
-      await saveTasks(taskPath, taskFile);
-      return mkResult(
-        plan,
-        true,
-        `taskify ok \u2014 added "${taskifyMeta.title}" to tasks.
+      try {
+        const taskFile = await mutateTasks(taskPath, sessionId, (f) => {
+          f.tasks.push({
+            id: `task_${randomUUID()}`,
+            title: taskifyMeta.title,
+            description: taskifyMeta.details || void 0,
+            type: "feature",
+            priority: "medium",
+            status: "pending",
+            createdAt: now,
+            updatedAt: now
+          });
+          return f;
+        });
+        return mkResult(
+          plan,
+          true,
+          `taskify ok \u2014 added "${taskifyMeta.title}" to tasks.
 ${formatTaskList(taskFile.tasks)}`
-      );
+        );
+      } catch (err) {
+        return mkResult(plan, false, `taskify: task not saved \u2014 ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
     return mkResult(plan, true, `Plan ${input.action} ok.`);
   }
@@ -6840,6 +7095,7 @@ var readTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  icon: "file",
   maxOutputBytes: 262144,
   timeoutMs: 5e3,
   inputSchema: {
@@ -6856,6 +7112,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"]
@@ -6869,14 +7130,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`);
@@ -6884,17 +7158,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,
@@ -6903,6 +7198,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",
@@ -6912,6 +7263,7 @@ var replaceTool = {
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
+  icon: "edit",
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -7203,6 +7555,7 @@ var scaffoldTool = {
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write.outside-project", "fs.write"],
+  icon: "scaffold",
   timeoutMs: 3e4,
   inputSchema: {
     type: "object",
@@ -7298,6 +7651,7 @@ var searchTool = {
   permission: "confirm",
   mutating: false,
   capabilities: ["net.outbound"],
+  icon: "search",
   timeoutMs: TIMEOUT_MS3,
   inputSchema: {
     type: "object",
@@ -7511,6 +7865,7 @@ var setWorkingDirTool = {
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.read"],
+  icon: "settings",
   timeoutMs: 5e3,
   inputSchema: {
     type: "object",
@@ -7571,11 +7926,12 @@ function findTaskIndex(tasks, query2) {
 var taskTool = {
   name: "task",
   category: "Session",
-  description: "Manage structured work items with dependencies, types, and priorities. Use this for complex, multi-step work where tasks have ordering constraints. Unlike `todo` (flat, tactical), `task` supports typed work (feature/bugfix/refactor/etc.), dependencies between items, priority ranking, and agent assignment. The task list persists across session resumes.",
-  usageHint: 'USE FOR STRUCTURED WORK:\n- `action: "replace"` \u2014 set the complete task list (tasks ordered by priority)\n- `action: "add"` \u2014 append a single task\n- `action: "status"` \u2014 update a task\'s status (e.g. pending\u2192in_progress, in_progress\u2192completed)\n- `action: "show"` \u2014 view current tasks without changing them\n- `action: "promote"` \u2014 convert a task into actionable todo items via `target` (id|index|substring)\n- `action: "planify"` \u2014 promote a task to a plan item (strategic level) via `target` (id|index|substring)\n\nTask fields:\n- `dependsOn`: list of task IDs this one waits for\n- `type`: "feature" | "bugfix" | "refactor" | "docs" | "test" | "chore"\n- `priority`: "critical" | "high" | "medium" | "low"\n- `assignee`: agent/subagent name (e.g. "bug-hunter", "refactor-planner")\n- `estimateHours`: rough time estimate',
+  description: 'Manage session-persistent structured work items with dependencies, types, and priorities. Unlike `todo` (flat, tactical), `task` supports typed work (feature/bugfix/refactor/etc.), dependencies between items, priority ranking, and agent assignment. Tasks are written to disk and survive session resumes. By default they are isolated to this session; use `scope: "project"` to store tasks in a shared project-level file visible to all sessions.',
+  usageHint: 'USE FOR STRUCTURED WORK:\n- `action: "replace"` \u2014 set the complete task list (tasks ordered by priority)\n- `action: "add"` \u2014 append a single task\n- `action: "status"` \u2014 update a task\'s status (e.g. pending\u2192in_progress, in_progress\u2192completed)\n- `action: "show"` \u2014 view current tasks without changing them\n- `action: "promote"` \u2014 convert a task into actionable todo items via `target` (id|index|substring)\n- `action: "planify"` \u2014 promote a task to a plan item (strategic level) via `target` (id|index|substring)\n\nTask fields:\n- `dependsOn`: list of task IDs this one waits for\n- `type`: "feature" | "bugfix" | "refactor" | "docs" | "test" | "chore"\n- `priority`: "critical" | "high" | "medium" | "low"\n- `assignee`: agent/subagent name (e.g. "bug-hunter", "refactor-planner")\n- `estimateHours`: rough time estimate\n- `scope`: "session" (default, isolated) or "project" (shared across sessions)',
   permission: "confirm",
   mutating: true,
   capabilities: ["fs.write"],
+  icon: "task",
   timeoutMs: 2e3,
   inputSchema: {
     type: "object",
@@ -7641,12 +7997,26 @@ var taskTool = {
         type: "array",
         items: { type: "string" },
         description: "Optional subtask titles for action=promote. Each becomes a pending todo."
+      },
+      scope: {
+        type: "string",
+        enum: ["session", "project"],
+        description: 'Storage scope: "session" (default, isolated to this session) or "project" (shared across all sessions for this project).'
       }
     },
     required: ["action"]
   },
   async execute(input, ctx) {
-    const taskPath = ctx.meta["task.path"];
+    const sessionTaskPath = ctx.meta["task.path"];
+    let taskPath;
+    if (input.scope === "project") {
+      if (typeof sessionTaskPath === "string") {
+        const lastSep = Math.max(sessionTaskPath.lastIndexOf("/"), sessionTaskPath.lastIndexOf("\\"));
+        taskPath = lastSep >= 0 ? sessionTaskPath.slice(0, lastSep + 1) + "backlog.tasks.json" : "backlog.tasks.json";
+      }
+    } else {
+      taskPath = sessionTaskPath;
+    }
     if (typeof taskPath !== "string" || !taskPath) {
       return { ok: false, message: "Task storage path not configured.", count: 0, completed: 0, inProgress: 0 };
     }
@@ -7656,23 +8026,66 @@ var taskTool = {
     const planifyMeta = { title: "", details: "" };
     let didPlanify = false;
     let todosToReplace = null;
-    const file = await mutateTasks(taskPath, sessionId, async (f) => {
-      switch (input.action) {
-        case "show":
-          break;
-        case "replace": {
-          if (!Array.isArray(input.tasks)) {
-            early = { ok: false, message: "action=replace requires `tasks` array.", count: 0, completed: 0, inProgress: 0 };
-            return f;
+    let file;
+    try {
+      file = await mutateTasks(taskPath, sessionId, async (f) => {
+        switch (input.action) {
+          case "show":
+            break;
+          case "replace": {
+            if (!Array.isArray(input.tasks)) {
+              early = { ok: false, message: "action=replace requires `tasks` array.", count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            const newIds = new Set(input.tasks.map((t) => t.id));
+            if (newIds.size !== input.tasks.length) {
+              const seen = /* @__PURE__ */ new Set();
+              const dupes = [...new Set(input.tasks.map((t) => t.id).filter((id) => seen.has(id) ? true : (seen.add(id), false)))];
+              early = {
+                ok: false,
+                message: `action=replace has duplicate task IDs: ${dupes.join(", ")}. Each task id must be unique.`,
+                count: 0,
+                completed: 0,
+                inProgress: 0
+              };
+              return f;
+            }
+            for (const t of input.tasks) {
+              if (t.dependsOn && t.dependsOn.length > 0) {
+                const missing = t.dependsOn.filter((d) => !newIds.has(d));
+                if (missing.length > 0) {
+                  early = {
+                    ok: false,
+                    message: `dependsOn validation failed: task "${t.id}" references unknown IDs: ${missing.join(", ")}`,
+                    count: 0,
+                    completed: 0,
+                    inProgress: 0
+                  };
+                  return f;
+                }
+              }
+            }
+            const now = (/* @__PURE__ */ new Date()).toISOString();
+            f.tasks = input.tasks.map((t) => ({
+              ...t,
+              createdAt: t.createdAt || now,
+              updatedAt: now
+            }));
+            break;
           }
-          const newIds = new Set(input.tasks.map((t) => t.id));
-          for (const t of input.tasks) {
+          case "add": {
+            const t = input.task;
+            if (!t || !t.title) {
+              early = { ok: false, message: "action=add requires `task` with at least `title`.", count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
             if (t.dependsOn && t.dependsOn.length > 0) {
-              const missing = t.dependsOn.filter((d) => !newIds.has(d));
+              const existingIds = new Set(f.tasks.map((e) => e.id));
+              const missing = t.dependsOn.filter((d) => !existingIds.has(d));
               if (missing.length > 0) {
                 early = {
                   ok: false,
-                  message: `dependsOn validation failed: task "${t.id}" references unknown IDs: ${missing.join(", ")}`,
+                  message: `dependsOn validation failed: unknown task IDs: ${missing.join(", ")}`,
                   count: 0,
                   completed: 0,
                   inProgress: 0
@@ -7680,165 +8093,170 @@ var taskTool = {
                 return f;
               }
             }
+            const now = (/* @__PURE__ */ new Date()).toISOString();
+            const newTask = {
+              id: `task_${Date.now()}_${randomUUID().slice(0, 8)}`,
+              title: t.title,
+              description: t.description,
+              type: t.type || "feature",
+              priority: t.priority || "medium",
+              status: t.status || "pending",
+              dependsOn: t.dependsOn,
+              assignee: t.assignee,
+              estimateHours: t.estimateHours,
+              tags: t.tags,
+              createdAt: now,
+              updatedAt: now
+            };
+            f.tasks.push(newTask);
+            break;
           }
-          const now = (/* @__PURE__ */ new Date()).toISOString();
-          f.tasks = input.tasks.map((t) => ({
-            ...t,
-            createdAt: t.createdAt || now,
-            updatedAt: now
-          }));
-          break;
-        }
-        case "add": {
-          const t = input.task;
-          if (!t || !t.title) {
-            early = { ok: false, message: "action=add requires `task` with at least `title`.", count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          if (t.dependsOn && t.dependsOn.length > 0) {
-            const existingIds = new Set(f.tasks.map((e) => e.id));
-            const missing = t.dependsOn.filter((d) => !existingIds.has(d));
-            if (missing.length > 0) {
-              early = {
-                ok: false,
-                message: `dependsOn validation failed: unknown task IDs: ${missing.join(", ")}`,
-                count: 0,
-                completed: 0,
-                inProgress: 0
-              };
+          case "status": {
+            if (!input.id || !input.status) {
+              early = { ok: false, message: "action=status requires `id` and `status`.", count: 0, completed: 0, inProgress: 0 };
               return f;
             }
+            const task = f.tasks.find((t) => t.id === input.id);
+            if (!task) {
+              early = { ok: false, message: `Task "${input.id}" not found.`, count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            task.status = input.status;
+            task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+            break;
           }
-          const now = (/* @__PURE__ */ new Date()).toISOString();
-          const newTask = {
-            id: `task_${Date.now()}_${randomUUID().slice(0, 8)}`,
-            title: t.title,
-            description: t.description,
-            type: t.type || "feature",
-            priority: t.priority || "medium",
-            status: t.status || "pending",
-            dependsOn: t.dependsOn,
-            assignee: t.assignee,
-            estimateHours: t.estimateHours,
-            tags: t.tags,
-            createdAt: now,
-            updatedAt: now
-          };
-          f.tasks.push(newTask);
-          break;
-        }
-        case "status": {
-          if (!input.id || !input.status) {
-            early = { ok: false, message: "action=status requires `id` and `status`.", count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          const task = f.tasks.find((t) => t.id === input.id);
-          if (!task) {
-            early = { ok: false, message: `Task "${input.id}" not found.`, count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          task.status = input.status;
-          task.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-          break;
-        }
-        case "promote": {
-          const target = input.target?.trim();
-          if (!target) {
-            early = { ok: false, message: "action=promote requires `target` (task id, index, or title substring).", count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          const idx = findTaskIndex(f.tasks, target);
-          if (idx === -1) {
-            early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          const match = f.tasks[idx];
-          if (!match) {
-            early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          if (match.status !== "completed" && match.status !== "failed") {
-            match.status = "in_progress";
-            match.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
-          }
-          const todos = [];
-          const ts2 = Date.now();
-          todos.push({
-            id: `todo_${ts2}_task`,
-            content: match.title,
-            status: "in_progress",
-            activeForm: match.title,
-            promotedFromTask: match.id
-          });
-          if (match.description) {
+          case "promote": {
+            const target = input.target?.trim();
+            if (!target) {
+              early = { ok: false, message: "action=promote requires `target` (task id, index, or title substring).", count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            const idx = findTaskIndex(f.tasks, target);
+            if (idx === -1) {
+              early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            const match = f.tasks[idx];
+            if (!match) {
+              early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            if (match.status !== "completed" && match.status !== "failed") {
+              match.status = "in_progress";
+              match.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+            }
+            const todos = [];
+            const ts2 = Date.now();
             todos.push({
-              id: `todo_${ts2}_${randomUUID().slice(0, 6)}`,
-              content: match.description.slice(0, 200),
-              status: "pending",
+              id: `todo_${ts2}_task`,
+              content: match.title,
+              status: "in_progress",
+              activeForm: match.title,
               promotedFromTask: match.id
             });
-          }
-          if (input.subtasks && input.subtasks.length > 0) {
-            for (const st of input.subtasks) {
+            if (match.description) {
               todos.push({
                 id: `todo_${ts2}_${randomUUID().slice(0, 6)}`,
-                content: st,
+                content: match.description.slice(0, 200),
                 status: "pending",
                 promotedFromTask: match.id
               });
             }
+            if (input.subtasks && input.subtasks.length > 0) {
+              for (const st of input.subtasks) {
+                todos.push({
+                  id: `todo_${ts2}_${randomUUID().slice(0, 6)}`,
+                  content: st,
+                  status: "pending",
+                  promotedFromTask: match.id
+                });
+              }
+            }
+            todosToReplace = todos;
+            promoteMeta.count = todos.length;
+            promoteMeta.title = match.title;
+            break;
           }
-          todosToReplace = todos;
-          promoteMeta.count = todos.length;
-          promoteMeta.title = match.title;
-          break;
-        }
-        case "planify": {
-          const target = input.target?.trim();
-          if (!target) {
-            early = { ok: false, message: "action=planify requires `target` (task id, index, or title substring).", count: 0, completed: 0, inProgress: 0 };
-            return f;
-          }
-          const idx = findTaskIndex(f.tasks, target);
-          if (idx === -1) {
-            early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
-            return f;
+          case "planify": {
+            const target = input.target?.trim();
+            if (!target) {
+              early = { ok: false, message: "action=planify requires `target` (task id, index, or title substring).", count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            const idx = findTaskIndex(f.tasks, target);
+            if (idx === -1) {
+              early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            const match = f.tasks[idx];
+            if (!match) {
+              early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
+              return f;
+            }
+            planifyMeta.title = match.title;
+            planifyMeta.details = match.description ?? "";
+            didPlanify = true;
+            break;
           }
-          const match = f.tasks[idx];
-          if (!match) {
-            early = { ok: false, message: `No task matched "${target}".`, count: 0, completed: 0, inProgress: 0 };
+          default:
+            early = { ok: false, message: `Unknown action "${input.action}". Use replace | add | status | show | promote | planify.`, count: 0, completed: 0, inProgress: 0 };
             return f;
-          }
-          planifyMeta.title = match.title;
-          planifyMeta.details = match.description ?? "";
-          didPlanify = true;
-          break;
         }
-        default:
-          early = { ok: false, message: `Unknown action "${input.action}". Use replace | add | status | show | promote | planify.`, count: 0, completed: 0, inProgress: 0 };
-          return f;
-      }
-      return f;
-    });
+        return f;
+      });
+    } catch (err) {
+      return {
+        ok: false,
+        message: `Task change not saved \u2014 ${err instanceof Error ? err.message : String(err)}`,
+        count: 0,
+        completed: 0,
+        inProgress: 0
+      };
+    }
     if (todosToReplace) ctx.state.replaceTodos(todosToReplace);
     if (early) return early;
     if (didPlanify) {
       const { title, details } = planifyMeta;
-      const planPath = ctx.meta["plan.path"];
-      if (typeof planPath === "string" && planPath) {
-        const planCfg = await loadPlan(planPath) ?? emptyPlan(sessionId);
-        const { plan: updated } = addPlanItem(planCfg, title, details || void 0);
-        await savePlan(planPath, updated);
+      const planPathRaw = ctx.meta["plan.path"];
+      const prog = computeTaskItemProgress(file.tasks);
+      if (typeof planPathRaw === "string" && planPathRaw) {
+        let planPath = planPathRaw;
+        if (input.scope === "project") {
+          const lastSep = Math.max(planPath.lastIndexOf("/"), planPath.lastIndexOf("\\"));
+          planPath = lastSep >= 0 ? planPath.slice(0, lastSep + 1) + "backlog.plan.json" : "backlog.plan.json";
+        }
+        let formatted = "";
+        try {
+          await mutatePlan(planPath, sessionId, (pf) => {
+            const { plan: updated } = addPlanItem(pf, title, details || void 0);
+            formatted = formatPlan(updated);
+            return updated;
+          });
+        } catch (err) {
+          return {
+            ok: false,
+            message: `planify: plan not saved \u2014 ${err instanceof Error ? err.message : String(err)}`,
+            count: file.tasks.length,
+            completed: prog.completed,
+            inProgress: prog.inProgress
+          };
+        }
         return {
           ok: true,
           message: `planify ok \u2014 added "${title}" to plan.
-${formatPlan(updated)}`,
+${formatted}`,
           count: file.tasks.length,
-          completed: computeTaskItemProgress(file.tasks).completed,
-          inProgress: computeTaskItemProgress(file.tasks).inProgress
+          completed: prog.completed,
+          inProgress: prog.inProgress
         };
       }
-      return { ok: false, message: "Plan storage path not configured \u2014 cannot planify.", count: 0, completed: 0, inProgress: 0 };
+      return {
+        ok: false,
+        message: "Plan storage path not configured \u2014 cannot planify.",
+        count: file.tasks.length,
+        completed: prog.completed,
+        inProgress: prog.inProgress
+      };
     }
     const p = computeTaskItemProgress(file.tasks);
     const summary = promoteMeta.count > 0 ? `promote ok \u2014 ${promoteMeta.count} todo(s) created from "${promoteMeta.title}".
@@ -7859,6 +8277,7 @@ var testTool = {
   usageHint: "ESSENTIAL BEFORE CONSIDERING WORK DONE:\n\n- Use `files` or `grep` to run only relevant tests during development.\n- `coverage: true` is useful when working on critical paths.\nRun tests frequently. A clean test run is usually required before the task can be considered complete.",
   permission: "confirm",
   mutating: false,
+  icon: "test",
   timeoutMs: 12e4,
   capabilities: ["shell.restricted"],
   inputSchema: {
@@ -8018,6 +8437,7 @@ var todoTool = {
   // mutates only conversation state (ctx.todos), not external state — no confirmation needed
   timeoutMs: 1e3,
   capabilities: ["session.todo"],
+  icon: "todo",
   inputSchema: {
     type: "object",
     properties: {
@@ -8126,6 +8546,7 @@ var toolHelpTool = {
   mutating: false,
   timeoutMs: 5e3,
   capabilities: ["tool.meta"],
+  icon: "meta",
   inputSchema: {
     type: "object",
     properties: {
@@ -8249,6 +8670,7 @@ var toolSearchTool = {
   mutating: false,
   timeoutMs: 1e3,
   capabilities: ["tool.meta"],
+  icon: "meta",
   inputSchema: {
     type: "object",
     properties: {
@@ -8328,6 +8750,7 @@ var toolUseTool = {
   mutating: true,
   timeoutMs: 6e4,
   capabilities: ["tool.mutate.any"],
+  icon: "meta",
   inputSchema: {
     type: "object",
     properties: {
@@ -8408,6 +8831,7 @@ var treeTool = {
   permission: "auto",
   mutating: false,
   capabilities: ["fs.read"],
+  icon: "tree",
   timeoutMs: 15e3,
   inputSchema: {
     type: "object",
@@ -8573,6 +8997,7 @@ var typecheckTool = {
   mutating: false,
   timeoutMs: 12e4,
   capabilities: ["shell.restricted"],
+  icon: "code",
   inputSchema: {
     type: "object",
     properties: {
@@ -8661,6 +9086,7 @@ var writeTool = {
   mutating: true,
   timeoutMs: 5e3,
   capabilities: ["fs.write"],
+  icon: "file",
   inputSchema: {
     type: "object",
     properties: {