pi-hashline-edit-pro 6.4.8 → 6.5.1

package/README.md

@@ -190,8 +190,6 @@ Edge cases:
 | `remove_to` | 4-char anchor marking the LAST line to remove (inclusive). |
 | `text` | The exact text to write in place of the removed range, as one string: `""` deletes the range. A trailing line break sets the newline of the last line written instead of adding a blank line; a lone newline writes one blank line. Embedded `\r\n`/`\r`/`\n` are preserved; escapes in the tool call are decoded once when the call is parsed, and the tool then writes the string it receives as-is, never decoding again — `\uXXXX` is the character, `\\uXXXX` the literal text. Legacy arrays are converted to text (elements joined with LF); prefer the string form. |
 
-`replace_from` and `replace_to` are accepted as aliases for `remove_from` and `remove_to`.
-
 Example: read showed `Hasu│old` and `arvm│old2`; to replace both:
 
 ```json
@@ -219,15 +217,11 @@ After a successful edit, the diff is capped at 50KB. A row over 50KB is shown as
 
 ### replace_match
 
-`replace_match` changes part of a line (or a range of lines) without retyping the rest. `replace_from` and `replace_to` are bare anchors marking the first and last line of the range; use the same anchor for a single line. `old_string` is the exact text to find inside that range, and `new_string` replaces every occurrence of it; every other character stays untouched. Send `old_string` as only the fragment that changes — never include text that `new_string` leaves unchanged — and use `replace` with the same anchors when the change covers whole lines or the whole range; if `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line change. That makes it the tool for a change the request quotes as a substring: a whole-line `replace` has to reproduce the rest of the line, so a slipped character becomes a wrong byte, while `replace_match` leaves everything the request did not name untouched. It is enabled by default; turn Replace match off in `/hashline-config` to remove the tool.
-
-`remove_from` and `remove_to` are accepted as aliases for `replace_from` and `replace_to`.
-
-`old_string` is matched against the range's text (LF line breaks, no final terminator) and every non-overlapping occurrence is replaced, left to right. A missing match is refused with `[E_SUBSTRING_NOT_FOUND]` and the current `anchor│content` rows, so the retry needs no `read`. The two boundary anchors are verified against what was last shown; lines strictly inside the range are matched against the file as it currently stands on disk.
+`replace_match` changes part of a line — or the same fragment on several lines of a range — 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 searched (the same anchor for a single line). `match` is the exact text to find inside that range, and `replacement` replaces every occurrence of it; every other character stays untouched. Both stay within one line: a single trailing line break is accepted as the line's own terminator and dropped, so the file keeps its separator, while a line break anywhere else is refused with `[E_BAD_SHAPE]` (a `match` that is only that trailing line break leaves nothing to find and is refused; in `replacement` it counts as `""` and deletes the matches). Send `match` as only the fragment that changes — never include text that `replacement` leaves unchanged — and use `replace` with the same anchors when the change covers whole lines; if `match` is an entire single-line range except indentation and trailing punctuation, that is a whole-line change. The anchors bound the search, so `match` only needs to be unique inside the selected range, not file-wide. That makes it the tool for a change the request quotes as a substring: a whole-line `replace` has to reproduce the rest of the lines, so a slipped character becomes a wrong byte, while `replace_match` leaves everything the request did not name untouched. It is enabled by default; turn Replace match off in `/hashline-config` to remove the tool.
 
-`replace_match` reports `[W_REPLACE_MATCH_WHOLE_RANGE]` when `old_string` is the entire selected range, and `[W_REPLACE_MATCH_RETYPE]` when `old_string` retypes a long run of text that `new_string` leaves unchanged. Both are refused in strict-input mode with `[E_BAD_SHAPE]`.
+`match` is matched against each selected line's text (LF line breaks) and every non-overlapping occurrence is replaced, left to right — since `match` stays within one line, so does each replacement. A missing match is refused with `[E_SUBSTRING_NOT_FOUND]` and the current `anchor│content` rows, so the retry needs no `read`. The two boundary anchors are verified against what was last shown; lines strictly inside the range are searched as they currently stand on disk.
 
-In a same-message batch it joins the other calls on its file: the batch validates everything against the pre-batch state and commits once, with one undo. A missing `old_string` fails that call on its own and is left out of the batch; the rest of the batch still commits. The post-edit diff carries fresh anchors, and the edit is undoable with `undo_last_change`.
+In a same-message batch it joins the other calls on its file: the batch validates everything against the pre-batch state and commits once, with one undo. A missing `match` fails that call on its own and is left out of the batch; the rest of the batch still commits. The post-edit diff carries fresh anchors, and the edit is undoable with `undo_last_change`.
 
 ### insert
 
@@ -459,20 +453,18 @@ Full reference:
 | Code | Meaning |
 | --- | --- |
 | `[E_CONFIG]` | `PI_HASHLINE_DIR` is nonempty but not an absolute path. |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `text` must be a string holding the exact text), content contains a NUL byte (`U+0000`), which would make the file binary, or a grep `glob` has invalid bracket or brace syntax. |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (for example `text` must be a string holding the exact text), content contains a NUL byte (`U+0000`), which would make the file binary, a grep `glob` has invalid bracket or brace syntax, or a `replace_match` string spans lines: `match`/`replacement` contains a line break after the optional trailing one. |
 | `[W_BAD_SHAPE]` | Auto-corrected request slip reported as a warning (for example legacy array text that could not be parsed and was kept as one literal line). |
 | `[E_BAD_REF]` | An anchor in `remove_from`/`remove_to` is not a bare 4-character anchor (the anchor table is letters only). |
-| `[E_SUBSTRING_NOT_FOUND]` | `replace_match` did not find `old_string` in the selected range. The current `anchor│content` rows are returned, and when `old_string` looks like a retyped copy of the range the message names the first mismatching line and column; copy only the fragment that changes from the served row and retry, or use `replace` for a whole-line rewrite. |
+| `[E_SUBSTRING_NOT_FOUND]` | `replace_match` did not find `match` in the selected range. The current `anchor│content` rows are returned, and when `match` looks like a retyped copy of a single-line range the message names the first mismatching column; copy only the fragment that changes from the served row and retry, or use `replace` for a whole-line rewrite. |
 | `[W_BAD_REF]` | A pasted `anchor│` or diff-preview marker was stripped from an anchor field with a warning. |
 | `[E_STALE_ANCHOR]` | An anchor is not owned in this session (it was never shown to you, or its line was edited or the file was rewritten); call `read` for fresh anchors. |
 | `[W_INVALID_PATCH]` | A `text` line is a diff-preview row (`+anchor│`, `-anchor│`, `-    │`). The marker is stripped automatically with a warning. |
 | `[W_BARE_HASH_PREFIX]` | A `text` line starts with an `anchor│` prefix. The prefix is stripped automatically with a warning. |
