pi-hashline-edit-pro 6.5.0 → 7.0.0

package/src/hashline/parse.ts

@@ -1,13 +1,13 @@
 import {
 	ANCHOR_LEN,
-	HASH_CLASS,
+	HASH_RUN,
 } from "./hash";
 import { ALPH_RE } from "./alphabet";
 import { NEW_CONTENT_NOT_ARRAY_MSG } from "../constants";
 import { splitWithEndings } from "../line-endings";
 import type { LineEnding } from "../normalize";
 
-const HASH_EXTRACT_RE = new RegExp(HASH_CLASS);
+const HASH_EXTRACT_RE = new RegExp(HASH_RUN);
 
 export type Anchor = { hash: string };
 
@@ -15,11 +15,11 @@ function diagRef(ref: string): string {
 	const trimmed = ref.trim();
 
 	if (!trimmed.length) {
-		return `[E_BAD_REF] Invalid anchor. Expected a 4-character anchor (letters only, e.g. "Hasu").`;
+		return `[E_BAD_REF] Invalid anchor. Expected a 5-character anchor (lowercase letters, e.g. "abcde") from read or grep output.`;
 	}
 
 	if (/^\d+/.test(trimmed)) {
-		return `[E_BAD_REF] Invalid anchor. Use the anchor alone (e.g. "Hasu"): no line numbers or trailing content.`;
+		return `[E_BAD_REF] Invalid anchor. Use the anchor alone (e.g. "abcde") with no line numbers or trailing content; anchors come from a read or grep row and are exactly 5 lowercase letters.`;
 	}
 	if (trimmed.includes("│") && trimmed.includes("\n")) {
 		const lines = trimmed.split(/\r?\n/);
@@ -28,29 +28,36 @@ function diagRef(ref: string): string {
 		const hashRe = HASH_EXTRACT_RE;
 		const firstMatch = first.match(hashRe);
 		const lastMatch = last.match(hashRe);
-		const firstHash = firstMatch?.[0] ?? "Hasu";
-		const lastHash = lastMatch?.[0] ?? "Hasu";
+		const firstHash = firstMatch?.[0] ?? "abcde";
+		const lastHash = lastMatch?.[0] ?? "abcde";
 		const preview = first.slice(0, 60);
-		return `[E_BAD_REF] Invalid anchor — remove_from and remove_to must each be a single bare 4-character anchor (letters only, e.g. "Hasu"), not a block with HASH│content. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as remove_from and "${lastHash}" as remove_to, and put the new content (without HASH│) in text.`;
+		return `[E_BAD_REF] Invalid anchor — remove_from and remove_to must each be a single bare 5-character anchor (lowercase letters, e.g. "abcde"), not a block with HASH│content. Received ${lines.length} lines starting "${preview}…" — use only the first hash "${firstHash}" as remove_from and "${lastHash}" as remove_to, and put the new content (without HASH│) in text.`;
 	}
 	if (trimmed.includes("│")) {
-		return `[E_BAD_REF] Invalid anchor "${trimmed}": use only the 4-character anchor, drop everything from "│" onward.`;
+		return `[E_BAD_REF] Invalid anchor "${trimmed.slice(0, 60)}": use only the 5-character anchor, drop everything from "│" onward (any line number, gutter, and content).`;
 	}
 
-	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 4-character anchor (letters only, e.g. "Hasu").`;
+	return `[E_BAD_REF] Invalid anchor "${trimmed.slice(0, 60)}". Expected a 5-character anchor (lowercase letters, e.g. "abcde") from read or grep output.`;
 }
 
-export function parseHashRef(ref: string): Anchor {
+export function parseHashRef(ref: string, warnings?: string[], label = "anchor"): Anchor {
 	const trimmed = ref.trim();
+	const unquoted = trimmed.length >= 2 && (trimmed[0] === '"' || trimmed[0] === "'") && trimmed[trimmed.length - 1] === trimmed[0]
+		? trimmed.slice(1, -1).trim()
+		: trimmed;
 
 	if (
-		trimmed.length === ANCHOR_LEN &&
-		ALPH_RE.test(trimmed)
+		unquoted.length === ANCHOR_LEN &&
+		ALPH_RE.test(unquoted)
 	) {
-		return { hash: trimmed };
+		const hash = unquoted.toLowerCase();
+		if (hash !== unquoted) {
+			warnings?.push(`[W_ANCHOR_CASE] ${label} "${unquoted}" was lowercased to "${hash}".`);
+		}
+		return { hash };
 	}
 
-	throw new Error(diagRef(ref));
+	throw new Error(diagRef(unquoted));
 }
 
 const JSON_ENVELOPE_RE = /^\s*\["(.*)"\]\.\s*$/;

package/src/hashline/resolve.ts

@@ -130,17 +130,17 @@ const ITEM_KS = new Set(["text", "remove_from", "remove_to"]);
 function assertBounds(edit: Record<string, unknown>): void {
 	if ("remove_from" in edit && typeof edit.remove_from !== "string") {
 		throw new Error(
-			`[E_BAD_SHAPE] Field "remove_from" must be an anchor string (4-char anchor).`,
+			`[E_BAD_SHAPE] Field "remove_from" must be an anchor string (5-char anchor).`,
 		);
 	}
 	if ("remove_to" in edit && typeof edit.remove_to !== "string") {
 		throw new Error(
-			`[E_BAD_SHAPE] Field "remove_to" must be an anchor string (4-char anchor).`,
+			`[E_BAD_SHAPE] Field "remove_to" must be an anchor string (5-char anchor).`,
 		);
 	}
 	if (typeof edit.remove_from !== "string" || typeof edit.remove_to !== "string") {
 		throw new Error(
-			`[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (4-char anchors from read output).`,
+			`[E_BAD_SHAPE] The edit requires "remove_from" and "remove_to" anchor strings (5-char anchors from read output).`,
 		);
 	}
 }
@@ -175,18 +175,32 @@ function resolveParsedEdit(removeFrom: string, removeTo: string, parsed: ParsedT
 	}) as [string, string];
 	return {
 		content_lines: replaceLines,
-		hash_bounds: [parseHashRef(bounds[0]), parseHashRef(bounds[1])],
+		hash_bounds: [parseHashRef(bounds[0], warnings, "remove_from"), parseHashRef(bounds[1], warnings, "remove_to")],
 		...(parsed.separators.some((separator) => separator !== undefined) ? { content_separators: parsed.separators } : {}),
 	};
 }
 
 export const ANCHOR_ROW_RE = new RegExp(`^([+-]?)(${HASH_RUN})│`);
 
+const NUMBERED_ANCHOR_ROW_RE = new RegExp(`^\\s*\\d+\\s*[:-]?\\s*│\\s*(${HASH_RUN})│`);
+
+const PAREN_LINE_SUFFIX_RE = new RegExp(`^(${HASH_RUN})\\s*\\(\\s*(?:line|lines)\\s+\\d+(?:\\s*[-–—]\\s*\\d+)?\\s*\\)$`, "i");
+
 export function stripAnchorRow(
 	trimmed: string,
 	entryLabel: string,
 	warnings?: string[],
 ): string {
+	const numbered = trimmed.match(NUMBERED_ANCHOR_ROW_RE);
+	if (numbered) {
+		warnings?.push(`[W_BAD_REF] Stripped line-numbered row from ${entryLabel} "${clipLine(trimmed, 48)}".`);
+		return numbered[1]!;
+	}
+	const paren = trimmed.match(PAREN_LINE_SUFFIX_RE);
+	if (paren) {
+		warnings?.push(`[W_BAD_REF] Stripped "(line N)" suffix from ${entryLabel} "${clipLine(trimmed, 48)}".`);
+		return paren[1]!;
+	}
 	const match = trimmed.match(ANCHOR_ROW_RE);
 	if (!match) return trimmed;
 	const marker =
@@ -435,17 +449,17 @@ export function assertRangeServed(
     rows.push(fmtRow(hash, clipLine(content)));
   }
   const location = filePath ? ` in ${filePath}` : "";
+  const rangeDescription = `the replaced range (lines ${startLine}-${endLine})${location}`;
   const first = mismatchLines[0]!;
-  const mismatchText =
-    mismatchLines.length === 1
-      ? `Line ${first} of the replaced range (lines ${startLine}-${endLine})${location} does not match`
-      : `${mismatchLines.length} of ${rangeLength} line(s) in the replaced range (lines ${startLine}-${endLine})${location} do not match`;
+  const mismatchText = mismatchLines.length === 1
+    ? `Line ${first} of ${rangeDescription} was never shown or changed on disk`
+    : `${mismatchLines.length} of ${rangeLength} line(s) in ${rangeDescription} were never shown or changed on disk`;
   const capHint =
     rangeLength > shownLength
       ? `\n\n[The range has ${rangeLength} lines; showing the first ${shownLength}. Call read()${filePath ? ` on ${filePath}` : ""} with offset=${startLine + shownLength} to see the rest.]`
       : "\n\nRetry with the fresh anchors above without a read.";
   const message =
-    `[E_RANGE_STALE] ${mismatchText} what was shown. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
+    `[E_RANGE_STALE] ${mismatchText}. Current range with fresh anchors:\n\n${rows.join("\n")}${capHint}`;
   throw new RangeStaleError(message, shownHashes, shownMap);
 }
 

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";
@@ -20,23 +20,19 @@ export { assertInsertReq, type InsertReq };
 
 const insertAnchorSchema = Type.String({
   description:
-    "4-char anchor of the line to insert next to.",
+    "5-char anchor of the line to insert next to.",
 });
 
-const insertDirectionSchema = Type.Union(
-  [Type.Literal("after"), Type.Literal("before")],
-  { description: '"after" or "before"' },
-);
+const insertDirectionSchema = Type.Unsafe<"after" | "before">({
+  type: "string",
+  enum: ["after", "before"],
+  description: '"after" or "before"',
+});
 const insertTextSchema = Type.String({
   description:
     `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 +46,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,
@@ -63,7 +59,7 @@ export function parseInsertAnchor(raw: string): { ref: Anchor; warnings: string[
   const trimmedAnchor = raw.trim();
   const warnings: string[] = [];
   const anchorText = stripAnchorRow(trimmedAnchor, "anchor entry", warnings);
-  return { ref: parseHashRef(anchorText), warnings };
+  return { ref: parseHashRef(anchorText, warnings, "anchor"), warnings };
 }
 
 export function buildInsertEdit(

package/src/payload-contract.ts

@@ -10,14 +10,14 @@ const textSchema = Type.String({
 
 const removeFromSchema = Type.String({
   description:
-    "4-char anchor of the FIRST line to remove.",
+    "5-char anchor of the FIRST line to remove.",
 });
 
 const removeToSchema = Type.String({
   description:
-    "4-char anchor of the LAST line to remove.",
+    "5-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.",
 });
@@ -59,11 +59,19 @@ export type RawReqParams = {
 };
 
 const ROOT_KS = new Set(["path", "remove_from", "remove_to", "text"]);
+
+const REPLACE_MATCH_SHAPE_KEYS = ["match", "replacement", "old_string", "new_string"];
+
+function replaceMatchFieldHint(request: Record<string, unknown>): string | undefined {
+  if (!REPLACE_MATCH_SHAPE_KEYS.some((key) => key in request)) return undefined;
+  return 'This looks like a replace_match request: to change part of a line, call replace_match with "replace_from", "replace_to", "match", and "replacement"; replace takes "remove_from", "remove_to", and "text".';
+}
+
 export function assertReq(request: unknown): asserts request is ReqParams {
   if (!isRec(request)) {
     throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
   }
-  rejectUnknownFields(request, ROOT_KS, "Edit request");
+  rejectUnknownFields(request, ROOT_KS, "Edit request", replaceMatchFieldHint(request));
   if (request.path !== undefined && typeof request.path !== "string") {
     throw new Error('[E_BAD_SHAPE] Edit request field "path" must be a string when provided.');
   }
@@ -124,7 +132,7 @@ export function assertInsertReq(request: unknown): asserts request is InsertReq
     throw new Error('[E_BAD_SHAPE] Insert request field "path" must be a string when provided.');
   }
   if (typeof request.anchor !== "string" || request.anchor.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (4-char anchor from read output).');
+    throw new Error('[E_BAD_SHAPE] Insert request requires an "anchor" string (5-char anchor from read output).');
   }
   if (request.direction !== "before" && request.direction !== "after") {
     throw new Error('[E_BAD_SHAPE] Insert request "direction" must be "before" or "after".');
@@ -154,13 +162,13 @@ export function assertTransferReq(request: unknown): asserts request is Transfer
     throw new Error('[E_BAD_SHAPE] Copy/move request field "path" must be a string when provided.');
   }
   if (typeof request.source_from !== "string" || request.source_from.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Copy/move request requires a "source_from" string (4-char anchor from read output).');
+    throw new Error('[E_BAD_SHAPE] Copy/move request requires a "source_from" string (5-char anchor from read output).');
   }
   if (typeof request.source_to !== "string" || request.source_to.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Copy/move request requires a "source_to" string (4-char anchor from read output).');
+    throw new Error('[E_BAD_SHAPE] Copy/move request requires a "source_to" string (5-char anchor from read output).');
   }
   if (typeof request.anchor !== "string" || request.anchor.length === 0) {
-    throw new Error('[E_BAD_SHAPE] Copy/move request requires an "anchor" string (4-char anchor from read output).');
+    throw new Error('[E_BAD_SHAPE] Copy/move request requires an "anchor" string (5-char anchor from read output).');
   }
   if (request.direction !== "before" && request.direction !== "after") {
     throw new Error('[E_BAD_SHAPE] Copy/move request "direction" must be "before" or "after" (the anchor is the destination line).');
@@ -177,22 +185,27 @@ export interface ReplaceMatchReq {
   replacement: string;
 }
 
-export function singleLineFragment(field: "match" | "replacement", raw: string): string {
+export function singleLineMatch(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.`,
+      `[E_BAD_SHAPE] match 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; a match that spans lines belongs to replace.`,
     );
   }
-  if (field === "match" && fragment.length === 0) {
+  if (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 replacementFragment(raw: string): string {
+  const text = toLF(raw);
+  return text.endsWith("\n") ? text.slice(0, -1) : text;
+}
+
 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.");
@@ -213,8 +226,7 @@ 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.');
   }
-  singleLineFragment("match", within.match);
-  singleLineFragment("replacement", within.replacement);
+  singleLineMatch(within.match);
   assertNoNul([within.replacement]);
 }
 
@@ -245,23 +257,19 @@ export function getReplaceMatchInput(args: unknown): { path?: string; replace_fr
 
 const replaceMatchFromSchema = Type.String({
   description:
-    "4-char anchor of the FIRST line of the range searched.",
+    "5-char anchor of the FIRST line of the range searched.",
 });
 const replaceMatchToSchema = Type.String({
   description:
-    "4-char anchor of the LAST line of the range searched; same as `replace_from` for a single line.",
+    "5-char anchor of the LAST line of the range searched; same as `replace_from` for a single line.",
 });
 const replaceMatchMatchSchema = Type.String({
   description:
-    "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. If `match` is an entire single-line range except indentation and trailing punctuation, that is a whole-line match: use `replace` instead.",
+    "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 replaceMatchReplacementSchema = Type.String({
   description:
-    `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.`,
-});
-const replaceMatchPathRequiredSchema = 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. A single trailing line break is accepted and dropped (a value that is only a line break counts as ""); an interior or leading line break splits the replacement into lines, and new lines inherit the file's line endings. The text around each match is kept byte-for-byte.`,
 });
 
 export const replaceMatchToolSchema = Type.Object(
@@ -278,7 +286,7 @@ export function buildReplaceMatchToolSchema(requirePath: boolean): typeof replac
   if (!requirePath) return replaceMatchToolSchema;
   return Type.Object(
     {
-      path: replaceMatchPathRequiredSchema,
+      path: pathRequiredSchema,
       replace_from: replaceMatchFromSchema,
       replace_to: replaceMatchToSchema,
       match: replaceMatchMatchSchema,

package/src/prompts.ts

@@ -14,7 +14,7 @@ const GUIDELINE_IDS_BY_NAME: Record<string, readonly string[]> = {
   "copy-guidelines.md": ["copy-single-anchor"],
   "move-guidelines.md": ["move-same-place"],
   "transfer-guidelines.md": ["transfer-boundary-serving", "transfer-same-file", "transfer-cross-file", "transfer-batch-move"],
-  "grep-guidelines.md": ["grep-literal", "grep-row-markers"],
+  "grep-guidelines.md": ["grep-literal"],
   "undo-last-change-guidelines.md": ["undo-single-level", "undo-write-clears", "undo-cross-file-move"],
 };
 

package/src/read.ts

@@ -17,9 +17,9 @@ import { lineHashes, fmtRegion, fmtRow, HASH_SEP, MAX_HASH_LINES, parseHashRef,
 import { toCwd } from "./paths";
 import { abortIf, isRec, makePrepareArguments, numberedRead, visLines, splitLines } from "./utils";
 import { loadP, loadGuidelines, type Guideline } from "./prompts";
-import { withReadPrompts, DEFAULT_EDIT_FLAGS, type EditToolFlags } from "./edit-common";
+import { withReadPrompts, DEFAULT_EDIT_FLAGS, staleAnchorMessage, type EditToolFlags } from "./edit-common";
 import { valAccess } from "./validation";
-import { withAnchorSession, adoptAnchors, ownerOf, ownersDifferingOnlyByCase, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
+import { withAnchorSession, adoptAnchors, ownerOf, formatAnchorReclaimNotice, takeReclaimedPaths } from "./anchor-registry";
 import { serveRows } from "./served";
 import { snapshotCache } from "./hash-store/cache";
 import { Text } from "@earendil-works/pi-tui";
@@ -208,9 +208,7 @@ export function resolveReadOffset(
 	const ref = parseHashRef(offset);
 	const owner = ownerOf(ref.hash);
 	if (owner === undefined) {
-		const folded = ownersDifferingOnlyByCase(ref.hash);
-		const hint = folded.length > 0 ? ` Anchors are case-sensitive; ${folded.map((match) => `"${match.anchor}"`).join(", ")} differs only in case.` : "";
-		throw new Error(`[E_STALE_ANCHOR] "${ref.hash}" is not owned in this session.${hint} Use a line number, or read again for fresh anchors.`);
+		throw new Error(staleAnchorMessage(ref.hash, "Use a line number, or read again for fresh anchors."));
 	}
 	if (owner.path !== resolvedPath) {
 		throw new Error(`[E_STALE_ANCHOR] "${ref.hash}" is owned by ${owner.path}. Use a line number, or read ${owner.path} to use that anchor.`);
@@ -320,7 +318,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-diff.ts

@@ -114,7 +114,7 @@ export function disambiguateDuplicateAnchors(diff: string): string {
     if (!match || match[1] !== "-") return line;
     if (!live.has(match[2]!)) return line;
     changed = true;
-    return `-    │${line.slice(match[0].length)}`;
+    return `-${" ".repeat(ANCHOR_LEN)}│${line.slice(match[0].length)}`;
   });
   return changed ? out.join("\n") : diff;
 }

package/src/replace-match.ts

@@ -12,7 +12,8 @@ import {
   buildReplaceMatchToolSchema,
   getReplaceMatchInput,
   normReq,
-  singleLineFragment,
+  replacementFragment,
+  singleLineMatch,
   type ReplaceMatchReq,
 } from "./payload-contract";
 import { literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
@@ -46,26 +47,6 @@ export interface MatchPlan {
   servedOverride?: ReadonlyMap<string, string>;
 }
 
-function replaceAllOccurrences(
-  line: string,
-  matchText: string,
-  replacementText: string,
-): { text: string; count: number } {
-  const parts: string[] = [];
-  let cursor = 0;
-  let count = 0;
-  for (;;) {
-    const found = line.indexOf(matchText, cursor);
-    if (found < 0) break;
-    parts.push(line.slice(cursor, found), replacementText);
-    cursor = found + matchText.length;
-    count += 1;
-  }
-  if (count === 0) return { text: line, count: 0 };
-  parts.push(line.slice(cursor));
-  return { text: parts.join(""), count };
-}
-
 function linesToPayloadText(lines: string[]): string {
   if (lines.length === 0) return "";
   const joined = lines.join("\n");
@@ -143,7 +124,33 @@ export function parseMatchAnchors(req: ReplaceMatchReq): { refs: MatchRefs; warn
   const warnings: string[] = [];
   const from = stripAnchorRow(req.replace_from.trim(), "replace_from entry", warnings);
   const to = stripAnchorRow(req.replace_to.trim(), "replace_to entry", warnings);
-  return { refs: { from: parseHashRef(from), to: parseHashRef(to) }, warnings };
+  return { refs: { from: parseHashRef(from, warnings, "replace_from"), to: parseHashRef(to, warnings, "replace_to") }, warnings };
+}
+
+function replacementLinesFor(raw: string): string[] {
+  const fragment = replacementFragment(raw);
+  return fragment.length === 0 ? [""] : fragment.split("\n");
+}
+
+function replaceInLine(
+  line: string,
+  matchText: string,
+  replacementLines: readonly string[],
+): { lines: string[]; count: number } {
+  const lines: string[] = [""];
+  let cursor = 0;
+  let count = 0;
+  for (;;) {
+    const found = line.indexOf(matchText, cursor);
+    if (found < 0) break;
+    lines[lines.length - 1] += line.slice(cursor, found) + replacementLines[0]!;
+    for (let index = 1; index < replacementLines.length; index++) lines.push(replacementLines[index]!);
+    cursor = found + matchText.length;
+    count += 1;
+  }
+  if (count === 0) return { lines: [line], count: 0 };
+  lines[lines.length - 1] += line.slice(cursor);
+  return { lines, count };
 }
 
 export function buildReplaceMatchEdit(
@@ -153,8 +160,8 @@ export function buildReplaceMatchEdit(
   displayPath: string,
   served?: ReadonlyMap<string, string>,
 ): MatchPlan {
-  const matchText = singleLineFragment("match", req.match);
-  const replacementText = singleLineFragment("replacement", req.replacement);
+  const matchText = singleLineMatch(req.match);
+  const fragmentLines = replacementLinesFor(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);
@@ -163,11 +170,12 @@ export function buildReplaceMatchEdit(
   assertBoundaryLinesServed(fileLines, preload.fileHashes, served, start, end, displayPath);
   const rangeLines = fileLines.slice(start - 1, end);
   let count = 0;
-  const replacementLines = rangeLines.map((line) => {
-    const result = replaceAllOccurrences(line, matchText, replacementText);
+  const replacementLines: string[] = [];
+  for (const line of rangeLines) {
+    const result = replaceInLine(line, matchText, fragmentLines);
     count += result.count;
-    return result.text;
-  });
+    replacementLines.push(...result.lines);
+  }
   if (count === 0) {
     throw new Error(notFoundMessage(displayPath, start, end, preload.fileHashes, fileLines, linesToPayloadText(rangeLines), matchText));
   }

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/src/replace.ts

@@ -10,7 +10,7 @@ import {
 } from "./replace-diff";
 import { readNormFile, type NormFile } from "./file-reader";
 import { editToolSchema, buildEditToolSchema, type ReqParams, type RawReqParams, assertReq, normReq } from "./payload-contract";
-import { literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
+import { isRec, literalEscapeHints, makePrepareArguments, splitLines } from "./utils";
 import { editResultSchema, withStructuredErrors } from "./structured";
 import { loadP, loadGuidelines } from "./prompts";
 import { type FileIdentity } from "./fs-write";
@@ -293,6 +293,16 @@ type ToolDef = ToolDefinition<
   RRState
 > & { renderShell?: "default" | "self" };
 
+const prepareRemoveArguments = makePrepareArguments("remove");
+
+function prepareReplaceArguments(args: unknown): unknown {
+  const prepared = prepareRemoveArguments(args);
+  if (isRec(prepared) && typeof prepared.text !== "string" && ("match" in prepared || "replacement" in prepared)) {
+    throw new Error('[E_BAD_SHAPE] Replace request received "match"/"replacement" instead of "remove_from"/"remove_to"/"text". To change part of a line, call replace_match with "replace_from", "replace_to", "match", and "replacement".');
+  }
+  return prepared;
+}
+
 export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef {
   const prompted = withReplacePrompts({
     description: loadP("../tool-prompts/replace.md"),
@@ -309,7 +319,7 @@ export function buildToolDef(flags: EditToolFlags = DEFAULT_EDIT_FLAGS): ToolDef
     promptSnippet: prompted.snippet,
     promptGuidelines: prompted.guidelines,
     ...editToolBase,
-    prepareArguments: makePrepareArguments("remove"),
+    prepareArguments: prepareReplaceArguments,
     renderCall: editRenderCallWrapper(compPreview),
     renderResult: editRenderResultWrapper,
     async execute(_toolCallId, params, signal, _onUpdate, ctx) {

package/src/write-hook.ts

@@ -1,17 +1,18 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { HASH_CLASS } from "./hashline/alphabet";
+import { HASH_RUN } from "./hashline/alphabet";
 import { HASH_SEP } from "./hashline/hash";
 import { sessionContextReadable, servedForPath, withAnchorSession, type AnchorSessionContext } from "./anchor-registry";
 import { resolveInCwd } from "./fs-write";
 import { abortIf, splitLines, isRec } from "./utils";
 import type { ModelLike } from "./model-gate";
 
-const HASH_ECHO_RE = new RegExp(`^(?: *[0-9]+(?: │ |[:-]│ ))?[+ -]?(${HASH_CLASS})${HASH_SEP}`);
+const HASH_ECHO_RE = new RegExp(`^(?: *[0-9]+(?: │ |[:-]│ ))?[+ -]?(${HASH_RUN})${HASH_SEP}`);
 
 function searchEcho(lines: string[], served: ReadonlyMap<string, string> | ReadonlySet<string>): { line: number; hash: string } | undefined {
   for (let i = 0; i < lines.length; i++) {
     const match = HASH_ECHO_RE.exec(lines[i]!);
-    if (match && served.has(match[1]! as never)) return { line: i + 1, hash: match[1]! };
+    const hash = match?.[1]?.toLowerCase();
+    if (hash !== undefined && served.has(hash)) return { line: i + 1, hash };
   }
   return undefined;
 }

package/tool-prompts/copy-guidelines.md

@@ -1 +1 @@
-- `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`: the same anchor in `source_from` and `source_to` copies one line.

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-guidelines.md

@@ -1,2 +1 @@
-- `grep`: set `literal: true` when the pattern contains regex metacharacters.
-- `grep`: `N:│` rows are matches and `N-│` rows are context;
+- `grep`: set `literal: true` to match the text exactly, when characters such as `(`, `[`, `.`, or `*` in it must not act as regex.

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 5-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. 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.
+A cross-file move whose source file also gets other edits in the same message runs outside any batch: same-message edits to its destination file can then either abort or make the move fail, so send that move in a separate message.