@wrongstack/tools 0.305.0 → 0.306.0

package/dist/plan.js

@@ -1390,6 +1390,18 @@ var KANBAN_INPUT_SCHEMA = {
     },
     transitionAction: { type: "string" },
     transitionComment: { type: "string" },
+    tickChecks: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: {
+          checkId: { type: "string" },
+          checkStatus: { type: "string", enum: ["passed", "failed", "skipped"] }
+        },
+        required: ["checkId", "checkStatus"]
+      },
+      description: "`transition_task` (to=done only): flip one or more manual criteria to `passed` before the gate fires. Read ids from kanban get_task. Non-manual criteria are refused."
+    },
     attachmentUrl: { type: "string" },
     attachmentTitle: { type: "string" },
     attachmentType: {
@@ -1577,6 +1589,9 @@ var kanbanTool = {
   description: KANBAN_TOOL_DESCRIPTION,
   usageHint: KANBAN_TOOL_USAGE_HINT,
   permission: "confirm",
+  // WS-046: gives permission decisions something to key on.
+  // The action performed; kanban has no single file or path subject.
+  subjectKey: "action",
   mutating: true,
   capabilities: ["fs.write"],
   icon: "task",
@@ -2018,6 +2033,7 @@ var kanbanTool = {
               actor: input.author,
               comment: input.transitionComment,
               ...input.transitionAction !== void 0 ? { action: input.transitionAction } : {},
+              ...input.tickChecks !== void 0 ? { tickChecks: input.tickChecks } : {},
               ...input.attachmentUrl !== void 0 ? {
                 attachment: {
                   url: input.attachmentUrl,
@@ -2410,8 +2426,52 @@ var kanbanTool = {
     } catch (err) {
       return fail(stripLifecycleIssues(err instanceof Error ? err.message : String(err)));
     }
+  },
+  serialize(output, input) {
+    return serializeKanbanOutput(output, input);
   }
 };
+var KANBAN_BOARD_TRANSCRIPT_BYTE_CAP = 16384;
+var KANBAN_FULL_BOARD_ACTIONS = /* @__PURE__ */ new Set([
+  "get_board",
+  "export_markdown",
+  "export_task_graph"
+]);
+function serializeKanbanOutput(output, input) {
+  const action = input && typeof input === "object" ? input.action : void 0;
+  const board = output.board;
+  if (board) {
+    const keepFull = typeof action === "string" && KANBAN_FULL_BOARD_ACTIONS.has(action);
+    let boardBytes = 0;
+    if (!keepFull) {
+      try {
+        boardBytes = Buffer.byteLength(JSON.stringify(board), "utf8");
+      } catch {
+        boardBytes = 0;
+      }
+    }
+    if (!keepFull && boardBytes > KANBAN_BOARD_TRANSCRIPT_BYTE_CAP) {
+      const columns = {};
+      for (const column of board.columns) {
+        columns[column.title || column.id] = board.tasks.filter(
+          (task) => task.columnId === column.id
+        ).length;
+      }
+      const compact = {
+        ...output,
+        board: {
+          id: board.id,
+          title: board.title,
+          columns,
+          totalTasks: board.tasks.length,
+          note: `Full board (${boardBytes} bytes) omitted from the transcript; use get_board to load it.`
+        }
+      };
+      return JSON.stringify(compact, null, 2);
+    }
+  }
+  return JSON.stringify(output, null, 2);
+}
 
 // src/todo.ts
 function normalizedTitle(value) {
@@ -2750,7 +2810,8 @@ var todoTool = {
     }
     for (const planId of completedPlanIds) {
       if (pendingPlanIds.has(planId)) continue;
-      const planPath = ctx.meta["plan.path"];
+      const meta = ctx.meta;
+      const planPath = meta["plan.path.resolved"] ?? meta["plan.path"];
       if (typeof planPath !== "string" || !planPath) continue;
       try {
         const plan = await loadPlan2(planPath);
@@ -2763,7 +2824,8 @@ var todoTool = {
     }
     for (const taskId of completedTaskIds) {
       if (pendingTaskIds.has(taskId)) continue;
-      const taskPath = ctx.meta["task.path"];
+      const meta = ctx.meta;
+      const taskPath = meta["task.path.resolved"] ?? meta["task.path"];
       if (typeof taskPath !== "string" || !taskPath) continue;
       try {
         const file = await loadTasks3(taskPath);
@@ -2879,7 +2941,16 @@ var planTool = {
           sessionPlanPath.lastIndexOf("/"),
           sessionPlanPath.lastIndexOf("\\")
         );
-        planPath = lastSep >= 0 ? sessionPlanPath.slice(0, lastSep + 1) + "backlog.plan.json" : "backlog.plan.json";
+        if (lastSep < 0) {
+          return {
+            ok: false,
+            message: `Cannot derive the project-scoped plan path: session plan path "${sessionPlanPath}" has no directory component.`,
+            plan: "",
+            count: 0,
+            open: 0
+          };
+        }
+        planPath = sessionPlanPath.slice(0, lastSep + 1) + "backlog.plan.json";
       }
     } else {
       planPath = sessionPlanPath;
@@ -3072,6 +3143,7 @@ var planTool = {
         open: 0
       };
     }
+    ctx.meta["plan.path.resolved"] = planPath;
     await projectSessionPlanToKanban(ctx.projectRoot, plan.items, sessionId);
     if (todosToReplace) {
       await todoTool.execute({ todos: todosToReplace }, ctx, {
@@ -3104,6 +3176,7 @@ var planTool = {
           });
           return f;
         });
+        ctx.meta["task.path.resolved"] = taskPath;
         return mkResult(
           plan,
           true,

package/dist/process-registry.d.ts

@@ -11,8 +11,14 @@ export interface TrackedProcess {
     sessionId?: string | undefined;
     /** The raw ChildProcess handle. Never call .kill() directly on this —
      *  use `kill()` below which handles process groups correctly on POSIX
-     *  and degrades gracefully on Windows. */
-    child: ChildProcess;
+     *  and degrades gracefully on Windows.
+     *
+     *  `null` for entries mirrored from the persistent registry
+     *  (process-registry-persistent.ts): those track processes owned by OTHER
+     *  host instances, so there is no live handle in this process. All
+     *  registry paths must tolerate a null child (kill by PID, liveness by
+     *  `process.kill(pid, 0)` probe). */
+    child: ChildProcess | null;
     /** True only when this child was spawned as a POSIX process-group/session
      *  leader (for example `spawn(..., { detached: true })`) and `pid` is the
      *  actual `child.pid`. Negative-PID signaling is host-wide dangerous for

package/dist/process-registry.js

@@ -201,8 +201,11 @@ var SENSITIVE_FLAG_PATTERNS = [
   /--(?:token|password|passwd|pwd|secret|api[-_]?key|api[-_]?secret|auth|credential|private[-_]?key|access[-_]?key|github[-_]?token|gh[-_]?token|bearer|jwt|oauth|pin|pincode|passphrase|access[-_]?token)(?:[=\s,][^\s]*)?/gi,
   // -t short flag (token): attached (-tVALUE), separated (-t VALUE), or -t=VALUE.
   // (?<![-\w]) anchors to a token start so we don't match the `-t` inside `--token`.
+  // The value must be token-like (>= 8 chars) so ordinary combined flags such
+  // as `tar -tf` / `ssh -tt` are not eaten. Global flag: EVERY occurrence is
+  // redacted, not just the first.
   // NOTE: synced with @wrongstack/core observability/redact-command.ts.
-  /(?<![-\w])-t(?:[=\s]+)?[^\s,-]+/,
+  /(?<![-\w])-t(?:[=\s]+)?[^\s,-]{8,}/g,
   // -p|-password|-a (redis auth) short flags: attached + separated + =value.
   // Same token-start anchor; over-redaction is an accepted tradeoff for a
   // redaction function. Synced with core copy.
@@ -210,8 +213,9 @@ var SENSITIVE_FLAG_PATTERNS = [
   // env var–style secrets: TOKEN=x, API_KEY=y, etc.
   /(?:TOKEN|API_KEY|API_SECRET|AUTH_TOKEN|GITHUB_TOKEN|GH_TOKEN|BEARER|JWT|OAUTH|CREDENTIAL|SECRET|PRIVATE_KEY|PASSWORD|PASSWD)\s*[=:]\s*[^\s,]+/gi,
   // Generic high-entropy look: base64 strings >32 chars or hex strings >32 digits — but only
-  // when preceded by a flag name (e.g. --github-token=EyJ...).
-  /--\w*(?:token|key|secret|password|passwd|auth|credential)\w*[=\s,][A-Za-z0-9+/=]{32,}/
+  // when preceded by a flag name (e.g. --github-token=EyJ...). Global flag so
+  // every such flag in the command line is redacted, not just the first.
+  /--\w*(?:token|key|secret|password|passwd|auth|credential)\w*[=\s,][A-Za-z0-9+/=]{32,}/g
 ];
 function redactCommand(cmd) {
   let result = cmd;
@@ -300,11 +304,15 @@ var ProcessRegistryImpl = class {
     return Number.isInteger(pid) && pid > 1 && pid !== process.pid && pid !== process.ppid;
   }
   _canSignalProcessGroup(p) {
-    return os.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && typeof p.child.pid === "number" && p.child.pid === p.pid;
+    return os.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && p.child !== null && typeof p.child.pid === "number" && p.child.pid === p.pid;
   }
   _killChildDirect(p, signal) {
     try {
-      p.child.kill(signal);
+      if (p.child) {
+        p.child.kill(signal);
+        return;
+      }
+      if (this._isSafeSignalPid(p.pid)) process.kill(p.pid, signal);
     } catch {
     }
   }
@@ -502,15 +510,15 @@ var ProcessRegistryImpl = class {
     this._pruneStale(pid);
     const p = this.processes.get(pid);
     if (!p) return false;
-    if (p.killed) return true;
+    if (p.killed && opts.force !== true) return true;
     if (p.protected && opts.includeProtected !== true) return false;
     if (opts.preserveBackground && p.background) return false;
     const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
     const isWin = os.platform() === "win32";
     if (isWin) {
-      const liveRealChild = p.child.exitCode === null && typeof p.child.pid === "number";
+      const liveRealChild = p.child === null || p.child.exitCode === null && typeof p.child.pid === "number";
       const directFallback = () => {
-        if (p.child.exitCode === null) {
+        if (p.child && p.child.exitCode === null) {
           try {
             p.child.kill("SIGKILL");
           } catch {
@@ -522,10 +530,7 @@ var ProcessRegistryImpl = class {
         onSettled: directFallback
       })) {
       } else {
-        try {
-          p.child.kill(force ? "SIGKILL" : "SIGTERM");
-        } catch {
-        }
+        this._killChildDirect(p, force ? "SIGKILL" : "SIGTERM");
       }
       p.killed = true;
       return true;
@@ -536,7 +541,7 @@ var ProcessRegistryImpl = class {
       } else {
         this._killPosix(p, "SIGTERM");
         const timer = setTimeout(() => {
-          if (this.processes.has(pid) && !p.child.killed) {
+          if (this.processes.has(pid) && !p.child?.killed) {
             this._killPosix(p, "SIGKILL");
           }
         }, graceMs);
@@ -591,6 +596,16 @@ var ProcessRegistryImpl = class {
    * before reusing a PID, but we want to clean up before that becomes a risk.
    */
   _isStaleEntry(entry) {
+    if (entry.child === null) {
+      if (Date.now() - entry.startedAt <= 6e4) return false;
+      if (os.platform() === "win32") return false;
+      try {
+        process.kill(entry.pid, 0);
+        return false;
+      } catch (err) {
+        return err.code !== "EPERM";
+      }
+    }
     return entry.child.exitCode !== null && Date.now() - entry.startedAt > 6e4;
   }
   /**

package/dist/ps-slash.js

@@ -270,11 +270,15 @@ var ProcessRegistryImpl = class {
     return Number.isInteger(pid) && pid > 1 && pid !== process.pid && pid !== process.ppid;
   }
   _canSignalProcessGroup(p) {
-    return os.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && typeof p.child.pid === "number" && p.child.pid === p.pid;
+    return os.platform() !== "win32" && p.processGroupLeader === true && this._isSafeSignalPid(p.pid) && p.child !== null && typeof p.child.pid === "number" && p.child.pid === p.pid;
   }
   _killChildDirect(p, signal) {
     try {
-      p.child.kill(signal);
+      if (p.child) {
+        p.child.kill(signal);
+        return;
+      }
+      if (this._isSafeSignalPid(p.pid)) process.kill(p.pid, signal);
     } catch {
     }
   }
@@ -472,15 +476,15 @@ var ProcessRegistryImpl = class {
     this._pruneStale(pid);
     const p = this.processes.get(pid);
     if (!p) return false;
-    if (p.killed) return true;
+    if (p.killed && opts.force !== true) return true;
     if (p.protected && opts.includeProtected !== true) return false;
     if (opts.preserveBackground && p.background) return false;
     const { force = false, graceMs = DEFAULT_GRACE_MS } = opts;
     const isWin = os.platform() === "win32";
     if (isWin) {
-      const liveRealChild = p.child.exitCode === null && typeof p.child.pid === "number";
+      const liveRealChild = p.child === null || p.child.exitCode === null && typeof p.child.pid === "number";
       const directFallback = () => {
-        if (p.child.exitCode === null) {
+        if (p.child && p.child.exitCode === null) {
           try {
             p.child.kill("SIGKILL");
           } catch {
@@ -492,10 +496,7 @@ var ProcessRegistryImpl = class {
         onSettled: directFallback
       })) {
       } else {
-        try {
-          p.child.kill(force ? "SIGKILL" : "SIGTERM");
-        } catch {
-        }
+        this._killChildDirect(p, force ? "SIGKILL" : "SIGTERM");
       }
       p.killed = true;
       return true;
@@ -506,7 +507,7 @@ var ProcessRegistryImpl = class {
       } else {
         this._killPosix(p, "SIGTERM");
         const timer = setTimeout(() => {
-          if (this.processes.has(pid) && !p.child.killed) {
+          if (this.processes.has(pid) && !p.child?.killed) {
             this._killPosix(p, "SIGKILL");
           }
         }, graceMs);
@@ -561,6 +562,16 @@ var ProcessRegistryImpl = class {
    * before reusing a PID, but we want to clean up before that becomes a risk.
    */
   _isStaleEntry(entry) {
+    if (entry.child === null) {
+      if (Date.now() - entry.startedAt <= 6e4) return false;
+      if (os.platform() === "win32") return false;
+      try {
+        process.kill(entry.pid, 0);
+        return false;
+      } catch (err) {
+        return err.code !== "EPERM";
+      }
+    }
     return entry.child.exitCode !== null && Date.now() - entry.startedAt > 6e4;
   }
   /**
@@ -854,7 +865,6 @@ var PersistentProcessRegistry = class {
     try {
       const data = await readRegistryFile(this.registryPath);
       data.instances.set(String(entry.pid), entry);
-      const child = null;
       this.baseRegistry.register({
         pid: entry.pid,
         name: entry.name,
@@ -862,7 +872,7 @@ var PersistentProcessRegistry = class {
         startedAt: entry.startedAt,
         sessionId: entry.sessionId,
         protected: entry.protected,
-        child
+        child: null
       });
       await writeRegistryFile(this.registryPath, data);
     } finally {

package/dist/read.js

@@ -7277,7 +7277,6 @@ import * as fs10 from "node:fs";
 import * as os3 from "node:os";
 import * as path14 from "node:path";
 import { fileURLToPath as fileURLToPath3 } from "node:url";
-import { assertUnixSocketPathWithinLimit } from "@wrongstack/core/utils";
 var PROJECT_INDEX_SERVER_PROTOCOL_VERSION = 1;
 var PROJECT_INDEX_SERVER_METADATA_FILE = "server.json";
 var PROJECT_INDEX_SERVER_SOCKET_DIR = `wsci-v${PROJECT_INDEX_SERVER_PROTOCOL_VERSION}`;
@@ -8254,7 +8253,7 @@ var MAX_BYTES = 5 * 1024 * 1024;
 var readTool = {
   name: "read",
   category: "Filesystem",
-  description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed with a `   N| ` prefix for easy reference in edits. When advanced mode is on or `includeSymbols` is set, the result also includes a `symbols` field listing codebase-index symbol names, kinds, and line numbers for the file (not file content).",
+  description: "Read the contents of a file with line numbers. This is the primary way to inspect source code, configuration, or any text file before making changes. Lines are returned 1-indexed in the form `N\u2192content` (line number, then a `\u2192` separator, then the raw line). The `N\u2192` prefix is display-only \u2014 always strip it before reusing the text, e.g. never include it in `edit.old_string`. When advanced mode is on or `includeSymbols` is set, the result also includes a `symbols` field listing codebase-index symbol names, kinds, and line numbers for the file (not file content).",
   usageHint: "FOUNDATIONAL TOOL \u2014 call this before almost any edit operation.\n\nBest practices:\n- Always read a file before using `edit`, `replace`, or `write` on it (the system often requires it for safety).\n- Use `offset` + `limit` for very large files instead of reading everything at once.\n- Default limit is generous (2000 lines) but can be increased.\n- The output format is designed to be directly usable as context for `edit` operations.\n- Set `includeSymbols: true` to also receive the codebase-index symbol listing for the file.\n- Enable advanced mode (`ctx.meta['tools.read.advancedMode'] = true`) to auto-inject symbols on every read.",
   selection: {
     doNotUseWhen: "you need to search many files for matching content.",
@@ -8275,11 +8274,13 @@ var readTool = {
       },
       offset: {
         type: "integer",
+        minimum: 1,
         description: "1-based starting line number. Use together with `limit` for large files."
       },
       limit: {
         type: "integer",
-        description: "Maximum number of lines to return (default is 2000)."
+        minimum: 0,
+        description: "Maximum number of lines to return (default 2000). Values above 5000 are clamped to 5000 \u2014 page with `offset` for more."
       },
       mode: {
         type: "string",
@@ -8358,7 +8359,12 @@ var readTool = {
     }
     const buf = await fs13.readFile(absPath);
     if (isBinaryBuffer(buf)) {
-      throw new Error(`read: "${input.path}" appears to be binary`);
+      throw new FsError({
+        message: `read: "${input.path}" appears to be binary`,
+        code: "FS_READ_FAILED",
+        path: absPath,
+        context: { reason: "binary" }
+      });
     }
     const text = buf.toString("utf8");
     const contentHash = sha256hex(text);

package/dist/replace.d.ts

@@ -16,7 +16,11 @@ interface ReplaceOutput {
         diff?: string | undefined;
     }[];
     dry_run: boolean;
+    /** Set when the combined diff payload was truncated to the output budget. */
+    note?: string | undefined;
 }
 export declare const replaceTool: Tool<ReplaceInput, ReplaceOutput>;
+/** Test-only: forget the cached rg availability so mocks can vary per test. */
+export declare function __resetRgDetectionForTests(): void;
 export {};
 //# sourceMappingURL=replace.d.ts.map

package/dist/replace.js

@@ -165,6 +165,20 @@ function ensureInsideRoot(absPath, ctx) {
 function safeResolve(input, ctx) {
   return ensureInsideRoot(resolvePath(input, ctx), ctx);
 }
+function truncateDiffPayload(diff, maxBytes) {
+  const total = Buffer.byteLength(diff, "utf8");
+  if (total <= maxBytes) return { text: diff, truncated: false };
+  const MARKER_RESERVE = 96;
+  let head = takeHeadBytes(diff, Math.max(0, maxBytes - MARKER_RESERVE));
+  const nl = head.lastIndexOf("\n");
+  if (nl > 0) head = head.slice(0, nl);
+  const kept = Buffer.byteLength(head, "utf8");
+  return {
+    text: `${head}
+\u2026[diff truncated: ${total - kept} of ${total} bytes omitted]`,
+    truncated: true
+  };
+}
 function isBinaryBuffer(buf) {
   const len = Math.min(buf.length, 8192);
   for (let i = 0; i < len; i++) {
@@ -172,14 +186,27 @@ function isBinaryBuffer(buf) {
   }
   return false;
 }
+function takeHeadBytes(s, maxBytes) {
+  if (maxBytes <= 0) return "";
+  if (Buffer.byteLength(s, "utf8") <= maxBytes) return s;
+  let lo = 0;
+  let hi = s.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    if (Buffer.byteLength(s.slice(0, mid), "utf8") <= maxBytes) lo = mid;
+    else hi = mid - 1;
+  }
+  return s.slice(0, lo);
+}
 
 // src/replace.ts
+var MAX_DIFF_BYTES = 262144;
 var DEFAULT_IGNORE = ["node_modules", ".git", "dist", "build", ".next", "coverage"];
 var replaceTool = {
   name: "replace",
   category: "Transform",
   description: "Perform a search-and-replace across multiple files using a regex pattern. This is a powerful bulk transformation tool. Dry-run is ON by default \u2014 set `dry_run: false` to apply changes.",
-  usageHint: "DANGEROUS IF USED CARELESSLY \u2014 review the diff output carefully.\n\nRecommended workflow:\n1. Run without `dry_run: false` first to see exactly what would change (dry-run is the default).\n2. Review the diff output, then re-run with `dry_run: false` to apply.\n3. Use a specific enough `pattern` (and `glob` / `files`) to avoid accidental broad changes.\n4. `replace_all` controls whether only the first match per file or all matches are replaced.\nThis tool is excellent for large-scale refactors (renaming, import updates, etc.) but must be used with caution.",
+  usageHint: "DANGEROUS IF USED CARELESSLY \u2014 review the diff output carefully.\n\nRecommended workflow:\n1. Run without `dry_run: false` first to see exactly what would change (dry-run is the default).\n2. Review the diff output, then re-run with `dry_run: false` to apply.\n3. Use a specific enough `pattern` (and `glob` / `files`) to avoid accidental broad changes.\n4. `replace_all` controls whether only the first match per file or all matches are replaced.\n5. `replacement` supports regex substitutions: `$1`\u2013`$9` insert capture groups, `$&` inserts the whole match, and `$$` inserts a literal dollar sign.\nThis tool is excellent for large-scale refactors (renaming, import updates, etc.) but must be used with caution.",
   permission: "confirm",
   // WS-046: gives permission decisions something to key on.
   // The file scope being rewritten, not the pattern: a trust rule should say
@@ -189,11 +216,15 @@ var replaceTool = {
   capabilities: ["fs.write"],
   icon: "edit",
   timeoutMs: 3e4,
+  maxOutputBytes: 262144,
   inputSchema: {
     type: "object",
     properties: {
       pattern: { type: "string", description: "Regex pattern to match" },
-      replacement: { type: "string", description: "Replacement string" },
+      replacement: {
+        type: "string",
+        description: "Replacement string. Supports `$1`\u2013`$9` (capture groups), `$&` (whole match), and `$$` (literal dollar sign) \u2014 same semantics as JavaScript String.replace."
+      },
       files: {
         type: "string",
         description: "File(s) to target: single path, comma-separated list, or glob pattern"
@@ -242,6 +273,9 @@ var replaceTool = {
     const realRoot = await fs.realpath(ctx.projectRoot).catch(() => ctx.projectRoot);
     const results = [];
     let totalReplacements = 0;
+    let diffBytesUsed = 0;
+    let diffsOmitted = 0;
+    let diffsTruncated = 0;
     for (const absPath of fileList) {
       const lstat2 = await fs.lstat(absPath).catch((err) => {
         if (err.code === "ENOENT") return null;
@@ -277,7 +311,7 @@ var replaceTool = {
       let newContentLf = contentLf;
       for (let i = matches.length - 1; i >= 0; i--) {
         const m = expectDefined(matches[i]);
-        newContentLf = newContentLf.slice(0, m.index) + input.replacement + newContentLf.slice(expectDefined(m.index) + m[0].length);
+        newContentLf = newContentLf.slice(0, m.index) + expandReplacement(input.replacement, m) + newContentLf.slice(expectDefined(m.index) + m[0].length);
       }
       re.lastIndex = 0;
       totalReplacements += count;
@@ -295,24 +329,76 @@ var replaceTool = {
           after: newContent
         });
       }
-      const diff = dryRun || matches.length > 0 ? unifiedDiff(content, toStyle(newContentLf, style), {
+      let diff = dryRun || matches.length > 0 ? unifiedDiff(content, toStyle(newContentLf, style), {
         fromFile: absPath,
         toFile: absPath
       }) : void 0;
+      if (diff !== void 0) {
+        const remaining = MAX_DIFF_BYTES - diffBytesUsed;
+        if (remaining <= 0) {
+          diff = void 0;
+          diffsOmitted++;
+        } else {
+          const capped = truncateDiffPayload(diff, remaining);
+          if (capped.truncated) diffsTruncated++;
+          diff = capped.text;
+          diffBytesUsed += Buffer.byteLength(diff, "utf8");
+        }
+      }
       results.push({
         path: absPath,
         replacements: matches.length,
         diff
       });
     }
+    const overBudget = diffsOmitted > 0 || diffsTruncated > 0;
     return {
       files_modified: results.length,
       total_replacements: totalReplacements,
       results,
-      dry_run: dryRun
+      dry_run: dryRun,
+      note: overBudget ? `Diff payload exceeded the 256 KiB output budget: ${diffsTruncated} diff(s) truncated, ${diffsOmitted} diff(s) omitted. Replacement counts are complete; use the read tool to inspect individual files.` : void 0
     };
   }
 };
+function expandReplacement(template, match) {
+  if (!template.includes("$")) return template;
+  let out = "";
+  for (let i = 0; i < template.length; i++) {
+    const ch = template[i];
+    if (ch !== "$") {
+      out += ch;
+      continue;
+    }
+    const next = template[i + 1];
+    if (next === "$") {
+      out += "$";
+      i++;
+    } else if (next === "&") {
+      out += match[0];
+      i++;
+    } else if (next !== void 0 && next >= "1" && next <= "9") {
+      const idx = next.charCodeAt(0) - 48;
+      if (idx < match.length) {
+        out += match[idx] ?? "";
+        i++;
+      } else {
+        out += "$";
+      }
+    } else {
+      out += "$";
+    }
+  }
+  return out;
+}
+function passesExtraGlob(extraGlob, name, full) {
+  extraGlob.lastIndex = 0;
+  const nameMatch = extraGlob.test(name);
+  extraGlob.lastIndex = 0;
+  const fullMatch = extraGlob.test(full);
+  extraGlob.lastIndex = 0;
+  return nameMatch || fullMatch;
+}
 async function resolveFiles(filesInput, ctx, extraGlob) {
   const base = ctx.cwd;
   const normalized = filesInput.trim();
@@ -323,6 +409,7 @@ async function resolveFiles(filesInput, ctx, extraGlob) {
   const resolved = [];
   for (const p of parts) {
     const absPath = safeResolve(p, ctx);
+    if (extraGlob && !passesExtraGlob(extraGlob, path2.basename(absPath), absPath)) continue;
     const stat2 = await fs.stat(absPath).catch(() => null);
     if (stat2?.isFile()) {
       resolved.push(absPath);
@@ -335,14 +422,22 @@ async function globFiles(pattern, base, extraGlob) {
   if (rgAvailable) {
     try {
       const { promise } = spawnRgFind(pattern, base);
-      return await promise;
+      const files = await promise;
+      if (extraGlob) {
+        return files.filter((f) => passesExtraGlob(extraGlob, path2.basename(f), f));
+      }
+      return files;
     } catch {
     }
   }
   return await globNative(pattern, base, extraGlob);
 }
+var rgAvailabilityCache;
+function __resetRgDetectionForTests() {
+  rgAvailabilityCache = void 0;
+}
 function checkRg() {
-  return new Promise((resolve2) => {
+  rgAvailabilityCache ??= new Promise((resolve2) => {
     try {
       const p = spawn("rg", ["--version"], {
         env: buildChildEnv(),
@@ -355,6 +450,7 @@ function checkRg() {
       resolve2(false);
     }
   });
+  return rgAvailabilityCache;
 }
 function spawnRgFind(pattern, base) {
   const args = ["--files", "--glob", pattern, base];
@@ -421,6 +517,7 @@ async function globNative(pattern, base, extraGlob) {
   return results;
 }
 export {
+  __resetRgDetectionForTests,
   replaceTool
 };
 //# sourceMappingURL=replace.js.map

package/dist/search.d.ts

@@ -15,6 +15,12 @@ interface SearchOutput {
     source: string;
     truncated: boolean;
     cached: boolean;
+    /**
+     * Present when the search engine could not be reached or returned an
+     * unusable response. `results` is empty in that case — the failure is never
+     * disguised as a synthetic result entry.
+     */
+    error?: string | undefined;
 }
 export declare const searchTool: Tool<SearchInput, SearchOutput>;
 /** Exposed for tests so they can reset the module-level cache between cases. */