-| `[W_REPLACE_MATCH_WHOLE_RANGE]` | `replace_match` `old_string` is the entire selected range. The anchors already identify it; use `replace` with the same anchors, or send only the changed fragment. Refused in strict-input mode. |
-| `[W_REPLACE_MATCH_RETYPE]` | `replace_match` `old_string` retypes a long run of text that `new_string` leaves unchanged. Send only the fragment that changes; refused in strict-input mode. |
 | `[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]` | 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 escapes in the tool call are decoded once when the call is parsed (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally. The hint is one line: `text: "\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_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 escapes in the tool call are decoded once when the call is parsed (`\uXXXX` → the character), so a doubled escape (`\\uXXXX`) lands literally. The hint is one line: `text: "\u200b" written as literal text (Kq3f│ col 31).` names the field, the escape, and up to three affected anchors with their columns; when more than three rows carry it, it gives `on 10 rows; undo_last_change 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 live anchor of the offending result row, when one can be identified, and the character as its JSON escape, for example `[H_UNICODE_LOST] Zbbb│ missing "\u2060"; Kq3f│ has it at col 31.` The column is attributed to the row that had the character: `; Kq3f│ has it at col N` while that row's anchor is still valid, otherwise `; the replaced row had it at col N`, and a dead anchor is never named. 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 the live anchor of the offending result row with both characters as JSON escapes, for example `[H_UNICODE_SWAPPED] Zbbb│ has "\u200d" at col 21; expected "\u200b".` A surviving reference row appears as `; Kq3f│ has "\u200b"`; a replaced row's dead anchor is never named. 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.` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "6.4.8",
+  "version": "6.5.1",
   "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/src/edit-common.ts

@@ -80,7 +80,6 @@ const UNDO_WRITE_CLEARS_ID = "undo-write-clears";
 const UNDO_CROSS_FILE_MOVE_ID = "undo-cross-file-move";
 const NEUTRAL_READ_REREAD = "`read`: call again after an edit when you need anchors you lack.";
 const NEUTRAL_UNDO_WRITE_CLEARS = "`undo_last_change`: only the last `replace`/`replace_match`/`insert`/`copy`/`move` per file is undoable; a `write` clears it, so undo before any other edit or write.";
-const GREP_OPS_PHRASE = "replace, insert, copy, or move";
 const UNDO_OPS_PHRASE = "replace, replace_match, insert, copy, or move";
 const UNDO_GUIDELINE_OPS_PHRASE = "`replace`/`replace_match`/`insert`/`copy`/`move`";
 
@@ -92,12 +91,12 @@ function batchGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_EDIT_OPS, flags);
   const outcome = flags.autoRead ? "diff" : "result";
   const script = flags.codemode ? ` ${SCRIPT_BATCH_GUIDELINE}` : "";
-  return `${tools}: same-file calls in one message commit as one batch; earlier calls reply \`In batch N (queued)\`, the last shows the combined ${outcome}, and one undo reverts all. A request-invalid call (anchors, shape, or \`old_string\`) fails alone; a failure while the batch runs aborts it.${script}`;
+  return `${tools}: same-file calls in one message commit as one batch. If you already know all the edits and their anchors, send them together instead of one turn at a time; an edit that needs anchors from a previous result waits for the next turn. Earlier calls reply \`In batch N (queued)\`, the last shows the combined ${outcome}, and one undo reverts all. A request-invalid call (anchors, shape, or \`match\`) fails alone; a failure while the batch runs aborts it.${script}`;
 }
 
 function diffGuideline(flags: EditToolFlags): string {
   const tools = operationNames(SHARED_DIFF_OPS, flags);
-  return `${tools}: in the post-edit diff, \`-anchor│\` rows are dead anchors; \`+anchor│\` and \` anchor│\` rows carry live anchors for the next edit.`;
+  return `${tools}: in the post-edit diff, \`-anchor│\` rows are dead anchors; \`+anchor│\` and \` anchor│\` rows carry live anchors for the next edit. Rows the diff does not show keep their anchors, so a follow-up edit on them needs no re-read.`;
 }
 
 function pathGuideline(flags: EditToolFlags): string {
@@ -157,10 +156,8 @@ export function withInsertPrompts(base: { description: string; snippet: string;
   return { description: base.description, snippet: base.snippet, guidelines: base.guidelines.map((guideline) => guideline.text) };
 }
 
-export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
-  const guidelines = base.guidelines.map((guideline) => guideline.text);
-  if (flags.strictInput) guidelines.push("`replace_match`: strict-input mode rejects an `old_string` that covers the whole range or retypes unchanged text.");
-  return { description: base.description, snippet: base.snippet, guidelines };
+export function withReplaceMatchPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, _flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
+  return { description: base.description, snippet: base.snippet, guidelines: base.guidelines.map((guideline) => guideline.text) };
 }
 
 function gatedEditOps(ops: string[], flags: EditToolFlags): string[] {
@@ -183,9 +180,7 @@ function joinOps(ops: string[], options?: { backtick?: boolean; separator?: "/"
 export function withGrepPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
   const guidelines = base.guidelines.map((guideline) => guideline.text);
   if (flags.codemode) guidelines.push(GREP_SCRIPT_GUIDELINE);
-  if (flags.copyMoveEnabled) return { description: base.description, snippet: base.snippet, guidelines };
-  const description = base.description.replaceAll(GREP_OPS_PHRASE, joinOps(gatedEditOps(["replace", "insert", "copy", "move"], flags)));
-  return { description, snippet: base.snippet, guidelines };
+  return { description: base.description, snippet: base.snippet, guidelines };
 }
 
 export function withUndoPrompts(base: { description: string; snippet: string; guidelines: Guideline[] }, flags: EditToolFlags): { description: string; snippet: string; guidelines: string[] } {
@@ -299,7 +294,7 @@ export async function resolveEditTargetWithRequirement(input: PathRequirementInp
   return anchorTarget;
 }
 
-const STRICT_INPUT_REJECT_CODES = ["[W_BAD_SHAPE]", "[W_BAD_REF]", "[W_INVALID_PATCH]", "[W_BARE_HASH_PREFIX]", "[W_REPLACE_MATCH_WHOLE_RANGE]", "[W_REPLACE_MATCH_RETYPE]"];
+const STRICT_INPUT_REJECT_CODES = ["[W_BAD_SHAPE]", "[W_BAD_REF]", "[W_INVALID_PATCH]", "[W_BARE_HASH_PREFIX]"];
 export async function throwIfStrictInput(warnings: string[]): Promise<void> {
   const fixes = warnings.filter((warning) => STRICT_INPUT_REJECT_CODES.some((code) => warning.startsWith(code)));
   if (fixes.length === 0) return;

package/src/edit-fidelity.ts

@@ -76,8 +76,12 @@ export function isFidelitySensitiveChar(char: string): boolean {
   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 formatCodePoint(char: string): string {
-  return `U+${char.codePointAt(0)!.toString(16).toUpperCase().padStart(4, "0")}`;
+export function formatCharEscape(char: string): string {
+  const codePoint = char.codePointAt(0);
+  if (codePoint === undefined) return "";
+  if (codePoint <= 0xffff) return `\\u${codePoint.toString(16).padStart(4, "0")}`;
+  const pair = codePoint - 0x10000;
+  return `\\u${(0xd800 + (pair >> 10)).toString(16).padStart(4, "0")}\\u${(0xdc00 + (pair & 0x3ff)).toString(16).padStart(4, "0")}`;
 }
 
 function plural(count: number, noun: string): string {
@@ -89,11 +93,16 @@ interface ReferenceRow {
   index: number;
 }
 
-function hiddenCharHint(char: string, reference: ReferenceRow, anchor: string | undefined): string {
+function hiddenCharHint(char: string, reference: ReferenceRow, liveAnchor: string | undefined, referenceAnchor: 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.`;
+  const escape = formatCharEscape(char);
+  const located = referenceAnchor === undefined
+    ? `the replaced row had it at col ${column}`
+    : `${referenceAnchor}${HASH_SEP} has it at col ${column}`;
+  if (liveAnchor === undefined) {
+    return `[H_UNICODE_LOST] "${escape}" missing; ${located}.`;
+  }
+  return `[H_UNICODE_LOST] ${liveAnchor}${HASH_SEP} missing "${escape}"; ${located}.`;
 }
 
 function withCharsRestored(line: string, chars: readonly string[], replacementFor: (char: string) => string): string {
@@ -122,6 +131,7 @@ interface SwappedChar {
 interface SwapCandidate {
   reference: ReferenceRow;
   swapped: SwappedChar;
+  liveAnchor?: string;
 }
 
 function containsSensitiveChar(line: string): boolean {
@@ -134,6 +144,14 @@ function normalizeSensitiveChars(line: string): string {
   return normalized;
 }
 
+function sensitiveStripped(line: string): string {
+  let visible = "";
+  for (const char of line) {
+    if (!isFidelitySensitiveChar(char)) visible += char;
+  }
+  return visible;
+}
+
 function isLookalikeSwap(oldChar: string, newChar: string): boolean {
   if (isFidelitySensitiveChar(oldChar) && isFidelitySensitiveChar(newChar)) return true;
   return LOOKALIKE_SUBSTITUTES[newChar] === oldChar;
@@ -150,21 +168,46 @@ function sharesFidelityClass(left: string, right: string): boolean {
   );
 }
 
-function findSubstitute(char: string, reference: ReferenceRow, payload: readonly string[]): string | undefined {
+interface SubstituteMatch {
+  value: string;
+  payloadIndex: number;
+  column: number;
+}
+
+interface SubstituteRank {
+  echo: boolean;
+  aligned: boolean;
+  distance: number;
+}
+
+function preferSubstitute(candidate: SubstituteRank, best: SubstituteRank | undefined): boolean {
+  if (best === undefined) return true;
+  if (candidate.echo !== best.echo) return candidate.echo;
+  if (candidate.aligned !== best.aligned) return candidate.aligned;
+  return candidate.distance < best.distance;
+}
+
+function findSubstitute(char: string, reference: ReferenceRow, payload: readonly string[]): SubstituteMatch | undefined {
   const referenceChars = [...reference.line];
   const column = referenceChars.indexOf(char);
-  for (const line of payload) {
+  const visibleReference = sensitiveStripped(reference.line);
+  let best: SubstituteMatch | undefined;
+  let bestRank: SubstituteRank | undefined;
+  for (let index = 0; index < payload.length; index += 1) {
+    const line = payload[index]!;
     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;
+    const echo = sensitiveStripped(line) === visibleReference;
+    const sameLength = candidateChars.length === referenceChars.length;
+    for (let at = 0; at < candidateChars.length; at += 1) {
+      const candidate = candidateChars[at]!;
+      if (candidate === char || !sharesFidelityClass(char, candidate)) continue;
+      const rank = { echo, aligned: sameLength && at === column, distance: Math.abs(at - column) };
+      if (!preferSubstitute(rank, bestRank)) continue;
+      bestRank = rank;
+      best = { value: candidate, payloadIndex: index, column: at + 1 };
     }
   }
-  return undefined;
+  return best;
 }
 
 function swappedCharPair(oldLine: string, newLine: string): SwappedChar | undefined {
@@ -193,10 +236,15 @@ function swappedCandidate(line: string, matches: IndexedLine[], spanStart: numbe
   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 swappedCharHint(swapped: SwappedChar, liveAnchor: string | undefined, referenceAnchor: string | undefined): string {
+  const newEscape = formatCharEscape(swapped.newChar);
+  const oldEscape = formatCharEscape(swapped.oldChar);
+  if (liveAnchor === undefined) {
+    const label = referenceAnchor === undefined ? "the replaced line" : `${referenceAnchor}${HASH_SEP}`;
+    return `[H_UNICODE_SWAPPED] "${newEscape}" at col ${swapped.column} where ${label} has "${oldEscape}".`;
+  }
+  const referenceNote = referenceAnchor === undefined ? `; expected "${oldEscape}"` : `; ${referenceAnchor}${HASH_SEP} has "${oldEscape}"`;
+  return `[H_UNICODE_SWAPPED] ${liveAnchor}${HASH_SEP} has "${newEscape}" at col ${swapped.column}${referenceNote}.`;
 }
 
 function trailingWhitespaceHint(oldLine: string, newLine: string, anchor: string | undefined): string {
@@ -327,18 +375,6 @@ function literalEscapeHintRows(
   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,
@@ -353,10 +389,29 @@ export function annotateLiteralEscapeHints(
     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.`;
+      return `${hint} on ${plural(rows.length, "row")}; undo_last_change 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.`;
+    return `${hint} (${locations}).`;
+  });
+}
+
+const LITERAL_ESCAPE_DETAIL_RE = /^\[H_LITERAL_ESCAPE\] [^:]*: "(.*?)" written as literal text(?: \((.*)\))?\.?$/;
+const LITERAL_ESCAPE_ANCHOR_RE = /([A-Za-z]{4})│/g;
+const UNICODE_LOST_DETAIL_RE = /^\[H_UNICODE_LOST\] ([A-Za-z]{4})│ missing "([^"]*)"/;
+
+export function dedupeLiteralEscapeHints(hints: readonly string[]): string[] {
+  const suppressed = new Set<string>();
+  for (const hint of hints) {
+    const literal = LITERAL_ESCAPE_DETAIL_RE.exec(hint);
+    if (literal === null) continue;
+    const escape = literal[1] ?? "";
+    for (const anchor of (literal[2] ?? "").matchAll(LITERAL_ESCAPE_ANCHOR_RE)) suppressed.add(`${anchor[1]}\0${escape}`);
+  }
+  if (suppressed.size === 0) return [...hints];
+  return hints.filter((hint) => {
+    const lost = UNICODE_LOST_DETAIL_RE.exec(hint);
+    return lost === null || !suppressed.has(`${lost[1]}\0${lost[2]}`);
   });
 }
 
@@ -404,6 +459,8 @@ export function fidelityHints(
     return sensitiveIndex;
   };
   let offset = 0;
+  const removedByAnySpan = (index: number): boolean =>
+    spans.some((candidate) => index >= candidate.start && index <= candidate.end);
   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) : [];
@@ -416,10 +473,31 @@ export function fidelityHints(
         ? 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 resultIndexForPayload = (payloadIndex: number): number =>
+        span.start + offset + (carried !== undefined && payloadIndex >= carried ? payloadIndex + 1 : payloadIndex);
+      const referenceSurvives = (reference: ReferenceRow): boolean =>
+        (carried !== undefined && reference.index === span.start && inserted[carried] === oldLines[reference.index]) ||
+        !removedByAnySpan(reference.index);
+      const liveAnchorForPayload = (payloadIndex: number): string | undefined =>
+        resultHashes?.[resultIndexForPayload(payloadIndex)];
+      const payloadIndexSharingRun = (line: string): number => {
+        const grams = gramSet([sensitiveStripped(line)], SIMILARITY_RUN);
+        return grams === undefined ? -1 : payload.findIndex((candidate) => sharesRun(sensitiveStripped(candidate), grams, SIMILARITY_RUN));
+      };
+      const liveAnchorForReference = (reference: ReferenceRow): string | undefined => {
+        const shared = payloadIndexSharingRun(reference.line);
+        if (shared >= 0) return liveAnchorForPayload(shared);
+        if (carried !== undefined || removed.length !== payload.length) return undefined;
+        const payloadIndex = reference.index - span.start;
+        return payloadIndex >= 0 && payloadIndex < payload.length ? liveAnchorForPayload(payloadIndex) : undefined;
+      };
+      const referenceAnchorFor = (reference: ReferenceRow): string | undefined =>
+        referenceSurvives(reference) ? originalHashes?.[reference.index] : undefined;
       const swapKeys = new Set<string>();
       const swaps: SwapCandidate[] = [];
       let candidates: Map<string, IndexedLine[]> | undefined;
-      for (const line of payload) {
+      for (let payloadIndex = 0; payloadIndex < payload.length; payloadIndex += 1) {
+        const line = payload[payloadIndex]!;
         if (!containsSensitiveChar(line)) continue;
         candidates ??= sensitiveLines();
         const matches = [...(candidates.get(normalizeSensitiveChars(line)) ?? []), ...references];
@@ -428,7 +506,7 @@ export function fidelityHints(
         const key = `${candidate.reference.index}:${candidate.swapped.oldChar}`;
         if (swapKeys.has(key)) continue;
         swapKeys.add(key);
-        swaps.push(candidate);
+        swaps.push({ ...candidate, liveAnchor: liveAnchorForPayload(payloadIndex) });
       }
       const missing = new Map<string, ReferenceRow>();
       for (const reference of references) {
@@ -449,17 +527,17 @@ export function fidelityHints(
         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]));
+          hints.push(swappedCharHint({ oldChar: char, newChar: substitute.value, column: substitute.column }, liveAnchorForPayload(substitute.payloadIndex), referenceAnchorFor(reference)));
           continue;
         }
-        hints.push(hiddenCharHint(char, reference, originalHashes?.[reference.index]));
+        hints.push(hiddenCharHint(char, reference, liveAnchorForReference(reference), referenceAnchorFor(reference)));
       }
       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]));
+        hints.push(swappedCharHint(candidate.swapped, candidate.liveAnchor, referenceAnchorFor(candidate.reference)));
       }
       const indentReferenceFor = (payloadIndex: number): ReferenceRow | undefined => {
         if (options?.indentHints === false) return undefined;
@@ -482,8 +560,6 @@ export function fidelityHints(
         }
         return undefined;
       };
