pi-hashline-edit-pro 2.6.4 → 2.7.0

package/README.md

@@ -2,18 +2,20 @@
 
 [![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. No line numbers, no fuzzy matching, no edits landing on the wrong line.
+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.
 
-## What you get
+## Features
 
-- **Read with anchors.** Every line comes back as `HASH│content`. The hash is the line's address.
-- **Edit by hash.** `replace` targets a range of hashes, so edits always land on the lines you meant.
-- **Anchors that stay put.** Edit one part of a file and the hashes of the rest stay the same. Read once, keep editing.
-- **Fresh anchors, automatically.** After every `write` you get the new anchors. After every `replace` you get the diff with the new hashes.
-- **Undo when you need it.** The last replace on a file can be reverted, even after a restart.
-- **Safe writes.** Permissions, line endings, BOMs, symlinks, and hard links survive every edit.
+- `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` 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
 
@@ -36,7 +38,7 @@ kQm│}
 }
 ```
 
-3. Keep editing. Anchors for lines you didn't touch stay valid, and auto-read hands you fresh anchors after each change.
+3. Keep editing. Anchors for lines you didn't touch stay valid, and auto-read returns fresh anchors after each change.
 
 ## Installation
 
@@ -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:
 
@@ -91,50 +93,98 @@ One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at t
 | --- | --- |
 | `remove_from` | 3-char hash from `read` output marking the FIRST line to remove (inclusive). |
 | `remove_to` | 3-char hash from `read` output marking the LAST line to remove (inclusive). |
-| `replacement_lines` | Replacement lines as an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element — each element is exactly one line. |
+| `replacement_lines` | Replacement lines as an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element: each element is exactly one line. |
 
 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 exact 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.
+- 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, 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 or deleted since the last replace or insert, the undo is refused rather than overwriting those changes.
 
 ## 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 automatic hashline anchors after write and post-edit diffs after replace and undo_last_replace operations. 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`:
 
