pi-hashline-edit-pro 0.8.0 → 0.9.0

package/README.md

@@ -66,19 +66,18 @@ Replaces using the `HASH│content` anchors from `read` output to target lines p
 {
   "path": "src/main.ts",
   "edits": [
-    { "start": "ve7", "end": "ve7", "lines": ["  console.log('hashline');"] }
+    { "old_range": ["ve7", "ve7"], "new_lines": ["  console.log('hashline');"] }
   ]
 }
 ```
 
 | Field | Purpose |
 |---|---|
-| `start` | Range-start anchor (required). |
-| `end` | Range-end anchor (required). Single-line replace: set `start` = `end`. |
-| `lines` | Replacement content (one string per line). Use `[]` to delete. |
+| `old_range` | Inclusive line range `[start_hash, end_hash]` (required). |
+| `new_lines` | Replacement content (one string per line). Use `[]` to delete. |
 
-- **Request structure validation.** The request envelope (path, edits, returnMode, returnRanges) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_OP]`.
-- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{start:"<HASH>", end:"<HASH>", lines:[...]}`.
+- **Request structure validation.** The request envelope (`path`, `edits`) and individual edit items are validated before any file I/O. Unknown fields, missing required fields, invalid types, and malformed anchors are rejected with `[E_BAD_SHAPE]` or `[E_BAD_OP]`.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
 
 All edits in a single call validate against the same pre-edit snapshot and apply bottom-up, so line numbers stay consistent across operations.
 
@@ -105,8 +104,8 @@ The post-edit diff (with `+`/`-` markers and new `HASH│content` anchors) is ex
 
 - **Stale anchors fail.** A hash mismatch means the file has changed since the last `read`. The error tells the model to call `read()` to get fresh anchors, then copy the 3-character HASH from each line into the next replace call.
 - **No fallback relocation.** Mismatched anchors are never silently relocated to a "close enough" line. This trades convenience for correctness.
-- **Strict patch content.** If `lines` contains `+HASH│` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH│` content (the first 4 chars of a `lines` entry looking like 3 base64 chars + `│`) is also rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
-- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{start:"<HASH>", end:"<HASH>", lines:[...]}`.
+- **Strict patch content.** If `new_lines` contains `+HASH│` display prefixes (or `-N   ` diff rows), the edit is rejected with `[E_INVALID_PATCH]`. Bare `HASH│` content (the first 4 chars of a `new_lines` entry looking like 3 base64 chars + `│`) is also rejected with `[E_BARE_HASH_PREFIX]`. When the suspect's prefix happens to match a real file-line anchor, the error message flags that as strong evidence the model copied an anchor from the read output.
+- **Legacy dialect rejected.** The native top-level `oldText`/`newText` (and `old_text`/`new_text`) dialect is rejected with `[E_LEGACY_SHAPE]`. The error message tells the model to call `read` first and send `{old_range: ["<START>", "<END>"], new_lines: [...]}`.
 - **Atomic writes.** Files are written via temp-file-then-rename to avoid corruption from interrupted writes. Symlink chains are resolved so the target file is updated without replacing the symlink. Hard-linked files are updated in place to preserve the shared inode. File permissions are preserved across atomic renames.
 - **Per-file mutation queue.** Edits queue by the canonical write target, so concurrent edits through different symlink paths still serialize onto the same underlying file.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-hashline-edit-pro",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Strict hashline read/replace tool for pi-coding-agent with hash-anchored edits (3-char, 18-bit, perfect hashing)",
   "main": "index.ts",
   "repository": {

package/prompts/read.md

@@ -6,7 +6,7 @@ HASH format:
 - The line number is not part of the output. Use the HASH to reference lines.
 
 Pagination:
-- Large files return a truncated preview with a `nextOffset` line. Call `read` again with `offset=nextOffset` to continue.
+- Large files return a truncated preview with a pagination hint (e.g. `[Showing lines 1-100 of 500. Use offset=101 to continue.]`). Call `read` again with `offset=N` to continue.
 
 File kinds:
 - Text files are returned as `HASH│content` lines.

package/prompts/replace-guidelines.md

@@ -1,3 +1,3 @@
 - Use `replace` with HASH anchors for all file changes; batch every change to one file into a single `replace` call.
 - After a successful `replace`, the returned `--- Anchors ---` block has fresh hashes for nearby follow-up replaces.
-- On `[E_STALE_ANCHOR]`, retry with the `>>>` lines quoted in the error instead of re-reading the whole file.
+- On `[E_STALE_ANCHOR]`, retry with the `>>>` lines quoted in the error instead of re-reading the whole file.

package/prompts/replace.md

@@ -13,10 +13,10 @@ read({ path: "src/main.ts" })
 // VRW│const z = 3;
 ```
 
-2. Copy the 3-character HASH (before `│`) into `start`/`end`:
+2. Copy the 3-character HASH (before `│`) into `old_range`:
 ```json
 { "path": "src/main.ts", "edits": [
-  { "start": "MQX", "end": "MQX", "lines": ["const x = 99;"] }
+  { "old_range": ["MQX", "MQX"], "new_lines": ["const x = 99;"] }
 ] }
 ```
 
