pi-hashline-edit-pro 2.6.5 → 2.7.1

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro) [![npm downloads](https://img.shields.io/npm/dm/pi-hashline-edit-pro.svg)](https://www.npmjs.com/package/pi-hashline-edit-pro)
 
-Hash-anchored `read` and `replace` tools for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Every line of a file gets a unique 3-character hash, and you edit by hash. There are no line numbers and no fuzzy matching, so edits land on the lines you meant.
+Hash-anchored `read`, `replace`, `insert`, and `grep` tools for [pi-coding-agent](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent). Every line of a file gets a unique 3-character hash, and you edit by hash. There are no line numbers and no fuzzy matching, so edits land on the lines you meant.
 
 Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extended with 3-character hashes and collision resolution.
 
@@ -10,9 +10,11 @@ Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by Rimur
 
 - `read` returns every line as `HASH│content`. The hash is the line's address.
 - `replace` targets a range of hashes, so edits land on the lines you meant.
+- `insert` adds lines after or before a line by hash: the anchor line is preserved and the new lines are applied literally, never deduplicated.
+- `grep` returns matching lines (and requested context) with `HASH│content` rows that are served like read output, so search results are immediately editable.
 - Editing one part of a file leaves the hashes of the rest unchanged, so anchors from an earlier read stay valid across edits.
-- After a `write` you get the new anchors. After a `replace` you get the diff with the new hashes.
-- The most recent replace on a file can be reverted, even after a restart.
+- After a `write` you get the new anchors. After a `replace` or `insert` you get the diff with the new hashes.
+- The most recent replace or insert on a file can be reverted, even after a restart.
 - Permissions, line endings, BOMs, symlinks, and hard links survive every edit.
 
 ## Quick start
@@ -74,7 +76,7 @@ Edge cases:
 
 ## The replace tool
 
-The built-in `edit` tool is disabled. `replace` is the only edit path, and it takes the hash anchors from `read` output.
+The built-in `edit` tool is disabled. `replace` and `insert` are the only edit paths, and both take the hash anchors from `read` output.
 
 One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at the top level:
 
@@ -98,43 +100,93 @@ Notes:
 - The request is checked before any file I/O, so a bad request never touches the file.
 - Common copy-paste slips are fixed automatically and reported: a leftover `HASH│` prefix (including a truncated or expanded prefix of up to 6 characters, e.g. `L3│` or `ab12│`) in `replacement_lines` or `remove_from`/`remove_to`, diff-preview rows pasted into the replacement, a reversed range, or a boundary line pasted twice. New lines that re-include a block adjacent to the range are stripped automatically when that block is unique in the file. The whole run is stripped as one unit (including repeated structural lines like `}`), so re-including an unchanged block next to the range never duplicates it. A missing `path` is resolved from the anchors when they uniquely identify a file in the hash store (reported as a warning); when the anchors match multiple known files the request is rejected with the candidate paths named. `file_path` works as an alias for `path` in all three tools.
 - An edit that produces identical content reports `No changes made` and leaves the anchors alone. When such a noop happened because a boundary anti-duplication cut removed lines from the replacement (the cut blocked a line that duplicates the block next to the range from being added), the same replacement sent once more runs with the edge anti-duplication turned off for that single call and is applied literally. The duplicated lines are kept, and the result carries a `[E_BOUNDARY_BYPASS]` notice. The pending bypass is per file and keyed to that payload; copied `HASH│` prefixes, diff markers, and stray whitespace in the resend are normalized before matching, so a copy-paste resend still hits it. Any applied edit clears it, and a successful `write` also clears it.
-- Every line in the removed range must match what was last shown to you. The extension records the `HASH│content` rows it serves (`read` output, the auto-read block after `write`, the `+HASH│`/` HASH│` rows of post-edit diffs (replace and undo), the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale/ambiguous-anchor feedback) and verifies the whole range against that record before writing. If an interior line changed on disk since it was shown (external editor, formatter-on-save, code generation) or was never shown, the edit is refused with `[E_RANGE_STALE]` and the current range is returned with fresh anchors, so the retry needs no `read`. Edits outside the served record are only possible for files that were never read (for example right after a `write` with auto-read disabled); once the file has been served, every replaced line must have been shown.
+- Every line in the removed range must match what was last shown to you. The extension records the `HASH│content` rows it serves (`read` output, the auto-read block after `write`, the `+HASH│`/` HASH│` rows of post-edit diffs (replace, insert, and undo), the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale/ambiguous-anchor feedback) and verifies the whole range against that record before writing. If an interior line changed on disk since it was shown (external editor, formatter-on-save, code generation) or was never shown, the edit is refused with `[E_RANGE_STALE]` and the current range is returned with fresh anchors, so the retry needs no `read`. Edits outside the served record are only possible for files that were never read (for example right after a `write` with auto-read disabled); once the file has been served, every replaced line must have been shown.
 - After a successful edit you get the post-edit diff with fresh anchors, so you can keep editing without re-reading.
-- Do not issue multiple replace calls on the same file in one message; parallel edits split attention across the post-edit diffs and removed lines are easy to miss. Verify each diff before the next edit on that file.
+- Do not issue multiple replace or insert calls on the same file in one message; parallel edits split attention across the post-edit diffs and removed lines are easy to miss. Verify each diff before the next edit on that file.
+
+## The insert tool
+
+`insert` adds lines after or before an existing line without removing anything. The anchor line is preserved, and the new lines go after it (`direction: "after"`) or before it (`direction: "before"`):
+
+```json
+{
+  "path": "src/main.ts",
+  "anchor": "szJ",
+  "direction": "after",
+  "lines": ["  console.log('hi');"]
+}
+```
+
+| Field | Description |
+| --- | --- |
+| `anchor` | 3-char hash from `read` output marking the line next to which the lines go (inclusive; the line is preserved). A pasted diff row like `+aB3│x` or a `HASH│` prefix is stripped automatically with a warning. |
+| `direction` | `"after"` to insert below the anchor line, `"before"` to insert above it. |
+| `lines` | Lines to insert as an array of strings, one element per line. Mirror `replacement_lines` semantics: use `[""]` for a blank line and do not embed `\n` inside an element. The anchor line is never part of `lines`. |
+
+Notes:
+
+- The anchor line must have been shown to you (read output, a post-edit diff row, grep output, or stale-range feedback). The same verification as `replace` applies: a stale or unshown anchor is rejected with `[E_STALE_ANCHOR]`, `[E_AMBIGUOUS_ANCHOR]`, or `[E_RANGE_STALE]` and the retry needs no `read`.
+- Lines are applied literally: nothing is removed, and a line that duplicates its neighbor is kept. `replace`'s boundary anti-duplication never runs for `insert`.
+- To seed an empty file, read it and insert after the `HASH│` empty-line row.
+- The same safety machinery as `replace` applies: undo is saved before the write (a failed write restores the previous undo record), line endings and BOMs survive, and an applied insert clears a pending boundary bypass.
+- Inserting nothing (`lines: []`) reports a noop and leaves the file unchanged; inserted lines are never deduplicated.
+
+## The grep tool
+
+`grep` replaces the built-in grep with a hash-anchored search. Every matching line (and each requested context line) is returned as a `HASH│content` row, and those rows are recorded in the served state exactly like `read` output, so you can target them with `replace` or `insert` immediately without a separate `read`.
+
+| Field | Description |
+| --- | --- |
+| `pattern` | Search pattern (regex, or literal text when `literal` is true). |
+| `path` | File or directory to search (default: the current working directory). |
+| `glob` | Filter files by glob pattern; `*` matches across directories, e.g. `*.ts` or `**/*.spec.ts`. |
+| `ignoreCase` | Case-insensitive search (default: false). |
+| `literal` | Treat the pattern as literal text instead of a regex (default: false). |
+| `context` | Lines of context before and after each match; context rows carry anchors too (default: 0). |
+| `limit` | Maximum number of matched lines to return (default: 100). |
+
+Notes:
+- Results are grouped per file under a `=== path ===` header; every shown row carries the anchor it would have in `read` output.
+- Directory searches skip `node_modules`, `.git`, `.tmp`, and `coverage`. Binary, image, and oversized files are skipped silently.
+- Output is capped at `limit` matched lines and 2000 rows, with a hint when the cap cut results. Directory scans stop after 4000 files with a hint; results may be incomplete.
+- `file_path` works as an alias for `path`.
 - Line endings and BOMs survive every edit. The file's line ending is detected from its first newline and restored on write; a file that mixes LF and CRLF (for example a WSL-edited file) is normalized to the first-seen ending.
 - Files with multiple hard links (`nlink > 1`) are rewritten in place rather than via a temp-file rename, so every link keeps seeing the same content; that write is direct rather than atomic.
 
 ## Undo
 
-`undo_last_replace` reverts the most recent successful `replace` on a file, restoring the exact previous content, BOM and line endings included, plus the previous anchors.
+`undo_last_change` reverts the most recent successful `replace` or `insert` on a file, restoring the exact previous content, BOM and line endings included, plus the previous anchors.
 
-- History is per-file and single-level: only the most recent replace can be reverted.
+- History is per-file and single-level: only the most recent replace or insert can be reverted.
 - History is persisted and survives session restarts. A failed `write` does not clear it.
-- Every applied replace is undoable: the undo record is saved before the edit is written.
+- Every applied replace or insert is undoable: the undo record is saved before the edit is written.
 - A successful `write` clears the history for that file.
-- If the file was modified or deleted since the last replace, the undo is refused rather than overwriting those changes.
+- If the file was modified since the last replace or insert, the undo is refused rather than overwriting those changes. The undo record is kept: once the file matches the edited state again (for example you revert the external change), `undo_last_change` succeeds.
+- If the file was deleted since the last replace or insert, `undo_last_change` restores it from the recorded pre-edit content. Nothing is overwritten, since the file no longer exists.
+- Missing-file cleanup never touches the undo record: the per-session prune of the hash store removes the snapshots and served records of files that no longer exist (both are recomputed on the next read), but the undo history survives — even when the file is temporarily absent, for example during a branch switch.
 
 ## Auto-read
 
 Enabled by default. After a successful `write` that changes the file, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so you get fresh `HASH│content` anchors without a separate `read` call.
 
-- After `replace` and `undo_last_replace`, the result shows the post-edit diff. The `+HASH│` and ` HASH│` rows carry the current hashes, so follow-up edits can anchor on the diff directly. The `-HASH│` rows show removed lines with their old hashes, so you can see exactly which anchors were deleted (those hashes are stale after the edit). Call `read` when you want the full file's anchors.
+- After `replace`, `insert`, and `undo_last_change`, the result shows the post-edit diff. The `+HASH│` and ` HASH│` rows carry the current hashes, so follow-up edits can anchor on the diff directly. The `-HASH│` rows show removed lines with their old hashes, so you can see exactly which anchors were deleted (those hashes are stale after the edit). When the context line touching a change is blank or whitespace-only, one more context line is shown in that direction, so the change stays anchored to visible content. Call `read` when you want the full file's anchors.
 - Auto-read keeps a 50KB display budget. Lines over 50KB are skipped with a marker instead of their content (use `read` for lines up to 200KB).
 - Toggle at runtime with `/toggle-auto-read`; the setting persists across sessions.
 
 ## Tool result details
 
-All three tools return machine-readable metadata in `details` alongside the model-visible text:
+All five tools return machine-readable metadata in `details` alongside the model-visible text:
 
 - `read`: `details.truncation` (set when the output was truncated), `details.snapshotId` (a `v2|path|ino|mtime|ctime|size` fingerprint of the file), `details.nextOffset` (use as the next `offset`), and `details.metrics` with `truncated` and `next_offset`.
-- `replace`: `details.diff` (the post-edit diff; `+HASH│` and ` HASH│` rows carry the current anchors), `details.patch` (a standard unified patch of the changes, for external tools), `details.firstChangedLine`, `details.snapshotId`, `details.classification` (`"noop"` when nothing changed), and `details.metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`.
-- `undo_last_replace`: `details.diff` (the undo diff with the restored anchors), `details.patch` (a standard unified patch of the restored changes), and `details.metrics` (same shape as `replace`).
+- `replace` and `insert`: `details.diff` (the post-edit diff; `+HASH│` and ` HASH│` rows carry the current anchors), `details.patch` (a standard unified patch of the changes, for external tools), `details.firstChangedLine`, `details.snapshotId`, `details.classification` (`"noop"` when nothing changed), and `details.metrics`: `edits_attempted`, `edits_noop`, `warnings`, `classification` (`"applied"` or `"noop"`), `changed_lines` (`{ first, last }`), `added_lines`, `removed_lines`.
+- `undo_last_change`: `details.diff` (the undo diff with the restored anchors), `details.patch` (a standard unified patch of the restored changes), and `details.metrics` (same shape as `replace`).
+- `grep`: `details.metrics` with `matches`, `files`, and `truncated`.
 
 ## Settings
 
 | Command | Description |
 | --- | --- |
-| `/toggle-auto-read` | Toggle auto-read anchors after write and post-edit diffs after replace and undo_last_replace. Persists across sessions. |
+| `/toggle-auto-read` | Toggle auto-read anchors after write and post-edit diffs after replace, insert, and undo_last_change. Persists across sessions. |
 
 Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatically when a setting is toggled. On non-Windows platforms, the config directory honors `XDG_CONFIG_HOME` when set (falling back to `~/.config`); on Windows it always uses `~/.config`:
 
@@ -150,7 +202,7 @@ Each line is canonicalized (carriage returns stripped, trailing whitespace trimm
 
 The alphabet is sized for an LLM consumer: the model reads the hashes as tokens rather than inspecting glyph shapes, so letters and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded. A hash starting with `-` looks like a diff-preview deletion row, and `-`/`_` at the start of a line are markdown-active, which invites mis-copying and false autocorrections.
 
-Anchors are unique by construction. If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions, runs of blank lines, repeated `}`, land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor; two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read` and `replace` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
+Anchors are unique by construction. If a line's base hash collides with an already-assigned hash, the next free hash is allocated from a bitset by probing with a stride coprime to the hash space (O(1) amortized). The stride is `62² + 62 + 1`, so consecutive collisions, runs of blank lines, repeated `}`, land on anchors that differ in all three characters instead of sharing a prefix. Every line in a file therefore gets a unique anchor; two byte-identical lines (repeated `}`, repeated `import` statements) never share one. The same guarantee sets the file size cap: at most 238,328 lines per file, beyond which `read`, `replace`, and `insert` reject with `[E_FILE_TOO_LARGE]` (use `write` for very large files).
 
 Hashes live in a persistent per-file store (`~/.config/pi-hashline-edit-pro/hash-store.sqlite`) that keeps the hashes of unchanged lines across edits. When a range is replaced, the runtime maps the old content onto the new content and copies hashes for lines that survived; only genuinely new lines get fresh hashes.
 
@@ -178,8 +230,8 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 | `[E_NOT_FOUND]` | The path does not exist. |
 | `[E_ACCESS]` | The file is not readable or writable. |
 | `[E_NOT_TEXT]` | The path is a directory, binary file, image, or UTF-16/UTF-32 encoded text; hashline editing only supports text files. |
-| `[E_UNDO_STALE]` | `undo_last_replace` refused: the file was modified or deleted after the last replace. |
-| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the `replace` was refused and the file was left unchanged. |
+| `[E_UNDO_STALE]` | `undo_last_change` refused: the file was modified after the last edit. The undo record is kept until the file matches the edited state again or a new edit replaces it. |
+| `[E_UNDO_UNAVAILABLE]` | Undo history could not be persisted to the hash store; the edit was refused and the file was left unchanged. |
 | `[E_RANGE_STALE]` | A line in the replaced range no longer matches what was last shown (the file changed on disk, or the line was never shown). The edit was refused; the current range is returned with fresh anchors. |
 | `[E_BOUNDARY_BYPASS]` | The boundary anti-duplication was turned off for one replace call (an identical replacement had previously been cut to a noop); the duplicate lines were applied literally. The dedup is restored for the next call. |
 | `[E_FILE_TOO_LARGE]` | The file exceeds the 238,328-line hashline limit or the 100MB size limit. |

package/index.ts

@@ -2,7 +2,9 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
-import { regReplaceUndo, clearUndo } from "./src/replace-undo";
+import { regInsert } from "./src/insert";
+import { regGrep } from "./src/grep";
+import { regUndo, clearUndo } from "./src/replace-undo";
 import { regRead, fmtReadPreview } from "./src/read";
 import type { RMetrics } from "./src/replace-response";
 import { extractWarnings } from "./src/replace-render";
@@ -25,7 +27,9 @@ export default function (pi: ExtensionAPI): void {
   regRead(pi);
 
   regReplace(pi);
-  regReplaceUndo(pi);
+  regInsert(pi);
+  regGrep(pi);
+  regUndo(pi);
 
   let autoRead = true;
 
@@ -48,7 +52,7 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("toggle-auto-read", {
-    description: "Toggle auto-read anchors after write and post-edit diffs after replace and undo_last_replace",
+    description: "Toggle auto-read anchors after write and post-edit diffs after replace, insert, and undo_last_change",
     handler: async (_args, ctx) => {
       autoRead = await toggleAutoRead();
       const state = autoRead ? "enabled" : "disabled";
@@ -61,13 +65,14 @@ export default function (pi: ExtensionAPI): void {
 
     if (event.toolName === "write") {
       const writtenPath = (event.input as Record<string, unknown>)?.path;
+      let resolvedPath: string | undefined;
       if (typeof writtenPath === "string") {
         try {
-          const target = await resolveTarget(toCwd(writtenPath, ctx.cwd));
-          await clearUndo(target);
-          clearBoundaryBypass(target);
+          resolvedPath = await resolveTarget(toCwd(writtenPath, ctx.cwd));
+          await clearUndo(resolvedPath);
+          clearBoundaryBypass(resolvedPath);
           const store = await loadHashStore();
-          clearServed(store, target);
+          clearServed(store, resolvedPath);
         } catch (error) {
           console.error("Failed to clear undo after write:", error);
         }
@@ -75,7 +80,7 @@ export default function (pi: ExtensionAPI): void {
       if (!autoRead) return;
       if (typeof writtenPath !== "string") return;
       try {
-        const resolvedPath = await resolveTarget(toCwd(writtenPath, ctx.cwd));
+        resolvedPath ??= await resolveTarget(toCwd(writtenPath, ctx.cwd));
         await valAccess(resolvedPath, writtenPath);
         const file = await loadFileKindAndText(resolvedPath, { maxLines: MAX_HASH_LINES, displayPath: writtenPath });
         if (file.kind !== "text") return;
@@ -111,7 +116,8 @@ export default function (pi: ExtensionAPI): void {
 
     if (
       event.toolName !== "replace" &&
-      event.toolName !== "undo_last_replace"
+      event.toolName !== "insert" &&
+      event.toolName !== "undo_last_change"
     ) return;
     if (!autoRead) return;
 

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.6.5",
+  "version": "2.7.1",
   "type": "module",
-  "description": "Hash-anchored read/replace/undo tools for pi-coding-agent. Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
+  "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 3-char hash (A-Za-z0-9) that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",
   "repository": {
     "type": "git",

package/prompts/grep-guidelines.md

@@ -0,0 +1,6 @@
+- `grep`: results carry `HASH│` anchors recorded like read output, so you can target them with replace or insert immediately.
+- `grep`: pass `path` for a single file or directory; the default is the current working directory. Directory searches skip node_modules, .git, .tmp, and coverage.
+- `grep`: use `literal: true` when the pattern contains regex metacharacters you want matched literally.
+- `grep`: use `context` to see surrounding lines; context rows carry anchors too.
+- `grep`: use `glob` to filter files; `*` matches across directories, e.g. `*.ts` or `**/*.spec.ts`.
+- `grep`: results are capped at `limit` matches (default 100) and 2000 rows; refine the pattern or raise limit to see more.

package/prompts/grep-snippet.md

@@ -0,0 +1 @@
+Search file contents; matching lines carry HASH│ anchors usable in replace/insert without a re-read

package/prompts/grep.md

@@ -0,0 +1 @@
+Search text files for a pattern. Returns every matching line (and the requested context lines) as `HASH│content` rows, so the results can be used directly as replace and insert anchors without a separate read. Directory searches skip node_modules, .git, .tmp, and coverage. Binary, image, and oversized files are skipped silently.

package/prompts/insert-guidelines.md

@@ -0,0 +1,6 @@
+- `insert`: anchor takes ONLY the bare 3-char hash of the line next to which the new lines go: read row `ve7│function hello() {` means `"anchor": "ve7"`. Never paste the line content or the whole `HASH│content` row.
+- `insert`: the anchor line is preserved. Include only the new lines in `lines`, never the anchor line itself.
+- `insert`: use `direction: "after"` to add lines after the anchor line, `"before"` to add them before it.
+- `insert`: read the file first, so the anchor line was shown to you. Use a post-edit diff row or grep output for follow-up inserts.
+- `insert`: to seed an empty file, read it and insert after the `HASH│` empty-line row.
+- `insert`: lines are applied literally — never deduplicated — so restating a neighbor is safe and has no effect on the result.

package/prompts/insert-snippet.md

@@ -0,0 +1 @@
+Insert lines after or before a line in a text file via bare 3-char HASH anchor from read: the anchor line stays, new lines go after/before it, applied literally

package/prompts/insert.md

@@ -0,0 +1 @@
+Insert lines after or before an existing line in a text file, targeted by the 3-char HASH anchors from read output. The anchor line is preserved; the new lines are added after it (direction "after") or before it (direction "before"). Each element of lines is exactly one line; do not embed \n inside an element: use separate elements. Use [""] for a blank line. The lines you send are added literally: nothing is removed, and lines that duplicate their neighbors are kept.

package/prompts/read-guidelines.md

@@ -1,2 +1,2 @@
 - `read`: call before `replace` when you need fresh HASH anchors for a file.
-- `read`: call again after an edit when you need anchors you do not have. The post-edit diff after replace/undo already carries fresh anchors for the changed range.
+- `read`: call again after an edit when you need anchors you do not have. The post-edit diff after replace/insert and the anchored rows after grep already carry fresh anchors for the changed range.

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

@@ -0,0 +1,3 @@
+- `undo_last_change`: reverts only the most recent replace or insert on the file: any write to the file clears the undo history, so call it immediately after a bad edit. An edit is bad when its post-edit diff shows `-HASH│` rows for lines you meant to keep (a closing brace, import, or declaration).
+- `undo_last_change`: when auto-read shows the post-edit diff, its `+HASH│` and ` HASH│` rows are the fresh anchors for the restored file, so follow-up edits can anchor on the diff without re-reading.
+- `undo_last_change`: if the file was deleted since the edit, the undo restores it from the recorded pre-edit content; if the file was modified since the edit, the undo is refused with `[E_UNDO_STALE]` and the record is kept, so reverting the external change makes the undo succeed.

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

@@ -0,0 +1 @@
+Undo the last change (replace or insert) on a file

package/prompts/undo-last-change.md

@@ -0,0 +1 @@
+Undo the last change (replace or insert) on a file, reverting it to its previous state. Use when an edit produced incorrect results (e.g., wrong content, duplicated lines, broken syntax). If the file was deleted since the edit, the undo restores it from the recorded content. If the file was modified since the edit, the undo is refused and the record is kept until the file matches the edited state again.

package/src/boundary-bypass.ts

@@ -1,6 +1,6 @@
 import { parseText } from "./hashline/parse";
 import { ANCHOR_ROW_RE } from "./hashline/resolve";
-import { HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE } from "./hashline/hash";
+import { stripRowPrefix } from "./hashline/hash";
 
 function canonRef(ref: string): string {
   const trimmed = ref.trim();
@@ -9,15 +9,7 @@ function canonRef(ref: string): string {
 }
 
 function canonLines(lines: string[]): string[] {
-  return parseText(lines).map((line) => {
-    const bare = line.match(HL_BARE_PREFIX_RE);
-    if (bare) return line.slice(bare[0].length);
-    const plus = line.match(HL_PREFIX_PLUS_RE);
-    if (plus) return line.slice(plus[0].length);
-    const minus = line.match(HL_PREFIX_MINUS_RE);
-    if (minus) return line.slice(minus[0].length);
-    return line;
-  });
+  return parseText(lines).map((line) => stripRowPrefix(line).text);
 }
 
 const boundaryBypassTracker = new Map<string, string>();

package/src/commit.ts

@@ -0,0 +1,107 @@
+import type { PipelineResult } from "./replace";
+import { abortIf } from "./utils";
+import { buildChanged, buildNoop, type RMeta, type TResult } from "./replace-response";
+import { saveUndo } from "./replace-undo";
+import { safeSnapId } from "./file-reader";
+import { writeAtomic } from "./fs-write";
+import { recordServedDiffSafe } from "./served";
+import { restoreEndings } from "./replace-diff";
+
+export interface CommitMeta {
+  path: string;
+  absolutePath: string;
+  mutationTargetPath: string;
+  signal?: AbortSignal;
+  verb?: string;
+  noopNoun?: string;
+  prefixWarnings?: string[];
+  appliedWarnings?: string[];
+  foldedAnchorLines?: number;
+  onApplied?: () => void;
+  onNoopDedup?: () => void;
+}
+
+export async function commitEdit(pipe: PipelineResult, meta: CommitMeta): Promise<TResult> {
+  const { path, absolutePath, mutationTargetPath, signal } = meta;
+  const warnings = [...(meta.prefixWarnings ?? []), ...pipe.warnings];
+  const editsAttempted = 1;
+
+  if (pipe.result === pipe.originalNormalized) {
+    const noopSnapshotId = await safeSnapId(absolutePath, "noop edit");
+    if (pipe.hadBoundaryDedup) meta.onNoopDedup?.();
+    return buildNoop(
+      {
+        path,
+        noopEdit: pipe.noopEdit,
+        snapshotId: noopSnapshotId,
+        editMeta: {
+          editsAttempted,
+          noopEditsCount: pipe.noopEdit ? 1 : 0,
+          addedLines: 0,
+          removedLines: 0,
+        },
+        warnings,
+        boundaryRemovedLines: pipe.boundaryRemovedLines,
+      },
+      meta.noopNoun,
+    );
+  }
+
+  warnings.push(...(meta.appliedWarnings ?? []));
+  if (pipe.hadUtf8DecodeErrors) {
+    warnings.push(
+      "Non-UTF-8 bytes were shown as U+FFFD; this edit rewrote the file as UTF-8.",
+    );
+  }
+
+  abortIf(signal);
+  const undo = await saveUndo(mutationTargetPath, {
+    content: pipe.originalNormalized,
+    bom: pipe.bom,
+    originalEnding: pipe.originalEnding,
+    hashes: pipe.originalHashes,
+    resultContent: pipe.result,
+  });
+  if (!undo.persisted) {
+    throw new Error(
+      `[E_UNDO_UNAVAILABLE] Could not persist undo history; the edit was not applied and ${path} is unchanged.`
+    );
+  }
+  try {
+    abortIf(signal);
+    await writeAtomic(
+      absolutePath,
+      pipe.bom + restoreEndings(pipe.result, pipe.originalEnding),
+    );
+  } catch (error) {
+    await undo.restore();
+    throw error;
+  }
+  meta.onApplied?.();
+  const updatedSnapshotId = await safeSnapId(absolutePath, "post-edit");
+
+  const editMeta: RMeta = {
+    editsAttempted,
+    noopEditsCount: pipe.noopEdit ? 1 : 0,
+    firstChangedLine: pipe.firstChangedLine,
+    lastChangedLine: pipe.lastChangedLine,
+    addedLines: Math.max(0, pipe.totalAddedLines - (meta.foldedAnchorLines ?? 0)),
+    removedLines: pipe.totalRemovedLines,
+  };
+
+  const successInput = {
+    path,
+    originalNormalized: pipe.originalNormalized,
+    originalHashes: pipe.originalHashes,
+    result: pipe.result,
+    resultHashes: pipe.resultHashes,
+    warnings,
+    snapshotId: updatedSnapshotId,
+    editMeta,
+  };
+  const changed = buildChanged(successInput, meta.verb);
+  if (changed.details.diff) {
+    await recordServedDiffSafe(mutationTargetPath, changed.details.diff, "post-edit diff", new Set(pipe.resultHashes));
+  }
+  return changed;
+}

package/src/file-reader.ts

@@ -61,6 +61,7 @@ export interface ReadNormOptions {
   signal?: AbortSignal;
   accessMode?: number;
   preloadedFile?: LFile;
+  preloadedNorm?: NormFile;
   maxLines?: number;
   store?: HashStore;
   noPersist?: boolean;
@@ -80,6 +81,9 @@ export async function readNormFile(
   await valAccess(resolvedPath, path, accessMode);
 
   abortIf(signal);
+  const preloadedNorm = options?.preloadedNorm;
+  if (preloadedNorm) return preloadedNorm;
+
   const file = options?.preloadedFile ?? (await loadFileKindAndText(resolvedPath, { maxLines: options?.maxLines, displayPath: path }));
   valKind(file, path);
   abortIf(signal);