@@ -148,9 +198,9 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 
 Each line is canonicalized (carriage returns stripped, trailing whitespace trimmed) and hashed with [xxhash-wasm](https://github.com/jungomi/xxhash-wasm) (xxHash32), then mapped to a 3-character string over `A-Za-z0-9`, which gives 62³ = 238,328 possible anchors. The canonicalization keeps anchors stable across editor-save cycles that add or remove trailing whitespace.
 
-The alphabet is sized for an LLM consumer: the model tokenizes rather than squinting at glyphs, so case and digits are all included. The URL-safe specials `-` and `_` are deliberately excluded. A hash starting with `-` is shape-identical to a diff-preview deletion row, and `-`/`_` at a line start are markdown-active, inviting mis-copying and false autocorrections.
+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.
 
-Unique anchors 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 +228,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 or deleted after the last edit. |
+| `[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,11 +52,11 @@ export default function (pi: ExtensionAPI): void {
   });
 
   pi.registerCommand("toggle-auto-read", {
-    description: "Toggle automatic hashline anchors after write and post-edit diffs after replace and undo_last_replace operations",
+    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";
-      ctx.ui.notify(`Auto-read anchors (write) and post-edit diffs (replace/undo): ${state}`, "info");
+      ctx.ui.notify(`Auto-read anchors after write and post-edit diffs after replace/undo: ${state}`, "info");
     },
   });
 
@@ -111,7 +115,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.4",
+  "version": "2.7.0",
   "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 any edit to that file — changed lines get new anchors (the post-edit diff rows from replace/undo also carry 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/read.md

@@ -1 +1 @@
-Read a text file; each line returned as HASH│content with a 3-char alphanumeric hash. No line numbers — use the HASH as the anchor in replace calls. Images → visual attachments; Binary/directory → rejected; UTF-16/UTF-32 (BOM) → rejected; empty → HASH│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.
+Read a text file; each line returned as HASH│content with a 3-char alphanumeric hash. No line numbers: use the HASH as the anchor in replace calls. Images → visual attachments; Binary/directory → rejected; UTF-16/UTF-32 (BOM) → rejected; empty → HASH│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD.

package/prompts/replace-guidelines.md

@@ -1,8 +1,8 @@
-- `replace`: remove_from and remove_to take ONLY the bare 3-char hash — read row `ve7│function hello() {` means `"remove_from": "ve7"`. Never paste the line content, a code line, a paragraph, or the whole `HASH│content` row into these fields.
+- `replace`: remove_from and remove_to take ONLY the bare 3-char hash: read row `ve7│function hello() {` means `"remove_from": "ve7"`. Never paste the line content, a code line, a paragraph, or the whole `HASH│content` row into these fields.
 - `replace`: remove_from and remove_to mark the exact lines that are REMOVED, and replacement_lines is their complete replacement applied in order; nothing outside the range changes. Every line inside the range that is not reproduced byte-exact in replacement_lines is deleted from the file.
-- `replace`: keep the range as tight as the change — anchor only the first and last line that actually change, never a whole function, class, or import block when only part of it changes.
-- `replace`: to replace a single line, set both remove_from and remove_to to the same hash: remove_from: "<HASH>", remove_to: "<HASH>".
+- `replace`: keep the range as tight as the change: anchor only the first and last line that actually change, never a whole function, class, or import block when only part of it changes.
+- `replace`: to replace a single line, use the same hash for both remove_from and remove_to (e.g. remove_from: "<HASH>", remove_to: "<HASH>").
 - `replace`: when copying a line from read output, remove its HASH│ prefix and keep the leading whitespace exactly as shown.
-- `replace`: replacement_lines is an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element — each element is exactly one line.
-- `replace`: when auto-read shows the post-edit diff, its rows are the fresh anchors for the new file — `+HASH│` and ` HASH│` rows carry current hashes and unchanged lines keep their previous hashes, so you can anchor follow-up edits on the diff without re-reading.
+- `replace`: replacement_lines is an array of strings, one element per line. Mirror the removed lines exactly, blank lines included: use `[]` to delete the range, `[""]` for a single blank line, `["a", ""]` for a line followed by a blank line, and `["", ""]` for two blank lines. Do not embed `\n` inside an element: each element is exactly one line.
+- `replace`: when auto-read shows the post-edit diff, its rows are the fresh anchors for the new file: `+HASH│` and ` HASH│` rows carry current hashes and unchanged lines keep their previous hashes, so you can anchor follow-up edits on the diff without re-reading.
 - `replace`: do not issue multiple replace calls on the same file in one message. Issue the next edit only after verifying the previous diff.

package/prompts/replace-snippet.md

@@ -1 +1 @@
-Replace lines in a text file via bare 3-char HASH anchors from read — hash only, never line content; anchor exactly the lines that change; one edit per tool call
+Replace lines in a text file via bare 3-char HASH anchors from read: hash only, never line content; anchor exactly the lines that change; one edit per tool call

package/prompts/replace.md

@@ -1 +1 @@
-Replace a range of lines in a text file, targeted by the 3-char HASH anchors from read output. remove_from and remove_to must each be a BARE 3-character hash: copy only the hash from the leftmost column of a read row (row `ve7│function hello() {` means `"remove_from": "ve7"`). Never pass the line content, a code line, or a paragraph into these fields.
+Replace a range of lines (or a single line) in a text file, targeted by the 3-char HASH anchors from read output. remove_from and remove_to must each be a BARE 3-character hash: copy only the hash from the leftmost column of a read row (row `ve7│function hello() {` means `"remove_from": "ve7"`). Never pass the line content, a code line, or a paragraph into these fields.

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

@@ -0,0 +1,2 @@
+- `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.

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).

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/constants.ts

@@ -7,5 +7,4 @@ export const MAX_RANGE_STALE_LINES = 100;
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 5;
 export const NEW_CONTENT_NOT_ARRAY_MSG =
-  `[E_BAD_SHAPE] "replacement_lines" must be an array of strings, one element per line, not a single string.`
-  + ` Do not pass one string with \\n separators — pass an array of lines: ["line1", "line2"]. Use [] to delete a range.`;
+  `[E_BAD_SHAPE] "replacement_lines" must be an array of strings, one per line (use [] to delete).`;

package/src/file-kind.ts

@@ -143,7 +143,7 @@ export async function loadFileKindAndText(
         }
         if (newlineCount > options.maxLines) {
           throw new Error(
-            `[E_FILE_TOO_LARGE] ${options.displayPath ?? filePath} has more than ${options.maxLines} lines, exceeding the ${options.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+            `[E_FILE_TOO_LARGE] ${options.displayPath ?? filePath} has more than ${options.maxLines} lines, exceeding the ${options.maxLines}-line hashline limit. For very large files, use write.`,
           );
         }
       }

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);
@@ -91,7 +95,7 @@ export async function readNormFile(
     const lineCount = visLines(normalized).length;
     if (lineCount > options.maxLines) {
       throw new Error(
-        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${options.maxLines}-line edit limit. Hashline editing targets source-sized files; for very large files use write or a non-line-based approach.`,
+        `[E_FILE_TOO_LARGE] ${path} has ${lineCount} lines, exceeding the ${options.maxLines}-line hashline limit. For very large files, use write.`,
       );
     }
   }