pi-hashline-edit-pro 5.0.0 → 5.1.0

package/README.md

@@ -188,7 +188,7 @@ Edge cases:
 | --- | --- |
 | `remove_from` | 4-char anchor marking the FIRST line to remove (inclusive). |
 | `remove_to` | 4-char anchor marking the LAST line to remove (inclusive). |
-| `replacement_lines` | The exact text to write in place of the removed range, as one string: `""` deletes the range, `"\n"` is one blank line, and a trailing line break sets the last line's ending instead of adding a blank line. Embedded `\r\n`/`\r`/`\n` are preserved; escapes decode once — `\uXXXX` is the character, `\\uXXXX` the literal text. Legacy arrays are converted to text (elements joined with LF); prefer the string form. |
+| `replacement_lines` | The exact text to write in place of the removed range, as one string: `""` deletes the range, `"\n"` is one blank line, and a trailing line break sets the last line's ending instead of adding a blank line. Embedded `\r\n`/`\r`/`\n` are preserved; JSON decoding happens once, before the tool; the tool writes the string it receives and never decodes — `\uXXXX` is the character, `\\uXXXX` the literal text. Legacy arrays are converted to text (elements joined with LF); prefer the string form. |
 
 Example: read showed `Hasu│old` and `arvm│old2`; to replace both:
 
@@ -201,6 +201,7 @@ Example: read showed `Hasu│old` and `arvm│old2`; to replace both:
 ```
 
 Single line: use the same anchor for `remove_from` and `remove_to`. `replace_from`/`replace_to` and `from`/`to` work as aliases.
+A deletion keeps blank lines at the edges of the removed range, so the separators around a block survive the edit; target a blank line on its own to delete it.
 
 The extension checks the request before any file I/O, so a bad request never touches the file.
 
@@ -208,7 +209,7 @@ Auto-fixable slips fall into two groups. Fixed silently: a reversed range, embed
 
 Content containing a NUL byte (`U+0000`) is rejected with `[E_BAD_SHAPE]` before any file I/O: writing it would make the file binary, so use an empty replacement to delete. This applies to `replace`'s `replacement_lines` and `insert`'s `lines`.
 
-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, `anchor_grep` output, the auto-read block after `write`, the `+anchor│` and ` anchor│` rows of post-edit diffs, the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale-anchor feedback) and verifies the whole range against that record before writing. A line that changed on disk since it was shown, or an anchor that is not owned in this session, refuses the edit with `[E_RANGE_STALE]` or `[E_STALE_ANCHOR]` and returns the current range with fresh anchors, so the retry needs no `read`. An owned anchor enters the served record when its row is shown (after a restart, restored ownership counts as shown), so a file with no owned anchors cannot be edited by anchor at all; call `read` first. An owned line that was never shown, for example beyond an auto-read preview's truncation cap, is refused with `[E_RANGE_STALE]` and returns the current range, so the retry still needs no `read`.
+Every line in the removed range must match what was last shown to you, except that a pure deletion (an empty replacement) verifies only the first and last line of the range and removes the interior as it currently stands. The extension records the `anchor│content` rows it serves (`read` output, `anchor_grep` output, the auto-read block after `write`, the `+anchor│` and ` anchor│` rows of post-edit diffs, the current-range rows of `[E_RANGE_STALE]` feedback, and the context rows of stale-anchor feedback) and verifies the whole range against that record before writing. A line that changed on disk since it was shown, or an anchor that is not owned in this session, refuses the edit with `[E_RANGE_STALE]` or `[E_STALE_ANCHOR]` and returns the current range with fresh anchors, so the retry needs no `read`. An owned anchor enters the served record when its row is shown (after a restart, restored ownership counts as shown), so a file with no owned anchors cannot be edited by anchor at all; call `read` first. An owned line that was never shown, for example beyond an auto-read preview's truncation cap, is refused with `[E_RANGE_STALE]` and returns the current range, so the retry still needs no `read`; only lines strictly between the boundaries of a pure deletion are exempt.
 
 An edit that changes neither content nor line endings reports `No changes made` and leaves the anchors alone.
 
@@ -230,9 +231,9 @@ A `replace_within` call is never grouped into a batch; it commits on its own lik
 | --- | --- |
 | `anchor` | 4-char anchor marking the line next to which the lines go. The anchor line is preserved. A pasted `+Hasu│x` diff row or `anchor│` prefix is stripped automatically with a warning. |
 | `direction` | `"after"` inserts below the anchor line, `"before"` above it. |
-| `lines` | The exact text to insert, as one string: `""` inserts nothing, `"\n"` is one blank line, and a trailing line break sets the last line's ending instead of adding a blank line. Never include the anchor line. Embedded `\r\n`/`\r`/`\n` are preserved; escapes decode once — `\uXXXX` is the character, `\\uXXXX` the literal text. Legacy arrays are converted to text (elements joined with LF); prefer the string form. |
+| `lines` | The exact text to insert, as one string: `""` inserts one blank line (the same as `"\n"`), and a trailing line break sets the last line's ending instead of adding a blank line. Never include the anchor line. Embedded `\r\n`/`\r`/`\n` are preserved; JSON decoding happens once, before the tool; the tool writes the string it receives and never decodes — `\uXXXX` is the character, `\\uXXXX` the literal text. Legacy arrays are converted to text (elements joined with LF); prefer the string form. |
 
-Nothing is removed and the inserted lines are written exactly as given; the anchor line and every other line stay in place. Inserting nothing (`lines: ""`) reports a noop. To seed an empty file, read it and insert after the `anchor│` empty-line row.
+Nothing is removed and the inserted lines are written exactly as given; the anchor line and every other line stay in place. An empty `lines` payload inserts one blank line. To seed an empty file, read it and insert after the `anchor│` empty-line row.
 
 Example: add a line after `Emno│`:
 
@@ -244,7 +245,7 @@ The same safety machinery as `replace` applies: undo is saved before the write (
 
 ### copy
 
-`copy` duplicates a range of lines to another position without removing the source. `source_from` and `source_to` select lines in the source file; `insert_after` selects the destination line, and it may live in a different file. An empty destination file is seeded with the copied lines. It is a served-anchor edit like `replace` and `insert`: the source lines and the destination anchor line must come from rows you were shown, and the request is refused if they changed on disk or were never served. With `requirePath` on, `path` must match the source or the destination file.
+`copy` duplicates a range of lines to another position without removing the source. `source_from` and `source_to` select lines in the source file; `insert_after` selects the destination line, and it may live in a different file. An empty destination file is seeded with the copied lines. It is a served-anchor edit like `replace` and `insert`: the source's first and last lines and the destination anchor line must come from rows you were shown, and the request is refused if they changed on disk or were never served; the interior of the range is transferred verbatim and does not need to have been shown. With `requirePath` on, `path` must match the source or the destination file.
 
 | Field | Description |
 | --- | --- |
@@ -308,8 +309,8 @@ Multiple `replace` and `insert` calls on the same file in one assistant message
 
 - A call outside a batch commits before its result returns.
 - A `copy`, `move`, or `replace_within` call is never grouped into a batch: it commits on its own, and a pending same-file batch aborts safely with `[E_OP_ABORTED]` if the file changed under it.
-- A batch validates every call against the pre-batch state and commits once, during the batch's last call: earlier calls reply `In batch N`, and the batch's last call shows the combined diff, with one undo reverting the whole batch.
-- If a batch aborts, an earlier member's row renders the abort message instead of the placeholder. Nothing commits until the last call succeeds.
+- A batch validates every call against the pre-batch state and commits once, during the batch's last call: earlier calls reply `In batch N (queued)`, and the batch's last call shows the combined diff, with one undo reverting the whole batch.
+- If a batch aborts, nothing is written: the failing call's error ends with `Aborts batch N.` and reports that the whole batch was discarded, and an earlier member's row renders the abort message instead of the queued placeholder. Nothing commits until the last call succeeds.
 - A batch member accepts the same request shapes and auto-fixes as a standalone call.
 
 Batched calls must target disjoint ranges; overlapping ranges, or any failing call, aborts the whole batch unwritten. One `insert` with `direction: "before"` and one with `direction: "after"` may target the same anchor line: the pair composes into a single insertion. A batch member that fails aborts its batch-mates with `[E_OP_ABORTED]`.
@@ -322,7 +323,7 @@ The hashline tools are sequential in pi, so a message that contains one runs all
 
 Auto-read is enabled by default. After a successful `write`, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block, so you get fresh `anchor│content` anchors without a separate `read` call.
 
-After `replace`, `replace_within`, `insert`, `copy`, `move`, and `undo_last_change`, the result shows the post-edit diff. Inside a same-message batch, only the batch's last call shows the combined diff, headed by a `batch N:` line; earlier calls reply `In batch N`. 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, which are stale after the edit. When the context line next to 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.
+After `replace`, `replace_within`, `insert`, `copy`, `move`, and `undo_last_change`, the result shows the post-edit diff. Inside a same-message batch, only the batch's last call shows the combined diff, headed by a `batch N:` line; earlier calls reply `In batch N (queued)`. 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, which are stale after the edit. When the context line next to 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.
 
 An edit that changes only line endings has no content diff; the result still reports `applied`, and one `undo_last_change` reverts it.
 
@@ -419,7 +420,7 @@ Codes starting with `E_` are errors: nothing was written, with one exception. `F
 Most common, with the fix:
 
 - `[E_STALE_ANCHOR]`: the anchor is not owned in this session. Call `read` for fresh anchors and retry.
-- `[E_RANGE_STALE]`: a line in the replaced range changed on disk or was never shown. The error already returns the current range with fresh anchors; retry with those.
+- `[E_RANGE_STALE]`: a line in the replaced range changed on disk or was never shown (a pure deletion checks only its first and last line). The error already returns the current range with fresh anchors; retry with those.
 - `[E_FILE_TOO_LARGE]`: the file exceeds the 1,353,139-line hashline limit or the 100MB size limit. Use `write` for very large files.
 - `[E_STORE_UNAVAILABLE]`: no SQLite runtime. Run pi under Node 22.19+ or a Bun build that ships `bun:sqlite`.
 - `[E_WRITE_HASH_ECHO]`: a `write` content line contains a copied served row. Remove the anchors and retry.
