pi-hashline-edit-pro 2.7.1 → 2.8.0

package/README.md

@@ -2,18 +2,18 @@
 
 [![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`, `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.
+Anchor-based `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 anchor, and you edit by anchor. 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.
+Fork of [pi-hashline-edit](https://github.com/RimuruW/pi-hashline-edit) by RimuruW, extended with 3-character anchors and collision resolution.
 
 ## Features
 
-- `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.
+- `read` returns every line as `anchor│content`. The anchor is the line's address.
+- `replace` targets a range of anchors, so edits land on the lines you meant.
+- `insert` adds lines after or before a line by anchor: the anchor line is preserved and the new lines are applied literally, never deduplicated.
+- `grep` returns matching lines (and requested context) with `anchor│content` rows that are served like read output, so search results are immediately editable.
+- Editing one part of a file leaves the anchors 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 anchors.
 - 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.
 
@@ -27,7 +27,7 @@ szJ│  console.log("world");
 kQm│}
 ```
 
-2. Replace a line by its hash:
+2. Replace a line by its anchor:
 
 ```json
 {
@@ -54,7 +54,7 @@ pi install /path/to/pi-hashline-edit-pro
 
 ## The read tool
 
-`read` returns a text file with every line prefixed by `HASH│content`. The hash is 3 characters from `A-Za-z0-9` (for example `aB3`).
+`read` returns a text file with every line prefixed by `anchor│content`. The anchor is 3 characters from `A-Za-z0-9` (for example `aB3`).
 
 | Parameter | Description |
 | --- | --- |
@@ -63,20 +63,20 @@ pi install /path/to/pi-hashline-edit-pro
 
 Paged output ends with a continuation hint, for example `[Showing lines 1-50 of 120. Use offset=51 to continue.]`.
 
-Lines up to 200KB are shown in full. Larger lines are replaced by a marker with a bash inspection hint (`sed -n 'Np' <path> | head -c 204800`), because hash anchors need full lines.
+Lines up to 50KB are shown in full. A larger line is replaced by a marker that keeps the line's anchor: `anchor│[Line N is 2.2MB, exceeds 50KB; content not shown. Use bash: sed -n 'Np' <path> | head -c 51200]`. The marker is served like a normal row, so the whole line can still be replaced via that anchor; `grep` shows an anchored fragment around a match on such a line instead.
 
 Edge cases:
 
 - Images (JPEG, PNG, GIF, WebP, BMP) come back as visual attachments. Other image formats (for example AVIF, HEIC/HEIF, TIFF, ICO, JPEG 2000, JPEG XL, PSD, APNG) are rejected as binary, since the built-in renderer cannot attach them.
 - Binary files and directories are rejected with a descriptive error. A magic-signature match is ignored when the sampled bytes contain no NUL bytes and decode as UTF-8, so a text file whose first bytes happen to match a binary or image signature (for example starting with `BM` or `8BPS`) is still read as text. The NUL-byte check covers the whole file, not just the sampled bytes: a file with a NUL byte anywhere is rejected as binary.
 - UTF-16 and UTF-32 text (detected via BOM) is rejected, since editing it would corrupt the file.
-- Empty files come back as a single empty-line hash (`HASH│`); use `replace` on that hash to insert content.
+- Empty files come back as a single empty-line anchor (`anchor│`); use `replace` on that anchor to insert content.
 - BOMs are stripped for display. Non-UTF-8 bytes are shown as `U+FFFD`; editing such a file rewrites it as UTF-8, with a warning.
 - Files over 238,328 lines or 100MB are rejected with `[E_FILE_TOO_LARGE]`.
 
 ## The replace tool
 
-The built-in `edit` tool is disabled. `replace` and `insert` are the only edit paths, and both take 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 anchors from `read` output.
 
 One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at the top level:
 
@@ -91,17 +91,17 @@ One edit per call, with `remove_from`, `remove_to`, and `replacement_lines` at t
 
 | Field | Description |
 | --- | --- |
-| `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). |
+| `remove_from` | 3-char anchor from `read` output marking the FIRST line to remove (inclusive). |
+| `remove_to` | 3-char anchor 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. |
 
 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, 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.
+- Common copy-paste slips are fixed automatically and reported: a leftover `anchor│` 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 five 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 `anchor│` 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 `anchor│content` rows it serves (`read` output, the auto-read block after `write`, the `+anchor│`/` anchor│` 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. The diff is capped at 50KB: a row longer than 50KB is shown as a marker that keeps the row's anchor (so the line stays editable via the diff), and when the total cap is hit the diff ends with a truncation note. Only the rows shown in the capped diff are recorded as served. The same caps apply to the `insert` and `undo_last_change` diffs, to the interactive previews, and to `details.patch` (which is flagged with `details.patchTruncated` when it was cut and can no longer be applied as-is).
 - 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
@@ -119,7 +119,7 @@ Notes:
 
 | 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. |
+| `anchor` | 3-char anchor 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 an `anchor│` 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`. |
 
@@ -127,19 +127,19 @@ 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.
+- To seed an empty file, read it and insert after the `anchor│` 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`.
+`grep` replaces the built-in grep with an anchored search. Every matching line (and each requested context line) is returned as an `anchor│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`. |
+| `glob` | Filter files by glob pattern; `*` matches across directories, e.g. `*.ts` or `**/*.spec.ts`. A leading `/` is ignored, and the pattern may be relative to the search root or to the current directory. |
 | `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). |
@@ -148,7 +148,7 @@ Notes:
 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.
+- Output is capped at `limit` matched lines, 2000 rows, and 50KB of text (whichever comes first), with a hint naming the cap that cut results. A matched line longer than 500 bytes is shown as a fragment around the match with `...` marking the truncated sides, so the relevant part of the hit stays visible; a context line over 500 bytes is shown as its head with a trailing `...`. Fragments keep the line's anchor (long lines are hashed from their first 500 bytes) and are served like full rows, so a fragmented match is still editable with `replace` (which always replaces the whole line). 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.
@@ -167,10 +167,10 @@ Notes:
 
 ## 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.
+Enabled by default. After a successful `write`, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so you get fresh `anchor│content` anchors without a separate `read` call.
 
-- 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).
+- After `replace`, `insert`, and `undo_last_change`, the result shows the post-edit diff. The `+anchor│` and ` anchor│` rows carry the current anchors, so follow-up edits can anchor on the diff directly. The `-anchor│` rows show removed lines with their old anchors, so you can see exactly which anchors were deleted (those anchors 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 the same 50KB / 2000-line budget as `read`. Lines over 50KB are shown as markers that keep the line's anchor (use `grep` for a fragment around a match).
 - Toggle at runtime with `/toggle-auto-read`; the setting persists across sessions.
 
 ## Tool result details
@@ -178,9 +178,9 @@ Enabled by default. After a successful `write` that changes the file, the extens
 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` 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`.
+- `replace` and `insert`: `details.diff` (the post-edit diff, capped at 50KB with markers for oversized rows; `+HASH│` and ` HASH│` rows carry the current anchors), `details.patch` (a standard unified patch of the changes, for external tools, capped at 50KB like the diff), `details.patchTruncated` (true when the patch was cut to fit the cap and cannot be applied as-is), `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, capped at 50KB like `replace`), `details.patchTruncated` (true when the patch was cut), and `details.metrics` (same shape as `replace`).
+- `grep`: `details.metrics` with `matches` (matched lines found, capped at `limit`), `files`, and `truncated` (true when the row, byte, file-scan, or `limit` cap cut the results), plus `details.truncation` (the standard pi truncation report — `truncatedBy`, `totalLines`, `outputLines`, `maxLines`, `maxBytes`, … — when the output was cut) and `details.linesTruncated` (true when long lines were shown as fragments).
 
 ## Settings
 
@@ -198,7 +198,7 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 
 ## How anchors work
 
-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.
+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. A line longer than 500 bytes is hashed from its first 500 bytes; uniqueness is still guaranteed by the collision-resolution below.
 
 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.
 
@@ -220,11 +220,11 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 | Code | Meaning |
 | --- | --- |
 | `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `replacement_lines` must be an array of strings, one element per line). |
-| `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 3-char hash. |
+| `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 3-char anchor. |
 | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
-| `[E_INVALID_PATCH]` | A `replacement_lines` element is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`). The marker is stripped automatically with a warning. |
-| `[E_BARE_HASH_PREFIX]` | A `replacement_lines` element starts with a hash-like `HASH│` prefix. The prefix is stripped automatically with a warning. |
+| `[E_INVALID_PATCH]` | A `replacement_lines` element is a diff-preview row (`+anchor│`, `-anchor│`, `-   │`). The marker is stripped automatically with a warning. |
+| `[E_BARE_HASH_PREFIX]` | A `replacement_lines` element starts with an `anchor│` prefix (the anchor plus the separator). The prefix is stripped automatically with a warning. |
 | `[E_BAD_OP]` | Range start line is after range end line. The pair is swapped automatically with a warning. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
 | `[E_NOT_FOUND]` | The path does not exist. |
@@ -235,6 +235,7 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 | `[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. |
+| `[E_WRITE_HASH_ECHO]` | A `write` `content` line begins with the exact `anchor│` served for this file at the same line. The write is refused, file byte-identical; retry with bare content (remove the copied anchors). |
 
 ## Troubleshooting
 

package/index.ts

@@ -1,5 +1,5 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { DEFAULT_MAX_BYTES } from "@earendil-works/pi-coding-agent";
+import { DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES } from "@earendil-works/pi-coding-agent";
 import { initHasher } from "./src/hashline";
 import { regReplace } from "./src/replace";
 import { regInsert } from "./src/insert";
@@ -9,7 +9,6 @@ import { regRead, fmtReadPreview } from "./src/read";
 import type { RMetrics } from "./src/replace-response";
 import { extractWarnings } from "./src/replace-render";
 import { MAX_HASH_LINES } from "./src/hashline";
-import { AUTO_READ_MAX } from "./src/constants";
 import {
   readConfig,
   toggleAutoRead,
@@ -17,10 +16,10 @@ import {
 import { loadHashStore, pruneMissing } from "./src/hash-store";
 import { recordServedSafe, clearServed } from "./src/served";
 import { clearBoundaryBypass } from "./src/boundary-bypass";
+import { registerWriteHook } from "./src/write-hook";
 import { readNormFile } from "./src/file-reader";
 import { loadFileKindAndText } from "./src/file-kind";
-import { toCwd } from "./src/paths";
-import { resolveTarget } from "./src/fs-write";
+import { resolveInCwd } from "./src/fs-write";
 import { valAccess } from "./src/validation";
 
 export default function (pi: ExtensionAPI): void {
@@ -30,6 +29,7 @@ export default function (pi: ExtensionAPI): void {
   regInsert(pi);
   regGrep(pi);
   regUndo(pi);
+  registerWriteHook(pi);
 
   let autoRead = true;
 
@@ -68,7 +68,7 @@ export default function (pi: ExtensionAPI): void {
       let resolvedPath: string | undefined;
       if (typeof writtenPath === "string") {
         try {
-          resolvedPath = await resolveTarget(toCwd(writtenPath, ctx.cwd));
+          resolvedPath = (await resolveInCwd(writtenPath, ctx.cwd)).resolved;
           await clearUndo(resolvedPath);
           clearBoundaryBypass(resolvedPath);
           const store = await loadHashStore();
@@ -80,7 +80,7 @@ export default function (pi: ExtensionAPI): void {
       if (!autoRead) return;
       if (typeof writtenPath !== "string") return;
       try {
-        resolvedPath ??= await resolveTarget(toCwd(writtenPath, ctx.cwd));
+        resolvedPath ??= (await resolveInCwd(writtenPath, ctx.cwd)).resolved;
         await valAccess(resolvedPath, writtenPath);
         const file = await loadFileKindAndText(resolvedPath, { maxLines: MAX_HASH_LINES, displayPath: writtenPath });
         if (file.kind !== "text") return;
@@ -93,7 +93,7 @@ export default function (pi: ExtensionAPI): void {
           fileHashes,
           absolutePath,
           DEFAULT_MAX_BYTES,
-          AUTO_READ_MAX,
+          DEFAULT_MAX_LINES,
         );
         await recordServedSafe(absolutePath, preview.servedHashes, "auto-read", new Set(fileHashes));
         return {
@@ -125,7 +125,8 @@ export default function (pi: ExtensionAPI): void {
     if (metrics?.classification === "noop") return;
 
     const diff = (event.details as { diff?: string } | undefined)?.diff;
-    if (!diff) return;
+    if (typeof diff !== "string") return;
+    const hasDiff = diff.length > 0;
 
     const rendered = (event.content ?? [])
       .filter(
@@ -135,11 +136,12 @@ export default function (pi: ExtensionAPI): void {
       .map((entry) => entry.text)
       .join("\n");
     const warnings = extractWarnings(rendered);
+    const hint = hasDiff ? (warnings ? `${diff}\n\n${warnings}` : diff) : warnings ? `[post-edit] applied successfully; the diff is empty (whitespace-only change).\n\n${warnings}` : "[post-edit] applied successfully; the diff is empty (whitespace-only change).";
     return {
       content: [
         {
           type: "text",
-          text: warnings ? `${diff}\n\n${warnings}` : diff,
+          text: hint,
         },
       ],
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "type": "module",
   "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",
@@ -45,7 +45,7 @@
     "xxhash-wasm": "^1.1.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": ">=0.75.0",
+    "@earendil-works/pi-coding-agent": ">=0.84.0",
     "@earendil-works/pi-tui": "*"
   },
   "engines": {

package/prompts/grep-guidelines.md

@@ -1,6 +1,3 @@
-- `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.
+- `grep`: every hit and `context` line comes back as `anchor│content` — use that anchor directly for `replace`/`insert` without a new `read`.
+- `grep`: use `path` for file or folder (default cwd), `glob` like `*.ts` to filter, `literal:true` for literal text, `context:N` for surrounding lines.
+- `grep`: search skips `node_modules/.git/.tmp/coverage` and skips binary/image files.

package/prompts/grep-snippet.md

@@ -1 +1 @@
-Search file contents; matching lines carry HASH│ anchors usable in replace/insert without a re-read
+Search with `anchor│content` hits usable directly for `replace`/`insert`; use `literal`/`glob`/`context`

package/prompts/grep.md

@@ -1 +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.
+Search text files for a pattern. Every hit and each `context` line is returned as `anchor│content` so you can use that anchor directly for `replace`/`insert` without a new `read`. Directory search skips `node_modules/.git/.tmp/coverage` and skips binary/image files. Matching lines longer than 500 bytes are shown as a fragment around the match with `...`, but the anchor is still valid for the whole line. If output says truncated, refine `pattern` or raise `limit` as hinted.

package/prompts/insert-guidelines.md

@@ -1,6 +1,3 @@
-- `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.
+- `insert`: `anchor` is bare `aB3` from `aB3│content` (never the content), direction `after` adds below, `before` adds above. Do not put the anchor line in `lines`; `[""]` is a blank line.
+- `insert`: `lines` is bare content, one element per line, kept literally even if it duplicates neighbors — nothing is removed.
+- `insert`: the anchor must have been shown by `read`, a post-edit diff (`+anchor│`/` anchor│`), or `grep`. For an empty file, `read` shows one `anchor│` empty row — insert `after` it.

package/prompts/insert-snippet.md

@@ -1 +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
+Insert `lines` after/before bare anchor `aB3` from `aB3│content`: anchor stays, lines are bare without `│`, one per element

package/prompts/insert.md

@@ -1 +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.
+Insert lines after or before one existing line in a text file, using a bare anchor like `aB3` from `aB3│content`. The anchor line stays; your `lines` are added after (`"after"`) or before (`"before"`) it, one string per line. Use `[""]` for a blank line, never put `\n` inside an element and never include the anchor line in `lines`. Lines are added literally, even if they duplicate neighbors.

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/insert and the anchored rows after grep already carry fresh anchors for the changed range.
+- `read`: call before `replace` when you need fresh anchors for a file.
+- `read`: call again after an edit when you need anchors you do not have — post-edit diff `+anchor│`/` anchor│` rows and `grep` hits are already fresh anchors for the changed range, so no new `read` needed for those lines.

package/prompts/read-snippet.md

@@ -1 +1 @@
-Read a file; each line returned as HASH│content
+Read a file; each line returned as anchor│content

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 `anchor│content` with a 3-character alphanumeric anchor (e.g. `aB3│hello` is anchor `aB3` plus content `hello`). No line numbers: use the anchor in replace and insert calls. Images → visual attachments; Binary/directory → rejected; UTF-16/UTF-32 (BOM) → rejected; empty → anchor│ (replace to insert); pageable with offset/limit; BOM stripped; non-UTF-8 shown as U+FFFD. If output says truncated, use `offset`/`limit` as hinted.

package/prompts/replace-guidelines.md

@@ -1,8 +1,5 @@
-- `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, 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`: do not issue multiple replace calls on the same file in one message. Issue the next edit only after verifying the previous diff.
+- `replace`: `remove_from` and `remove_to` are bare anchors like `aB3` (the 3 chars before `│` in `aB3│content`), never the full row or file content. Use the same anchor for both to change one line.
+- `replace`: `replacement_lines` is bare content without `│`, one element per line. Use `[]` to delete, `[""]` for one blank line, never put `\n` inside an element and never include the `anchor│` prefix.
+- `replace`: the range from `remove_from` to `remove_to` is exactly deleted and replaced in order — make it tight, only the lines that actually change, and copy leading spaces exactly.
+- `replace`: diff markers like `+aB3│` or `-aB3│` are stripped automatically if pasted, but always try to send bare content.
+- `replace`: `+anchor│` and ` anchor│` rows in a post-edit diff are fresh anchors — you can use them for the next edit without a new `read`. Do one `replace`/`insert` per turn and check the diff before the next edit.

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 via bare 3-char anchor `aB3` from `aB3│content`: `remove_from`/`remove_to` are `aB3` only, `replacement_lines` is bare lines without `│`; one edit per call

package/prompts/replace.md

@@ -1 +1 @@
-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.
+Replace a range of lines (or a single line) in a text file, targeted by 3-character anchors from read output. Saw `aB3│content` in read/diff/grep: `aB3` is the bare HASH before `│`, `aB3│content` is the full row. `remove_from` and `remove_to` are bare HASH only (e.g. `"aB3"`), never the full row or file content. `replacement_lines` is bare content without `│`, one string per line — use `[]` to delete. Example: read showed `aB3│old` and `kQm│old2`, to replace both use `{"remove_from":"aB3","remove_to":"kQm","replacement_lines":["new line 1","new line 2"]}`. Single line → same anchor for both.

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

@@ -1,3 +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.
-- `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.
+- `undo_last_change`: only the last `replace`/`insert` per file can be undone; a successful `write` clears it, so call immediately after a bad diff (look for `-anchor│` lines you wanted to keep).
+- `undo_last_change`: if the file changed after the edit you get `[E_UNDO_STALE]` — the record is kept, so undo again after the file matches the edited state; if the file was deleted it is restored.

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

@@ -1 +1 @@
-Undo the last change (replace or insert) on a file
+Undo last `replace`/`insert` on a file; restores deleted file, keeps record on `[E_UNDO_STALE]`

package/prompts/undo-last-change.md

@@ -1 +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.
+Undo the last `replace` or `insert` on a file, restoring previous content, BOM and line endings. Use after a bad edit when the diff showed wrong lines removed. If the file was deleted, it is restored; if changed elsewhere, you get `[E_UNDO_STALE]` and the record is kept so you can retry after restoring the edited state. If output says truncated, use `read` to see full file.

package/src/constants.ts

@@ -1,8 +1,10 @@
-export const AUTO_READ_MAX = 2000;
 export const SNIFF_BYTES = 8192;
 export const MAX_BYTES = 100 * 1024 * 1024;
-export const MAX_READ_LINE_BYTES = 200 * 1024;
 export const MAX_RANGE_STALE_LINES = 100;
+export const MAX_OVERSIZED_WARNING_LINES = 100;
+
+export const MAX_HASH_SOURCE_BYTES = 500;
+export const MAX_GREP_LINE_BYTES = 500;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 5;

package/src/file-kind.ts

@@ -1,6 +1,7 @@
 import { open as fsOpen, stat as fsStat } from "fs/promises";
 import { fileTypeFromBuffer } from "file-type";
 import { SNIFF_BYTES, MAX_BYTES } from "./constants";
+import { assertLineLimit, lineLimitMoreThanMessage } from "./utils";
 
 const IMG_TYPES = new Set<string>([
   "image/bmp",
@@ -141,11 +142,7 @@ export async function loadFileKindAndText(
         for (let i = 0; i < decoded.length; i++) {
           if (decoded.charCodeAt(i) === 10) newlineCount++;
         }
-        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 hashline limit. For very large files, use write.`,
-          );
-        }
+        if (newlineCount > options.maxLines) throw new Error(lineLimitMoreThanMessage(options.displayPath ?? filePath, options.maxLines));
       }
       return decoded;
     }
@@ -169,6 +166,11 @@ export async function loadFileKindAndText(
       position += chunkBytesRead;
     }
     parts.push(decodeChunk(new Uint8Array(0), false));
+    const text = parts.join("");
+    if (options?.maxLines !== undefined && text.length > 0) {
+      const normalized = text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+      assertLineLimit(normalized, options.displayPath ?? filePath, options.maxLines);
+    }
 
     if (containsNul) {
       return { kind: "binary", description: "contains NUL bytes" };
@@ -176,7 +178,7 @@ export async function loadFileKindAndText(
 
     return {
       kind: "text",
-      text: parts.join(""),
+      text,
       ...(hadUtf8DecodeErrors ? { hadUtf8DecodeErrors: true as const } : {}),
     };
   } finally {

package/src/file-reader.ts

@@ -1,13 +1,13 @@
 import { constants } from "fs";
 import { stat } from "fs/promises";
+import { relative } from "path";
 import { lineHashes } from "./hashline";
 import { loadFileKindAndText, type LFile } from "./file-kind";
 import { resolveTarget } from "./fs-write";
 import { toCwd } from "./paths";
 import { detectEnding, toLF, stripBOM, type LineEnding } from "./replace-diff";
-import { abortIf } from "./utils";
+import { abortIf, errCode, assertLineLimit } from "./utils";
 import { valKind, valAccess } from "./validation";
-import { visLines } from "./utils";
 import type { HashStore } from "./hash-store";
 export interface NormFile {
   absolutePath: string;
@@ -52,7 +52,7 @@ export async function safeSnapId(
   try {
     return (await fileSnap(absolutePath)).snapshotId;
   } catch (error) {
-    console.error(`Failed to compute snapshot (${context}):`, error);
+    console.error(`[safeSnapId] ${context}: failed to stat "${absolutePath}" (code=${errCode(error) ?? "?"}):`, error);
     return undefined;
   }
 }
@@ -91,14 +91,7 @@ export async function readNormFile(
   const originalEnding = detectEnding(rawContent);
   const normalized = toLF(rawContent);
 
-  if (options?.maxLines !== undefined) {
-    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 hashline limit. For very large files, use write.`,
-      );
-    }
-  }
+  if (options?.maxLines !== undefined) assertLineLimit(normalized, path, options.maxLines);
 
   const fileHashes = await lineHashes(normalized, resolvedPath, undefined, options?.store, options?.noPersist !== true);
   return {
@@ -110,3 +103,24 @@ export async function readNormFile(
     hadUtf8DecodeErrors: file.hadUtf8DecodeErrors === true,
   };
 }
+
+export async function tryReadNormFile(
+  absPath: string,
+  cwd: string,
+  options?: ReadNormOptions,
+): Promise<NormFile | undefined> {
+  try {
+    const displayPath = relative(cwd, absPath).replace(/\\/g, "/") || absPath;
+    const file = await loadFileKindAndText(absPath, { maxLines: options?.maxLines, displayPath });
+    if (file.kind !== "text") return undefined;
+    return await readNormFile(absPath, cwd, { ...options, preloadedFile: file });
+  } catch (error) {
+    const code = errCode(error);
+    if (code === "EACCES" || code === "EPERM" || code === "ENOENT" || code === "ELOOP") return undefined;
+    if (error instanceof Error) {
+      const msg = error.message;
+      if (msg.startsWith("[E_FILE_TOO_LARGE]") || msg.startsWith("[E_NOT_FOUND]") || msg.startsWith("[E_ACCESS]") || msg.startsWith("[E_NOT_TEXT]")) return undefined;
+    }
+    throw error;
+  }
+}