-      const resultIndexForPayload = (payloadIndex: number): number =>
-        span.start + offset + (carried !== undefined && payloadIndex >= carried ? payloadIndex + 1 : payloadIndex);
       for (let index = 0; index < payload.length; index += 1) {
         if (hints.length >= MAX_FIDELITY_HINTS) break;
         const payloadLine = payload[index]!;

package/src/grep.ts

@@ -393,7 +393,7 @@ const grepToolSchema = Type.Object(
     limit: Type.Optional(
       Type.Integer({
         minimum: 1,
-        description: "Maximum number of matched lines to return",
+        description: "Maximum number of matched lines to return (default 100)",
       }),
     ),
   },

package/src/insert.ts

@@ -11,7 +11,7 @@ import type { LineEnding } from "./normalize";
 import { stripAnchorRow } from "./hashline/resolve";
 import { withAnchorSession } from "./anchor-registry";
 import { loadP, loadGuidelines } from "./prompts";
-import { assertInsertReq, normReq, type InsertReq } from "./payload-contract";
+import { assertInsertReq, normReq, pathRequiredSchema, type InsertReq } from "./payload-contract";
 import { anchorCarryIndex, 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";
@@ -32,11 +32,6 @@ const insertTextSchema = Type.String({
     `The exact text to insert; an empty string inserts one blank line. ${TEXT_ENDING_NOTE} Never include the anchor line.`,
 });
 
-const insertPathRequiredSchema = Type.String({
-  description:
-    "Path to the file the anchor was served for; required and must match anchor ownership.",
-});
-
 const insertToolSchema = Type.Object(
   {
     anchor: insertAnchorSchema,
@@ -50,7 +45,7 @@ export function buildInsertToolSchema(requirePath: boolean): typeof insertToolSc
   if (!requirePath) return insertToolSchema;
   return Type.Object(
     {
-      path: insertPathRequiredSchema,
+      path: pathRequiredSchema,
       anchor: insertAnchorSchema,
       direction: insertDirectionSchema,
       text: insertTextSchema,

package/src/payload-contract.ts

@@ -1,6 +1,7 @@
 import { Type } from "typebox";
 import { isRec, normalizeRequest, rejectUnknownFields, assertNoNul } from "./utils";
 import { TEXT_ENDING_NOTE, TEXT_NOT_STRING_MSG, NEW_CONTENT_NOT_STRING_MSG } from "./constants";
+import { toLF } from "./normalize";
 
 const textSchema = Type.String({
   description:
@@ -16,7 +17,7 @@ const removeToSchema = Type.String({
   description:
     "4-char anchor of the LAST line to remove.",
 });
-const pathRequiredSchema = Type.String({
+export const pathRequiredSchema = Type.String({
   description:
     "Path to the file the anchors were served for; required and must match anchor ownership.",
 });
@@ -166,25 +167,44 @@ export function assertTransferReq(request: unknown): asserts request is Transfer
   }
 }
 
-const MATCH_KS = new Set(["path", "replace_from", "replace_to", "old_string", "new_string"]);
+const MATCH_KS = new Set(["path", "replace_from", "replace_to", "match", "replacement"]);
 
 export interface ReplaceMatchReq {
   path?: string;
   replace_from: string;
   replace_to: string;
-  old_string: string;
-  new_string: string;
+  match: string;
+  replacement: string;
+}
+
+export function singleLineFragment(field: "match" | "replacement", raw: string): string {
+  const text = toLF(raw);
+  const fragment = text.endsWith("\n") ? text.slice(0, -1) : text;
+  const lineBreak = fragment.indexOf("\n");
+  if (lineBreak >= 0) {
+    const column = [...fragment.slice(0, lineBreak)].length + 1;
+    throw new Error(
+      `[E_BAD_SHAPE] ${field} must stay within one line, but the value contains a line break at column ${column}. A trailing line break is accepted as the line's own terminator; text on another line belongs to replace.`,
+    );
+  }
+  if (field === "match" && fragment.length === 0) {
+    throw new Error('[E_BAD_SHAPE] Replace-match request field "match" must be a non-empty string holding the exact text to find.');
+  }
+  return fragment;
 }
 
 export function assertReplaceMatchReq(request: unknown): asserts request is ReplaceMatchReq {
   if (!isRec(request)) {
     throw new Error("[E_BAD_SHAPE] Replace-match request must be an object.");
   }
+  if ("old_string" in request || "new_string" in request) {
+    throw new Error('[E_BAD_SHAPE] Replace-match request no longer accepts "old_string"/"new_string"; use "match" for the text to find and "replacement" for the new text.');
+  }
   rejectUnknownFields(request, MATCH_KS, "Replace-match request");
   if (request.path !== undefined && typeof request.path !== "string") {
     throw new Error('[E_BAD_SHAPE] Replace-match request field "path" must be a string when provided.');
   }
-  for (const key of ["replace_from", "replace_to", "old_string", "new_string"] as const) {
+  for (const key of ["replace_from", "replace_to", "match", "replacement"] as const) {
     if (typeof (request as Record<string, unknown>)[key] !== "string") {
       throw new Error(`[E_BAD_SHAPE] Replace-match request requires a "${key}" string.`);
     }
@@ -193,13 +213,12 @@ export function assertReplaceMatchReq(request: unknown): asserts request is Repl
   if (within.replace_from.length === 0 || within.replace_to.length === 0) {
     throw new Error('[E_BAD_SHAPE] Replace-match request requires non-empty "replace_from" and "replace_to" anchors.');
   }
-  if (within.old_string.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Replace-match request field "old_string" must be a non-empty string holding the exact text to find.');
-  }
-  assertNoNul([within.new_string]);
+  singleLineFragment("match", within.match);
+  singleLineFragment("replacement", within.replacement);
+  assertNoNul([within.replacement]);
 }
 
-export function getReplaceMatchInput(args: unknown): { path?: string; replace_from: string; replace_to: string; old_string: string; new_string: string } | null {
+export function getReplaceMatchInput(args: unknown): { path?: string; replace_from: string; replace_to: string; match: string; replacement: string } | null {
   let normalized: unknown;
   try {
     normalized = normalizeRequest(args, "replace");
@@ -210,8 +229,8 @@ export function getReplaceMatchInput(args: unknown): { path?: string; replace_fr
   if (
     typeof normalized.replace_from !== "string" ||
     typeof normalized.replace_to !== "string" ||
-    typeof normalized.old_string !== "string" ||
-    typeof normalized.new_string !== "string"
+    typeof normalized.match !== "string" ||
+    typeof normalized.replacement !== "string"
   ) {
     return null;
   }
@@ -219,8 +238,8 @@ export function getReplaceMatchInput(args: unknown): { path?: string; replace_fr
     ...(typeof normalized.path === "string" ? { path: normalized.path } : {}),
     replace_from: normalized.replace_from,
     replace_to: normalized.replace_to,
-    old_string: normalized.old_string,
-    new_string: normalized.new_string,
+    match: normalized.match,
+    replacement: normalized.replacement,
   };
 }
 
@@ -230,27 +249,23 @@ const replaceMatchFromSchema = Type.String({
 });
 const replaceMatchToSchema = Type.String({
   description:
-    "4-char anchor of the LAST line of the range searched; same as replace_from for a single line.",
-});
-const replaceMatchOldStringSchema = Type.String({
-  description:
-    "The exact text to find inside the selected line(s), copied from the served row: only the fragment that changes, never text that `new_string` leaves unchanged. If `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line match: use `replace` instead. Every occurrence inside the range is replaced; the text around each match is left untouched. Matching uses LF line breaks and excludes the last line's terminator.",
+    "4-char anchor of the LAST line of the range searched; same as `replace_from` for a single line.",
 });
-const replaceMatchNewStringSchema = Type.String({
+const replaceMatchMatchSchema = Type.String({
   description:
-    `The exact replacement for every matched occurrence. "" deletes the matches. ${TEXT_ENDING_NOTE} The rest of the range is kept byte-for-byte.`,
+    "The exact text to find inside the selected lines, copied from the served row: only the fragment that changes, never text that `replacement` leaves unchanged. It must stay within one line and hold text: a single trailing line break is accepted as the line's own terminator, a line break anywhere else is refused, and a value that is only a line break leaves nothing to find and is refused. Every occurrence inside the range is replaced; the text around each match is left untouched.",
 });
-const replaceMatchPathRequiredSchema = Type.String({
+const replaceMatchReplacementSchema = Type.String({
   description:
-    "Path to the file the anchors were served for; required and must match anchor ownership.",
+    `The exact replacement for every matched occurrence within the range. "" deletes the matches. It must stay within one line: a single trailing line break is accepted and dropped (a value that is only a line break counts as ""), and a line break anywhere else is refused. The rest of each line is kept byte-for-byte.`,
 });
 
 export const replaceMatchToolSchema = Type.Object(
   {
     replace_from: replaceMatchFromSchema,
     replace_to: replaceMatchToSchema,
-    old_string: replaceMatchOldStringSchema,
-    new_string: replaceMatchNewStringSchema,
+    match: replaceMatchMatchSchema,
+    replacement: replaceMatchReplacementSchema,
   },
   { additionalProperties: true },
 );
@@ -259,11 +274,11 @@ export function buildReplaceMatchToolSchema(requirePath: boolean): typeof replac
   if (!requirePath) return replaceMatchToolSchema;
   return Type.Object(
     {
-      path: replaceMatchPathRequiredSchema,
+      path: pathRequiredSchema,
       replace_from: replaceMatchFromSchema,
       replace_to: replaceMatchToSchema,
-      old_string: replaceMatchOldStringSchema,
-      new_string: replaceMatchNewStringSchema,
+      match: replaceMatchMatchSchema,
+      replacement: replaceMatchReplacementSchema,
     },
     { additionalProperties: true },
   ) as typeof replaceMatchToolSchema;

package/src/read.ts

@@ -320,7 +320,7 @@ function buildReadToolSchema(codemode: boolean) {
 		limit: Type.Optional(
 			Type.Integer({
 				minimum: 1,
-				description: "Maximum number of lines to read from offset",
+				description: "Maximum number of lines to read from offset; counted from the anchor row when `offset` is an anchor",
 			}),
 		),
 		...(codemode

package/src/replace-match.ts

@@ -1,10 +1,9 @@
 import type { ExtensionAPI, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { constants } from "node:fs";
-import * as Diff from "diff";
 import { execPipeline, noteAnchorError, previewFromPipe, previewError, type ReplaceDetails } from "./replace";
 import { commitEdit } from "./commit";
 import { readNormFile, type NormFile } from "./file-reader";
-import { fmtRegion, MAX_HASH_LINES, parseHashRef, parsePayloadText, planEdit, preserveDeletionSeparators, resEdit, resolveAnchorLine, stripAnchorRow, type Anchor } from "./hashline";
+import { fmtRegion, MAX_HASH_LINES, parseHashRef, planEdit, preserveDeletionSeparators, resEdit, resolveAnchorLine, stripAnchorRow, type Anchor } from "./hashline";
 import { servedForPath, withAnchorSession } from "./anchor-registry";
 import { batchMemberFor, executeBatchMember, noteBatchFailure, registerBatchPlanner, type BatchMemberPlan, type BatchPlannerInput } from "./batch";
 import { loadP, loadGuidelines } from "./prompts";
@@ -13,13 +12,13 @@ import {
   buildReplaceMatchToolSchema,
   getReplaceMatchInput,
   normReq,
+  singleLineFragment,
   type ReplaceMatchReq,
 } from "./payload-contract";
 import { literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
-import { toLF, type LineEnding } from "./normalize";
-import { isFidelitySensitiveChar } from "./edit-fidelity";
-import { countNewlines, splitWithEndings } from "./line-endings";
+import { type LineEnding } from "./normalize";
 import { MAX_RANGE_STALE_LINES } from "./constants";
+import { formatCharEscape, isFidelitySensitiveChar } from "./edit-fidelity";
 import {
   assertBoundaryLinesServed,
   DEFAULT_EDIT_FLAGS,
@@ -43,73 +42,43 @@ interface MatchRefs {
 
 export interface MatchPlan {
   editParams: { remove_from: string; remove_to: string; text: string };
-  warnings: string[];
   contentSeparators: (LineEnding | undefined)[];
   servedOverride?: ReadonlyMap<string, string>;
 }
 
-function formatMatchRange(start: number, end: number): string {
-  return start === end ? `line ${start}` : `lines ${start}-${end}`;
-}
-
 function replaceAllOccurrences(
-  text: string,
-  oldText: string,
-  newText: string,
-): { text: string; separators: (LineEnding | undefined)[]; count: number } {
+  line: string,
+  matchText: string,
+  replacementText: string,
+): { text: string; count: number } {
   const parts: string[] = [];
-  const inserted: Array<{ start: number; end: number }> = [];
-  let length = 0;
-  const append = (chunk: string, fromNewText: boolean): void => {
-    if (fromNewText) inserted.push({ start: length, end: length + chunk.length });
-    parts.push(chunk);
-    length += chunk.length;
-  };
   let cursor = 0;
   let count = 0;
   for (;;) {
-    const found = text.indexOf(oldText, cursor);
+    const found = line.indexOf(matchText, cursor);
     if (found < 0) break;
-    append(text.slice(cursor, found), false);
-    append(newText, true);
-    cursor = found + oldText.length;
+    parts.push(line.slice(cursor, found), replacementText);
+    cursor = found + matchText.length;
     count += 1;
   }
-  if (count === 0) return { text, separators: [], count: 0 };
-  append(text.slice(cursor), false);
-  const replacement = parts.join("");
-  const parsed = splitWithEndings(replacement);
-  const separators: (LineEnding | undefined)[] = [];
-  let offset = 0;
-  let insertedIndex = 0;
-  for (let index = 0; index < parsed.lines.length; index++) {
-    offset += parsed.lines[index]!.length;
-    const ending = parsed.endings[index];
-    if (ending === undefined) continue;
-    while (insertedIndex < inserted.length && inserted[insertedIndex]!.end <= offset) insertedIndex += 1;
-    const fromNewText = insertedIndex < inserted.length && offset >= inserted[insertedIndex]!.start && offset < inserted[insertedIndex]!.end;
-    separators.push(fromNewText ? ending : undefined);
-    offset += ending.length;
-  }
-  return { text: replacement, separators, count };
+  if (count === 0) return { text: line, count: 0 };
+  parts.push(line.slice(cursor));
+  return { text: parts.join(""), count };
 }
 
-const RETYPE_DIFF_MAX_CHARS = 20_000;
-const RETYPE_MAX_EDIT_LENGTH = 2000;
-const RETYPE_MIN_UNCHANGED_CHARS = 40;
-const RETYPE_MIN_UNCHANGED_MULTILINE = 20;
-const RETYPE_EXAMPLE_MAX_CHARS = 40;
-const WHOLE_RANGE_MIN_CHARS = 40;
-const WHOLE_RANGE_MIN_LINES = 2;
-const NEAR_MISS_MIN_OLD_CHARS = 20;
-const NEAR_MISS_MATCH_RATIO = 0.8;
+function linesToPayloadText(lines: string[]): string {
+  if (lines.length === 0) return "";
+  const joined = lines.join("\n");
+  return lines[lines.length - 1] === "" ? `${joined}\n` : joined;
+}
 
-interface RetypeAnalysis {
-  changed: number;
-  unchanged: number;
-  middle: { oldFragment: string; newFragment: string };
+function fileInheritedEndings(lineCount: number): (LineEnding | undefined)[] {
+  return new Array<LineEnding | undefined>(lineCount).fill(undefined);
 }
 
+const NEAR_MISS_MIN_MATCH_CHARS = 20;
+const NEAR_MISS_MATCH_RATIO = 0.8;
+
 function commonPrefixLength(left: string, right: string): number {
   const limit = Math.min(left.length, right.length);
   let index = 0;
@@ -124,91 +93,50 @@ function commonSuffixLength(left: string, right: string, prefix: number): number
   return suffix;
 }
 
-function analyzeRetype(oldText: string, newText: string): RetypeAnalysis {
-  const prefix = commonPrefixLength(oldText, newText);
-  const suffix = commonSuffixLength(oldText, newText, prefix);
-  const middle = {
-    oldFragment: oldText.slice(prefix, oldText.length - suffix),
-    newFragment: newText.slice(prefix, newText.length - suffix),
-  };
-  if (oldText.length + newText.length <= RETYPE_DIFF_MAX_CHARS) {
-    const parts = Diff.diffChars(oldText, newText, { maxEditLength: RETYPE_MAX_EDIT_LENGTH }) as Array<{ added?: boolean; removed?: boolean; value: string }> | undefined;
-    if (parts !== undefined) {
-      let changed = 0;
-      let removed = 0;
-      for (const part of parts) {
-        if (part.added === true) changed += part.value.length;
-        else if (part.removed === true) {
-          changed += part.value.length;
-          removed += part.value.length;
-        }
-      }
-      return { changed, unchanged: oldText.length - removed, middle };
-    }
-  }
-  return { changed: middle.oldFragment.length + middle.newFragment.length, unchanged: prefix + suffix, middle };
-}
-
-function retypeSuggestion(analysis: RetypeAnalysis): string {
-  const { oldFragment, newFragment } = analysis.middle;
-  if (oldFragment.length === 0 && newFragment.length === 0) return "Send only the fragment that changes instead.";
-  if (oldFragment.length === 0) return "Send the added text with insert instead.";
-  if (
-    oldFragment.length > RETYPE_EXAMPLE_MAX_CHARS ||
-    newFragment.length > RETYPE_EXAMPLE_MAX_CHARS ||
-    oldFragment.includes("\n") ||
-    newFragment.includes("\n")
-  ) {
-    return "Send only the fragment that changes instead.";
-  }
-  return `Send old_string ${JSON.stringify(oldFragment)} and new_string ${JSON.stringify(newFragment)} instead.`;
+function charAt(text: string, index: number): string | undefined {
+  if (index >= text.length) return undefined;
+  return String.fromCodePoint(text.codePointAt(index)!);
 }
 
-function retypeWarning(oldText: string, newText: string): string | undefined {
-  const analysis = analyzeRetype(oldText, newText);
-  if (analysis.changed === 0) return undefined;
-  const minUnchanged = oldText.includes("\n") ? RETYPE_MIN_UNCHANGED_MULTILINE : RETYPE_MIN_UNCHANGED_CHARS;
-  if (analysis.unchanged < minUnchanged) return undefined;
-  const lineCount = oldText.split("\n").length;
-  return `[W_REPLACE_MATCH_RETYPE] "old_string" retypes ${analysis.unchanged} unchanged character(s) across ${lineCount} line(s). ${retypeSuggestion(analysis)}`;
-}
-
-function wholeRangeWarning(oldText: string, rangeText: string, lineCount: number, start: number, end: number, startHash: string, endHash: string): string | undefined {
-  if (oldText !== rangeText) return undefined;
-  if (lineCount < WHOLE_RANGE_MIN_LINES && oldText.length < WHOLE_RANGE_MIN_CHARS) return undefined;
-  return `[W_REPLACE_MATCH_WHOLE_RANGE] "old_string" is the entire selected range (${formatMatchRange(start, end)}); the anchors already identify it. Use replace with remove_from "${startHash}", remove_to "${endHash}" and the new text, or send only the fragment that changes.`;
+function codePointStart(text: string, index: number): number {
+  if (index <= 0 || index >= text.length) return index;
+  const before = text.charCodeAt(index - 1);
+  const at = text.charCodeAt(index);
+  return before >= 0xd800 && before <= 0xdbff && at >= 0xdc00 && at <= 0xdfff ? index - 1 : index;
 }
 
 function describeChar(char: string | undefined): string {
   if (char === undefined) return "the end of the text";
   const codePoint = char.codePointAt(0)!;
-  const shown = JSON.stringify(char);
-  return isFidelitySensitiveChar(char) || codePoint < 0x20 || codePoint > 0x7e
-    ? `${shown} (U+${codePoint.toString(16).toUpperCase().padStart(4, "0")})`
-    : shown;
+  return isFidelitySensitiveChar(char) || codePoint > 0x7e ? `"${formatCharEscape(char)}"` : JSON.stringify(char);
 }
 
-function nearMissDetail(oldText: string, rangeText: string, start: number): string | undefined {
-  if (oldText.length < NEAR_MISS_MIN_OLD_CHARS && !oldText.includes("\n")) return undefined;
-  const prefix = commonPrefixLength(oldText, rangeText);
-  const suffix = commonSuffixLength(oldText, rangeText, prefix);
-  const comparable = Math.min(oldText.length, rangeText.length);
+function nearMissDetail(matchText: string, lineText: string, line: number): string | undefined {
+  if (matchText.length < NEAR_MISS_MIN_MATCH_CHARS) return undefined;
+  const prefix = commonPrefixLength(matchText, lineText);
+  const suffix = commonSuffixLength(matchText, lineText, prefix);
+  const comparable = Math.min(matchText.length, lineText.length);
   if (prefix + suffix < Math.floor(comparable * NEAR_MISS_MATCH_RATIO)) return undefined;
-  const lineOffset = countNewlines(rangeText.slice(0, prefix));
-  const column = prefix - rangeText.lastIndexOf("\n", prefix - 1);
-  return `the first mismatch is at line ${start + lineOffset}, col ${column}: the file has ${describeChar(rangeText[prefix])} where old_string has ${describeChar(oldText[prefix])}.`;
+  const fileStart = codePointStart(lineText, prefix);
+  const matchStart = codePointStart(matchText, prefix);
+  const column = [...lineText.slice(0, fileStart)].length + 1;
+  return `the first mismatch is at line ${line}, col ${column}: the file has ${describeChar(charAt(lineText, fileStart))} where match has ${describeChar(charAt(matchText, matchStart))}.`;
 }
 
-function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[], rangeText: string, oldText: string): string {
+function formatMatchRange(start: number, end: number): string {
+  return start === end ? `line ${start}` : `lines ${start}-${end}`;
+}
+
+function notFoundMessage(displayPath: string, start: number, end: number, fileHashes: string[], fileLines: string[], rangeText: string, matchText: string): string {
   const rangeLength = end - start + 1;
   const shownCount = Math.min(rangeLength, MAX_RANGE_STALE_LINES);
   const shown = fmtRegion(fileHashes.slice(start - 1, start - 1 + shownCount), fileLines.slice(start - 1, start - 1 + shownCount));
-  const more = rangeLength > shownCount ? `\n[The range has ${rangeLength} lines; showing the first ${shownCount}.]` : "";
-  const nearMiss = nearMissDetail(oldText, rangeText, start);
+  const more = rangeLength > shownCount ? `\n[The range has ${rangeLength} lines; showing the first ${shownCount}. Call read with offset=${start + shownCount} to see the rest.]` : "";
+  const nearMiss = start === end ? nearMissDetail(matchText, rangeText, start) : undefined;
   const advice = nearMiss !== undefined
-    ? `${nearMiss} That looks like a retyped copy of the range; send only the fragment that changes (copy it from the served row), or use replace with the same anchors.`
-    : "Copy only the fragment that changes from the served row (comparison uses LF breaks and excludes the last line's terminator) and retry; for a whole-line or whole-range rewrite use replace with the same anchors.";
-  return `[E_SUBSTRING_NOT_FOUND] "old_string" was not found in ${formatMatchRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\n${advice}`;
+    ? `${nearMiss} That looks like a retyped copy of the line; send only the fragment that changes (copy it from the served row), or use replace with the same anchor.`
+    : "Copy only the fragment that changes from the served row (a trailing line break is accepted and dropped) and retry; for a whole-line rewrite use replace with the same anchors.";
+  return `[E_SUBSTRING_NOT_FOUND] "match" was not found in ${formatMatchRange(start, end)} of ${displayPath}. Current rows:\n\n${shown}${more}\n\n${advice}`;
 }
 
 export function parseMatchAnchors(req: ReplaceMatchReq): { refs: MatchRefs; warnings: string[] } {
@@ -225,6 +153,8 @@ export function buildReplaceMatchEdit(
   displayPath: string,
   served?: ReadonlyMap<string, string>,
 ): MatchPlan {
+  const matchText = singleLineFragment("match", req.match);
+  const replacementText = singleLineFragment("replacement", req.replacement);
   const fileLines = splitLines(preload.normalized);
   const fromLine = resolveAnchorLine(refs.from, fileLines, preload.fileHashes, displayPath);
   const toLine = resolveAnchorLine(refs.to, fileLines, preload.fileHashes, displayPath);
@@ -232,33 +162,26 @@ export function buildReplaceMatchEdit(
   const end = Math.max(fromLine, toLine);
   assertBoundaryLinesServed(fileLines, preload.fileHashes, served, start, end, displayPath);
   const rangeLines = fileLines.slice(start - 1, end);
-  const rangeText = `${rangeLines.join("\n")}${rangeLines[rangeLines.length - 1] === "" ? "\n" : ""}`;
-  const oldText = toLF(req.old_string);
-  const newText = toLF(req.new_string);
-  const { text: replacement, separators: replacementSeparators, count } = replaceAllOccurrences(rangeText, oldText, req.new_string);
+  let count = 0;
+  const replacementLines = rangeLines.map((line) => {
+    const result = replaceAllOccurrences(line, matchText, replacementText);
+    count += result.count;
+    return result.text;
+  });
   if (count === 0) {
-    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, rangeText, oldText));
+    throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, linesToPayloadText(rangeLines), matchText));
   }
-  const contentSeparators = parsePayloadText(replacement).lines.map((_, index) => replacementSeparators[index]);
+  const replacement = linesToPayloadText(replacementLines);
   const startRef = fromLine <= toLine ? refs.from : refs.to;
   const endRef = fromLine <= toLine ? refs.to : refs.from;
   const servedOverride = trustRangeServed(fileLines, preload.fileHashes, served, start, end);
-  const warnings: string[] = [];
-  const retype = retypeWarning(oldText, newText);
-  if (retype !== undefined) {
-    warnings.push(retype);
-  } else {
-    const wholeRange = wholeRangeWarning(oldText, rangeText, rangeLines.length, start, end, startRef.hash, endRef.hash);
-    if (wholeRange !== undefined) warnings.push(wholeRange);
-  }
   return {
     editParams: {
       remove_from: startRef.hash,
       remove_to: endRef.hash,
       text: replacement,
     },
-    warnings,
-    contentSeparators,
+    contentSeparators: fileInheritedEndings(replacementLines.length),
     ...(servedOverride !== undefined ? { servedOverride } : {}),
   };
 }
@@ -267,7 +190,7 @@ function planReplaceMatchBatchMember(input: BatchPlannerInput): BatchMemberPlan
   const req = normReq(input.member.args, "replace");
   assertReplaceMatchReq(req);
   const { refs, warnings } = parseMatchAnchors(req);
-  const hints = [...literalEscapeHints([req.old_string], "old_string"), ...literalEscapeHints([req.new_string], "new_string")];
+  const hints = [...literalEscapeHints([req.match], "match"), ...literalEscapeHints([req.replacement], "replacement")];
   const preload = { normalized: input.base.content, fileHashes: input.base.hashes } as NormFile;
   const matchPlan = buildReplaceMatchEdit(req, refs, preload, input.displayPath, input.served);
   const resWarnings: string[] = [];
@@ -281,11 +204,10 @@ function planReplaceMatchBatchMember(input: BatchPlannerInput): BatchMemberPlan
   });
   return {
     hedit,
-    warnings: [...warnings, ...hints, ...resWarnings, ...matchPlan.warnings],
+    warnings: [...warnings, ...hints, ...resWarnings],
     contentSeparators: matchPlan.contentSeparators,
     planned,
     foldedLines: 0,
-    ...(matchPlan.servedOverride !== undefined ? { servedOverride: matchPlan.servedOverride } : {}),
   };
 }
 
@@ -312,7 +234,6 @@ export async function replaceMatchPreview(request: unknown, cwd: string, signal?
       signal,
     });
     const plan = buildReplaceMatchEdit(req, refs, preload, targetPath, servedForPath(preload.absolutePath));
-    await throwIfStrictInput(plan.warnings);
     const pipe = await execPipeline(targetPath, plan.editParams, cwd, {
       accessMode: constants.R_OK,
       noPersist: true,
@@ -367,7 +288,7 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
           if (member) noteBatchFailure(member, error);
           throw error;
         }
-        const hints = [...literalEscapeHints([req.old_string], "old_string"), ...literalEscapeHints([req.new_string], "new_string")];
+        const hints = [...literalEscapeHints([req.match], "match"), ...literalEscapeHints([req.replacement], "replacement")];
         const targetPath = await resolveEditTargetWithRequirement({
           removeFrom: req.replace_from,
           removeTo: req.replace_to,
@@ -394,7 +315,6 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
             await noteAnchorError(mutationTargetPath, error);
             throw error;
           }
-          await throwIfStrictInput(plan.warnings);
           const pipe = await execPipeline(targetPath, plan.editParams, ctx.cwd, {
             accessMode: constants.R_OK | constants.W_OK,
             signal,
@@ -407,7 +327,7 @@ export function buildReplaceMatchToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLA
             absolutePath,
             mutationTargetPath,
             editAnchors: [plan.editParams.remove_from, plan.editParams.remove_to],
-            prefixWarnings: [...warnings, ...hints, ...plan.warnings],
+            prefixWarnings: [...warnings, ...hints],
             signal,
             verb: "replaced",
             noopNoun: "Replacement",

package/src/replace-response.ts

@@ -2,7 +2,7 @@ import { HASH_SEP, type NEdit } from "./hashline";
 import type { ReplaceDetails } from "./replace";
 import { genDiff, genPatch, type DiffSpan } from "./replace-diff";
 import { visLines, clipLine } from "./utils";
-import { annotateLiteralEscapeHints, fidelityHints } from "./edit-fidelity";
+import { annotateLiteralEscapeHints, dedupeLiteralEscapeHints, fidelityHints } from "./edit-fidelity";
 import { anchoredLine, anchoredLinesFromDiff, diffAnchorsOmitted, toEditVerb, type EditStructured, type EditVerb, type Json } from "./structured";
 
 export type TResult = {
@@ -164,7 +164,8 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
   });
   const { warnings: noticeWarnings, hints } = splitNotices(fidelity.length > 0 ? [...(warnings ?? []), ...fidelity] : warnings);
   const annotatedHints = annotateLiteralEscapeHints(hints, result, spans, resultHashes);
-  const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(annotatedHints)}`;
+  const dedupedHints = dedupeLiteralEscapeHints(annotatedHints);
+  const noticesBlock = `${warnBlock(noticeWarnings)}${hintBlock(dedupedHints)}`;
   const successPrefix = `Successfully ${verb} in ${path}.`;
   const lineSummary = addedLines > 0 || removedLines > 0
     ? ` Added ${addedLines} line(s), removed ${removedLines} line(s).`
@@ -203,7 +204,7 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
 		text,
 		diff: diffResult.diff,
 		warnings: [...noticeWarnings],
-		hints: [...annotatedHints],
+		hints: [...dedupedHints],
 		firstChangedLine: editMeta.firstChangedLine ?? diffResult.firstChangedLine ?? null,
 		anchors,
 		anchorsOmitted,
@@ -220,7 +221,7 @@ export function buildChanged(input: SuccessInput, verb = "replaced", diffContext
       metrics,
       diffLineNumbers: diffResult.lineNumbers.map((line) => line ?? null),
       ...(noticeWarnings.length ? { warnings: [...noticeWarnings] } : {}),
-      ...(annotatedHints.length ? { hints: [...annotatedHints] } : {}),
+      ...(dedupedHints.length ? { hints: [...dedupedHints] } : {}),
     },
     structuredContent,
   };

package/tool-prompts/copy.md

@@ -1,3 +1,3 @@
-Duplicate a range of lines at another anchor, in this or another file. The source rows and anchors stay live; the copied lines get fresh anchors in the destination's post-edit diff and keep their source line endings.
+Duplicate a range of lines at another anchor. The source rows and anchors stay live; the copied lines get fresh anchors in the destination's post-edit diff and keep their source line endings.
 
 A copy duplicates the content its source anchors were served from, so a same-message edit to the source file does not change what is copied.

package/tool-prompts/grep.md

@@ -1 +1 @@
-Search text files with ripgrep. Hits come back as `lineNumber:│ anchor│content` rows and context lines as `lineNumber-│ anchor│content`, editable with replace, insert, copy, or move without a new read; the `=== path ===` header and line numbers locate the match. Patterns are regex by default; set `literal: true` for exact text, `ignoreCase` for case-insensitive search, and `context` for surrounding rows. Rust regex syntax (no backreferences or look-around) through a linear-time engine. Searches respect `.gitignore`, always skip `.git`, and skip binary and image files silently. A match over 500 bytes is shown as a `...` fragment around the hit, but its anchor still covers the whole line. When cut by match limit, raise `limit` (default 100); when cut by rows/bytes, refine `pattern` or narrow `path`.
+Search text files with ripgrep. Hits come back as `lineNumber:│ anchor│content` rows and context lines as `lineNumber-│ anchor│content`, editable with replace, insert, copy, or move without a new read. A row returned by `grep` is already a served row, so you do not need to `read` the file to edit that line. The `=== path ===` header and line numbers locate the match. Patterns use ripgrep's Rust regex syntax (no backreferences or look-around) through a linear-time engine. Searches respect `.gitignore`, always skip `.git`, and skip binary and image files silently. A match over 500 bytes is shown as a `...` fragment around the hit, but its anchor still covers the whole line. When output is cut by the match limit, raise `limit`; when cut by rows or bytes, refine `pattern` or narrow `path`.

package/tool-prompts/insert.md

@@ -1 +1 @@
-Insert text after or before one existing line, addressed by `anchor` (a bare anchor from any served `anchor│content` row). `direction` places `text` after or before the anchor line; `text` is the exact text to insert.
+Insert text next to an existing line without removing anything. The anchor line stays in place, and `anchor` is a bare 4-character anchor from any served `anchor│content` row.

package/tool-prompts/move.md

@@ -1,3 +1,3 @@
-Relocate a range of lines to another anchor, in this or another file. Within one file the destination must sit outside the source range; moving a range onto itself reports `No changes made` and leaves the anchors alone.
+Relocate a range of lines to another anchor. Within one file the destination must sit outside the source range; moving a range onto itself reports `No changes made` and leaves the anchors alone. Rows between the source and the destination keep their content but may be re-anchored, so read that span again if you plan to edit it.
 
 A cross-file move commits on its own when its source file also has batched edits in the message.

package/tool-prompts/read-guidelines.md

@@ -1,3 +1,3 @@
 - `read`: call again after an edit when you need anchors you lack — post-edit diff `+`/` ` rows and served `anchor│content` rows already carry fresh anchors for the changed range.
 - `read`: an auto-read-all outline row shows a symbol label, or a single-line symbol's content; its `[limit N]` is the span to request.
-- `read`: `replace_match` needs both boundary lines served; copy `old_string` from a served row or read the lines first.
+- `read`: `replace_match` needs both boundary lines served; copy `match` from a served row or read the lines first.

package/tool-prompts/replace-match-guidelines.md

@@ -1,3 +1,3 @@
-- `replace_match`: `old_string` is only the fragment that changes — never text that `new_string` leaves unchanged; every occurrence inside the range is replaced, so scope the range when only some lines should change.
-- `replace_match`: if `old_string` is everything on the line except indentation and trailing punctuation, that match is the whole line — use `replace`. A shorter fragment repeated on several lines (a value, a name) is the intended multi-line use.
-- `replace_match`: when the change covers whole lines or the whole range, use `replace` with the same anchors and the exact text.
+- `replace_match`: `match` is only the fragment that changes — never text that `replacement` leaves unchanged; every occurrence inside the range is replaced, so narrow the anchors when only some lines should change.
+- `replace_match`: the anchors bound the range searched, and `match`/`replacement` must each stay within one line — a trailing line break is the line's terminator, an interior one belongs to `replace`, and a lone break cannot be a `match`.
+- `replace_match`: when the change covers the whole line, use `replace` with the same anchor and the exact text.

package/tool-prompts/replace-match-snippet.md

@@ -1 +1 @@
-Replace part of a line or range by anchor: every `old_string` occurrence inside `replace_from`/`replace_to` becomes `new_string`; the rest of the line stays untouched
+Replace part of a line or range by anchor: every `match` occurrence inside the range becomes `replacement`; the rest of each line stays untouched

package/tool-prompts/replace-match.md

@@ -1,3 +1,3 @@
-Replace part of a line (or a range of lines) without retyping the rest. `replace_from`/`replace_to` are bare anchors from served `anchor│content` rows marking the range's first and last line (the same anchor for one line), and `old_string` is the exact text to find inside that range. Send only the fragment that changes — never text that `new_string` leaves unchanged. If `old_string` is everything on the line except indentation and trailing punctuation, that is a whole-line rewrite: use `replace` with the same anchors. The same short fragment on several lines (a value, a name) may be replaced in one call. `remove_from`/`remove_to` are accepted as aliases.
+Replace part of a line — or the same fragment on several lines of a range — without retyping the rest. `match` is the exact text to find inside the anchored range, and `replacement` replaces every occurrence; the text around each match is left untouched. Send only the fragment that changes — never text that `replacement` leaves unchanged — and narrow `replace_from`/`replace_to` when only one occurrence should change. `match` only needs to be unique inside the anchored range, not file-wide. For a whole-line rewrite, use `replace` with the same anchors.
 
-The two boundary anchors must still match what was last shown; lines strictly inside the range are matched against the file as it is on disk.
+The two boundary anchors must still match what was last shown; lines strictly inside the range are searched as they are on disk.

package/tool-prompts/replace.md

@@ -1,3 +1,3 @@
-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 its first and last line, `text` is the exact replacement text, and `replace_from`/`replace_to` are accepted as aliases. Deleting every line empties the file, and the result names the empty-line anchor, so a follow-up `replace` can seed content without a `read`.
+Replace a range of lines (or a single line) in a text file by anchor. Deleting every line empties the file, and the result names the empty-line anchor, so a follow-up `replace` can seed content without a `read`.
 
 To change only part of a line without retyping the rest, use `replace_match` instead; it preserves every character the request does not name.

package/tool-prompts/transfer-guidelines.md

@@ -1,4 +1,4 @@
-- `copy`/`move`: only the source's two boundary rows and the destination line need serving; to append to the end of a file, anchor that file's last line with `direction: "after"` — not a marker line and not the block's own end.
+- `copy`/`move`: only the first and last marker rows and the destination line need anchors — grep the markers, the body is copied; to append to the end of a file, anchor that file's last line with `direction: "after"`.
 - `copy`/`move`: within one file the insertion point must fall before the source range's first line or after its last; anchoring the block's last line with `direction: "after"` (or its first line with `direction: "before"`) targets the gap right beside the block.
 - `copy`/`move`: `source_from` and `source_to` may live in a different file than `anchor`; an empty destination file is seeded with the copied or moved lines.
 - `move`: a batched cross-file move does not display the source file's diff; its removal commits with the batch, and the source file needs a read for fresh anchors.