@@ -440,15 +441,20 @@ Full reference:
 | `[W_INVALID_PATCH]` | A `replacement_lines` line is a diff-preview row (`+anchor│`, `-anchor│`, `-    │`). The marker is stripped automatically with a warning. |
 | `[W_BARE_HASH_PREFIX]` | A `replacement_lines` line starts with an `anchor│` prefix. The prefix is stripped automatically with a warning. |
 | `[W_ANCHOR_RECLAIMED]` | The session's anchor quota was exhausted, so all anchors of the listed files (the least recently read or edited) were freed to make room. Read those files again before editing them. |
-| `[H_LITERAL_ESCAPE]` | `lines` or `replacement_lines` contains literal escaped text such as `\uXXXX` or `\n`; the file receives those backslash characters as written. Escapes decode once in the tool call (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally — resend with the real character if that was not intended. |
-| `[H_UNICODE_LOST]` | The removed line contained an invisible or look-alike character (for example `U+200B` zero-width space, `U+00A0` no-break space, or a smart quote) that the replacement does not. The edit applied as sent; copy the character from the served row if the request did not ask to remove it. |
+| `[H_LITERAL_ESCAPE]` | A payload field contains literal escaped text such as `\uXXXX`, `\n`, `\t`, `\r`, or `\"` (one hint per distinct escape, up to three). The file receives those backslash characters as written, because JSON decoding happens once, before the tool call (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally. The hint is one line: `lines: "\u200b" written as literal text (Kq3f│ col 31); resend with U+200B if unintended.` names the field, the escape, and up to three affected anchors with their columns, then the fix; when more than three rows carry it, it gives `on 10 rows; undo_last_change + resend with U+200B if unintended.` instead of the anchor list. |
+| `[H_UNICODE_LOST]` | The new text is missing an invisible or look-alike character (for example `U+200B`, `U+2060`, `U+00A0`, or a smart quote) that a replaced row has, or that a context row sharing a long run with an inserted line has. The edit applied as sent; the one-line hint names the character, its column, and the reference anchor, for example `[H_UNICODE_LOST] U+2060 missing at col 31; Kq3f│ has it; resend with U+2060 if unintended.` When another look-alike character (including `U+FFFD`) takes its place, the hint reports the substitute with `[H_UNICODE_SWAPPED]` wording. |
+| `[H_UNICODE_SWAPPED]` | The new text uses a different invisible or look-alike character than the line it matches (for example `U+200D` where that line has `U+200B`, or an ASCII stand-in such as `.` for `。` or a space for `U+00A0`). The edit applied as sent; the one-line hint names both code points, the column, and the reference anchor, for example `[H_UNICODE_SWAPPED] U+200D at col 21 where Kq3f│ has U+200B; resend with U+200B if unintended.` The substitute may also be `U+FFFD`, for example where a row has `U+00A0`. |
+| `[H_TRAILING_WHITESPACE]` | The new text differs from the replaced line only in trailing whitespace. Anchor checksums trim trailing whitespace, so the change does not invalidate the anchor; the one-line hint names the old and new trailing-whitespace counts and the column, for example `[H_TRAILING_WHITESPACE] 1 trailing whitespace character at col 7; Kq3f│ had 0.` |
+| `[H_INDENT_MISMATCH]` | The new line has fewer leading whitespace characters than a structurally similar row (a reference row near the anchor line for an insert, or the replaced line). The edit applied as sent; the one-line hint names both counts and the reference anchor, for example `[H_INDENT_MISMATCH] new line has 0 leading whitespace characters; Kq3f│ has 2.` Copied or moved blocks are not checked, because their indentation comes from the source lines. |
+| `[H_SEPARATOR_MOVED]` | An insert landed its text directly against the anchor line, and the blank line that separated the anchor from its neighbor was displaced to the other side of the inserted text. The edit applied as sent; the one-line hint names the anchor and which side lost the blank line, for example `[H_SEPARATOR_MOVED] blank separator above Kq3f│ was displaced; add a blank line before Kq3f│ if unintended.` |
+| `[H_SEPARATOR_LOST]` | A pure deletion removed a run of blank lines that sat between two content lines. The edit applied as sent; the one-line hint names the two surviving anchors and the removed count, for example `[H_SEPARATOR_LOST] deletion removed 2 blank lines between Aaaa│ and Dddd│.` |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. A cross-file `move` may empty its source file. |
 | `[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_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_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; a pure deletion checks only its first and last line). The edit was refused; the current range is returned with fresh anchors. |
 | `[E_FILE_TOO_LARGE]` | The file exceeds the 1,353,139-line hashline limit or the 100MB size limit. |
 | `[E_REGISTRY]` | The anchor registry was not initialized; a serve or edit ran outside an initialized session. |
 | `[E_STORE_UNAVAILABLE]` | No SQLite runtime could be loaded: the host exposes neither `node:sqlite` (Node 22.19+) nor `bun:sqlite`. The pi release binary's bundled Bun lacks `node:sqlite`; run pi under Node or a Bun build that ships SQLite. |
@@ -464,7 +470,7 @@ Full reference:
 ## Troubleshooting
 
 - Stale anchors. `[E_STALE_ANCHOR]` means an anchor is not owned in this session: it was never shown to you, or its line was edited or the file was rewritten since. Call `read` for fresh anchors and retry.
-- Range changed on disk. `[E_RANGE_STALE]` means a line inside the replaced range changed after it was last shown to you (or was never shown). Nothing was modified; the error carries the current range with fresh anchors, so retry with those without a `read`.
+- Range changed on disk. `[E_RANGE_STALE]` means a line inside the replaced range changed after it was last shown to you (or was never shown; a pure deletion only needs its first and last line shown). Nothing was modified; the error carries the current range with fresh anchors, so retry with those without a `read`.
 - Multi-conversation hosts. Anchors, served records, and ownership logs are resolved per calling session, so a tool call in one conversation is never answered by another conversation's registry; a foreign anchor fails with `[E_STALE_ANCHOR]`. Interactive previews are the one exception: pi does not pass the session into render callbacks, so when one process serves several conversations at once a preview can fall back to the most recently active session and show a stale or wrong-file diff. Previews never write files or claim anchors; run the call for the authoritative result.
 - Undo scope. `undo_last_change` records are keyed by file path, not by session, so in a multi-conversation host any conversation that names the file can revert its most recent `replace` or `insert`, even one made by another conversation. Anchor ownership remains session-scoped; only undo is shared.
 - Reset the anchor state. Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars) and in per-session ownership logs under `~/.config/pi-hashline-edit-pro/sessions/`. Quit pi, delete those files, and everything is rebuilt on the next session. Anchor history is lost, but no project files are touched.
@@ -524,13 +530,7 @@ Allocated anchors live in a persistent per-file snapshot (`~/.config/pi-hashline
 
 ## Benchmark
 
-pi-hashline-edit-pro is measured on the [Explicit Edit Benchmark](https://github.com/alexshpunt/explicit-edit-benchmark), an open third-party benchmark maintained by [alexshpunt](https://github.com/alexshpunt). The suite has 226 deterministic, byte-exact editing tasks across many edit shapes and file types. A verifier compares the result file tree byte by byte, so nothing is graded on compilation or behavioral equivalence. Many harnesses are scored on it.
-
-The current release scores 98.7% in the explorer's harness-family view for `pi-hashline-edit-pro`, with 99.6% or better final exactness on every model route.
-
-First exact means the first attempt, with no recovery round, reproduced the expected bytes exactly. Final exact is the same after the benchmark's allowed recovery rounds. Quality is `0.75 × first exact + 0.25 × final exact`, so first-attempt accuracy dominates. The family rollup is the median quality across the complete, eligible model-route configurations scored with this harness; partial and quarantined configurations stay visible in the dataset but do not enter the median.
-
-Per-model and per-version numbers, plus the spread behind the headline value, are in the [benchmark explorer](https://huggingface.co/spaces/alexshpunt/benchmark-explorer?card=harness%3Api-hashline-edit-pro%40latest); raw observations and scoring rules are in the [dataset](https://huggingface.co/datasets/alexshpunt/explicit-edit-benchmark) and the [methodology](https://github.com/alexshpunt/explicit-edit-benchmark/blob/main/docs/methodology.md). Treat the score as one measurement of this suite at one point in time.
+pi-hashline-edit-pro is scored on the [Explicit Edit Benchmark](https://github.com/alexshpunt/explicit-edit-benchmark), an open third-party suite of 226 deterministic, byte-exact editing tasks. Per-model results and the scoring rules are in the [benchmark explorer](https://huggingface.co/spaces/alexshpunt/benchmark-explorer?card=harness%3Api-hashline-edit-pro%40latest) and the [dataset](https://huggingface.co/datasets/alexshpunt/explicit-edit-benchmark).
 
 ## Development
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "5.0.0",
+  "version": "5.1.0",
   "type": "module",
   "description": "Hash-anchored read/replace/insert/grep tools for pi-coding-agent. Every line gets a unique 4-char tokenizer-friendly anchor that stays stable across edits; stale or ambiguous anchors are rejected, never fuzzy-matched. Undo persists across restarts.",
   "main": "index.ts",

package/prompts/copy-guidelines.md

@@ -1 +1,2 @@
 - `copy`: the same anchor in `source_from` and `source_to` copies one line; copied lines get fresh anchors in the post-edit diff and the source rows keep theirs.
+- `copy`: for a block copy, this tool is the cheap path: only the source's two boundary rows and the destination line need serving, the interior transfers verbatim, and the block lands in one commit. Rebuilding the file with shell commands costs range verification, the post-edit diff, and undo; to append at the end, use the destination's last served line as `insert_after`.

package/prompts/insert-guidelines.md

@@ -1 +1 @@
-- `insert`: after inserting a quoted payload, check the post-edit diff for an extra `+anchor│` blank row before the next line.
+- `insert`: compare both edges of the inserted block in the post-edit diff against the request; a missing or extra `+anchor│` blank row at either boundary is the classic insert slip.

package/prompts/insert.md

@@ -1,3 +1,3 @@
-Insert text after or before one existing line in a text file, addressed by a bare anchor from any served anchor│content row. The anchor line is preserved: `lines` go after it with `direction: "after"` or before it with `direction: "before"`. `lines` is one string holding the exact text to insert; escapes decode once — `\uXXXX` is the character, `\\uXXXX` the literal text.
+Insert text after or before one existing line in a text file, addressed by a bare anchor from any served anchor│content row. The anchor line is preserved: `lines` go after it with `direction: "after"` or before it with `direction: "before"`. `lines` is one string holding the exact text to insert (an empty string inserts one blank line); JSON decoding happens once, before the tool; the tool writes the string it receives and never decodes — `\uXXXX` is the character, `\\uXXXX` the literal text. A trailing line break sets the last line's ending instead of adding a blank line, so a blank line next to the anchor line must be an extra break in `lines`: `"x\n"` leaves the anchor line directly after `x`, and `"x\n\n"` leaves one blank line between them (`direction: "after"` mirrors this at the start of `lines`).
 
-Same-file calls in one message batch: earlier calls reply `In batch N` and the last call shows the combined diff, with one undo for the whole batch.
+Same-file calls in one message batch: earlier calls reply `In batch N (queued)` and the last call shows the combined diff, with one undo for the whole batch.

package/prompts/move-guidelines.md

@@ -1 +1,2 @@
 - `move`: a cross-file move records one undo entry per file — undo both sides. Lines between source and target may be re-anchored.
+- `move`: for a block move, this tool is the cheap path: only the source's two boundary rows and the destination line need serving, the interior moves verbatim, and rebuilding the file with shell commands costs range verification, the post-edit diff, and undo; to append at the end, use the destination's last served line as `insert_after`.

package/prompts/replace-guidelines.md

@@ -1,2 +1,4 @@
 - `replace`: same-file same-message calls batch: disjoint ranges, one undo. A call whose anchors resolve nowhere fails alone.
+- `replace`: a pure deletion (`replacement_lines: ""`) is the cheap way to clear a large range: it verifies only the first and last line against the served record and removes the interior as it currently stands.
+- `replace`: to delete several blocks, `anchor_grep` serves each block's first line and a short `read` around each block serves its closing line; then one message of pure-deletion `replace` calls (`remove_from`/`remove_to` per block, `replacement_lines: ""`) removes them all as one batch.
 - `replace`: `replacement_lines` is one string; a pasted `anchor│` prefix is stripped; single line: same anchor for `remove_from` and `remove_to`.

package/prompts/replace-within-guidelines.md

@@ -1,3 +1,3 @@
 - `replace_within`: use it instead of `replace` to change part of a line, so every character the request does not name is preserved as served.
 - `replace_within`: `replace_old` must be copied exactly from the served row and occur once in the range; a missing or repeated match is refused and returns the current rows.
-- `replace_within`: a batch never groups it; it commits on its own, like `copy` and `move`.
+- `replace_within`: when the same `replace_old` occurs many times, `anchor_grep` with `literal: true` serves every matching row in one call, and one `replace_within` per row is cheap — only the named bytes change, so a wrong match costs one line, not a rewritten file.

package/prompts/replace-within.md

@@ -1,5 +1,5 @@
 Replace part of a line (or a range of lines) without retyping the rest. `replace_from` and `replace_to` are bare anchors from served `anchor│content` rows marking the first and last line of the range; use the same anchor for one line. `replace_old` is the exact text to find inside that range, copied from the served row; it must occur exactly once. `replace_new` replaces just that match, and every other character stays untouched.
 
-Example: read served `Hasu│    {"id": "checkout-5", "feature": "legacyCheckout", "retries": 3},`. Call { "replace_from": "Hasu", "replace_to": "Hasu", "replace_old": "legacyCheckout", "replace_new": "stableCheckout" }. The line becomes `    {"id": "checkout-5", "feature": "stableCheckout", "retries": 3},` and the post-edit diff carries fresh anchors.
+Example: read served `Hasu│    {"name": "widget", "size": "small"},`. Call { "replace_from": "Hasu", "replace_to": "Hasu", "replace_old": "small", "replace_new": "large" }. The line becomes `    {"name": "widget", "size": "large"},` and the post-edit diff carries fresh anchors.
 
-Both strings are exact text; escapes decode once — `\uXXXX` is the character, `\\uXXXX` the literal text. Matching uses LF line breaks and excludes the last line's terminator. A missing match is refused with the current rows, a repeated match with the matching line numbers, so the retry needs no read. Nothing but the matched text changes.
+Both strings are exact text; JSON decoding happens once, before the tool; the tool writes the string it receives and never decodes — `\uXXXX` is the character, `\\uXXXX` the literal text. Matching uses LF line breaks and excludes the last line's terminator. A missing match is refused with the current rows, a repeated match with the matching line numbers, so the retry needs no read. Nothing but the matched text changes.

package/prompts/replace.md

@@ -1,6 +1,6 @@
-Replace a range of lines (or a single line) in a text file by anchor. `remove_from` and `remove_to` are the 4-character anchors of the first and last line to remove, and `replacement_lines` is one string with the exact replacement text: `""` deletes the range, and escapes decode once — `\uXXXX` is the character, `\\uXXXX` the literal text. The text is written exactly as given, and nothing else in the file changes.
+Replace a range of lines (or a single line) in a text file by anchor. `remove_from` and `remove_to` are the 4-character anchors of the first and last line to remove, and `replacement_lines` is one string with the exact replacement text: `""` deletes the range. JSON decoding happens once, before the tool; the tool writes the string it receives and never decodes — `\uXXXX` is the character, `\\uXXXX` the literal text. The text is written exactly as given, and nothing else in the file changes. A trailing line break sets the last line's ending instead of adding a blank line: `"x\n"` leaves the next line directly after `x`, and `"x\n\n"` leaves one blank line between them.
 To change only part of a line without retyping the rest, use `replace_within` instead; it preserves every character the request does not name.
 
-Same-file calls in one message batch: earlier calls reply `In batch N` and the last call shows the combined diff, with one undo for the whole batch.
+Same-file calls in one message batch: earlier calls reply `In batch N (queued)` and the last call shows the combined diff, with one undo for the whole batch.
 
 Example: read served `Hasu│old` and `arvm│old2`. Call { "remove_from": "Hasu", "remove_to": "arvm", "replacement_lines": "new line 1\nnew line 2" }. The post-edit diff shows `-Hasu│old`, `-arvm│old2`, `+Qwer│new line 1`: the `-` rows are dead anchors now; the `+` and ` ` rows are live anchors for the next edit.

package/src/batch.ts

@@ -12,6 +12,7 @@ import {
   changedRange,
   lineHashes,
   planEdit,
+  preserveDeletionSeparators,
   MAX_HASH_LINES,
   type HEdit,
   type PlannedEdit,
@@ -121,6 +122,7 @@ type NormalizedEditArgs =
   | { kind: "insert"; anchor: string; path?: string };
 
 const MAX_TRACKED_BATCHES = 256;
+const BATCH_DISCARDED_NOTE = "Nothing was written; the whole batch was discarded.";
 
 const plan = new Map<string, PlannedMember>();
 const batches = new Map<number, BatchState>();
@@ -346,7 +348,7 @@ function batchPlaceholder(member: PlannedMember, piece: BatchPiece, snapshotId:
     content: [
       {
         type: "text",
-        text: `In batch ${member.display}`,
+        text: `In batch ${member.display} (queued)`,
       },
     ],
     details: {
@@ -364,7 +366,8 @@ function batchPlaceholder(member: PlannedMember, piece: BatchPiece, snapshotId:
 export function withAbortSuffix(message: string, display: number): string {
   const suffix = `Aborts batch ${display}.`;
   if (message.includes(suffix)) return message;
-  return message.endsWith(".") ? `${message} ${suffix}` : `${message}. ${suffix}`;
+  const ended = message.endsWith(".") ? `${message} ${suffix}` : `${message}. ${suffix}`;
+  return `${ended} ${BATCH_DISCARDED_NOTE}`;
 }
 
 const ERROR_CODE_RE = /\[(E_[A-Z0-9_]+)\]/;
@@ -393,7 +396,9 @@ function firstFailureCause(runtime: BatchState): string | undefined {
   const error = runtime.firstError;
   if (!(error instanceof Error)) return undefined;
   const suffix = ` Aborts batch ${runtime.display}.`;
-  const message = error.message.endsWith(suffix) ? error.message.slice(0, -suffix.length) : error.message;
+  const discarded = ` ${BATCH_DISCARDED_NOTE}`;
+  const withoutDiscarded = error.message.endsWith(discarded) ? error.message.slice(0, -discarded.length) : error.message;
+  const message = withoutDiscarded.endsWith(suffix) ? withoutDiscarded.slice(0, -suffix.length) : withoutDiscarded;
   const firstLine = message.split("\n")[0]?.trim() ?? "";
   if (firstLine.length === 0) return undefined;
   if (!firstLine.endsWith(":")) return firstLine;
@@ -404,10 +409,12 @@ function firstFailureCause(runtime: BatchState): string | undefined {
 function abortedBatchMessage(runtime: BatchState): string {
   const failure = runtime.failure;
   if (failure?.code !== undefined) {
-    return `[E_OP_ABORTED] Batch ${runtime.display} aborted: [${failure.kind}] Call Nr ${failure.order} errored [${failure.code}]`;
+    return `[E_OP_ABORTED] Batch ${runtime.display} aborted: [${failure.kind}] Call Nr ${failure.order} errored [${failure.code}]. ${BATCH_DISCARDED_NOTE}`;
   }
   const cause = firstFailureCause(runtime);
-  return cause ? `[E_OP_ABORTED] Batch ${runtime.display} aborted: ${cause}` : `[E_OP_ABORTED] Batch ${runtime.display} aborted.`;
+  if (cause === undefined) return `[E_OP_ABORTED] Batch ${runtime.display} aborted. ${BATCH_DISCARDED_NOTE}`;
+  const ended = cause.endsWith(".") || cause.endsWith("!") || cause.endsWith("?") ? cause : `${cause}.`;
+  return `[E_OP_ABORTED] Batch ${runtime.display} aborted: ${ended} ${BATCH_DISCARDED_NOTE}`;
 }
 
 function batchAbortedError(runtime: BatchState): Error {
@@ -482,9 +489,10 @@ export async function executeBatchMember(input: BatchMemberInput): Promise<TResu
     throw error;
   }
   const displayPath = runtime.paths?.displayPath ?? input.targetPath;
+  const effectiveHedit = preserveDeletionSeparators(input.hedit, base.baseLines, base.hashes);
   let planned: PlannedEdit;
   try {
-    planned = planEdit(base.content, input.hedit, base.hashes, {
+    planned = planEdit(base.content, effectiveHedit, base.hashes, {
       filePath: displayPath,
       servedHashes: runtime.served,
       signal: input.signal,
@@ -519,8 +527,8 @@ export async function executeBatchMember(input: BatchMemberInput): Promise<TResu
     ...(carryIndex !== undefined ? { carryIndex } : {}),
     start,
     end,
-    fromHash: input.hedit.hash_bounds[0].hash,
-    toHash: input.hedit.hash_bounds[1].hash,
+    fromHash: planned.resolved.hash_bounds[0].hash,
+    toHash: planned.resolved.hash_bounds[1].hash,
     newLines: [...newLines],
     ...(separators !== undefined ? { separators } : {}),
     warnings: [...input.extraWarnings, ...planned.warnings],

package/src/constants.ts

@@ -17,10 +17,10 @@ export const NEW_CONTENT_NOT_STRING_MSG =
   `[E_BAD_SHAPE] "replacement_lines" must be a string holding the exact text to write. Use "" to delete the range and "\\n" for one blank line; line breaks inside the string separate lines.`;
 
 export const LINES_NOT_STRING_MSG =
-  `[E_BAD_SHAPE] "lines" must be a string holding the exact text to insert. Use "" to insert nothing and "\\n" for one blank line; line breaks inside the string separate lines.`;
+  `[E_BAD_SHAPE] "lines" must be a string holding the exact text to insert. Use "\\n" for one blank line; line breaks inside the string separate lines.`;
 
 export const NUL_CONTENT_MSG =
-  `[E_BAD_SHAPE] Content contains a NUL byte (U+0000); a text file cannot contain NUL, and writing it would break further reads and edits. Remove the NUL byte and retry. An empty replacement ([]) deletes a range or inserts nothing.`;
+  `[E_BAD_SHAPE] Content contains a NUL byte (U+0000); a text file cannot contain NUL, and writing it would break further reads and edits. Remove the NUL byte and retry. An empty replacement ([]) deletes a range.`;
 
 export const ANCHOR_POOL_EXHAUSTED_PREFIX =
   "[E_FILE_TOO_LARGE] The session's anchor pool is exhausted";

package/src/copy-move.ts

@@ -158,7 +158,8 @@ export function buildTransferEdit(input: {
     );
   }
   assertRangeVerified(fileLines, preload.fileHashes, insertLine, insertLine, served, displayPath);
-  assertRangeVerified(fileLines, preload.fileHashes, sourceStart, sourceEnd, served, displayPath);
+  assertRangeVerified(fileLines, preload.fileHashes, sourceStart, sourceStart, served, displayPath);
+  assertRangeVerified(fileLines, preload.fileHashes, sourceEnd, sourceEnd, served, displayPath);
   const sourceLines = fileLines.slice(sourceStart - 1, sourceEnd);
   const sourceEndings = endingsForRange(preload.endingSeparators, sourceStart, sourceEnd);
   if (kind === "copy") {
@@ -272,7 +273,8 @@ async function prepareCrossTransfer(input: {
     throw error;
   }
   try {
-    assertRangeVerified(sourceLines, sourcePreload.fileHashes, sourceStart, sourceEnd, sourceServed, sourceDisplay);
+    assertRangeVerified(sourceLines, sourcePreload.fileHashes, sourceStart, sourceStart, sourceServed, sourceDisplay);
+    assertRangeVerified(sourceLines, sourcePreload.fileHashes, sourceEnd, sourceEnd, sourceServed, sourceDisplay);
   } catch (error) {
     await adopt(sourcePreload.absolutePath, error);
     throw error;
@@ -567,6 +569,7 @@ async function executeCrossFile(
       signal,
       preloadedNorm: prepared.sourcePreload,
       allowEmpty: true,
+      preserveDeletionSeparators: false,
     });
     return commitMovePair({
       source: { pipe: sourcePipe, displayPath: prepared.sourceDisplay, absolutePath: source.absolute, mutationTargetPath: source.resolved, foldedAnchorLines: 0 },
@@ -631,6 +634,7 @@ export async function transferPreview(kind: TransferKind, request: unknown, cwd:
       noPersist: true,
       preloadedNorm: prepared.sourcePreload,
       allowEmpty: true,
+      preserveDeletionSeparators: false,
       signal,
     });
     const destinationPreview = previewFromPipe(destinationPipe);

package/src/edit-common.ts

@@ -38,10 +38,15 @@ export async function currentEditFlags(): Promise<EditToolFlags> {
   };
 }
 
+function preferenceGuideline(flags: EditToolFlags): string {
+  const tools = gatedEditOps(["read", "replace", "replace_within", "insert", "copy", "move", "undo_last_change"], flags);
+  return `Prefer the hashline tools for anything that touches files: ${joinOps(tools, { backtick: true })}.`;
+}
+
 export function withReplacePrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   let description = base.description;
   const snippetParts = [base.snippet];
-  let guidelines = [...base.guidelines];
+  let guidelines = [preferenceGuideline(flags), ...base.guidelines];
   if (!flags.autoRead) {
     description = description.replace(/\n\nExample:[\s\S]*$/, "");
     guidelines = guidelines.filter((guideline) => !guideline.includes("post-edit diff"));
@@ -64,14 +69,15 @@ export function withReplacePrompts(base: { description: string; snippet: string;
 }
 
 export function withReadPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  const preference = preferenceGuideline(flags);
   if (flags.autoReadAllActive) {
     const rewritten = base.guidelines
       .filter((guideline) => !guideline.includes("call again after an edit"))
-    return { description: base.description, snippet: base.snippet, guidelines: [...rewritten] };
+    return { description: base.description, snippet: base.snippet, guidelines: [preference, ...rewritten] };
   }
   const withoutAutoReadAll = base.guidelines.filter((guideline) => !guideline.includes("E_AUTO_READ_ALL"))
-  if (flags.autoRead) return { description: base.description, snippet: base.snippet, guidelines: [...withoutAutoReadAll] };
-  const guidelines = [...withoutAutoReadAll];
+  if (flags.autoRead) return { description: base.description, snippet: base.snippet, guidelines: [preference, ...withoutAutoReadAll] };
+  const guidelines = [preference, ...withoutAutoReadAll];
   const mapped = guidelines.map((guideline) => guideline.startsWith("`read`: call again after an edit") ? "`read`: call again after an edit when you need anchors you lack." : guideline);
   return { description: base.description, snippet: base.snippet, guidelines: mapped };
 }
@@ -96,7 +102,7 @@ export function withInsertPrompts(base: { description: string; snippet: string;
 export function withReplaceWithinPrompts(base: { description: string; snippet: string; guidelines: string[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const descriptionParts = [base.description];
   const snippetParts = [base.snippet];
-  const guidelines = base.guidelines.map((guideline) => flags.copyMoveEnabled ? guideline : guideline.replace(", like `copy` and `move`", ""));
+  const guidelines = [...base.guidelines];
   if (flags.requirePath) {
     descriptionParts.push("Also give `path` matching the file the anchors were served for; it is required and must match anchor ownership.");
     snippetParts.push("; include `path` (required)");

package/src/edit-fidelity.ts

@@ -1,24 +1,43 @@
 import { splitLines } from "./utils";
+import { HASH_SEP, canon } from "./hashline";
 import type { DiffSpan } from "./replace-diff";
 
 const INVISIBLE_RE = /\p{Default_Ignorable_Code_Point}/u;
 const LOOKALIKE_SPACE_RE = /[\u00a0\u1680\u2000-\u200a\u202f\u205f\u3000]/u;
 const LOOKALIKE_DASH_RE = /[\u2010-\u2015\u2212]/u;
 const LOOKALIKE_QUOTE_RE = /[\u2018\u2019\u201c\u201d]/u;
-const MAX_LISTED_CHARS = 3;
-
-const CHAR_NAMES: Readonly<Record<number, string>> = {
-  0x00a0: "no-break space",
-  0x200b: "zero-width space",
-  0x200c: "zero-width non-joiner",
-  0x200d: "zero-width joiner",
-  0x200e: "left-to-right mark",
-  0x200f: "right-to-left mark",
-  0x2011: "non-breaking hyphen",
-  0x202f: "narrow no-break space",
-  0x2060: "word joiner",
-  0xfeff: "zero-width no-break space",
+const FULLWIDTH_PUNCT_RANGES: ReadonlyArray<readonly [number, number]> = [
+  [0xff01, 0xff0f],
+  [0xff1a, 0xff20],
+  [0xff3b, 0xff40],
+  [0xff5b, 0xff5e],
+];
+const IDEOGRAPHIC_PUNCT_SUBSTITUTES: Readonly<Record<string, string>> = {
+  "\u3001": ",",
+  "\u3002": ".",
+  "\uff61": ".",
+  "\uff64": ",",
 };
+const FULLWIDTH_PUNCT_SUBSTITUTES: Readonly<Record<string, string>> = Object.fromEntries(
+  FULLWIDTH_PUNCT_RANGES.flatMap(([start, end]): Array<[string, string]> =>
+    Array.from({ length: end - start + 1 }, (_, offset): [string, string] => {
+      const code = start + offset;
+      return [String.fromCodePoint(code), String.fromCodePoint(code - 0xfee0)];
+    }),
+  ),
+);
+const LOOKALIKE_PUNCT_RE = new RegExp(
+  `[${FULLWIDTH_PUNCT_RANGES.map(([start, end]) => `${String.fromCodePoint(start)}-${String.fromCodePoint(end)}`).join("")}${Object.keys(IDEOGRAPHIC_PUNCT_SUBSTITUTES).join("")}]`,
+  "u",
+);
+const MAX_FIDELITY_HINTS = 3;
+const INSERT_REFERENCE_WINDOW = 12;
+const INDENT_REFERENCE_WINDOW = 1;
+const SIMILARITY_RUN = 10;
+const ECHO_TEXT_RE = /[\p{L}\p{N}]/u;
+const INDENT_SIMILARITY_RUN = 14;
+const CALL_HEAD_RE = /^[A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*\s*\(/;
+const INSERT_GRAM_BUDGET = 200_000;
 
 const LOOKALIKE_SUBSTITUTES: Readonly<Record<string, string>> = {
   "\u00a0": " ",
@@ -48,23 +67,33 @@ const LOOKALIKE_SUBSTITUTES: Readonly<Record<string, string>> = {
   "\u2019": "'",
   "\u201c": "\"",
   "\u201d": "\"",
+  ...FULLWIDTH_PUNCT_SUBSTITUTES,
+  ...IDEOGRAPHIC_PUNCT_SUBSTITUTES,
 };
 
+const REPLACEMENT_CHAR = String.fromCodePoint(0xfffd);
 export function isFidelitySensitiveChar(char: string): boolean {
-  return INVISIBLE_RE.test(char) || LOOKALIKE_SPACE_RE.test(char) || LOOKALIKE_DASH_RE.test(char) || LOOKALIKE_QUOTE_RE.test(char);
+  return char === REPLACEMENT_CHAR || INVISIBLE_RE.test(char) || LOOKALIKE_SPACE_RE.test(char) || LOOKALIKE_DASH_RE.test(char) || LOOKALIKE_QUOTE_RE.test(char) || LOOKALIKE_PUNCT_RE.test(char);
 }
 
-function describeChar(char: string): string {
-  const codePoint = char.codePointAt(0)!;
-  const hex = `U+${codePoint.toString(16).toUpperCase().padStart(4, "0")}`;
-  const name = CHAR_NAMES[codePoint];
-  return name === undefined ? hex : `${hex} (${name})`;
+function formatCodePoint(char: string): string {
+  return `U+${char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`;
 }
 
-function unicodeLostHint(chars: string[]): string {
-  const listed = chars.slice(0, MAX_LISTED_CHARS).map(describeChar).join(", ");
-  const more = chars.length > MAX_LISTED_CHARS ? ` (+${chars.length - MAX_LISTED_CHARS} more)` : "";
-  return `[H_UNICODE_LOST] The removed line contained ${listed}${more}, which the replacement does not. If the request did not ask to remove it, copy the character from the served row.`;
+function plural(count: number, noun: string): string {
+  return `${count} ${noun}${count === 1 ? "" : "s"}`;
+}
+
+interface ReferenceRow {
+  line: string;
+  index: number;
+}
+
+function hiddenCharHint(char: string, reference: ReferenceRow, anchor: string | undefined): string {
+  const column = [...reference.line].indexOf(char) + 1;
+  const codePoint = formatCodePoint(char);
+  const referenceNote = anchor === undefined ? "" : `; ${anchor}${HASH_SEP} has it`;
+  return `[H_UNICODE_LOST] ${codePoint} missing at col ${column}${referenceNote}; resend with ${codePoint} if unintended.`;
 }
 
 function withCharsRestored(line: string, chars: readonly string[], replacementFor: (char: string) => string): string {
@@ -79,30 +108,410 @@ function isDeliberateCharFix(oldLine: string, newLine: string, lostChars: readon
   return withCharsRestored(oldLine, lostChars, () => "") === newLine;
 }
 
-export function fidelityHints(originalContent: string, resultContent: string, spans: readonly DiffSpan[] | undefined): string[] {
+interface IndexedLine {
+  line: string;
+  index: number;
+}
+
+interface SwappedChar {
+  oldChar: string;
+  newChar: string;
+  column: number;
+}
+
+interface SwapCandidate {
+  reference: ReferenceRow;
+  swapped: SwappedChar;
+}
+
+function containsSensitiveChar(line: string): boolean {
+  return line.includes(REPLACEMENT_CHAR) || INVISIBLE_RE.test(line) || LOOKALIKE_SPACE_RE.test(line) || LOOKALIKE_DASH_RE.test(line) || LOOKALIKE_QUOTE_RE.test(line) || LOOKALIKE_PUNCT_RE.test(line);
+}
+
+function normalizeSensitiveChars(line: string): string {
+  let normalized = "";
+  for (const char of line) normalized += isFidelitySensitiveChar(char) ? "?" : char;
+  return normalized;
+}
+
+function isLookalikeSwap(oldChar: string, newChar: string): boolean {
+  if (isFidelitySensitiveChar(oldChar) && isFidelitySensitiveChar(newChar)) return true;
+  return LOOKALIKE_SUBSTITUTES[newChar] === oldChar;
+}
+function sharesFidelityClass(left: string, right: string): boolean {
+  if (left === REPLACEMENT_CHAR || right === REPLACEMENT_CHAR) return isFidelitySensitiveChar(left) || isFidelitySensitiveChar(right);
+  return (
+    (INVISIBLE_RE.test(left) && INVISIBLE_RE.test(right)) ||
+    (LOOKALIKE_SPACE_RE.test(left) && LOOKALIKE_SPACE_RE.test(right)) ||
+    (LOOKALIKE_DASH_RE.test(left) && LOOKALIKE_DASH_RE.test(right)) ||
+    (LOOKALIKE_QUOTE_RE.test(left) && LOOKALIKE_QUOTE_RE.test(right)) ||
+    (LOOKALIKE_PUNCT_RE.test(left) && LOOKALIKE_PUNCT_RE.test(right)) ||
+    LOOKALIKE_SUBSTITUTES[left] === right
+  );
+}
+
+function findSubstitute(char: string, reference: ReferenceRow, payload: readonly string[]): string | undefined {
+  const referenceChars = [...reference.line];
+  const column = referenceChars.indexOf(char);
+  for (const line of payload) {
+    const candidateChars = [...line];
+    if (candidateChars.length !== referenceChars.length) continue;
+    const candidate = candidateChars[column];
+    if (candidate !== undefined && candidate !== char && sharesFidelityClass(char, candidate)) return candidate;
+  }
+  for (const line of payload) {
+    for (const candidate of line) {
+      if (candidate !== char && sharesFidelityClass(char, candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+function swappedCharPair(oldLine: string, newLine: string): SwappedChar | undefined {
+  const oldChars = [...oldLine];
+  const newChars = [...newLine];
+  if (oldChars.length !== newChars.length) return undefined;
+  let swapped: SwappedChar | undefined;
+  for (let index = 0; index < oldChars.length; index += 1) {
+    const oldChar = oldChars[index]!;
+    const newChar = newChars[index]!;
+    if (oldChar === newChar) continue;
+    if (!isLookalikeSwap(oldChar, newChar)) return undefined;
+    swapped ??= { oldChar, newChar, column: index + 1 };
+  }
+  return swapped;
+}
+
+function swappedCandidate(line: string, matches: IndexedLine[], spanStart: number, spanEnd: number): SwapCandidate | undefined {
+  const candidates: SwapCandidate[] = [];
+  for (const match of matches) {
+    if (match.line === line) continue;
+    const swapped = swappedCharPair(match.line, line);
+    if (swapped === undefined) continue;
+    candidates.push({ reference: { line: match.line, index: match.index }, swapped });
+  }
+  return candidates.find((candidate) => candidate.reference.index >= spanStart && candidate.reference.index <= spanEnd) ?? candidates[0];
+}
+
+function swappedCharHint(swapped: SwappedChar, anchor: string | undefined): string {
+  const label = anchor === undefined ? "the replaced line" : `${anchor}${HASH_SEP}`;
+  const expected = formatCodePoint(swapped.oldChar);
+  return `[H_UNICODE_SWAPPED] ${formatCodePoint(swapped.newChar)} at col ${swapped.column} where ${label} has ${expected}; resend with ${expected} if unintended.`;
+}
+
+function trailingWhitespaceHint(oldLine: string, newLine: string, anchor: string | undefined): string {
+  const oldTrail = oldLine.length - oldLine.trimEnd().length;
+  const newTrail = newLine.length - newLine.trimEnd().length;
+  const column = newLine.trimEnd().length + 1;
+  const label = anchor === undefined ? "the replaced line" : `${anchor}${HASH_SEP}`;
+  return `[H_TRAILING_WHITESPACE] ${plural(newTrail, "trailing whitespace character")} at col ${column}; ${label} had ${oldTrail}.`;
+}
+
+function leadingWhitespace(line: string): string {
+  const trimmed = line.trimStart();
+  return line.slice(0, line.length - trimmed.length);
+}
+
+function sameCallHead(payloadLine: string, referenceLine: string): boolean {
+  const left = CALL_HEAD_RE.exec(payloadLine.trimStart())?.[0];
+  const right = CALL_HEAD_RE.exec(referenceLine.trimStart())?.[0];
+  return left !== undefined && left === right;
+}
+
+function indentMismatchHint(payloadLine: string, reference: ReferenceRow, anchor: string | undefined): string | undefined {
+  const payloadIndent = leadingWhitespace(payloadLine);
+  const referenceIndent = leadingWhitespace(reference.line);
+  if (payloadIndent.length >= referenceIndent.length || !referenceIndent.startsWith(payloadIndent)) return undefined;
+  const grams = gramSet([payloadLine], INDENT_SIMILARITY_RUN);
+  const sharesLongRun = grams !== undefined && sharesRun(reference.line, grams, INDENT_SIMILARITY_RUN);
+  if (!sharesLongRun && !sameCallHead(payloadLine, reference.line)) return undefined;
+  const label = anchor === undefined ? "the nearby line" : `${anchor}${HASH_SEP}`;
+  return `[H_INDENT_MISMATCH] new line has ${plural(payloadIndent.length, "leading whitespace character")}; ${label} has ${referenceIndent.length}.`;
+}
+
+function referenceRows(lines: string[], start: number, end: number): ReferenceRow[] {
+  const from = Math.max(0, start - INSERT_REFERENCE_WINDOW);
+  const to = Math.min(lines.length - 1, end + INSERT_REFERENCE_WINDOW);
+  const rows: ReferenceRow[] = [];
+  for (let index = from; index <= to; index++) rows.push({ line: lines[index]!, index });
+  return rows;
+}
+
+function isBlankLine(line: string | undefined): boolean {
+  return (line ?? "").trim().length === 0;
+}
+
+function separatorMovedHint(
+  oldLines: string[],
+  anchorIndex: number,
+  carried: number | undefined,
+  payload: string[],
+  anchor: string | undefined,
+): string | undefined {
+  if (carried === undefined || payload.length < 2) return undefined;
+  const anchorLine = oldLines[anchorIndex] ?? "";
+  if (anchorLine.trim().length === 0) return undefined;
+  let side: "before" | "after";
+  if (carried === 0) {
+    if (anchorIndex + 1 >= oldLines.length || !isBlankLine(oldLines[anchorIndex + 1])) return undefined;
+    if ((payload[0] ?? "").trim().length === 0) return undefined;
+    side = "after";
+  } else if (carried === payload.length) {
+    if (anchorIndex === 0 || !isBlankLine(oldLines[anchorIndex - 1])) return undefined;
+    if ((payload[payload.length - 1] ?? "").trim().length === 0) return undefined;
+    side = "before";
+  } else {
+    return undefined;
+  }
+  const label = anchor === undefined ? "the anchor line" : `${anchor}${HASH_SEP}`;
+  return `[H_SEPARATOR_MOVED] blank separator ${side === "before" ? "above" : "below"} ${label} was displaced; add a blank line ${side} ${label} if unintended.`;
+}
+
+function gramSet(lines: readonly string[], size: number, requireText = false): Set<string> | undefined {
+  const grams = new Set<string>();
+  let total = 0;
+  for (const line of lines) {
+    total += line.length;
+    if (total > INSERT_GRAM_BUDGET) return undefined;
+    const chars = [...line];
+    for (let index = 0; index + size <= chars.length; index += 1) {
+      const gram = chars.slice(index, index + size).join("");
+      if (requireText && !ECHO_TEXT_RE.test(gram)) continue;
+      grams.add(gram);
+    }
+  }
+  return grams;
+}
+
+function sharesRun(line: string, grams: Set<string>, size: number): boolean {
+  const chars = [...line];
+  for (let index = 0; index + size <= chars.length; index += 1) {
+    if (grams.has(chars.slice(index, index + size).join(""))) return true;
+  }
+  return false;
+}
+
+const LITERAL_ESCAPE_HINT_PREFIX = "[H_LITERAL_ESCAPE] ";
+const LITERAL_ESCAPE_TEXT_RE = /^\[H_LITERAL_ESCAPE\] [^:]*: "(.*)" written as literal text$/;
+const MAX_LITERAL_ESCAPE_ROWS = 3;
+
+function literalEscapeColumn(line: string, escape: string): number {
+  const index = line.indexOf(escape);
+  return index < 0 ? 1 : [...line.slice(0, index)].length + 1;
+}
+
+function literalEscapeHintRows(
+  resultContent: string,
+  spans: readonly DiffSpan[],
+  resultHashes: readonly string[],
+  escape: string,
+): ReferenceRow[] {
+  const newLines = splitLines(resultContent);
+  const rows: ReferenceRow[] = [];
+  let offset = 0;
+  for (const span of [...spans].sort((a, b) => a.start - b.start)) {
+    const removedCount = span.end >= span.start ? span.end - span.start + 1 : 0;
+    const inserted = newLines.slice(span.start + offset, span.start + offset + span.replacementCount);
+    for (let index = 0; index < inserted.length; index += 1) {
+      if (span.carry === index) continue;
+      const line = inserted[index]!;
+      if (!line.includes(escape)) continue;
+      const resultIndex = span.start + offset + index;
+      if (resultIndex >= 0 && resultIndex < resultHashes.length) rows.push({ line, index: resultIndex });
+    }
+    offset += span.replacementCount - removedCount;
+  }
+  return rows;
+}
+
+function actualEscapeName(escape: string): string {
+  const hex = /^\\u([0-9a-fA-F]{4})$/.exec(escape)?.[1];
+  if (hex !== undefined) return `U+${hex.toUpperCase()}`;
+  if (escape.length === 2) {
+    if (escape[1] === "n") return "a line break";
+    if (escape[1] === "r") return "a carriage return";
+    if (escape[1] === "t") return "a tab";
+    if (escape[1] === '"') return "a double quote";
+  }
+  return "the character";
+}
+
+export function annotateLiteralEscapeHints(
+  hints: string[],
+  resultContent: string,
+  spans: readonly DiffSpan[] | undefined,
+  resultHashes: readonly string[],
+): string[] {
+  if (spans === undefined || spans.length === 0) return hints;
+  return hints.map((hint) => {
+    if (!hint.startsWith(LITERAL_ESCAPE_HINT_PREFIX)) return hint;
+    const escape = LITERAL_ESCAPE_TEXT_RE.exec(hint)?.[1];
+    if (escape === undefined || escape.length === 0) return hint;
+    const rows = literalEscapeHintRows(resultContent, spans, resultHashes, escape);
+    if (rows.length === 0) return hint;
+    if (rows.length > MAX_LITERAL_ESCAPE_ROWS) {
+      return `${hint} on ${plural(rows.length, "row")}; undo_last_change + resend with ${actualEscapeName(escape)} if unintended.`;
+    }
+    const locations = rows.map((row) => `${resultHashes[row.index]!}${HASH_SEP} col ${literalEscapeColumn(row.line, escape)}`).join(", ");
+    return `${hint} (${locations}); resend with ${actualEscapeName(escape)} if unintended.`;
+  });
+}
+
+function separatorLostHint(oldLines: string[], span: DiffSpan, originalHashes?: readonly string[]): string | undefined {
+  if (span.replacementCount !== 0 || span.end < span.start) return undefined;
+  const beforeIndex = span.start - 1;
+  const afterIndex = span.end + 1;
+  if (beforeIndex < 0 || afterIndex >= oldLines.length) return undefined;
+  for (let index = span.start; index <= span.end; index += 1) {
+    if (!isBlankLine(oldLines[index])) return undefined;
+  }
+  if (isBlankLine(oldLines[beforeIndex]) || isBlankLine(oldLines[afterIndex])) return undefined;
+  const before = originalHashes?.[beforeIndex];
+  const after = originalHashes?.[afterIndex];
+  if (before === undefined || after === undefined) return undefined;
+  return `[H_SEPARATOR_LOST] deletion removed ${plural(span.end - span.start + 1, "blank line")} between ${before}${HASH_SEP} and ${after}${HASH_SEP}.`;
+}
+
+export function fidelityHints(
+  originalContent: string,
+  resultContent: string,
+  spans: readonly DiffSpan[] | undefined,
+  originalHashes?: readonly string[],
+  options?: { separatorMoved?: boolean; indentHints?: boolean },
+): string[] {
   if (spans === undefined || spans.length === 0) return [];
   const oldLines = splitLines(originalContent);
   const newLines = splitLines(resultContent);
-  const lost = new Set<string>();
+  const hints: string[] = [];
+  const seen = new Set<string>();
+  let sensitiveIndex: Map<string, IndexedLine[]> | undefined;
+  const sensitiveLines = (): Map<string, IndexedLine[]> => {
+    if (sensitiveIndex === undefined) {
+      sensitiveIndex = new Map();
+      for (let index = 0; index < oldLines.length; index += 1) {
+        const line = oldLines[index]!;
+        if (!containsSensitiveChar(line)) continue;
+        const key = normalizeSensitiveChars(line);
+        const list = sensitiveIndex.get(key) ?? [];
+        list.push({ line, index });
+        sensitiveIndex.set(key, list);
+      }
+    }
+    return sensitiveIndex;
+  };
   let offset = 0;
   for (const span of [...spans].sort((a, b) => a.start - b.start)) {
     const removedCount = span.end >= span.start ? span.end - span.start + 1 : 0;
     const removed = removedCount > 0 ? oldLines.slice(span.start, span.end + 1) : [];
     const inserted = newLines.slice(span.start + offset, span.start + offset + span.replacementCount);
     if (removed.length > 0 && inserted.length > 0) {
-      const insertedText = inserted.join("\n");
-      const dropped: string[] = [];
-      for (const line of removed) {
-        for (const char of line) {
-          if (!dropped.includes(char) && isFidelitySensitiveChar(char) && !insertedText.includes(char)) dropped.push(char);
+      const carried = span.carry;
+      const payload = carried === undefined ? inserted : inserted.filter((_, index) => index !== carried);
+      const payloadText = payload.join("\n");
+      const references: ReferenceRow[] = carried === undefined
+        ? removed.map((line, index) => ({ line, index: span.start + index }))
+        : referenceRows(oldLines, span.start, span.end);
+      const insertGate = carried === undefined ? null : (gramSet(payload, SIMILARITY_RUN, true) ?? new Set<string>());
+      const swapKeys = new Set<string>();
+      const swaps: SwapCandidate[] = [];
+      let candidates: Map<string, IndexedLine[]> | undefined;
+      for (const line of payload) {
+        if (!containsSensitiveChar(line)) continue;
+        candidates ??= sensitiveLines();
+        const matches = [...(candidates.get(normalizeSensitiveChars(line)) ?? []), ...references];
+        const candidate = swappedCandidate(line, matches, span.start, span.end);
+        if (candidate === undefined) continue;
+        const key = `${candidate.reference.index}:${candidate.swapped.oldChar}`;
+        if (swapKeys.has(key)) continue;
+        swapKeys.add(key);
+        swaps.push(candidate);
+      }
+      const missing = new Map<string, ReferenceRow>();
+      for (const reference of references) {
+        if (insertGate !== null && !sharesRun(reference.line, insertGate, SIMILARITY_RUN)) continue;
+        for (const char of reference.line) {
+          if (missing.has(char) || !isFidelitySensitiveChar(char) || payloadText.includes(char)) continue;
+          if (swapKeys.has(`${reference.index}:${char}`)) continue;
+          missing.set(char, reference);
         }
       }
-      const deliberateFix = removed.length === 1 && inserted.length === 1 && isDeliberateCharFix(removed[0]!, inserted[0]!, dropped);
-      if (!deliberateFix) {
-        for (const char of dropped) lost.add(char);
+      if (carried === undefined && removed.length === 1 && inserted.length === 1) {
+        const chars = [...missing.keys()];
+        if (isDeliberateCharFix(removed[0]!, inserted[0]!, chars)) missing.clear();
       }
+      for (const [char, reference] of missing) {
+        if (seen.has(char) || hints.length >= MAX_FIDELITY_HINTS) continue;
+        seen.add(char);
+        const substitute = findSubstitute(char, reference, payload);
+        if (substitute !== undefined) {
+          seen.add(`swap:${reference.index}:${char}`);
+          hints.push(swappedCharHint({ oldChar: char, newChar: substitute, column: [...reference.line].indexOf(char) + 1 }, originalHashes?.[reference.index]));
+          continue;
+        }
+        hints.push(hiddenCharHint(char, reference, originalHashes?.[reference.index]));
+      }
+      for (const candidate of swaps) {
+        if (hints.length >= MAX_FIDELITY_HINTS) break;
+        const key = `swap:${candidate.reference.index}:${candidate.swapped.oldChar}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        hints.push(swappedCharHint(candidate.swapped, originalHashes?.[candidate.reference.index]));
+      }
+      const indentReferenceFor = (payloadIndex: number): ReferenceRow | undefined => {
+        if (options?.indentHints === false) return undefined;
+        if (carried !== undefined) {
+          let nearest: ReferenceRow | undefined;
+          let nearestDistance = Number.POSITIVE_INFINITY;
+          for (const candidate of references) {
+            if (candidate.index < span.start - INDENT_REFERENCE_WINDOW || candidate.index > span.end + INDENT_REFERENCE_WINDOW) continue;
+            if (indentMismatchHint(payload[payloadIndex]!, candidate, undefined) === undefined) continue;
+            const distance = Math.abs(candidate.index - span.start);
+            if (distance < nearestDistance) {
+              nearest = candidate;
+              nearestDistance = distance;
+            }
+          }
+          return nearest;
+        }
+        if (removed.length === payload.length) {
+          return { line: removed[payloadIndex]!, index: span.start + payloadIndex };
+        }
+        return undefined;
+      };
+      for (let index = 0; index < payload.length; index += 1) {
+        if (hints.length >= MAX_FIDELITY_HINTS) break;
+        const payloadLine = payload[index]!;
+        const reference = indentReferenceFor(index);
+        if (reference === undefined) continue;
+        const indentHint = indentMismatchHint(payloadLine, reference, originalHashes?.[reference.index]);
+        if (indentHint === undefined) continue;
+        const key = `indent:${reference.index}:${payloadLine}`;
+        if (seen.has(key)) continue;
+        seen.add(key);
+        hints.push(indentHint);
+      }
+      if (options?.separatorMoved) {
+        const separatorHint = separatorMovedHint(oldLines, span.start, carried, payload, originalHashes?.[span.start]);
+        if (separatorHint !== undefined && hints.length < MAX_FIDELITY_HINTS) hints.push(separatorHint);
+      }
+      if (carried === undefined && removed.length === inserted.length) {
+        for (let index = 0; index < removed.length; index += 1) {
+          if (hints.length >= MAX_FIDELITY_HINTS) break;
+          const oldLine = removed[index]!;
+          const newLine = inserted[index]!;
+          if (oldLine === newLine || canon(oldLine) !== canon(newLine)) continue;
+          const key = `trailing:${span.start + index}`;
+          if (seen.has(key)) continue;
+          seen.add(key);
+          hints.push(trailingWhitespaceHint(oldLine, newLine, originalHashes?.[span.start + index]));
+        }
+      }
+    }
+    if (removed.length > 0 && inserted.length === 0) {
+      const lost = separatorLostHint(oldLines, span, originalHashes);
+      if (lost !== undefined && hints.length < MAX_FIDELITY_HINTS) hints.push(lost);
     }
     offset += span.replacementCount - removedCount;
   }
-  return lost.size > 0 ? [unicodeLostHint([...lost].sort())] : [];
+  return hints;
 }

package/src/hashline/index.ts

@@ -38,6 +38,7 @@ export {
 	stripDiffPrefixes,
 	type StripWarningLocation,
 	swapReversedRanges,
+	preserveDeletionSeparators,
 	assertRangeServed,
 	RangeStaleError,
 	AnchorMismatchError,

package/src/hashline/resolve.ts

@@ -272,6 +272,27 @@ export function swapReversedRanges(
 	return { ...edit, hash_bounds: [endRef, startRef] as [Anchor, Anchor] };
 }
 
+export function preserveDeletionSeparators(edit: HEdit, fileLines: string[], fileHashes: string[]): HEdit {
+	if (edit.content_lines.length > 0) return edit;
+	const lineByHash = new Map<string, number>();
+	for (let index = 0; index < fileHashes.length; index++) {
+		const hash = fileHashes[index]!;
+		if (!lineByHash.has(hash)) lineByHash.set(hash, index);
+	}
+	const fromLine = lineByHash.get(edit.hash_bounds[0].hash);
+	const toLine = lineByHash.get(edit.hash_bounds[1].hash);
+	if (fromLine === undefined || toLine === undefined) return edit;
+	const rangeStart = Math.min(fromLine, toLine);
+	const rangeEnd = Math.max(fromLine, toLine);
+	const isBlank = (index: number): boolean => (fileLines[index] ?? "").trim().length === 0;
+	let start = rangeStart;
+	let end = rangeEnd;
+	while (start <= end && isBlank(start)) start += 1;
+	while (end >= start && isBlank(end)) end -= 1;
+	if (start > end || (start === rangeStart && end === rangeEnd)) return edit;
+	return { ...edit, hash_bounds: [{ hash: fileHashes[start]! }, { hash: fileHashes[end]! }] };
+}
+
 export function valEdit(
 	edit: HEdit,
 	fileLines: string[],
@@ -380,10 +401,12 @@ export function assertRangeServed(
   const startLine = resolved.hash_bounds[0].line;
   const endLine = resolved.hash_bounds[1].line;
   const mismatchLines: number[] = [];
+  const deletion = resolved.content_lines.length === 0;
   for (let line = startLine; line <= endLine; line++) {
     const hash = fileHashes[line - 1]!;
     const content = fileLines[line - 1]!;
     const servedContent = served?.get(hash);
+    if (servedContent === undefined && deletion && line !== startLine && line !== endLine) continue;
     if (servedContent === undefined || servedContent !== lineChecksum(content)) mismatchLines.push(line);
   }
   if (mismatchLines.length === 0) return;

package/src/insert.ts

@@ -11,7 +11,7 @@ import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuide } from "./prompts";
 import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
-import { isRec, literalEscapeHint, splitLines } from "./utils";
+import { isRec, literalEscapeHints, splitLines } from "./utils";
 import { queuedEdit, editToolBase, editRenderCallWrapper, editRenderResultWrapper, resolveEditTargetWithRequirement, throwIfStrictInput, withInsertPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
 import type { RPreview, RRState } from "./replace-render";
 export { assertInsertReq, type InsertReq };
@@ -27,7 +27,7 @@ const insertDirectionSchema = Type.Union(
 );
 const insertLinesSchema = Type.String({
   description:
-    'The exact text to insert. "" inserts nothing, "\\n" is one blank line, and a trailing line break sets the last line\'s ending instead of adding a blank line. Never include the anchor line.',
+    'The exact text to insert; an empty string inserts one blank line. "\\n" is one blank line, and a trailing line break sets the last line\'s ending instead of adding a blank line. Never include the anchor line.',
 });
 
 const insertPathRequiredSchema = Type.String({
@@ -70,7 +70,7 @@ export function buildInsertEdit(
   ref: Anchor,
   path: string,
 ): { editParams: HTEdit; anchorLine: string | undefined; contentSeparators: (LineEnding | undefined)[] } {
-  const parsed = parsePayloadText(req.lines);
+  const parsed = parsePayloadText(req.lines.length === 0 ? "\n" : req.lines);
   const fileLines = splitLines(preload.normalized);
   const line = resolveAnchorLine(ref, fileLines, preload.fileHashes, path);
   const anchorLine = preload.normalized.length === 0 ? undefined : fileLines[line - 1];
@@ -177,9 +177,7 @@ export function buildInsertToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): I
         const canonical = normReq(params);
         assertInsertReq(canonical);
         const req = canonical;
-        const insertWarnings: string[] = [];
-        const literalEscape = literalEscapeHint([req.lines], "lines");
-        if (literalEscape !== undefined) insertWarnings.push(literalEscape);
+        const insertWarnings: string[] = [...literalEscapeHints([req.lines], "lines")];
         const targetPath = await resolveEditTargetWithRequirement({
           anchor: req.anchor,
           providedPath: req.path,

package/src/prompts.ts

@@ -1,11 +1,22 @@
 import { readFileSync } from "node:fs";
+import { errCode } from "./utils";
 
 export function loadP(relativePath: string): string {
   return readFileSync(new URL(relativePath, import.meta.url), "utf-8").trim();
 }
 
 export function loadGuide(relativePath: string): string[] {
-  return readFileSync(new URL(relativePath, import.meta.url), "utf-8")
+  let raw: string;
+  try {
+    raw = readFileSync(new URL(relativePath, import.meta.url), "utf-8");
+  } catch (error) {
+    if (errCode(error) === "ENOENT") {
+      console.warn(`hashline: missing prompt file ${relativePath}; continuing without those guidelines`);
+      return [];
+    }
+    throw error;
+  }
+  return raw
     .split("\n")
     .map((line) => line.trim())
     .filter((line) => line.startsWith("- "))

package/src/replace-render.ts

@@ -380,7 +380,7 @@ export function renderEditResult(
 		if (abortedMessage !== undefined) {
 			return reuseText(context, `\n${highlightBatchRefs(abortedMessage, theme)}`);
 		}
-		return reuseText(context, theme.fg("warning", `In batch ${batch.id}`));
+		return reuseText(context, theme.fg("warning", `In batch ${batch.id} (queued)`));
 	}
 	if (context.isError) {
 		return renderedText

package/src/replace-response.ts

@@ -2,7 +2,7 @@ import type { NEdit } from "./hashline";
 import type { ReplaceDetails } from "./replace";
 import { genDiff, genPatch, type DiffSpan } from "./replace-diff";
 import { visLines, clipLine } from "./utils";
-import { fidelityHints } from "./edit-fidelity";
+import { annotateLiteralEscapeHints, fidelityHints } from "./edit-fidelity";
 
 export type TResult = {
 	content: Array<{ type: "text"; text: string }>;
@@ -140,9 +140,10 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
   const diffResult = genDiff(originalNormalized, result, diffContextLines, resultHashes, originalHashes, undefined, spans);
   const addedLines = editMeta.addedLines;
   const removedLines = editMeta.removedLines;
-  const fidelity = fidelityHints(originalNormalized, result, spans);
+  const fidelity = fidelityHints(originalNormalized, result, spans, originalHashes, { separatorMoved: verb === "inserted" || verb === "edited", indentHints: verb !== "copied" && verb !== "moved" });
   const { warnings: noticeWarnings, hints } = splitNotices(fidelity.length > 0 ? [...(warnings ?? []), ...fidelity] : warnings);
-  const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(hints)}`;
+  const annotatedHints = annotateLiteralEscapeHints(hints, result, spans, resultHashes);
+  const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(annotatedHints)}`;
   const successPrefix = `Successfully ${verb} in ${path}.`;
   const lineSummary = addedLines > 0 || removedLines > 0
     ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
@@ -177,7 +178,7 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
       metrics,
       diffLineNumbers: diffResult.lineNumbers.map((line) => line ?? null),
       ...(noticeWarnings.length ? { warnings: [...noticeWarnings] } : {}),
-      ...(hints.length ? { hints: [...hints] } : {}),
+      ...(annotatedHints.length ? { hints: [...annotatedHints] } : {}),
     },
   };
 }

package/src/replace-within.ts

@@ -13,7 +13,7 @@ import {
   normalizeReplaceWithinRequest,
   type ReplaceWithinReq,
 } from "./payload-contract";
-import { literalEscapeHint, splitLines } from "./utils";
+import { literalEscapeHints, splitLines } from "./utils";
 import { toLF } from "./normalize";
 import { MAX_RANGE_STALE_LINES } from "./constants";
 import {
@@ -178,10 +178,7 @@ export function buildReplaceWithinToolDef(flags: EditToolFlags = DEFAULT_EDIT_FL
         const req = normalized;
         const { refs, warnings } = parseWithinAnchors(req);
         await throwIfStrictInput(warnings);
-        const hints = [
-          literalEscapeHint([req.replace_old], "replace_old"),
-          literalEscapeHint([req.replace_new], "replace_new"),
-        ].filter((hint): hint is string => hint !== undefined);
+        const hints = [...literalEscapeHints([req.replace_old], "replace_old"), ...literalEscapeHints([req.replace_new], "replace_new")];
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: req.replace_from,
           removeTo: req.replace_to,

package/src/replace.ts

@@ -10,12 +10,13 @@ import {
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, buildEditToolSchema, type ReqParams, type RawReqParams, assertReq, normReq } from "./payload-contract";
-import { literalEscapeHint, splitLines } from "./utils";
+import { literalEscapeHints, splitLines } from "./utils";
 import { loadP, loadGuide } from "./prompts";
 import { type FileIdentity } from "./fs-write";
 import { applyEdit,
   lineHashes,
   resEdit,
+  preserveDeletionSeparators,
   MAX_HASH_LINES,
   RangeStaleError,
   AnchorMismatchError,
@@ -84,6 +85,7 @@ export interface ExecPipelineOptions {
   allowEmpty?: boolean;
   stripWarning?: StripWarningLocation;
   endingOverrides?: (LineEnding | undefined)[];
+  preserveDeletionSeparators?: boolean;
 }
 
 export function hashSpan(hashes: string[], from: string, to: string): [number, number] | undefined {
@@ -157,12 +159,15 @@ export async function execPipeline(
     targetPath, cwd, { signal: options?.signal, accessMode: options?.accessMode, maxLines: MAX_HASH_LINES, store: hashStore, noPersist: options?.noPersist, allocation: options?.noPersist ? "shadow" : "real", preloadedNorm: options?.preloadedNorm },
   );
   const displayPath = toDisplayPath(cwd, absolutePath, targetPath);
+  const effectiveEdit = options?.preserveDeletionSeparators === false
+    ? anchoredEdit
+    : preserveDeletionSeparators(anchoredEdit, splitLines(originalNormalized), originalHashes);
 
   let anchorResult: ReturnType<typeof applyEdit>;
   try {
     anchorResult = applyEdit(
       originalNormalized,
-      anchoredEdit,
+      effectiveEdit,
       options?.signal,
       originalHashes,
       displayPath,
@@ -187,10 +192,10 @@ export async function execPipeline(
   const warnings = [...editWarnings, ...(anchorResult.warnings ?? [])];
   await throwIfStrictInput(warnings);
   const { totalAddedLines, totalRemovedLines } = countLineChanges(
-    edit, originalHashes, isNoop,
+    effectiveEdit, originalHashes, isNoop,
   );
 
-  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, edit.hash_bounds[0].hash, edit.hash_bounds[1].hash, result);
+  const pipeSpan = isNoop ? undefined : spanForEdit(originalHashes, effectiveEdit.hash_bounds[0].hash, effectiveEdit.hash_bounds[1].hash, result);
   const pipeSpans = pipeSpan ? [pipeSpan] : undefined;
   return {
     path: displayPath,
@@ -210,7 +215,7 @@ export async function execPipeline(
     totalRemovedLines,
     identity,
     ...(pipeSpans ? { spans: pipeSpans } : {}),
-    ...(anchoredEdit.content_separators !== undefined ? { contentSeparators: anchoredEdit.content_separators } : {}),
+    ...(effectiveEdit.content_separators !== undefined ? { contentSeparators: effectiveEdit.content_separators } : {}),
   };
 }
 
@@ -285,7 +290,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
         const canonical = normReq(params);
         assertReq(canonical);
         const normalizedParams = canonical;
-        const literalEscape = literalEscapeHint([normalizedParams.replacement_lines], "replacement_lines");
+        const literalEscapes = literalEscapeHints([normalizedParams.replacement_lines], "replacement_lines");
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: normalizedParams.remove_from,
           removeTo: normalizedParams.remove_to,
@@ -310,7 +315,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
               absolutePath,
               mutationTargetPath,
               editAnchors: [normalizedParams.remove_from, normalizedParams.remove_to],
-              prefixWarnings: literalEscape !== undefined ? [literalEscape] : [],
+              prefixWarnings: literalEscapes,
               signal,
             });
           }
@@ -329,7 +334,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
             cwd: ctx.cwd,
             signal,
             hedit: built.edit,
-            extraWarnings: [...(literalEscape !== undefined ? [literalEscape] : []), ...built.warnings],
+            extraWarnings: [...literalEscapes, ...built.warnings],
           });
         });
       });

package/src/utils.ts

@@ -380,6 +380,7 @@ function normalizeEditLines(record: Record<string, unknown>): void {
 const LITERAL_ESCAPE_RE = /\\(?:u([0-9a-fA-F]{4})|([ntr"]))/g;
 
 const REAL_LINE_BREAK_RE = /[\n\r]/;
+const MAX_LITERAL_ESCAPE_HINTS = 3;
 
 function isSurrogateEscapePair(line: string, index: number, hex: string): boolean {
 	const code = Number.parseInt(hex, 16);
@@ -398,7 +399,9 @@ function isSurrogateEscapePair(line: string, index: number, hex: string): boolea
 	return false;
 }
 
-export function literalEscapeHint(lines: string[], label: string): string | undefined {
+export function literalEscapeHints(lines: string[], label: string): string[] {
+	const hints: string[] = [];
+	const seen = new Set<string>();
 	for (const line of lines) {
 		if (!line.includes("\\")) continue;
 		const hasRealBreak = REAL_LINE_BREAK_RE.test(line);
@@ -410,8 +413,12 @@ export function literalEscapeHint(lines: string[], label: string): string | unde
 				if (hex.toLowerCase() === "dddd") continue;
 				if (isSurrogateEscapePair(line, match.index, hex)) continue;
 			}
-			return `[H_LITERAL_ESCAPE] "${label}" contains the literal escaped text "${match[0]}"`;
+			const text = match[0];
+			if (seen.has(text)) continue;
+			seen.add(text);
+			hints.push(`[H_LITERAL_ESCAPE] ${label}: "${text}" written as literal text`);
+			if (hints.length >= MAX_LITERAL_ESCAPE_HINTS) return hints;
 		}
 	}
-	return undefined;
+	return hints;
 }