pi-hashline-edit-pro 0.16.0 → 0.16.1

package/README.md

@@ -99,11 +99,11 @@ Hashes are now computed with a persistent store (`~/.config/pi-hashline-edit-pro
 The store contains per-file snapshots: the last known content and hashes for each file. On read, if the file content matches the snapshot, the saved hashes are returned immediately. Stale snapshots (for files that no longer exist) are pruned on session start.
 
 ### Chained edits
-After a successful replace, the response confirms with `Successfully replaced in {path}.` (warnings are still shown if present). To get fresh anchors for follow-up edits, call `read` on the file first. This avoids token overhead from re-displaying content the model already knows.
+After a successful replace, the response confirms with `Successfully replaced in {path}.` (warnings are still shown if present). When auto-read is enabled, fresh anchors are appended automatically. Otherwise call `read` to get fresh anchors for follow-up edits.
 
-### Auto-read after write
+### Auto-read after write and replace
 
-Auto-read is **disabled by default**. When enabled, after a successful `write` the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH│content` anchors for the newly written file without requiring a separate `read` call. The workflow becomes:
+Auto-read is **disabled by default**. When enabled, after a successful `write` or `replace` the extension automatically reads the file and appends a `--- Auto-read (hashline anchors) ---` block to the result. This gives the model immediate `HASH│content` anchors for the file without requiring a separate `read` call. The workflow becomes:
 
 1. `write` a file, result includes hashline anchors
 2. `replace` using those anchors directly
@@ -121,7 +121,7 @@ The post-edit diff (with `+`/`-` markers) is exposed to the host UI via `details
 | Command | Description |
 | --- | --- |
 | `/toggle-replace-mode` | Switch between bulk mode (`changes` array) and flat mode (top-level fields). Persists across sessions. |
-| `/toggle-auto-read` | Toggle automatic hashline anchors after write operations. Persists across sessions. |
+| `/toggle-auto-read` | Toggle automatic hashline anchors after write and replace operations. Persists across sessions. |
 
 ### Config file
 
@@ -171,7 +171,7 @@ npm test
 
 Set `PI_HASHLINE_DEBUG=1` to show an "active" notification at session start.
 
-Set `PI_HASHLINE_AUTO_READ=1` to enable auto-read after write by default on first run (can still be toggled at runtime with `/toggle-auto-read`; the setting persists across sessions once toggled).
+Set `PI_HASHLINE_AUTO_READ=1` to enable auto-read after write and replace by default on first run (can still be toggled at runtime with `/toggle-auto-read`; the setting persists across sessions once toggled).
 
 ## Credits
 

package/index.ts

@@ -20,12 +20,9 @@ import { loadHashStore, pruneHashStore } from "./src/hash-store";
 export default function (pi: ExtensionAPI): void {
   regRead(pi);
 
-  // Register the bulk-mode replace tool by default. The session_start handler
-  // will re-register with the correct mode from the persisted config.
   regReplace(pi);
   regReplaceUndo(pi);
   const debugValue = process.env.PI_HASHLINE_DEBUG;
-  // Initial auto-read from env var; session_start overrides with persisted value
   const autoReadValue = process.env.PI_HASHLINE_AUTO_READ;
   let autoRead = autoReadValue === "1" || autoReadValue === "true";
 
@@ -33,12 +30,10 @@ export default function (pi: ExtensionAPI): void {
     const active = pi.getActiveTools();
     pi.setActiveTools(active.filter((t) => t !== "edit"));
     await initHasher();
-    // Prune stale snapshots (files that no longer exist) on session start
     try {
       const store = await loadHashStore();
       await pruneHashStore(store);
-    } catch { /* best-effort */ }
-    // Re-register the replace tool according to the persisted mode
+    } catch {}
     const mode = await readReplaceMode();
     if (mode === "flat") {
       regReplaceFlat(pi);
@@ -46,7 +41,6 @@ export default function (pi: ExtensionAPI): void {
       regReplace(pi);
     }
 
-    // Read the persisted auto-read setting (overrides env var default)
     autoRead = await readAutoRead();
 
     if (debugValue === "1" || debugValue === "true") {
@@ -58,7 +52,6 @@ export default function (pi: ExtensionAPI): void {
     description: "Toggle replace tool between bulk (changes array) and flat (single edit at top level) mode",
     handler: async (_args, ctx) => {
       const mode = await toggleReplaceMode();
-      // Re-register the tool with the new mode
       if (mode === "flat") {
         regReplaceFlat(pi);
       } else {
@@ -69,10 +62,9 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("toggle-auto-read", {
-    description: "Toggle automatic hashline anchors after write operations",
+    description: "Toggle automatic hashline anchors after write and replace operations",
     handler: async (_args, ctx) => {
       autoRead = await toggleAutoRead();
-      // Re-register the tool so prompts reflect the new auto-read setting
       const mode = await readReplaceMode();
       if (mode === "flat") {
         regReplaceFlat(pi);
@@ -80,13 +72,14 @@ export default function (pi: ExtensionAPI): void {
         regReplace(pi);
       }
       const state = autoRead ? "enabled" : "disabled";
-      ctx.ui.notify(`Auto-read after write: ${state}`, "info");
+      ctx.ui.notify(`Auto-read after write/replace: ${state}`, "info");
     },
   });
 
   pi.on("tool_result", async (event, ctx) => {
     if (!autoRead) return;
-    if (event.toolName !== "write" || event.isError) return;
+    if (event.isError) return;
+    if (event.toolName !== "write" && event.toolName !== "replace") return;
 
     const filePath = (event.input as Record<string, unknown>)?.path;
     if (typeof filePath !== "string") return;
@@ -108,7 +101,7 @@ export default function (pi: ExtensionAPI): void {
         ],
       };
     } catch (error) {
-      console.error("Auto-read after write failed:", error);
+      console.error("Auto-read after write/replace failed:", error);
     }
   });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.16.0",
+  "version": "0.16.1",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/replace-bulk-guidelines.md

@@ -1,5 +1,6 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
-- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
+- After a successful `replace`, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace-bulk.md

@@ -128,4 +128,4 @@ Error recovery:
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 
-**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.
+**Undo:** If a replace produced incorrect results, call `undo_last_replace` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace-flat-guidelines.md

@@ -1,5 +1,6 @@
 - Use `replace` with HASH anchors for all file changes. Only one edit per call (flat mode — no `changes` array).
-- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
+- After a successful `replace`, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
-- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace-flat.md

@@ -114,4 +114,4 @@ Error recovery:
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 
-**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.
+**Undo:** If a replace produced incorrect results, call `undo_last_replace` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/replace-guidelines.md

@@ -1,5 +1,7 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
-- After a successful `replace`, the response text is empty (warnings only). {{AUTO_READ_GUIDANCE}}
+- After a successful `replace`, the response shows the change summary. {{AUTO_READ_GUIDANCE}}
 - On `[E_STALE_ANCHOR]`, call `read` to get fresh anchors, copy the 3-character HASH of the start and end of the range you are replacing into `hash_range_inclusive`, and retry.
 - `hash_range_inclusive` replaces the ENTIRE range inclusively. Every line from the first anchor through the second anchor is deleted. Only put the replacement lines in `content_lines` — do not include lines that already exist outside the range.
-- Two modes are available: bulk (default, uses `changes` array) and flat (top-level `hash_range_inclusive`/`content_lines`). Toggle with `/toggle-replace-mode`.
+- **Preserve leading whitespace (indentation) exactly.** The content after `│` in read output includes all leading spaces and tabs — copy them into `content_lines` unchanged.
+- Two modes are available: bulk (default, uses `changes` array) and flat (top-level `hash_range_inclusive`/`content_lines`). Toggle with `/toggle-replace-mode`.
+- If the response includes a "Boundary duplication" warning, the edge line of your `content_lines` matches a line outside the replaced range. Remove that line from `content_lines` — the original is still in the file outside the range.

package/prompts/replace.md

@@ -178,4 +178,4 @@ Error recovery:
 - `[E_INVALID_PATCH]` — a `content_lines` entry matches the diff preview's `+HASH│…` addition-row form. Use literal file content. (Plain `+`/`-` lines are not rejected — they are written literally.)
 - `[E_WOULD_EMPTY]` — edit would empty a non-empty file.
 
-**Undo:** If a replace produced incorrect results, call `last_replace_undo` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.
+**Undo:** If a replace produced incorrect results, call `undo_last_replace` with the file path to revert the last replace. The tool reports how many lines were removed and restored. After undoing, call `read` to get fresh anchors for a corrected replace.

package/prompts/undo-last-replace-guidelines.md

@@ -0,0 +1,3 @@
+- Call `undo_last_replace` with the file path to revert the last replace on that file.
+- After undoing, call `read` to get fresh anchors for a corrected replace.
+- Only the most recent replace per file is tracked — calling undo twice without an intervening replace will produce "no undo history".

package/prompts/undo-last-replace-snippet.md

@@ -0,0 +1 @@
+Undo the last replace on a file

package/prompts/undo-last-replace.md

@@ -0,0 +1 @@
+Undo the last replace operation on a file, reverting it to its previous state. Use this when a replace produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). After undoing, call `read` to get fresh anchors for a corrected replace.

package/src/config.ts

@@ -1,7 +1,6 @@
 import { readFileSync } from "fs";
-import { homedir } from "os";
-import { join } from "path";
 import { readFile, writeFile, mkdir } from "fs/promises";
+import { configDir, configPath } from "./paths";
 
 export type ReplaceMode = "bulk" | "flat";
 
@@ -12,18 +11,9 @@ export interface Config {
 
 const DEFAULT_CONFIG: Config = {
   replaceMode: "bulk",
-  autoRead: false,
+  autoRead: false
 };
 
-/** Compute config path lazily so tests can override HOME before calling. */
-function configPath(): string {
-  return join(homedir(), ".config", "pi-hashline-edit-pro", "config.json");
-}
-
-function configDir(): string {
-  return join(homedir(), ".config", "pi-hashline-edit-pro");
-}
-
 export async function readConfig(): Promise<Config> {
   try {
     const content = await readFile(configPath(), "utf-8");

package/src/constants.ts

@@ -2,14 +2,4 @@ export const AUTO_READ_MAX = 2000;
 export const SNIFF_BYTES = 8192;
 export const MAX_BYTES = 100 * 1024 * 1024;
 
-/**
- * Hard ceiling on the number of lines the edit/hash path will process. Guards
- * `lineHashes` (which holds a per-line array plus a Set of every hash) and the
- * host diff against pathological inputs such as a multi-tens-of-MB generated
- * bundle or data dump. Only the `replace` path enforces it (`readNormFile` is
- * called with this limit only from `replace.ts`); `read` keeps its
- * truncate-and-preview behavior. ~1M lines is well above any realistic source
- * file, so this only fires on genuine pathologies. Tunable: lower it to bound
- * hashing cost more tightly.
- */
 export const MAX_HASH_LINES = 1_000_000;

package/src/fs-write.ts

@@ -101,14 +101,14 @@ export async function writeAtomic(
     }
   } catch (error: unknown) {
     await tempHandle.close();
-    try { await rm(tempPath, { force: true }); } catch { /* best-effort */ }
+    try { await rm(tempPath, { force: true }); } catch {}
     throw error;
   }
   try {
     await tempHandle.close();
     await rename(tempPath, targetPath);
   } catch (error: unknown) {
-    try { await rm(tempPath, { force: true }); } catch { /* best-effort */ }
+    try { await rm(tempPath, { force: true }); } catch {}
     throw error;
   }
 }

package/src/hash-store.ts

@@ -1,7 +1,6 @@
 import { readFile, writeFile, mkdir } from "fs/promises";
-import { homedir } from "os";
-import { join, dirname } from "path";
 import { stat } from "fs/promises";
+import { hashStorePath, hashStoreDir } from "./paths";
 
 export interface FileSnapshot {
   content: string;
@@ -13,36 +12,28 @@ export interface HashStore {
   snapshots: Record<string, FileSnapshot>;
 }
 
-function storePath(): string {
-  return join(homedir(), ".config", "pi-hashline-edit-pro", "hash-store.json");
-}
-
-function storeDir(): string {
-  return dirname(storePath());
-}
-
 export async function loadHashStore(): Promise<HashStore> {
   try {
-    const content = await readFile(storePath(), "utf-8");
+    const content = await readFile(hashStorePath(), "utf-8");
     const parsed = JSON.parse(content) as Partial<HashStore>;
     return {
       version: 1,
       snapshots: parsed.snapshots ?? {},
     };
   } catch {
-    await mkdir(storeDir(), { recursive: true });
+    await mkdir(hashStoreDir(), { recursive: true });
     const defaultStore: HashStore = {
       version: 1,
       snapshots: {},
     };
-    await writeFile(storePath(), JSON.stringify(defaultStore), "utf-8");
+    await writeFile(hashStorePath(), JSON.stringify(defaultStore), "utf-8");
     return defaultStore;
   }
 }
 
 export async function saveHashStore(store: HashStore): Promise<void> {
-  await mkdir(storeDir(), { recursive: true });
-  await writeFile(storePath(), JSON.stringify(store, null, 2), "utf-8");
+  await mkdir(hashStoreDir(), { recursive: true });
+  await writeFile(hashStorePath(), JSON.stringify(store, null, 2), "utf-8");
 }
 
 export async function pruneHashStore(store: HashStore): Promise<void> {

package/src/hashline/apply.ts

@@ -212,14 +212,6 @@ function assemble(
 	return result;
 }
 
-/**
- * Builds the boundary-duplication warning shown after an edit. A minimal header
- * is followed by a hashline-anchored window: 2 lines of context before the
- * duplicated pair, the pair itself, and 2 lines after. The window carries the
- * post-edit hashes the model needs to remove the duplicate in a follow-up
- * `replace` (no `read` round-trip required, since the hashes are current and
- * staleness is per-line). Rows are plain `HASH│content` — no annotations.
- */
 export function fmtBoundaryWarning(params: {
 	kind: "trailing" | "leading";
 	survivingContent: string;
@@ -232,10 +224,6 @@ export function fmtBoundaryWarning(params: {
 			? "Boundary duplication (trailing): the last replacement line duplicated the next line. This happens when `content_lines` includes a line that was already outside the replaced range. Delete the duplicate — the original line outside the range is still there."
 			: "Boundary duplication (leading): the first replacement line duplicated the previous line. This happens when `content_lines` includes a line that was already outside the replaced range. Delete the duplicate — the original line outside the range is still there.";
 
-	// Locate the adjacent duplicated pair (two identical neighboring lines). The
-	// occurrence-based matchIndex usually lands inside the pair; when a file has
-	// several identical lines we pick the pair nearest matchIndex so the window
-	// frames the duplication this edit introduced, not an unrelated one.
 	let pairStart = -1;
 	let bestDist = Infinity;
 	for (let i = 0; i < params.resultLines.length - 1; i++) {
@@ -284,12 +272,6 @@ export function applyEdits(
 			lastChangedLine: undefined,
 		};
 
-  edits = edits.map((edit) =>
-    edit.content_lines.length === 1 &&
-    edit.content_lines[0] === ""
-      ? { ...edit, content_lines: [] }
-      : edit,
-  );
 
 	const lineIndex = buildIdx(content);
 	const fileHashes = precomputedHashes ?? _lineHashesPure(content);

package/src/hashline/hash.ts

@@ -5,11 +5,6 @@ import { loadHashStore, saveHashStore } from "../hash-store";
 export const HASH_LEN = 3;
 export const ANCHOR_LEN = HASH_LEN;
 
-/**
- * The `│` (U+2502) delimiter between a hash anchor and its line content. This
- * is the wire-format separator in `HASH│content` rows. Kept as a constant so
- * every construction site resolves the same delimiter.
- */
 export const HASH_SEP = "│";
 
 const ALPH =
@@ -74,17 +69,6 @@ function canon(line: string): string {
 	return line.replace(/\r/g, "").trimEnd();
 }
 
-/**
- * Pure hash computation — no I/O, no persistence. Used internally by the
- * stable path and as a fallback when no file path is available.
- * Each line is hashed with xxHash32 over its canonical form (trailing
- * whitespace and CR characters stripped). If the base hash collides with a
- * hash already assigned to an earlier line, a retry counter (`:R{retry}`)
- * is appended to the canonical content and the hash is recomputed until a
- * unique anchor is found. This perfect-hashing step guarantees every line
- * in a file receives a distinct anchor, even when multiple lines contain
- * identical text (e.g. repeated `}` or `import` statements).
- */
 export function _lineHashesPure(content: string): string[] {
 	const lines = content.split("\n");
 	const hashes = new Array<string>(lines.length);
@@ -103,24 +87,6 @@ export function _lineHashesPure(content: string): string[] {
 	return hashes;
 }
 
-/**
- * Stable, persistent-aware hash computation.
- *
- * When `path` is provided, uses the persistent hash store to preserve
- * hashes for unchanged lines across edits. When `previous` is also
- * provided (called from the replace pipeline), diffs the previous content
- * against the new content and copies hashes for unchanged lines to their
- * new positions. New/changed lines allocate fresh hashes with collision
- * avoidance against the preserved set.
- *
- * When `path` is provided without `previous` (called from read), loads
- * the stored snapshot for that path. If the content matches, returns the
- * saved hashes. Otherwise computes fresh hashes via `_lineHashesPure` and
- * saves a new snapshot.
- *
- * When `path` is not provided, falls back to `_lineHashesPure` (for
- * backward compatibility and tests that don't need persistence).
- */
 export async function lineHashes(
   content: string,
   path?: string,
@@ -132,7 +98,6 @@ export async function lineHashes(
 
   const store = await loadHashStore();
 
-  // Case 1: previous content provided (replace pipeline) — diff and preserve
   if (previous) {
     const newHashes = mapStableHashes(
       previous.content, previous.hashes,
@@ -144,28 +109,17 @@ export async function lineHashes(
     return newHashes;
   }
 
-  // Case 2: no previous — check snapshot or compute fresh
   const snapshot = store.snapshots[path];
   if (snapshot && snapshot.content === content) {
     return snapshot.hashes;
   }
 
-  // Compute fresh hashes
   const newHashes = _lineHashesPure(content);
   store.snapshots[path] = { content, hashes: newHashes };
   await saveHashStore(store);
   return newHashes;
 }
 
-/**
- * Maps old hashes to new positions using hash-aware content matching.
- * Unlike Diff.diffLines (which is content-only and cannot distinguish
- * identical lines at different positions), this algorithm uses the
- * removedHashes set to disambiguate: when a line appears multiple times
- * in the old content and one occurrence was targeted by the edit,
- * the surviving occurrence is matched to the non-removed hash.
- * New/changed lines allocate fresh hashes with collision avoidance.
- */
 function mapStableHashes(
   oldContent: string,
   oldHashes: string[],
@@ -176,8 +130,6 @@ function mapStableHashes(
   const newHashes = new Array<string>(newLines.length);
   const used = new Set<string>();
 
-  // Build a map from line content to list of (index, hash) for the old content.
-  // We process occurrences left-to-right so that matching preserves order.
   const contentMap = new Map<string, { index: number; hash: string }[]>();
   const oldLines = oldContent.split("\n");
   for (let i = 0; i < oldLines.length; i++) {
@@ -191,17 +143,11 @@ function mapStableHashes(
     }
   }
 
-  // Match each new line to an old occurrence by content.
-  // For lines with duplicate content, prefer occurrences whose hash
-  // was NOT targeted by the edit (those are the survivors).
   for (let i = 0; i < newLines.length; i++) {
     const line = newLines[i]!;
     const candidates = contentMap.get(line);
     if (!candidates || candidates.length === 0) continue;
 
-    // Find the best match: prefer a non-removed occurrence.
-    // If all remaining occurrences are removed, use the first one anyway
-    // (it will get a fresh hash in the fill step since its hash is in used+removed).
     let bestIdx = 0;
     if (removedHashes && removedHashes.size > 0) {
       for (let j = 0; j < candidates.length; j++) {
@@ -217,7 +163,6 @@ function mapStableHashes(
     used.add(match.hash);
   }
 
-  // Fill remaining (new/changed) lines with fresh hashes
   for (let i = 0; i < newLines.length; i++) {
     if (newHashes[i]) continue;
     const c = canon(newLines[i]!);
@@ -230,7 +175,6 @@ function mapStableHashes(
     used.add(hash);
     newHashes[i] = hash;
   }
-
   return newHashes;
 }
 

package/src/paths.ts

@@ -0,0 +1,19 @@
+import { homedir } from "os";
+import { join, dirname } from "path";
+
+
+export function configDir(): string {
+  return join(homedir(), ".config", "pi-hashline-edit-pro");
+}
+
+export function configPath(): string {
+  return join(configDir(), "config.json");
+}
+
+export function hashStorePath(): string {
+  return join(configDir(), "hash-store.json");
+}
+
+export function hashStoreDir(): string {
+  return dirname(hashStorePath());
+}

package/src/read.ts

@@ -41,11 +41,6 @@ function normPosInt(
 	return value;
 }
 
-/**
- * Builds the `[Showing lines A-B of N. Use offset=M to continue.]` hint shared by
- * `fmtReadPreview` and the auto-read-after-write handler. `byteLimit` adds the
- * `(size limit)` suffix used when truncation is byte-driven.
- */
 export function formatPaginationHint(
 	startLine: number,
 	endLine: number,

package/src/replace-diff.ts

@@ -47,10 +47,6 @@ export function genDiff(
   newContentHashes?: string[],
   oldHashes?: string[],
 ): { diff: string; firstChangedLine: number | undefined } {
-  // Run Diff.diffLines on raw content only (no hash annotations) so that
-  // lines whose content is identical are never reported as changed even
-  // when their hash differs due to collision resolution or position
-  // tracking. Hashes are used purely for display via fmtDiffLine.
   const oldLines = oldContent.split("\n");
   const newLines = newContent.split("\n");
   const effectiveOldHashes = oldHashes ?? _lineHashesPure(oldContent);

package/src/replace-normalize.ts

@@ -9,12 +9,6 @@ function tryParseJSON<T>(value: unknown, guard: (v: unknown) => v is T): T | und
   return undefined;
 }
 
-/**
- * Coerces an array of edit items: JSON-string items → objects,
- * JSON-string content_lines → string arrays. Shared by the `changes`
- * and `edits` normalization branches.
- * Returns a warning if any item was a JSON string.
- */
 function coerceEditArray(items: unknown[]): { result: unknown[]; warnings: string[] } {
   const warnings: string[] = [];
   const result = items
@@ -43,12 +37,6 @@ function coerceEditArray(items: unknown[]): { result: unknown[]; warnings: strin
   return { result, warnings };
 }
 
-/**
- * Normalizes a field from `from` to `to`: JSON-string arrays → real arrays,
- * single objects → wrapped in array. Shared by the `changes` and `edits`
- * normalization branches.
- * Returns a warning if the field was a JSON string.
- */
 function normalizeField(
   record: Record<string, unknown>,
   from: string,
@@ -85,6 +73,19 @@ function normalizeField(
   return undefined;
 }
 
+export function normalizeFilePath(record: Record<string, unknown>): void {
+  if (typeof record.path !== "string" && typeof record.file_path === "string") {
+    record.path = record.file_path;
+    delete record.file_path;
+  }
+}
+
+export function tryParseField(record: Record<string, unknown>, field: string): void {
+  if (typeof record[field] === "string") {
+    try { record[field] = JSON.parse(record[field] as string); } catch {}
+  }
+}
+
 export function normReq(input: unknown): unknown {
   if (!isRec(input)) {
     return input;
@@ -93,18 +94,13 @@ export function normReq(input: unknown): unknown {
   const record: Record<string, unknown> = { ...input };
   const warnings: string[] = [];
 
-  if (typeof record.path !== "string" && typeof record.file_path === "string") {
-    record.path = record.file_path;
-    delete record.file_path;
-  }
+  normalizeFilePath(record);
 
   const w1 = normalizeField(record, "changes", "changes");
   if (w1) warnings.push(w1);
   const w2 = normalizeField(record, "edits", "changes");
   if (w2) warnings.push(w2);
 
-  // Handle flat format: hash_range_inclusive and content_lines at top level
-  // (no changes array). Wrap them into a single-element changes array.
   if (!Array.isArray(record.changes) && has(record, "hash_range_inclusive") && has(record, "content_lines")) {
     const hriRaw = record.hash_range_inclusive;
     const hri = tryParseJSON(hriRaw, (v): v is string[] =>

package/src/replace-response.ts

@@ -1,6 +1,6 @@
 import type { ReplaceDetails } from "./replace";
 import { genDiff } from "./replace-diff";
-import { visLines } from "./utils";
+import { visLines, cntDiff } from "./utils";
 
 type TResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -50,19 +50,6 @@ export interface SuccessInput {
   editMeta: RMeta;
 }
 
-function cntDiff(diff: string, marker: "+" | "-"): number {
-	if (!diff) return 0;
-	let count = 0;
-	for (const line of diff.split("\n")) {
-		if (
-			line.startsWith(marker) &&
-			!line.startsWith(`${marker}${marker}${marker}`)
-		) {
-			count += 1;
-		}
-	}
-	return count;
-}
 
 function buildM(args: {
 	classification: "applied" | "noop";

package/src/replace-undo.ts

@@ -7,29 +7,17 @@ import { loadHashStore, saveHashStore } from "./hash-store";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { toCwd } from "./path-utils";
 import { toLF, stripBOM, genDiff, restoreEndings } from "./replace-diff";
+import { cntDiff } from "./utils";
+import { loadP, loadGuide } from "./prompts";
 
-function cntDiff(diff: string, marker: "+" | "-"): number {
-  if (!diff) return 0;
-  let count = 0;
-  for (const line of diff.split("\n")) {
-    if (
-      line.startsWith(marker) &&
-      !line.startsWith(`${marker}${marker}${marker}`)
-    ) {
-      count += 1;
-    }
-  }
-  return count;
-}
 
 export function regReplaceUndo(pi: ExtensionAPI): void {
   pi.registerTool({
-    name: "last_replace_undo",
+    name: "undo_last_replace",
     label: "Undo Last Replace",
-    description:
-      "Undo the last replace operation on a file, reverting it to its previous state. " +
-      "Use this when a replace produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). " +
-      "After undoing, call `read` to get fresh anchors for a corrected replace.",
+    description: loadP("../prompts/undo-last-replace.md"),
+    promptSnippet: loadP("../prompts/undo-last-replace-snippet.md"),
+    promptGuidelines: loadGuide("../prompts/undo-last-replace-guidelines.md"),
     parameters: Type.Object({
       path: Type.String({
         description: "Path to the file to undo the last replace on",
@@ -56,29 +44,24 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
       }
 
       return withFileMutationQueue(mutationTargetPath, async () => {
-        // Read current file content to compute diff against the pre-replace state
         let currentNormalized = "";
         try {
           const currentRaw = await readFile(mutationTargetPath, "utf-8");
           const { text: currentStripped } = stripBOM(currentRaw);
           currentNormalized = toLF(currentStripped);
         } catch {
-          // File may have been deleted; treat as empty
           currentNormalized = "";
         }
 
-        // Compute diff: old = pre-replace (undo.content), new = current
         const diffResult = genDiff(undo.content, currentNormalized, 0);
         const linesAddedByReplace = cntDiff(diffResult.diff, "+");
         const linesRemovedByReplace = cntDiff(diffResult.diff, "-");
 
-        // Write the pre-edit content back to the file
         await writeAtomic(
           mutationTargetPath,
           undo.bom + restoreEndings(undo.content, undo.originalEnding),
         );
 
-        // Restore the hash store snapshot so the next read returns the same hashes
         const store = await loadHashStore();
         store.snapshots[mutationTargetPath] = {
           content: undo.content,
@@ -86,7 +69,6 @@ export function regReplaceUndo(pi: ExtensionAPI): void {
         };
         await saveHashStore(store);
 
-        // Clear undo so a second call without an intervening replace is a no-op
         clearUndo(mutationTargetPath);
 
         const parts: string[] = [

package/src/replace.ts

@@ -11,7 +11,7 @@ import {
   restoreEndings,
 } from "./replace-diff";
 import { readNormFile } from "./file-reader";
-import { normReq } from "./replace-normalize";
+import { normReq, normalizeFilePath, tryParseField } from "./replace-normalize";
 import { isRec, has, rejectUnknownFields } from "./utils";
 import { MAX_HASH_LINES } from "./constants";
 import { resolveTarget, writeAtomic } from "./fs-write";
@@ -76,11 +76,6 @@ export const editToolSchema = Type.Object(
   { additionalProperties: false },
 );
 
-/**
- * Flat-mode schema: hash_range_inclusive and content_lines are at the top
- * level instead of inside a "changes" array. Only a single edit is supported
- * per call (no bulk changes).
- */
 export const flatEditToolSchema = Type.Object(
   {
     path: Type.String({ description: "path" }),
@@ -181,12 +176,6 @@ export async function execPipeline(
 
   const result = anchorResult.content;
 
-  // Collect hashes targeted by the edit for hash-aware diff disambiguation.
-  // Include every hash in the replaced range, not just the boundary anchors,
-  // so that a surviving line whose content is identical to an interior line
-  // of the edit is not matched to a removed hash.
-  // Use originalHashes.indexOf to find line numbers since resEdits returns
-  // HEdit[] (Anchor = { hash }) not RHEdit[] (RAnchor = { line, hash }).
   const removedHashes = new Set<string>();
   for (const edit of resolved) {
     const startHash = edit.hash_range_inclusive[0].hash;
@@ -200,14 +189,12 @@ export async function execPipeline(
     }
   }
 
-  // Compute stable result hashes using hash-aware preservation
   const resultHashes = await lineHashes(result, resolvedPath, {
     content: originalNormalized,
     hashes: originalHashes,
     removedHashes,
   });
 
-  // Format boundary warnings using stable result hashes
   const resultLines = result.split("\n");
   const warnings = [...(anchorResult.warnings ?? [])];
   for (const bw of anchorResult.boundaryWarnings ?? []) {
@@ -299,7 +286,7 @@ export function reuseMarkdown(context: any, content: string, theme: any): Markdo
 export function buildToolDef(opts: { flat: boolean }): ToolDef {
   const autoRead = readAutoReadSync();
   const readGuidance = autoRead
-    ? "Anchors are provided automatically after write operations when auto-read is enabled."
+    ? "Anchors are provided automatically after write and replace operations when auto-read is enabled."
     : "Call `read` to get fresh anchors for follow-up edits.";
 
   const E_DESC = loadP(opts.flat ? "../prompts/replace-flat.md" : "../prompts/replace-bulk.md", {
@@ -321,20 +308,11 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
     promptGuidelines: E_GUIDE,
     prepareArguments: opts.flat
       ? (args: unknown) => {
-          // Minimal normalization: file_path → path, JSON string parsing.
-          // The flat-to-canonical conversion happens in execute().
           if (!isRec(args)) return args as any;
           const record = { ...args };
-          if (typeof record.path !== "string" && typeof record.file_path === "string") {
-            record.path = record.file_path;
-            delete record.file_path;
-          }
-          if (typeof record.hash_range_inclusive === "string") {
-            try { record.hash_range_inclusive = JSON.parse(record.hash_range_inclusive as string); } catch { /* keep as-is */ }
-          }
-          if (typeof record.content_lines === "string") {
-            try { record.content_lines = JSON.parse(record.content_lines as string); } catch { /* keep as-is */ }
-          }
+          normalizeFilePath(record);
+          tryParseField(record, "hash_range_inclusive");
+          tryParseField(record, "content_lines");
           return record as any;
         }
       : (args: unknown) =>
@@ -428,8 +406,6 @@ export function buildToolDef(opts: { flat: boolean }): ToolDef {
     },
 
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {
-      // Flat mode: wrap top-level fields into a single-element changes array.
-      // Bulk mode: use params as-is after normReq normalization.
       const canonical = opts.flat
         ? normReq({
             path: (params as any).path,

package/src/undo-store.ts

@@ -1,22 +1,8 @@
-/**
- * In-memory undo store for the last_replace_undo tool.
- *
- * Before each successful replace, the pre-edit file state (normalized content,
- * BOM, original line ending, and hashes) is saved keyed by absolute path.
- * The undo tool reads this entry, restores the file, and clears the entry.
- *
- * Only the most recent replace per file is tracked — calling undo twice
- * without an intervening replace will produce "no undo history".
- */
 
 export interface UndoEntry {
-  /** Normalized (LF) content before the edit */
   content: string;
-  /** BOM prefix that was stripped from the original file */
   bom: string;
-  /** Original line ending detected before the edit */
   originalEnding: "\r\n" | "\n";
-  /** Hash array for the pre-edit content */
   hashes: string[];
 }
 

package/src/utils.ts

@@ -17,16 +17,30 @@ export function cntLines(text: string): number {
 }
 
 export function rejectUnknownFields(
-	obj: Record<string, unknown>,
-	allowed: Set<string>,
-	label: string,
-	hint?: string,
+  obj: Record<string, unknown>,
+  allowed: Set<string>,
+  label: string,
+  hint?: string,
 ): void {
-	const unknown = Object.keys(obj).filter((key) => !allowed.has(key));
-	if (unknown.length > 0) {
-		const suffix = hint ? ` ${hint}` : "";
-		throw new Error(
-			`[E_BAD_SHAPE] ${label} contains unknown or unsupported fields: ${unknown.join(", ")}.${suffix}`,
-		);
-	}
+  const unknown = Object.keys(obj).filter((key) => !allowed.has(key));
+  if (unknown.length > 0) {
+    const suffix = hint ? ` ${hint}` : "";
+    throw new Error(
+      `[E_BAD_SHAPE] ${label} contains unknown or unsupported fields: ${unknown.join(", ")}.${suffix}`,
+    );
+  }
+}
+
+export function cntDiff(diff: string, marker: "+" | "-"): number {
+  if (!diff) return 0;
+  let count = 0;
+  for (const line of diff.split("\n")) {
+    if (
+      line.startsWith(marker) &&
+      !line.startsWith(`${marker}${marker}${marker}`)
+    ) {
+      count += 1;
+    }
+  }
+  return count;
 }