@@ -25,14 +25,14 @@ Examples:
 1. Single line replace:
 ```json
 { "path": "src/main.ts", "edits": [
-  { "start": "MQX", "end": "MQX", "lines": ["const x = 1;"] }
+  { "old_range": ["MQX", "MQX"], "new_lines": ["const x = 1;"] }
 ] }
 ```
 
 2. Range replace (3 lines → 3 new lines):
 ```json
 { "path": "src/main.ts", "edits": [
-  { "start": "ZPM", "end": "VRW", "lines": [
+  { "old_range": ["ZPM", "VRW"], "new_lines": [
     "function greet(name) {",
     "  return `Hello, ${name}`;",
     "}"
@@ -43,24 +43,32 @@ Examples:
 3. Multiple regions in one call (delete two non-adjacent ranges):
 ```json
 { "path": "src/server.ts", "edits": [
-  { "start": "aB3", "end": "xY7", "lines": [] },
-  { "start": "MQX", "end": "ZPM", "lines": [] }
+  { "old_range": ["aB3", "xY7"], "new_lines": [] },
+  { "old_range": ["MQX", "ZPM"], "new_lines": [] }
 ] }
 ```
 
 Rules:
-- `start` and `end` are required. A single-line replace is `start=X, end=X`.
-- To delete a range, use `lines: []`.
-- `start`, `end` are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
-- `lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix, no `+`/`-` diff markers.
+- `old_range` is a pair `[start, end]`. A single-line replace is `old_range: ["X", "X"]`.
+- To delete a range, use `new_lines: []`.
+- `old_range` elements are HASH anchors only (e.g. `aB3`). Do not include `│` or line content.
+- `new_lines` is literal file content — each string becomes exactly one line in the file. No `HASH│` prefix, no `+`/`-` diff markers.
 - Don't add `""` for spacing unless you actually want a new blank line.
 - Copy anchors from the most recent `read` of the file. Do not guess or construct them.
 - All edits in one call must be non-conflicting. The runtime rejects with `[E_EDIT_CONFLICT]` if two ranges overlap.
-- If `lines` matches current content, the replace is classified as `noop` (file unchanged).
-- The `start`/`end` range is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
+- If `new_lines` matches current content, the replace is classified as `noop` (file unchanged).
+- The `old_range` is inclusive — both anchors and every line between them are replaced. If your replacement content includes lines that already exist in the file (e.g. closing brackets), make sure those lines are within your range, otherwise they will appear twice.
 
 On success, the response contains an `--- Anchors ---` block with fresh HASH anchors for the changed region. Use those for nearby follow-up replaces instead of re-reading.
 
 Error recovery:
-- `[E_STALE_ANCHOR]` — file changed since last read. The error includes fresh `>>> HASH│content` lines; copy the HASH and retry.
+- `[E_STALE_ANCHOR]` — file changed since last read. Call `read` to get fresh anchors, then copy the HASH and retry.
 - `[E_BAD_REF]` — malformed HASH. Re-read and try again.
+- `[E_BAD_OP]` — invalid operation (e.g. start line > end line).
+- `[E_BAD_SHAPE]` — malformed request or edit item (missing fields, wrong types, unknown fields).
+- `[E_LEGACY_SHAPE]` — old `oldText`/`newText` format detected. Use `{old_range, new_lines}` instead.
+- `[E_EDIT_CONFLICT]` — two edits overlap on the same line range. Make edits non-overlapping.
+- `[E_AMBIGUOUS_ANCHOR]` — hash collision. Call `read` to get fresh anchors.
+- `[E_BARE_HASH_PREFIX]` — edit line starts with `HASH│`. Use literal file content in `new_lines`, not read output.
+- `[E_INVALID_PATCH]` — diff prefixes (`+`/`-`) in `new_lines`. Use literal content only.
+- `[E_WOULD_EMPTY]` — edit would empty a non-empty file.

package/src/hashline/apply.ts

