pi-hashline-edit-pro 1.2.0 → 2.0.0

package/README.md

@@ -42,8 +42,8 @@ kQm│}
 ```json
 {
   "path": "src/main.ts",
-  "hash_range_inclusive": ["szJ", "szJ"],
-  "content_lines": ["  console.log('hi');"]
+  "hash_bounds": ["szJ", "szJ"],
+  "new_content": "  console.log('hi');"
 }
 ```
 
@@ -77,31 +77,30 @@ Edge cases:
 
 The built-in `edit` tool is disabled — `replace` is the only edit path; call it with the hash anchors from `read` output.
 
-Exactly one edit per call, with `hash_range_inclusive` and `content_lines` at the top level of the request:
+Exactly one edit per call, with `hash_bounds` and `new_content` at the top level of the request:
 
 ```json
 {
   "path": "src/main.ts",
-  "hash_range_inclusive": ["szJ", "kQm"],
-  "content_lines": ["  console.log('hi');", "}"]
+  "hash_bounds": ["szJ", "kQm"],
+  "new_content": "  console.log('hi');\n}"
 }
 ```
 
 | Field | Description |
 | --- | --- |
-| `hash_range_inclusive` | Pair of 3-char hashes from `read` output marking the first and last line of the range to replace (inclusive). |
-| `content_lines` | Replacement content, one string per line; entries must not contain line breaks. Use `[]` to delete the range. |
+| `hash_bounds` | Pair of 3-char hashes from `read` output marking the first and last line of the range to replace (inclusive). |
+| `new_content` | Replacement content as a single string with `\n` line separators; a trailing newline is the last line's ending, not an extra empty line. Use `""` to delete the range. |
 
 Behavior:
 
 - **Validation before any file I/O.** Unknown fields, missing fields, wrong types, and malformed anchors are rejected with `[E_BAD_SHAPE]` / `[E_BAD_REF]`. The edit applies against the pre-edit snapshot, so all hashes in the request come from one consistent file state.
-- **Rejected dialects.** The `changes` array dialect and the legacy `oldText`/`newText` dialect are rejected with `[E_LEGACY_SHAPE]`; the error tells you to send `{hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}`.
 - **Autocorrections** (all accompanied by a warning unless noted):
-  - A `HASH│` prefix accidentally left on a `content_lines` entry is stripped.
-  - Diff-preview rows (`+HASH│…`, `-HASH│…`, `-   │…`) pasted into `content_lines` have their markers stripped. Numbered deletion rows (`-1    foo`) and unified-diff lines are written literally — never silently altered.
+  - A `HASH│` prefix accidentally left on a `new_content` line is stripped.
+  - Diff-preview rows (`+HASH│…`, `-HASH│…`, `-   │…`) pasted into `new_content` have their markers stripped. Numbered deletion rows (`-1    foo`) and unified-diff lines are written literally — never silently altered.
   - A reversed range (start hash after end hash) is swapped and applied.
   - A duplicated boundary line — the classic `}`, `});`, or `} else {` pasted twice — is silently removed; the duplicate never reaches the file.