@@ -79,31 +79,31 @@ function resolveEditToSpan(
 ): ResolvedEditSpan | null {
 	const { fileLines, lineStarts, hasTerminalNewline } = lineIndex;
 
-	const startLine = edit.start.line;
-	const endLine = edit.end.line;
+	const startLine = edit.old_range[0].line;
+	const endLine = edit.old_range[1].line;
 	const originalLines = fileLines.slice(startLine - 1, endLine);
 	if (
-		originalLines.length === edit.lines.length &&
+		originalLines.length === edit.new_lines.length &&
 		originalLines.every(
-			(line, lineIndex) => line === edit.lines[lineIndex],
+			(line, lineIndex) => line === edit.new_lines[lineIndex],
 		)
 	) {
 		noopEdits.push({
 			editIndex: index,
-			loc: edit.start.hash,
+			loc: edit.old_range[0].hash,
 			currentContent: originalLines.join("\n"),
 		});
 		return null;
 	}
 
-	if (edit.lines.length > 0) {
+	if (edit.new_lines.length > 0) {
 		return {
 			kind: "replace",
 			index,
 			label: describeEdit(edit),
 			start: lineStarts[startLine - 1]!,
 			end: lineStarts[endLine - 1]! + fileLines[endLine - 1]!.length,
-			replacement: edit.lines.join("\n"),
+			replacement: edit.new_lines.join("\n"),
 		};
 	}
 
@@ -235,11 +235,11 @@ export function applyHashlineEdits(
 			lastChangedLine: undefined,
 		};
 
-	// Normalize lines: [""] to lines: [] for deletion.
+	// Normalize new_lines: [""] to new_lines: [] for deletion.
 	edits = edits.map((edit) =>
-		edit.lines.length === 1 &&
-		edit.lines[0] === ""
-			? { ...edit, lines: [] }
+		edit.new_lines.length === 1 &&
+		edit.new_lines[0] === ""
+			? { ...edit, new_lines: [] }
 			: edit,
 	);
 

package/src/hashline/resolve.ts

@@ -10,11 +10,10 @@ export type ResolvedAnchor = {
 	hashMatched: boolean;
 };
 
-export type HashlineEdit = { start: Anchor; end: Anchor; lines: string[] };
+export type HashlineEdit = { old_range: [Anchor, Anchor]; new_lines: string[] };
 export type ResolvedHashlineEdit = {
-	start: ResolvedAnchor;
-	end: ResolvedAnchor;
-	lines: string[];
+	old_range: [ResolvedAnchor, ResolvedAnchor];
+	new_lines: string[];
 };
 interface HashMismatch {
 	ref: Anchor;
@@ -29,9 +28,8 @@ export interface NoopEdit {
 }
 
 export type HashlineToolEdit = {
-	start?: string;
-	end?: string;
-	lines?: string[];
+	old_range?: [string, string];
+	new_lines?: string[];
 	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
 	oldText?: string;
 	/** @deprecated Legacy field — rejected with [E_LEGACY_SHAPE] at validation time. */
@@ -76,16 +74,16 @@ export function formatMismatchError(
 	const notFound = mismatches.filter((m) => m.kind === "not_found");
 	const ambiguous = mismatches.filter((m) => m.kind === "ambiguous");
 
+	const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
 	if (notFound.length > 0) {
-		const refList = notFound.map((m) => `"${m.ref.hash}"`).join(", ");
 	out.push(
-		`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}: ${refList}. Call read() to get fresh anchors, then copy the 4-character HASH from each line into your next replace call.`
+		`[E_STALE_ANCHOR] ${notFound.length} stale anchor${notFound.length > 1 ? "s" : ""}: ${refList}. Call read() to get fresh anchors, then copy the 3-character HASH from each line into your next replace call.`
 	);
 	}
 	if (ambiguous.length > 0) {
 		if (out.length > 0) out.push("");
 	out.push(
-		`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}. Call read() to get fresh anchors, then copy the 4-character HASH from each line into your next replace call.`
+		`[E_AMBIGUOUS_ANCHOR] ${ambiguous.length} ambiguous anchor${ambiguous.length > 1 ? "s" : ""}. Call read() to get fresh anchors, then copy the 3-character HASH from each line into your next replace call.`
 	);
 		for (const m of ambiguous) {
 			const sample = (m.candidates ?? []).slice(0, 5);
@@ -110,13 +108,21 @@ export function formatMismatchError(
 }
 
 
-const ITEM_KEYS = new Set(["start", "end", "lines"]);
+const ITEM_KEYS = new Set(["old_range", "new_lines"]);
 function isStringArray(value: unknown): value is string[] {
 	return (
 		Array.isArray(value) && value.every((item) => typeof item === "string")
 	);
 }
 
+function isStringPair(value: unknown): value is [string, string] {
+	return (
+		Array.isArray(value) &&
+		value.length === 2 &&
+		value.every((item) => typeof item === "string")
+	);
+}
+
 function assertEditItem(edit: Record<string, unknown>, index: number): void {
 	const unknownKeys = Object.keys(edit).filter((key) => !ITEM_KEYS.has(key));
 	if (unknownKeys.length > 0) {
@@ -125,28 +131,20 @@ function assertEditItem(edit: Record<string, unknown>, index: number): void {
 		);
 	}
 
-	if ("start" in edit && typeof edit.start !== "string") {
+	if ("old_range" in edit && !isStringPair(edit.old_range)) {
 		throw new Error(
-			`[E_BAD_SHAPE] Edit ${index} field "start" must be a string when provided.`,
+			`[E_BAD_SHAPE] Edit ${index} field "old_range" must be a pair of anchor strings [start, end].`,
 		);
 	}
-	if ("end" in edit && typeof edit.end !== "string") {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} field "end" must be a string when provided.`);
+	if (!("new_lines" in edit)) {
+		throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "new_lines" field.`);
 	}
-	if (!("lines" in edit)) {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} requires a "lines" field.`);
-	}
-	if ("lines" in edit && !isStringArray(edit.lines)) {
-		throw new Error(`[E_BAD_SHAPE] Edit ${index} field "lines" must be a string array.`);
-	}
-	if (typeof edit.start !== "string") {
-		throw new Error(
-			`[E_BAD_OP] Edit ${index} requires a "start" anchor string.`,
-		);
+	if ("new_lines" in edit && !isStringArray(edit.new_lines)) {
+		throw new Error(`[E_BAD_SHAPE] Edit ${index} field "new_lines" must be a string array.`);
 	}
-	if (typeof edit.end !== "string") {
+	if (!isStringPair(edit.old_range)) {
 		throw new Error(
-			`[E_BAD_OP] Edit ${index} requires an "end" anchor string.`,
+			`[E_BAD_OP] Edit ${index} requires an "old_range" pair of anchor strings [start, end].`,
 		);
 	}
 
@@ -157,16 +155,15 @@ export function resolveEditAnchors(edits: HashlineToolEdit[]): HashlineEdit[] {
 	for (const [index, edit] of edits.entries()) {
 		assertEditItem(edit as Record<string, unknown>, index);
 
-		// Normalize lines: [""] to lines: [] for deletion.
-		const replaceLines = hashlineParseText(edit.lines ?? null);
+		// Normalize new_lines: [""] to new_lines: [] for deletion.
+		const replaceLines = hashlineParseText(edit.new_lines ?? null);
 		const normalizedLines =
 			replaceLines.length === 1 && replaceLines[0] === ""
 				? []
 				: replaceLines;
 		result.push({
-			start: parseHashRef(edit.start!),
-			end: parseHashRef(edit.end!),
-			lines: normalizedLines,
+			old_range: [parseHashRef(edit.old_range![0]), parseHashRef(edit.old_range![1])],
+			new_lines: normalizedLines,
 		});
 	}
 	return result;
@@ -177,7 +174,7 @@ function maybeWarnSuspiciousUnicodeEscapePlaceholder(
 	warnings: string[],
 ): void {
 	for (const edit of edits) {
-		if (edit.lines.some((line) => /\\uDDDD/i.test(line))) {
+		if (edit.new_lines.some((line) => /\\uDDDD/i.test(line))) {
 			warnings.push(
 				"Detected literal \\uDDDD in edit content; no autocorrection applied. Verify whether this should be a real Unicode escape or plain text.",
 			);
@@ -198,8 +195,8 @@ export function assertNoBareHashPrefixLines(
 	const suspects: { line: string; hash: string; editIndex: number; lineIndex: number }[] = [];
 	for (let editIndex = 0; editIndex < edits.length; editIndex++) {
 		const edit = edits[editIndex]!;
-		for (let lineIndex = 0; lineIndex < edit.lines.length; lineIndex++) {
-			const line = edit.lines[lineIndex]!;
+		for (let lineIndex = 0; lineIndex < edit.new_lines.length; lineIndex++) {
+			const line = edit.new_lines[lineIndex]!;
 			const match = line.match(HASHLINE_BARE_PREFIX_RE);
 			if (match) suspects.push({ line, hash: match[1]!, editIndex, lineIndex });
 		}
@@ -227,7 +224,7 @@ export function assertNoBareHashPrefixLines(
  * Human-readable label for a resolved edit (used in warnings and conflict errors).
  */
 export function describeEdit(edit: ResolvedHashlineEdit): string {
-	return `replace ${edit.start.hash}-${edit.end.hash}`;
+	return `replace ${edit.old_range[0].hash}-${edit.old_range[1].hash}`;
 }
 
 export function validateAnchorEdits(
@@ -257,19 +254,19 @@ export function validateAnchorEdits(
 
 	for (const edit of edits) {
 		throwIfAborted(signal);
-		const startResolved = tryResolve(edit.start);
-		const endResolved = tryResolve(edit.end);
+		const startResolved = tryResolve(edit.old_range[0]);
+		const endResolved = tryResolve(edit.old_range[1]);
 		if (!startResolved || !endResolved) {
 			continue;
 		}
 		if (startResolved.line > endResolved.line) {
 			throw new Error(
-				`[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.start.hash} and ${edit.end.hash}).`,
+				`[E_BAD_OP] Range start line ${startResolved.line} must be <= end line ${endResolved.line} (anchors ${edit.old_range[0].hash} and ${edit.old_range[1].hash}).`,
 			);
 		}
 		const endLine = endResolved.line;
 		const nextLine = fileLines[endLine];
-		const replacementLastLine = edit.lines.at(-1)?.trim();
+		const replacementLastLine = edit.new_lines.at(-1)?.trim();
 		if (
 			nextLine !== undefined &&
 			replacementLastLine &&
@@ -277,16 +274,15 @@ export function validateAnchorEdits(
 			replacementLastLine === nextLine.trim()
 		) {
 			const resolvedEdit: ResolvedHashlineEdit = {
-				start: startResolved,
-				end: endResolved,
-				lines: edit.lines,
+				old_range: [startResolved, endResolved],
+				new_lines: edit.new_lines,
 			};
 			warnings.push(
 				`Potential boundary duplication after ${describeEdit(resolvedEdit)}: the replacement ends with a line that matches the next surviving line after trim.`,
 			);
 		}
 		const prevLine = fileLines[startResolved.line - 2];
-		const replacementFirstLine = edit.lines[0]?.trim();
+		const replacementFirstLine = edit.new_lines[0]?.trim();
 		if (
 			prevLine !== undefined &&
 			replacementFirstLine &&
@@ -294,18 +290,16 @@ export function validateAnchorEdits(
 			replacementFirstLine === prevLine.trim()
 		) {
 			const resolvedEdit: ResolvedHashlineEdit = {
-				start: startResolved,
-				end: endResolved,
-				lines: edit.lines,
+				old_range: [startResolved, endResolved],
+				new_lines: edit.new_lines,
 			};
 			warnings.push(
 				`Potential boundary duplication before ${describeEdit(resolvedEdit)}: the replacement starts with a line that matches the preceding surviving line after trim.`,
 			);
 		}
 		resolved.push({
-			start: startResolved,
-			end: endResolved,
-			lines: edit.lines,
+			old_range: [startResolved, endResolved],
+			new_lines: edit.new_lines,
 		});
 	}
 

package/src/replace-render.ts

@@ -144,7 +144,6 @@ export function isAppliedChangedResult(
 	const metrics = details?.metrics;
 	return (
 		metrics?.classification === "applied" &&
-		metrics.return_mode === "changed" &&
 		metrics.added_lines !== undefined &&
 		metrics.removed_lines !== undefined
 	);
@@ -153,14 +152,11 @@ export function isAppliedChangedResult(
 export function buildAppliedChangedResultText(
 	text: string | undefined,
 	details: HashlineReplaceToolDetails | undefined,
-	preview: ReplacePreview | undefined,
 	theme: FgTheme,
 ): string | undefined {
-	const previewDiff =
-		preview && !("error" in preview) ? preview.diff : undefined;
 	const sections: string[] = [];
 
-	if (details?.diff && details.diff !== previewDiff) {
+	if (details?.diff) {
 		sections.push(formatResultDiff(details.diff, theme));
 	}
 
@@ -169,7 +165,6 @@ export function buildAppliedChangedResultText(
 
 	return sections.length > 0 ? sections.join("\n\n") : undefined;
 }
-
 // ─── Markdown rendering ─────────────────────────────────────────────────
 
 function trimEdgeEmptyLines(lines: string[]): string[] {

package/src/replace-response.ts

@@ -5,7 +5,6 @@ import {
 	computeLineHashes,
 	formatHashlineRegion,
 } from "./hashline";
-import { formatHashlineReadPreview } from "./read";
 import { getVisibleLines } from "./utils";
 
 type ToolResult = {
@@ -17,31 +16,10 @@ type ToolResult = {
 const CHANGED_ANCHOR_TEXT_BUDGET_BYTES = 50 * 1024;
 
 
-export type ReturnMode = "changed" | "full" | "ranges";
-
-export type ReturnRange = {
-	start: number;
-	end?: number;
-};
-
-export type ReturnedRangePreview = {
-	start: number;
-	end: number;
-	text: string;
-	nextOffset?: number;
-	empty?: true;
-};
-
-export type FullContentPreview = {
-	text: string;
-	nextOffset?: number;
-};
-
 export type ReplaceMetrics = {
 	edits_attempted: number;
 	edits_noop: number;
 	warnings: number;
-	return_mode: ReturnMode;
 	classification: "applied" | "noop";
 	changed_lines?: { first: number; last: number };
 	added_lines?: number;
@@ -66,14 +44,12 @@ type NoopEditEntry = {
 	currentContent: string;
 };
 
+
 // ─── Builder inputs ─────────────────────────────────────────────────────
 
 export interface NoopResponseInput {
 	path: string;
-	returnMode: ReturnMode;
-	requestedReturnRanges: ReturnRange[] | undefined;
 	noopEdits: NoopEditEntry[] | undefined;
-	originalNormalized: string;
 	snapshotId: string;
 	editMeta: ReplaceMeta;
 	warnings: string[] | undefined;
@@ -81,14 +57,8 @@ export interface NoopResponseInput {
 
 export interface SuccessResponseInput {
 	path: string;
-	returnMode: ReturnMode;
-	requestedReturnRanges: ReturnRange[] | undefined;
 	originalNormalized: string;
 	result: string;
-	/** Precomputed hashes for `result`. When omitted the response builder
-	 * computes them on demand; the caller should pass them in when the same
-	 * result is rendered through more than one path (full / ranges / changed)
-	 * to avoid redundant work. */
 	resultHashes?: string[];
 	warnings: string[] | undefined;
 	snapshotId: string;
@@ -114,7 +84,6 @@ function countDiffLines(diff: string, marker: "+" | "-"): number {
 
 function buildMetrics(args: {
 	classification: "applied" | "noop";
-	returnMode: ReturnMode;
 	editsAttempted: number;
 	noopEditsCount: number;
 	warningsCount: number;
@@ -127,7 +96,6 @@ function buildMetrics(args: {
 		edits_attempted: args.editsAttempted,
 		edits_noop: args.noopEditsCount,
 		warnings: args.warningsCount,
-		return_mode: args.returnMode,
 		classification: args.classification,
 	};
 	if (
@@ -150,117 +118,12 @@ function warningsBlockOf(warnings: string[] | undefined): string {
 	return warnings?.length ? `\n\nWarnings:\n${warnings.join("\n")}` : "";
 }
 
-function outlineBlockOf(outlineText: string): string {
-	return outlineText ? `\n\n${outlineText}` : "";
-}
-
-// ─── Structure outline ──────────────────────────────────────────────────
-
-const STRUCTURE_MARKER_RE =
-	/^(#{1,6}\s+.+|(export\s+)?(async\s+)?function\s+\w+|(export\s+)?class\s+\w+|(export\s+)?interface\s+\w+|(export\s+)?type\s+\w+|(export\s+)?enum\s+\w+|(const|let|var)\s+\w+\s*=\s*(async\s*)?\()/;
-
-function truncateOutlineEntry(text: string, max = 88): string {
-	return text.length <= max ? text : `${text.slice(0, max - 1)}…`;
-}
-
-function collectOutlineEntries(previewText: string): string[] {
-	const structural: string[] = [];
-	for (const line of previewText.split("\n")) {
-		const match = line.match(/^\s*([A-Za-z0-9_\-]{3})│(.*)$/);
-		if (!match) continue;
-		const content = match[2]!.trim();
-		if (content.length === 0) continue;
-		if (!STRUCTURE_MARKER_RE.test(content)) continue;
-		structural.push(truncateOutlineEntry(content.replace(/\s+/g, " ")));
-	}
-	return structural.slice(0, 8);
-}
-
-function buildStructureOutline(
-	sections: Array<{ label?: string; previewText: string }>,
-): { text: string; outline: string[] } {
-	const outlineLines: string[] = [];
-	const detailOutline: string[] = [];
-	const useSectionLabels = sections.length > 1;
-
-	for (const section of sections) {
-		const entries = collectOutlineEntries(section.previewText);
-		if (entries.length === 0) continue;
-		if (useSectionLabels && section.label) {
-			outlineLines.push(`- ${section.label}`);
-		}
-		for (const entry of entries) {
-			outlineLines.push(useSectionLabels ? `  - ${entry}` : `- ${entry}`);
-			detailOutline.push(section.label ? `${section.label}: ${entry}` : entry);
-		}
-	}
-
-	if (outlineLines.length === 0) {
-		return { text: "", outline: [] };
-	}
-	return {
-		text: ["Structure outline:", ...outlineLines].join("\n"),
-		outline: detailOutline,
-	};
-}
-
-// ─── Range previews ─────────────────────────────────────────────────────
-
-function formatRequestedRangePreviews(
-	text: string,
-	ranges: ReturnRange[],
-	precomputedHashes?: string[],
-): { text: string; returnedRanges: ReturnedRangePreview[] } {
-	const totalLines = getVisibleLines(text).length;
-	const returnedRanges = ranges.map((range) => {
-		const requestedEnd = range.end ?? range.start;
-		const preview = formatHashlineReadPreview(
-			text,
-			{
-				offset: range.start,
-				limit: requestedEnd - range.start + 1,
-			},
-			precomputedHashes,
-		);
-		const hasReturnedLines = /^\s*[A-Za-z0-9_\-]{3}│/m.test(preview.text);
-		const actualEnd = hasReturnedLines
-			? preview.nextOffset !== undefined
-				? preview.nextOffset - 1
-				: Math.min(requestedEnd, totalLines)
-			: requestedEnd;
-		return {
-			start: range.start,
-			end: hasReturnedLines ? Math.max(range.start, actualEnd) : actualEnd,
-			text: preview.text,
-			...(preview.nextOffset !== undefined
-				? { nextOffset: preview.nextOffset }
-				: {}),
-			...(!hasReturnedLines ? { empty: true as const } : {}),
-		};
-	});
-
-	const formatted = returnedRanges
-		.map(
-			(range, index) =>
-				`--- Range ${index + 1} ---\n${range.text}`,
-		)
-		.join("\n\n");
-
-	return {
-		text: formatted,
-		returnedRanges,
-	};
-}
-
 // ─── Builders ───────────────────────────────────────────────────────────
 
 export function buildNoopResponse(input: NoopResponseInput): ToolResult {
 	const {
 		path,
-		returnMode,
-		requestedReturnRanges,
 		noopEdits,
-		originalNormalized,
 		snapshotId,
 		editMeta,
 		warnings,
@@ -275,39 +138,10 @@ export function buildNoopResponse(input: NoopResponseInput): ToolResult {
 				.join("\n")
 		: "The edits produced identical content.";
 
-	const fullPreview =
-		returnMode === "full"
-			? formatHashlineReadPreview(originalNormalized, { offset: 1 })
-			: undefined;
-	const rangePreviews =
-		returnMode === "ranges"
-			? formatRequestedRangePreviews(
-					originalNormalized,
-					requestedReturnRanges!,
-				)
-			: undefined;
-	const outline =
-		returnMode === "full"
-			? buildStructureOutline([{ previewText: fullPreview!.text }])
-			: returnMode === "ranges"
-				? buildStructureOutline(
-						rangePreviews!.returnedRanges.map((range, index) => ({
-							label: `Range ${index + 1} (lines ${range.start}-${range.end})`,
-							previewText: range.text,
-						})),
-					)
-				: undefined;
-
-	const text =
-		returnMode === "full"
-			? `No changes made to ${path}\nClassification: noop${outlineBlockOf(outline!.text)}\n\nFull content is available in details.fullContent.`
-			: returnMode === "ranges"
-				? `No changes made to ${path}\nClassification: noop${outlineBlockOf(outline!.text)}\n\nRequested range payloads are available in details.returnedRanges.`
-				: `No changes made to ${path}\nClassification: noop\n${noopDetailsText}`;
+	const text = `No changes made to ${path}\nClassification: noop\n${noopDetailsText}`;
 
 	const metrics = buildMetrics({
 		classification: "noop",
-		returnMode,
 		editsAttempted: editMeta.editsAttempted,
 		noopEditsCount: editMeta.noopEditsCount,
 		warningsCount: warnings?.length ?? 0,
@@ -320,119 +154,6 @@ export function buildNoopResponse(input: NoopResponseInput): ToolResult {
 			firstChangedLine: undefined,
 			snapshotId,
 			classification: "noop" as const,
-			...(fullPreview?.nextOffset !== undefined
-				? { nextOffset: fullPreview.nextOffset }
-				: {}),
-			...(fullPreview
-				? {
-						fullContent: {
-							text: fullPreview.text,
-							...(fullPreview.nextOffset !== undefined
-								? { nextOffset: fullPreview.nextOffset }
-								: {}),
-						},
-					}
-				: {}),
-			...(rangePreviews
-				? { returnedRanges: rangePreviews.returnedRanges }
-				: {}),
-			...(outline ? { structureOutline: outline.outline } : {}),
-			metrics,
-		},
-	};
-}
-
-export function buildFullResponse(input: SuccessResponseInput): ToolResult {
-	const { path, result, warnings, snapshotId, originalNormalized, editMeta } =
-		input;
-
-	const diffResult = generateDiffString(originalNormalized, result);
-	const resultHashes = input.resultHashes ?? computeLineHashes(result);
-	const fullPreview = formatHashlineReadPreview(
-		result,
-		{ offset: 1 },
-		resultHashes,
-	);
-	const outline = buildStructureOutline([{ previewText: fullPreview.text }]);
-	const text = `Updated ${path}${warningsBlockOf(warnings)}${outlineBlockOf(outline.text)}\n\nFull content is available in details.fullContent.`;
-
-	const metrics = buildMetrics({
-		classification: "applied",
-		returnMode: "full",
-		editsAttempted: editMeta.editsAttempted,
-		noopEditsCount: editMeta.noopEditsCount,
-		warningsCount: warnings?.length ?? 0,
-		firstChangedLine: editMeta.firstChangedLine,
-		lastChangedLine: editMeta.lastChangedLine,
-	});
-
-	return {
-		content: [{ type: "text", text }],
-		details: {
-			diff: diffResult.diff,
-			firstChangedLine:
-				editMeta.firstChangedLine ?? diffResult.firstChangedLine,
-			snapshotId,
-			...(fullPreview.nextOffset !== undefined
-				? { nextOffset: fullPreview.nextOffset }
-				: {}),
-			fullContent: {
-				text: fullPreview.text,
-				...(fullPreview.nextOffset !== undefined
-					? { nextOffset: fullPreview.nextOffset }
-					: {}),
-			},
-			structureOutline: outline.outline,
-			metrics,
-		},
-	};
-}
-
-export function buildRangesResponse(input: SuccessResponseInput): ToolResult {
-	const {
-		path,
-		result,
-		warnings,
-		snapshotId,
-		originalNormalized,
-		requestedReturnRanges,
-		editMeta,
-	} = input;
-
-	const diffResult = generateDiffString(originalNormalized, result);
-	const resultHashes = input.resultHashes ?? computeLineHashes(result);
-	const rangePreviews = formatRequestedRangePreviews(
-		result,
-		requestedReturnRanges!,
-		resultHashes,
-	);
-	const outline = buildStructureOutline(
-		rangePreviews.returnedRanges.map((range, index) => ({
-			label: `Range ${index + 1} (lines ${range.start}-${range.end})`,
-			previewText: range.text,
-		})),
-	);
-	const text = `Updated ${path}${warningsBlockOf(warnings)}${outlineBlockOf(outline.text)}\n\nRequested range payloads are available in details.returnedRanges.`;
-
-	const metrics = buildMetrics({
-		classification: "applied",
-		returnMode: "ranges",
-		editsAttempted: editMeta.editsAttempted,
-		noopEditsCount: editMeta.noopEditsCount,
-		warningsCount: warnings?.length ?? 0,
-		firstChangedLine: editMeta.firstChangedLine,
-		lastChangedLine: editMeta.lastChangedLine,
-	});
-
-	return {
-		content: [{ type: "text", text }],
-		details: {
-			diff: diffResult.diff,
-			firstChangedLine:
-				editMeta.firstChangedLine ?? diffResult.firstChangedLine,
-			snapshotId,
-			returnedRanges: rangePreviews.returnedRanges,
-			structureOutline: outline.outline,
 			metrics,
 		},
 	};
@@ -463,7 +184,7 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 					anchorRange.start - 1,
 					anchorRange.end,
 				);
-			const formatted = formatHashlineRegion(regionHashes, region);
+				const formatted = formatHashlineRegion(regionHashes, region);
 				const block = `--- Anchors ---\n${formatted}`;
 				return Buffer.byteLength(block, "utf8") <=
 					CHANGED_ANCHOR_TEXT_BUDGET_BYTES
@@ -472,15 +193,21 @@ export function buildChangedResponse(input: SuccessResponseInput): ToolResult {
 			})()
 		: resultLines.length === 0
 			? "File is empty. Use edit to insert content."
-			: "Anchors omitted; use read for subsequent edits.";
-
+			: (() => {
+					const diffLines = diffResult.diff.split("\n");
+					const MAX_DIFF_LINES = 30;
+					if (diffLines.length <= MAX_DIFF_LINES) {
+						return `Diff preview:\n${diffResult.diff}`;
+					}
+					const truncated = diffLines.slice(0, MAX_DIFF_LINES).join("\n");
+					return `Diff preview (${diffLines.length} lines, showing first ${MAX_DIFF_LINES}):\n${truncated}\n...`;
+				})();
 	const text = [anchorsBlock, warningsBlock.trimStart()]
 		.filter((section) => section.length > 0)
 		.join("\n\n");
 
 	const metrics = buildMetrics({
 		classification: "applied",
-		returnMode: "changed",
 		editsAttempted: editMeta.editsAttempted,
 		noopEditsCount: editMeta.noopEditsCount,
 		warningsCount: warnings?.length ?? 0,

package/src/replace.ts

@@ -30,11 +30,9 @@ import { throwIfAborted } from "./runtime";
 import { getFileSnapshot } from "./snapshot";
 import {
 	buildChangedResponse,
-	buildFullResponse,
 	buildNoopResponse,
-	buildRangesResponse,
 	type ReplaceMeta,
-	type ReturnMode,
+	type ReplaceMetrics,
 } from "./replace-response";
 import {
 	buildAppliedChangedResultText,
@@ -48,69 +46,31 @@ import {
 	type ReplaceRenderState,
 } from "./replace-render";
 
-function stringEnumSchema<const Values extends readonly string[]>(
-	values: Values,
-	options: { description: string },
-) {
-	return Type.Unsafe<Values[number]>({
-		type: "string",
-		enum: [...values],
-		description: options.description,
-	});
-}
 
-const hashlineEditLinesSchema = Type.Array(Type.String(), {
+const hashlineEditNewLinesSchema = Type.Array(Type.String(), {
 	description:
 		"replacement content, one array entry per line, no HASH| prefix",
 });
 
-const returnRangeSchema = Type.Object(
+const hasheditOldRangeSchema = Type.Array(
+	Type.String({ description: "anchor (3-char HASH)" }),
 	{
-		start: Type.Integer({
-			minimum: 1,
-			description: "first post-edit line to return",
-		}),
-		end: Type.Optional(
-			Type.Integer({
-				minimum: 1,
-				description: "last post-edit line to return",
-			}),
-		),
+		description: "inclusive line range to replace [start, end]",
+		minItems: 2,
+		maxItems: 2,
 	},
-	{ additionalProperties: false },
 );
 
 const hashlineEditItemSchema = Type.Object(
 	{
-		start: Type.Optional(
-			Type.String({
-				description:
-					"required range-start anchor (hash anchor like \"aB3x\" copied from read output); no content may follow the anchor",
-			}),
-		),
-		end: Type.Optional(
-			Type.String({
-				description:
-					"required range-end anchor (hash anchor like \"aB3x\"). To replace a single line, set start = end = the line's anchor",
-			}),
-		),
-		lines: Type.Optional(hashlineEditLinesSchema),
+		old_range: Type.Optional(hasheditOldRangeSchema),
+		new_lines: Type.Optional(hashlineEditNewLinesSchema),
 	},
 	{ additionalProperties: false },
 );
 export const hashlineEditToolSchema = Type.Object(
 	{
 		path: Type.String({ description: "path" }),
-		returnMode: Type.Optional(
-			stringEnumSchema(["changed", "full", "ranges"] as const, {
-				description: 'response mode: "changed", "full", or "ranges"',
-			}),
-		),
-		returnRanges: Type.Optional(
-			Type.Array(returnRangeSchema, {
-				description: "post-edit line ranges when returnMode is ranges",
-			}),
-		),
 		edits: Type.Optional(
 			Type.Array(hashlineEditItemSchema, { description: "edits over $path" }),
 		),
@@ -118,41 +78,11 @@ export const hashlineEditToolSchema = Type.Object(
 	{ additionalProperties: false },
 );
 
-type ReturnRange = {
-	start: number;
-	end?: number;
-};
-
-type ReturnedRangePreview = {
-	start: number;
-	end: number;
-	text: string;
-	nextOffset?: number;
-	empty?: true;
-};
-
-type FullContentPreview = {
-	text: string;
-	nextOffset?: number;
-};
-
 export type ReplaceRequestParams = {
 	path: string;
-	returnMode?: "changed" | "full" | "ranges";
-	returnRanges?: ReturnRange[];
 	edits?: HashlineToolEdit[];
 };
 
-type ReplaceMetrics = {
-	edits_attempted: number;
-	edits_noop: number;
-	warnings: number;
-	return_mode: "changed" | "full" | "ranges";
-	classification: "applied" | "noop";
-	changed_lines?: { first: number; last: number };
-	added_lines?: number;
-	removed_lines?: number;
-};
 
 export type HashlineReplaceToolDetails = {
 	diff: string;
@@ -164,9 +94,6 @@ export type HashlineReplaceToolDetails = {
 	 */
 	snapshotId?: string;
 	classification?: "noop";
-	nextOffset?: number;
-	fullContent?: FullContentPreview;
-	returnedRanges?: ReturnedRangePreview[];
 	structureOutline?: string[];
 	/**
 	 * Phase 2 C — opt-in observability surface for hosts. Never echoed in text.
@@ -194,7 +121,7 @@ const EDIT_PROMPT_GUIDELINES = readFileSync(
 	.map((line) => line.trim())
 	.filter((line) => line.startsWith("- "))
 	.map((line) => line.slice(2));
-const ROOT_KEYS = new Set(["path", "returnMode", "returnRanges", "edits"]);
+const ROOT_KEYS = new Set(["path", "edits"]);
 
 export function assertReplaceRequest(
 	request: unknown,
@@ -203,10 +130,10 @@ export function assertReplaceRequest(
 		throw new Error("[E_BAD_SHAPE] Edit request must be an object.");
 	}
 
-	for (const legacyKey of ["oldText", "newText", "old_text", "new_text"]) {
+	for (const legacyKey of ["oldText", "newText", "old_text", "new_text", "start", "end", "lines"]) {
 		if (hasOwn(request, legacyKey)) {
 			throw new Error(
-				`[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {start:"<HASH>", end:"<HASH>", lines:[...]}.`
+				`[E_LEGACY_SHAPE] "${legacyKey}" is not supported. Use {old_range: ["<START>", "<END>"], new_lines: [...]}.`
 			);
 		}
 	}
@@ -228,66 +155,7 @@ export function assertReplaceRequest(
 		throw new Error('[E_BAD_SHAPE] Edit request requires an "edits" array when provided.');
 	}
 
-	if (hasOwn(request, "returnMode")) {
-		if (
-			request.returnMode !== "changed" &&
-			request.returnMode !== "full" &&
-			request.returnMode !== "ranges"
-		) {
-			throw new Error(
-				'[E_BAD_SHAPE] Edit request field "returnMode" must be "changed", "full", or "ranges" when provided.',
-			);
-		}
-	}
-
-	if (hasOwn(request, "returnRanges")) {
-		if (
-			!Array.isArray(request.returnRanges) ||
-			request.returnRanges.length === 0
-		) {
-			throw new Error(
-				'[E_BAD_SHAPE] Edit request field "returnRanges" must be a non-empty array when provided.',
-			);
-		}
-		for (const [index, range] of request.returnRanges.entries()) {
-			if (!isRecord(range)) {
-				throw new Error(`[E_BAD_SHAPE] returnRanges[${index}] must be an object.`);
-			}
-			if (!Number.isInteger(range.start) || (range.start as number) < 1) {
-				throw new Error(
-					`[E_BAD_SHAPE] returnRanges[${index}].start must be a positive integer.`,
-				);
-			}
-			if (hasOwn(range, "end")) {
-				if (!Number.isInteger(range.end) || (range.end as number) < 1) {
-					throw new Error(
-						`[E_BAD_SHAPE] returnRanges[${index}].end must be a positive integer when provided.`,
-					);
-				}
-				if ((range.end as number) < (range.start as number)) {
-					throw new Error(`[E_BAD_SHAPE] returnRanges[${index}].end must be >= start.`);
-				}
-			}
-		}
-	}
-
-	if (request.returnMode === "ranges") {
-		if (
-			!Array.isArray(request.returnRanges) ||
-			request.returnRanges.length === 0
-		) {
-			throw new Error(
-				'[E_BAD_SHAPE] Edit request with returnMode "ranges" requires a non-empty "returnRanges" array.',
-			);
-		}
-	} else if (hasOwn(request, "returnRanges")) {
-		throw new Error(
-			'[E_BAD_SHAPE] Edit request field "returnRanges" is only supported when returnMode is "ranges".',
-		);
-	}
-
 }
-
 async function executeEditPipeline(
 	request: unknown,
 	cwd: string,
@@ -495,7 +363,6 @@ const editToolDefinition: EditToolDefinition = {
 		const renderedText = getRenderedEditTextContent(typedResult);
 
 		const renderState = context.state as ReplaceRenderState | undefined;
-		const previewBeforeResult = renderState?.preview;
 		if (renderState) {
 			renderState.preview = undefined;
 			renderState.previewGeneration = (renderState.previewGeneration ?? 0) + 1;
@@ -517,7 +384,6 @@ const editToolDefinition: EditToolDefinition = {
 			const appliedChangedText = buildAppliedChangedResultText(
 				renderedText,
 				typedResult.details,
-				previewBeforeResult,
 				theme,
 			);
 			if (!appliedChangedText) {
@@ -549,9 +415,6 @@ const editToolDefinition: EditToolDefinition = {
 		const normalizedParams = normalized;
 		const path = normalizedParams.path;
 		const absolutePath = resolveToCwd(path, ctx.cwd);
-		const returnMode = normalizedParams.returnMode ?? "changed";
-		const requestedReturnRanges = normalizedParams.returnRanges;
-
 		const mutationTargetPath = await resolveMutationTargetPath(absolutePath);
 		return withFileMutationQueue(mutationTargetPath, async () => {
 			throwIfAborted(signal);
@@ -581,8 +444,6 @@ const editToolDefinition: EditToolDefinition = {
 				const noopSnapshotId = (await getFileSnapshot(absolutePath)).snapshotId;
 				return buildNoopResponse({
 					path,
-					returnMode: returnMode as ReturnMode,
-					requestedReturnRanges,
 					noopEdits,
 					originalNormalized,
 					snapshotId: noopSnapshotId,
@@ -617,8 +478,6 @@ const editToolDefinition: EditToolDefinition = {
 
 			const successInput = {
 				path,
-				returnMode: returnMode as ReturnMode,
-				requestedReturnRanges,
 				originalNormalized,
 				result,
 				resultHashes: computeLineHashes(result),
@@ -627,8 +486,6 @@ const editToolDefinition: EditToolDefinition = {
 				editMeta,
 			};
 
-			if (returnMode === "full") return buildFullResponse(successInput);
-			if (returnMode === "ranges") return buildRangesResponse(successInput);
 			return buildChangedResponse(successInput);
 		});
 	},