-  - `file_path` is accepted as an alias for `path`; a JSON-string `content_lines` is parsed into an array.
+  - `file_path` is accepted as an alias for `path`.
 - **Response.** With auto-read enabled (the default), a successful edit returns the post-edit diff — the same `+HASH│` / `-   │` / ` HASH│` rows the user sees — instead of the summary. With auto-read disabled, the edit reports `Successfully replaced in {path}. Added X line(s), removed Y line(s).` plus any warnings, and no diff is shown to the model. Warnings are appended in both modes. An edit that produces identical content reports `No changes made` and never rotates anchors. The post-edit diff is exposed to the host UI via `details.diff` — the TUI always shows it — and reaches the model-visible text only while auto-read is on.
 - **Undo.** Every successful replace is undoable once via `undo_last_replace` — see [Undo](#undo).
 
@@ -121,7 +120,7 @@ A no-op replace never changes the file, so anchors remain valid. On first run af
 Enabled by default. After a successful `write` that changes the file, the extension reads the file and appends an `--- Auto-read (hashline anchors) ---` block to the result, so the model gets immediate `HASH│content` anchors without a separate `read` call.
 
 - A no-op `replace` produces no diff — the file is unchanged, so existing anchors remain valid.
-- After `replace` / `undo_last_replace`, the success summary is replaced by the post-edit diff (the same `+HASH│` / `-   │` / ` HASH│` rows used for replace) plus any warnings, so the model sees the change like a git diff instead of line counts; no anchor block is appended — call `read` for fresh anchors.
+- After `replace` / `undo_last_replace`, the success summary is replaced by the post-edit diff (the same `+HASH│` / `-   │` / ` HASH│` rows used for replace) plus any warnings, so the model sees the change like a git diff instead of line counts; no anchor block is appended — the diff rows themselves are the fresh anchors (`+HASH│` and ` HASH│` rows carry the current hashes, and unchanged lines keep their previous hashes), so follow-up edits can anchor on the diff directly; call `read` when you want the full file's anchors.
 - With auto-read disabled, `replace` / `undo_last_replace` results keep the plain summary in the model-visible text — no diff and no anchor block reach the model (the post-edit diff is still shown to the user).
 - After `write`, the block dumps from the top of the file. For files over 2000 lines, the dump is truncated with a pagination hint — use `read` with `offset` to continue.
 - Auto-read keeps a 50KB display budget: lines over 50KB are skipped with a marker instead of their content (use `read` for lines up to 200KB).
@@ -157,13 +156,12 @@ Settings live in `~/.config/pi-hashline-edit-pro/config.json`, created automatic
 
 | Code | Meaning |
 | --- | --- |
-| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields, or a `content_lines` entry contains a line break. |
-| `[E_BAD_REF]` | An anchor in `hash_range_inclusive` is not a bare 3-char hash. |
+| `[E_BAD_SHAPE]` | Request envelope or edit item has unknown, missing, or wrongly-typed fields (e.g. `new_content` must be a string with `\n` line separators). |
+| `[E_BAD_REF]` | An anchor in `hash_bounds` is not a bare 3-char hash. |
 | `[E_STALE_ANCHOR]` | An anchor does not match any line in the current file; call `read` for fresh anchors. |
 | `[E_AMBIGUOUS_ANCHOR]` | An anchor matches multiple lines; call `read` for fresh anchors. |
-| `[E_INVALID_PATCH]` | A `content_lines` entry is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`) — the marker is stripped automatically with a warning. |
-| `[E_BARE_HASH_PREFIX]` | A `content_lines` entry starts with a hash-like `HASH│` prefix — the prefix is stripped automatically with a warning. |
-| `[E_LEGACY_SHAPE]` | The request uses an unsupported dialect: `oldText`/`newText` fields or a `changes` array. |
+| `[E_INVALID_PATCH]` | A `new_content` line is a diff-preview row (`+HASH│`, `-HASH│`, `-   │`) — the marker is stripped automatically with a warning. |
+| `[E_BARE_HASH_PREFIX]` | A `new_content` line starts with a hash-like `HASH│` prefix — the prefix is stripped automatically with a warning. |
 | `[E_BAD_OP]` | Range start line is after range end line — the pair is swapped automatically with a warning. |
 | `[E_WOULD_EMPTY]` | An edit would empty a non-empty file; use `write` instead. |
 | `[E_NOT_FOUND]` | The path does not exist. |
@@ -187,7 +185,7 @@ The alphabet is sized for an LLM consumer: the model tokenizes rather than squin
 - **Autocorrection only when the intent is unambiguous**, and always visible: hash-prefix and diff-row stripping produce a warning; the boundary-duplication fix is silent because the duplicate never reaches the file. Literal content is never silently altered when the intent is ambiguous (numbered deletion rows and unified-diff lines are written verbatim).
 - **Byte-exact preservation.** UTF-8 BOMs, CRLF, LF, and CR-only line endings, file permissions, and trailing newlines survive edits and undo; files with mixed line endings are normalized to a single line ending on edit.
 - **Atomic and ordered writes.** Files are written via temp-file-then-rename; symlink chains are resolved so the target is updated without replacing the symlink; hard-linked files are updated in place; concurrent edits to the same underlying file serialize through a per-target mutation queue.
-- **One edit per call.** The request shape stays `{path, hash_range_inclusive, content_lines}` from schema through validation to application; there is no batching dialect.
+- **One edit per call.** The request shape stays `{path, hash_bounds, new_content}` from schema through validation to application; there is no batching dialect.
 
 ## Troubleshooting
 
@@ -195,7 +193,7 @@ The alphabet is sized for an LLM consumer: the model tokenizes rather than squin
 - **Reset the hash store.** Anchors live in `~/.config/pi-hashline-edit-pro/hash-store.sqlite` (with `-wal`/`-shm` sidecars). Quit pi, delete those three files, and the store is rebuilt on the next session. Anchor history is lost, but no project files are touched.
 - **Upgrading.** A hash-allocation change clears the hash store once on the first run after upgrade — anchors are rebuilt on the next read and undo history is lost, but no project files are touched.
 - **Corrupt store.** If the store fails its health check it is renamed to `hash-store.sqlite.corrupt-<timestamp>` (plus `-wal`/`-shm` variants) and rebuilt automatically; the quarantined files can be deleted once a healthy store exists.
-- **Legacy migration.** On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`, which can be deleted.
+- **Legacy migration.** On first run after upgrading from an older version, the previous `hash-store.json` is imported once and renamed to `hash-store.json.bak`, which can be deleted. Legacy snapshots containing duplicate hashes are skipped and rebuilt on the next read.
 - **`[E_UNDO_UNAVAILABLE]`.** The edit was refused because the undo record could not be written — check disk space and that the config directory is writable, then retry.
 
 ## Development

package/index.ts

@@ -7,6 +7,7 @@ import { regRead, fmtReadPreview } from "./src/read";
 import type { RMetrics } from "./src/replace-response";
 import { extractWarnings } from "./src/replace-render";
 import { MAX_HASH_LINES } from "./src/hashline";
+import { AUTO_READ_MAX } from "./src/constants";
 import {
   readConfig,
   toggleAutoRead,
@@ -81,6 +82,7 @@ export default function (pi: ExtensionAPI): void {
           fileHashes,
           absolutePath,
           DEFAULT_MAX_BYTES,
+          AUTO_READ_MAX,
         );
         return {
           content: [

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "1.2.0",
+  "version": "2.0.0",
   "type": "module",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 62-symbol, perfect hashing)",
   "main": "index.ts",

package/prompts/read-guidelines.md

@@ -1,2 +1,2 @@
 - `read`: call before `replace` when you need fresh HASH anchors for a file.
-- `read`: call again after any edit to that file — changed lines get new anchors.
+- `read`: call again after any edit to that file — changed lines get new anchors (the post-edit diff rows from replace/undo also carry fresh anchors for the changed range).

package/prompts/replace-guidelines.md

@@ -1,6 +1,7 @@
-- `replace`: hash_range_inclusive must use only anchors from the most recent read of the same file.
-- `replace`: hash_range_inclusive marks the exact lines that are REMOVED, and content_lines is their complete replacement applied in order; nothing outside the range changes. Every line inside the range that is not reproduced byte-exact in content_lines is deleted from the file — including closing braces and other structural lines.
+- `replace`: hash_bounds must use only anchors from the most recent read of the same file.
+- `replace`: hash_bounds marks the exact lines that are REMOVED, and new_content is their complete replacement applied in order; nothing outside the range changes. Every line inside the range that is not reproduced byte-exact in new_content is deleted from the file — including closing braces and other structural lines.
 - `replace`: minimize the replaced range — anchor only the lines that actually change, so few unchanged lines must be reproduced byte-exact.
-- `replace`: to replace a single line, repeat its hash in both positions of hash_range_inclusive: ["<HASH>", "<HASH>"] — never extend the range to neighboring lines for a one-line edit.
-- `replace`: content_lines is a native JSON array of strings — never a serialized JSON string. When copying a line from read output, remove its HASH│ prefix and keep the leading whitespace exactly as shown.
-- `replace`: content_lines entries are single lines — never embed a line break inside an entry; pass each line as its own array entry.
+- `replace`: to replace a single line, repeat its hash in both positions of hash_bounds: ["<HASH>", "<HASH>"] — never extend the range to neighboring lines for a one-line edit.
+- `replace`: new_content is a single string with \n line separators — never a JSON array. When copying a line from read output, remove its HASH│ prefix and keep the leading whitespace exactly as shown.
+- `replace`: a trailing newline in new_content is the last line's ending, not an extra empty line; use an explicit empty line (e.g. ending with \n\n) to add a blank line.
+- `replace`: when auto-read shows the post-edit diff, its rows are the fresh anchors for the new file — `+HASH│` and ` HASH│` rows carry current hashes and unchanged lines keep their previous hashes, so you can anchor follow-up edits on the diff without re-reading.

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

@@ -1 +1,2 @@
-- `undo_last_replace`: reverts only the most recent replace on the file — any write to the file clears the undo history, so call it immediately after a bad replace.
+- `undo_last_replace`: reverts only the most recent replace on the file — any write to the file clears the undo history, so call it immediately after a bad replace.
+- `undo_last_replace`: when auto-read shows the post-edit diff, its `+HASH│` and ` HASH│` rows are the fresh anchors for the restored file, so follow-up edits can anchor on the diff without re-reading.

package/src/constants.ts

@@ -5,6 +5,6 @@ export const MAX_READ_LINE_BYTES = 200 * 1024;
 
 export const HASH_STORE_BUSY_TIMEOUT = 1000;
 export const HASH_STORE_VERSION = 5;
-export const CONTENT_LINES_NOT_STRING_MSG =
-  `[E_BAD_SHAPE] "content_lines" must be a native JSON array of strings, not a JSON string.`
-  + ` Do not serialize the array (e.g. '["line1", "line2"]') — pass it as a proper JSON array: ["line1", "line2"].`;
+export const NEW_CONTENT_NOT_STRING_MSG =
+  `[E_BAD_SHAPE] "new_content" must be a string with \\n line separators, not an array.`
+  + ` Do not pass an array of lines — pass the replacement text as one string: "line1\\nline2". Use "" to delete a range.`;

package/src/hash-store.ts

@@ -318,6 +318,10 @@ async function migrateLegacy(db: DatabaseSync): Promise<void> {
   const rows: [string, string, number, string, number][] = [];
   for (const [key, value] of Object.entries(raw)) {
     if (!isValidSnapshot(value)) continue;
+    if (new Set(value.hashes).size !== value.hashes.length) {
+      console.warn(`Skipped legacy snapshot with duplicate hashes for ${key}; it will be re-hashed on next read.`);
+      continue;
+    }
     rows.push([
       key,
       contentChecksum(value.content),

package/src/hashline/apply.ts

@@ -65,8 +65,8 @@ function resToSpan(
 ): RESpan | NoopSpan {
   const { fileLines, lineStarts } = lineIndex;
 
-  const startLine = edit.hash_range_inclusive[0].line;
-  const endLine = edit.hash_range_inclusive[1].line;
+  const startLine = edit.hash_bounds[0].line;
+  const endLine = edit.hash_bounds[1].line;
   const originalLines = fileLines.slice(startLine - 1, endLine);
   if (
     originalLines.length === edit.content_lines.length &&
@@ -76,7 +76,7 @@ function resToSpan(
   ) {
     return {
       kind: "noop",
-      loc: edit.hash_range_inclusive[0].hash,
+      loc: edit.hash_bounds[0].hash,
       currentContent: originalLines.join("\n"),
     };
   }

package/src/hashline/parse.ts

@@ -2,7 +2,7 @@ import {
 	ANCHOR_LEN,
 	ALPH_RE,
 } from "./hash";
-import { CONTENT_LINES_NOT_STRING_MSG } from "../constants";
+import { NEW_CONTENT_NOT_STRING_MSG } from "../constants";
 
 export type Anchor = { hash: string };
 
@@ -18,7 +18,7 @@ function diagRef(ref: string): string {
 	}
 
 	if (trimmed.includes("│")) {
-		return `[E_BAD_REF] Invalid anchor "${trimmed}". hash_range_inclusive must contain the 3-char hash only — remove everything from "│" onward.`;
+		return `[E_BAD_REF] Invalid anchor "${trimmed}". hash_bounds must contain the 3-char hash only — remove everything from "│" onward.`;
 	}
 
 	return `[E_BAD_REF] Invalid anchor "${trimmed}". Expected a 3-char alphanumeric anchor (e.g. "aB3").`;
@@ -39,18 +39,13 @@ function parseRef(ref: string): Anchor {
 
 export const parseHashRef = parseRef;
 
-export function parseText(edit: string[] | string | null): string[] {
-  if (edit === null) {
-    throw new Error('[E_BAD_SHAPE] "content_lines" must be a string array; use [] to delete a range.');
+export function parseText(edit: string): string[] {
+  if (typeof edit !== "string") {
+    throw new Error(NEW_CONTENT_NOT_STRING_MSG);
   }
-  if (typeof edit === "string") {
-    throw new Error(CONTENT_LINES_NOT_STRING_MSG);
-  }
-  const lineBreakIndex = edit.findIndex((line) => /[\r\n]/.test(line));
-  if (lineBreakIndex >= 0) {
-    throw new Error(
-      `[E_BAD_SHAPE] "content_lines" entry at index ${lineBreakIndex} contains a \\r or \\n line break. Pass each line as its own array entry.`,
-    );
-  }
-  return edit;
+  const normalized = edit.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (normalized === "") return [];
+  const lines = normalized.split("\n");
+  if (normalized.endsWith("\n")) lines.pop();
+  return lines;
 }

package/src/hashline/resolve.ts

@@ -1,7 +1,7 @@
 import { abortIf, rejectUnknownFields, lastNonEmpty, firstNonEmpty, clipLine } from "../utils";
 import { HL_BARE_PREFIX_RE, HL_PREFIX_PLUS_RE, HL_PREFIX_MINUS_RE } from "./hash";
 import { parseHashRef, parseText, type Anchor } from "./parse";
-import { CONTENT_LINES_NOT_STRING_MSG } from "../constants";
+import { NEW_CONTENT_NOT_STRING_MSG } from "../constants";
 
 export type RAnchor = {
 	line: number;
@@ -9,10 +9,10 @@ export type RAnchor = {
 	hashMatched: boolean;
 };
 
-export type HEdit = { content_lines: string[]; hash_range_inclusive: [Anchor, Anchor] };
+export type HEdit = { content_lines: string[]; hash_bounds: [Anchor, Anchor] };
 export type RHEdit = {
   content_lines: string[];
-  hash_range_inclusive: [RAnchor, RAnchor];
+  hash_bounds: [RAnchor, RAnchor];
 };
 
 interface HMismatch {
@@ -40,8 +40,8 @@ export interface NEdit {
 }
 
 export type HTEdit = {
-  content_lines: string[];
-  hash_range_inclusive: [string, string];
+  new_content: string;
+  hash_bounds: [string, string];
 };
 
 function resAnchorFromMap(
@@ -89,7 +89,7 @@ export function fmtMismatch(
   const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
   if (notFound.length > 0) {
     out.push(
-      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. The file content has changed since those anchors were read. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
+      `[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}: ${refList}. The file content has changed since those anchors were read. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_bounds of your next replace call.`
     );
     for (const m of notFound) {
       const ctx = m.context;
@@ -107,7 +107,7 @@ export function fmtMismatch(
   if (ambiguous.length > 0) {
     if (out.length > 0) out.push("");
     out.push(
-      `[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_range_inclusive of your next replace call.`
+      `[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}${filePath ? ` in ${filePath}` : ""}. Call read() to get fresh anchors, then copy the 3-char HASH of the start and end of the range you are replacing into hash_bounds of your next replace call.`
     );
     for (const m of ambiguous) {
       const sample = (m.candidates ?? []).slice(0, 5);
@@ -130,13 +130,7 @@ export function fmtMismatch(
   return out.join("\n");
 }
 
-const ITEM_KS = new Set(["content_lines", "hash_range_inclusive"]);
-
-function isStrArr(value: unknown): value is string[] {
-	return (
-		Array.isArray(value) && value.every((item) => typeof item === "string")
-	);
-}
+const ITEM_KS = new Set(["new_content", "hash_bounds"]);
 
 function isStrPair(value: unknown): value is [string, string] {
 	return (
@@ -147,36 +141,22 @@ function isStrPair(value: unknown): value is [string, string] {
 }
 
 function assertItem(edit: Record<string, unknown>): void {
-  rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { content_lines, hash_range_inclusive }.");
+  rejectUnknownFields(edit, ITEM_KS, "Edit", "The edit takes only { new_content, hash_bounds }.");
 
-  if ("hash_range_inclusive" in edit && !isStrPair(edit.hash_range_inclusive)) {
+  if ("hash_bounds" in edit && !isStrPair(edit.hash_bounds)) {
     throw new Error(
-      `[E_BAD_SHAPE] Field "hash_range_inclusive" must be a pair of anchor strings [start, end].`,
+      `[E_BAD_SHAPE] Field "hash_bounds" must be a pair of anchor strings [start, end].`,
     );
   }
-  if (!("content_lines" in edit)) {
-    throw new Error(`[E_BAD_SHAPE] The edit requires a "content_lines" field. Provide the replacement lines (use [] to delete).`);
+  if (!("new_content" in edit)) {
+    throw new Error(`[E_BAD_SHAPE] The edit requires a "new_content" field. Provide the replacement text (use "" to delete).`);
   }
-  if ("content_lines" in edit && !isStrArr(edit.content_lines)) {
-    const val = edit.content_lines;
-    if (typeof val === "string") {
-      try {
-        const parsed = JSON.parse(val);
-        if (Array.isArray(parsed)) {
-          edit.content_lines = parsed;
-        } else {
-          throw new Error(CONTENT_LINES_NOT_STRING_MSG);
-        }
-      } catch {
-        throw new Error(CONTENT_LINES_NOT_STRING_MSG);
-      }
-    } else {
-      throw new Error(`[E_BAD_SHAPE] Field "content_lines" must be a string array.`);
-    }
+  if (typeof edit.new_content !== "string") {
+    throw new Error(NEW_CONTENT_NOT_STRING_MSG);
   }
-  if (!isStrPair(edit.hash_range_inclusive)) {
+  if (!isStrPair(edit.hash_bounds)) {
     throw new Error(
-      `[E_BAD_SHAPE] The edit requires a "hash_range_inclusive" pair of anchor strings [start, end].`,
+      `[E_BAD_SHAPE] The edit requires a "hash_bounds" pair of anchor strings [start, end].`,
     );
   }
 }
@@ -184,10 +164,10 @@ function assertItem(edit: Record<string, unknown>): void {
 export function resEdit(edit: HTEdit): HEdit {
   assertItem(edit as Record<string, unknown>);
 
-  const replaceLines = parseText(edit.content_lines);
+  const replaceLines = parseText(edit.new_content);
   return {
     content_lines: replaceLines,
-    hash_range_inclusive: [parseHashRef(edit.hash_range_inclusive[0]), parseHashRef(edit.hash_range_inclusive[1])],
+    hash_bounds: [parseHashRef(edit.hash_bounds[0]), parseHashRef(edit.hash_bounds[1])],
   };
 }
 
@@ -217,15 +197,19 @@ export function stripBarePrefixes(
 	});
 	if (stripped.length === 0) return edit;
 	const locations = stripped
-		.map((s) => `content_lines[${s.lineIndex}]`)
+		.map((s) => `new_content line ${s.lineIndex + 1}`)
 		.join(", ");
 	const matchedCount = stripped.filter((s) => s.matched).length;
 	const evidence =
 		matchedCount === 0
 			? "none of the stripped hashes match current file lines"
 			: `${matchedCount} of ${stripped.length} stripped hash(es) match current file lines`;
+	const guidance =
+		matchedCount === 0
+			? " Verify that these lines were pasted from read output; literal content starting with 'HASH│' would be altered by this strip."
+			: "";
 	warnings.push(
-		`[E_BARE_HASH_PREFIX] Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).`
+		`[E_BARE_HASH_PREFIX] Autocorrected: stripped "HASH│" prefix copied from read output in ${locations} (${evidence}).${guidance}`
 	);
 	return { ...edit, content_lines: contentLines };
 }
@@ -249,7 +233,7 @@ export function stripDiffPrefixes(
 		return line;
 	});
 	if (stripped.length === 0) return edit;
-	const locations = stripped.map((i) => `content_lines[${i}]`).join(", ");
+	const locations = stripped.map((i) => `new_content line ${i + 1}`).join(", ");
 	warnings.push(
 		`[E_INVALID_PATCH] Autocorrected: stripped diff-preview marker copied from the diff preview in ${locations}.`
 	);
@@ -265,7 +249,7 @@ export function swapReversedRanges(
 	for (let i = 0; i < fileHashes.length; i++) {
 		lineByHash.set(fileHashes[i]!, i + 1);
 	}
-	const [startRef, endRef] = edit.hash_range_inclusive;
+	const [startRef, endRef] = edit.hash_bounds;
 	const startLine = lineByHash.get(startRef.hash);
 	const endLine = lineByHash.get(endRef.hash);
 	if (
@@ -276,9 +260,9 @@ export function swapReversedRanges(
 		return edit;
 	}
 	warnings.push(
-		`[E_BAD_OP] Autocorrected: hash_range_inclusive was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
+		`[E_BAD_OP] Autocorrected: hash_bounds was reversed (start ${startRef.hash} is after end ${endRef.hash}); swapped the pair.`
 	);
-	return { ...edit, hash_range_inclusive: [endRef, startRef] as [Anchor, Anchor] };
+	return { ...edit, hash_bounds: [endRef, startRef] as [Anchor, Anchor] };
 }
 
 function checkBoundaryDup(
@@ -330,21 +314,21 @@ export function valEdit(
 	};
 
 	abortIf(signal);
-	const startResolved = tryResolve(edit.hash_range_inclusive[0]);
-	const endResolved = tryResolve(edit.hash_range_inclusive[1]);
+	const startResolved = tryResolve(edit.hash_bounds[0]);
+	const endResolved = tryResolve(edit.hash_bounds[1]);
 	if (!startResolved || !endResolved) {
 		if (!startResolved && endResolved) {
-			const startMismatch = mismatches.findLast((m) => m.ref === edit.hash_range_inclusive[0]);
+			const startMismatch = mismatches.findLast((m) => m.ref === edit.hash_bounds[0]);
 			if (startMismatch && startMismatch.kind === "not_found") startMismatch.context = endResolved;
 		} else if (startResolved && !endResolved) {
-			const endMismatch = mismatches.findLast((m) => m.ref === edit.hash_range_inclusive[1]);
+			const endMismatch = mismatches.findLast((m) => m.ref === edit.hash_bounds[1]);
 			if (endMismatch && endMismatch.kind === "not_found") endMismatch.context = startResolved;
 		}
 		return { resolved: undefined, mismatches, boundaryWarnings };
 	}
 	if (startResolved.line > endResolved.line) {
 		throw new Error(
-			`[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_range_inclusive[0].hash} and ${edit.hash_range_inclusive[1].hash}).`,
+			`[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.hash_bounds[0].hash} and ${edit.hash_bounds[1].hash}).`,
 		);
 	}
 	const endLine = endResolved.line;
@@ -360,7 +344,7 @@ export function valEdit(
 	return {
 		resolved: {
 			content_lines: edit.content_lines,
-			hash_range_inclusive: [startResolved, endResolved],
+			hash_bounds: [startResolved, endResolved],
 		},
 		mismatches,
 		boundaryWarnings,

package/src/read.ts

@@ -3,6 +3,7 @@ import {
 	createReadTool,
 	formatSize,
 	truncateHead,
+	DEFAULT_MAX_LINES,
 	type TruncationResult,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -57,6 +58,7 @@ export async function fmtReadPreview(
 	precomputedHashes?: string[],
 	path?: string,
 	maxLineBytes = MAX_READ_LINE_BYTES,
+	maxTruncLines = DEFAULT_MAX_LINES,
 ): Promise<{ text: string; truncation?: TruncationResult; nextOffset?: number }> {
 	const allLines = visLines(text);
 	const totalLines = allLines.length;
@@ -99,7 +101,7 @@ export async function fmtReadPreview(
 				? `[Line ${row.lineNumber} is ${formatSize(row.bytes)}, exceeds ${formatSize(maxBytes)}; content not shown. Use bash: sed -n '${row.lineNumber}p' <path> | head -c ${maxBytes}]`
 				: fmtRegion([selectedHashes[index]!], [selected[index]!]),
 		);
-		const skippedTruncation = truncateHead(rows.join("\n"), { maxBytes });
+		const skippedTruncation = truncateHead(rows.join("\n"), { maxBytes, maxLines: maxTruncLines });
 		const shownRowCount = skippedTruncation.content === "" ? 0 : skippedTruncation.content.split("\n").length;
 		const lastShownLine = shownRowCount > 0 ? startLine + shownRowCount - 1 : startLine - 1;
 		const lineLabel = oversized.length === 1 ? `Line ${oversized[0]!.lineNumber}` : `Lines ${oversized.map((row) => row.lineNumber).join(", ")}`;
@@ -121,7 +123,7 @@ export async function fmtReadPreview(
 		};
 	}
 
-	const truncation = truncateHead(formatted, { maxBytes });
+	const truncation = truncateHead(formatted, { maxBytes, maxLines: maxTruncLines });
 
 	let preview = truncation.content;
 	let nextOffset: number | undefined;

package/src/replace-normalize.ts

@@ -1,19 +1,4 @@
-import { isRec, has } from "./utils";
-import { CONTENT_LINES_NOT_STRING_MSG } from "./constants";
-
-export function tryParseContentLines(record: Record<string, unknown>, key: string): void {
-  const val = record[key];
-  if (typeof val !== "string") return;
-  try {
-    const parsed = JSON.parse(val);
-    if (Array.isArray(parsed)) {
-      record[key] = parsed;
-      return;
-    }
-  } catch {
-  }
-  throw new Error(CONTENT_LINES_NOT_STRING_MSG);
-}
+import { isRec } from "./utils";
 
 export function normalizeFilePath(record: Record<string, unknown>): void {
   if (typeof record.path !== "string" && typeof record.file_path === "string") {
@@ -31,9 +16,5 @@ export function normReq(input: unknown): unknown {
 
   normalizeFilePath(record);
 
-  if (has(record, "content_lines") && typeof record.content_lines === "string") {
-    tryParseContentLines(record, "content_lines");
-  }
-
   return record;
 }

package/src/replace-render.ts

@@ -32,18 +32,14 @@ export function getPreviewInput(
 		return null;
 	}
 
-	if (Array.isArray(normalized.changes)) {
-		return { path: normalized.path, hash_range_inclusive: ["", ""] as [string, string], content_lines: [] };
-	}
-
-	if (!Array.isArray(normalized.hash_range_inclusive) || !Array.isArray(normalized.content_lines)) {
+	if (!Array.isArray(normalized.hash_bounds) || typeof normalized.new_content !== "string") {
 		return null;
 	}
 
 	const request: ReqParams = {
 		path: normalized.path,
-		hash_range_inclusive: normalized.hash_range_inclusive as [string, string],
-		content_lines: normalized.content_lines as string[],
+		hash_bounds: normalized.hash_bounds as [string, string],
+		new_content: normalized.new_content,
 	};
 	return request;
 }

package/src/replace.ts

@@ -12,8 +12,8 @@ import {
   type LineEnding,
 } from "./replace-diff";
 import { readNormFile } from "./file-reader";
-import { normReq, normalizeFilePath, tryParseContentLines } from "./replace-normalize";
-import { isRec, has, rejectUnknownFields, abortIf } from "./utils";
+import { normReq, normalizeFilePath } from "./replace-normalize";
+import { isRec, rejectUnknownFields, abortIf } from "./utils";
 import { resolveTarget, writeAtomic } from "./fs-write";
 import { applyEdit,
   lineHashes,
@@ -45,12 +45,12 @@ import { loadP, loadGuide } from "./prompts";
 import { saveUndo } from "./replace-undo";
 import { loadHashStore, type HashStore } from "./hash-store";
 
-const contentLinesSchema = Type.Array(Type.String(), {
+const newContentSchema = Type.String({
   description:
-    "Replacement content, one string per line; entries must not contain line breaks. Use [] to delete the range."
+    "Replacement content as a single string with \\n line separators; a trailing newline is the last line's ending, not an extra empty line. Use \"\" to delete the range."
 });
 
-const hashRangeInclSchema = Type.Array(
+const hashBoundsSchema = Type.Array(
   Type.String({ description: "A 3-char HASH from read output" }),
   {
     description: "Pair of 3-char hashes from read output marking the first and last line of the range to replace (inclusive).",
@@ -62,15 +62,15 @@ const hashRangeInclSchema = Type.Array(
 export const editToolSchema = Type.Object(
   {
     path: Type.String({ description: "Path to edit" }),
-    hash_range_inclusive: hashRangeInclSchema,
-    content_lines: contentLinesSchema,
+    hash_bounds: hashBoundsSchema,
+    new_content: newContentSchema,
   },
   { additionalProperties: false },
 );
 export type ReqParams = {
   path: string;
-  hash_range_inclusive: [string, string];
-  content_lines: string[];
+  hash_bounds: [string, string];
+  new_content: string;
 };
 
 export type ReplaceDetails = {
@@ -100,20 +100,7 @@ interface PipelineResult {
 
 const PREVIEW_DEBOUNCE_MS = 150;
 
-const ROOT_KS = new Set(["path", "content_lines", "hash_range_inclusive"]);
-
-const LEGACY_KS = ["oldText", "newText", "old_text", "new_text", "old_range", "start", "end", "lines", "changes"];
-
-export function assertNoLegacyKeys(request: unknown): void {
-  if (!isRec(request)) return;
-  for (const legacyKey of LEGACY_KS) {
-    if (has(request, legacyKey)) {
-      throw new Error(
-        `[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {hash_range_inclusive: ["<START>", "<END>"], content_lines: [...]}.`
-      );
-    }
-  }
-}
+const ROOT_KS = new Set(["path", "new_content", "hash_bounds"]);
 
 export function assertReq(
   request: unknown,
@@ -122,17 +109,15 @@ export function assertReq(
     throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
   }
 
-  assertNoLegacyKeys(request);
-
   rejectUnknownFields(request, ROOT_KS, "Edit request");
 
   if (typeof request.path !== "string" || request.path.length === 0) {
     throw new Error('[E_BAD_SHAPE] Edit request requires a non-empty "path" string.');
   }
 
-  if (!Array.isArray(request.hash_range_inclusive) || !Array.isArray(request.content_lines)) {
+  if (!Array.isArray(request.hash_bounds) || typeof request.new_content !== "string") {
     throw new Error(
-      '[E_BAD_SHAPE] Edit request requires both "hash_range_inclusive" and "content_lines" at the top level.',
+      '[E_BAD_SHAPE] Edit request requires both "hash_bounds" and "new_content" at the top level.',
     );
   }
 }
@@ -149,8 +134,8 @@ function collectRemovedHashes(
   originalHashes: string[],
 ): Set<string> {
   const removedHashes = new Set<string>();
-  const startHash = edit.hash_range_inclusive[0].hash;
-  const endHash = edit.hash_range_inclusive[1].hash;
+  const startHash = edit.hash_bounds[0].hash;
+  const endHash = edit.hash_bounds[1].hash;
   const startLine = originalHashes.indexOf(startHash);
   const endLine = originalHashes.indexOf(endHash);
   if (startLine >= 0 && endLine >= 0) {
@@ -171,8 +156,8 @@ function countLineChanges(
 ): { totalAddedLines: number; totalRemovedLines: number } {
   if (isNoop) return { totalAddedLines: 0, totalRemovedLines: 0 };
   let totalRemovedLines = 0;
-  const startLine = originalHashes.indexOf(edit.hash_range_inclusive[0].hash);
-  const endLine = originalHashes.indexOf(edit.hash_range_inclusive[1].hash);
+  const startLine = originalHashes.indexOf(edit.hash_bounds[0].hash);
+  const endLine = originalHashes.indexOf(edit.hash_bounds[1].hash);
   if (startLine >= 0 && endLine >= 0) {
     totalRemovedLines = Math.abs(endLine - startLine) + 1;
   }
@@ -190,16 +175,16 @@ export async function execPipeline(
 
   const path = params.path;
 
-  const hashStore = options?.store ?? await loadHashStore();
+  const edit = resEdit({
+    hash_bounds: params.hash_bounds,
+    new_content: params.new_content,
+  });
 
+  const hashStore = options?.store ?? await loadHashStore();
   const { normalized: originalNormalized, bom, originalEnding, fileHashes: originalHashes, hadUtf8DecodeErrors, absolutePath } = await readNormFile(
     path, cwd, { signal: options?.signal, accessMode: options?.accessMode, maxLines: MAX_HASH_LINES, store: hashStore },
   );
 
-  const edit = resEdit({
-    hash_range_inclusive: params.hash_range_inclusive,
-    content_lines: params.content_lines,
-  });
   const anchorResult = applyEdit(
     originalNormalized,
     edit,
@@ -307,13 +292,9 @@ export function buildToolDef(): ToolDef {
     promptSnippet: E_SNIPPET,
     promptGuidelines: E_GUIDE,
     prepareArguments: (args: unknown) => {
-      assertNoLegacyKeys(args);
       if (!isRec(args)) return args as any;
       const record = { ...args };
       normalizeFilePath(record);
-      if (has(record, "content_lines") && typeof record.content_lines === "string") {
-        tryParseContentLines(record, "content_lines");
-      }
       return record;
     },
     renderShell: "default",