@d3ara1n/pi-hashline-edit 0.1.2 → 0.2.0

package/README.md

@@ -2,15 +2,44 @@
 
 > Hashline-style file editing for [pi](https://github.com/earendil-works/pi-coding-agent) — line-anchored edits verified by content hash, replacing `oldText`/`newText` matching.
 
-Edits reference lines by `LINE#HASH` anchors (copied from `read` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
+Edits reference lines by `LINE#HASH` anchors (copied from `read`/`grep` output) instead of retyping the code to be changed — eliminating string-not-found loops and whitespace battles at the root.
+
+## Why hashline?
+
+The built-in `edit` matches `oldText`/`newText` exactly. When the model can't reproduce the source verbatim — wrong indentation, a non-unique snippet, or a line that drifted since the read — the edit fails and you loop. Hashline sidesteps all of it:
+
+- **No string-not-found loops** — you edit by reference (`LINE#HASH`), not by retyping the line you want to change.
+- **No whitespace battles** — the new content is the only thing you type; nothing has to match what's already there. Indentation mistakes on the *old* code are impossible.
+- **Unique-by-construction hashes** — the line number is folded into the hash, so identical lines (blank lines, `}`) never share a hash and never collide.
+- **Chain edits without re-reading** — a successful `edit` returns fresh anchors for the lines it produced, so the next edit cites them directly instead of forcing a full re-read.
+- **Grep-to-edit, no detour** — search results carry the same `LINE#HASH` anchors (grouped by file, context lines included); grab one and edit directly, skipping the read you'd otherwise need.
+- **Surgical drift detection** — each cited anchor is rechecked against the current line only; an unrelated change elsewhere never blocks your edit.
+- **Self-healing stale anchors** — a drifted anchor (content shifted by an edit above it) doesn't force a full re-read: the applicator rescans ±lines for the original content and hands back a fresh `LINE#HASH` to retry with, only asking for a re-read when the content genuinely changed.
+
+## When to use it
+
+Routine local code editing in pi — the common case. If you spend turns fighting "old_string not found" or fixing indentation the model dropped, this is the fix.
+
+## When to turn it off
+
+Set `hashlineEdit.enabled = false` (or uninstall) to fall back to the built-in `read`/`edit`/`grep` when you need **remote or custom-storage files** — the overrides read/write/search the local filesystem directly, so pi's custom `ReadOperations`/`GrepOperations` (SSH, etc.) aren't supported. The same switch lets you opt out per-project.
+
+## Gotchas (vs. the built-in `read`/`edit`)
+
+Once hashline overrides the built-ins, a few things behave differently:
+
+- **`read` is globally overridden.** Every read shows the `LINE#HASH│` prefix on each line — even reads that won't lead to an edit. This is expected (it's the substrate the reliability is built on), just don't be surprised when the format changes for all files.
+- **Conservative overlap.** Two ops whose ranges touch (e.g. `insert_after` immediately followed by `replace` at the same line) are rejected to avoid backfill ambiguity — issue them as two separate `edit` calls.
 
 ## Design
 
-- **Per-line hash + line number, dual anchor**: `read` shows each line with a short hash (`3#aF3│code`); `edit` references `LINE#HASH`. The line number is the address; the hash is a checksum that the line at that address is still what was read.
-- **Line + content hash**: each line's hash mixes its 1-based line number into its content, so every line gets a unique hash by construction — no in-file collisions, no length extension. The hash changes only when the line's own content changes, never when a neighbor changes.
-- **Live, surgical verification**: at apply time each cited anchor's hash is recomputed from the CURRENT line content and compared — no stored snapshot, no whole-file stale check. A line that changed (or was misremembered) fails its own anchor; an unrelated change elsewhere never blocks the edit. No fuzzy matching, no boundary repair, no drift relocation.
-- **Chain edits without re-reading**: a successful `edit` returns `Updated anchors` (`LINE#HASH│`) for the lines it produced (and the line that shifted into a deletion gap), so the next edit to the same file can cite them directly.
-- **No legacy compatibility**: overrides the built-in `edit`/`read`. `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use.
+- **Per-line hash + line number, dual anchor**: `read` shows each line as `3#aF3│code`; `edit` references `LINE#HASH`. The line number is the address; the hash is a checksum that the line at that address is still what was read.
+- **Line folded into the hash**: each line's hash mixes its 1-based line number into its content, so every line is unique by construction — no in-file collisions, no length extension. The hash changes only when the line's own content changes, never when a neighbor changes.
+- **Live, surgical verification**: at apply time each cited anchor's hash is recomputed from the current line content and compared — no stored snapshot, no whole-file stale check. A line that changed (or was misremembered) fails its own anchor; an unrelated change elsewhere never blocks the edit. No fuzzy matching, no boundary repair.
+- **Shifted-anchor recovery**: a mismatched anchor isn't a dead end. The applicator rescans ±`shiftRadius` lines for the original content — holding the original line number fixed and re-hashing each candidate (`hash(line, candidate) === cited` iff the candidate *is* the original) — and returns a ready-to-resend anchor on a unique hit, the candidate list when ambiguous, or the cited line's live content when nothing matches. The model retries without a re-read in the common drift case.
+- **Atomic batches, all failures collected**: every op in one `edit` is verified against the same snapshot; if any anchor fails, *all* failures (each with its recovery) are returned together and nothing is written — partial writes would shift lines and invalidate the very recovery info just returned.
+- **Chain edits without re-reading**: a successful `edit` returns `Updated anchors` for the lines it produced (and the line that shifted into a deletion gap), so the next edit can cite them directly.
+- **No legacy compatibility**: `edit` accepts only structured hashline ops; sending legacy `oldText`/`newText` is rejected at the schema layer (never silently degrades) — so you always know whether hashline is actually in use.
 
 ## Protocol
 
@@ -18,11 +47,22 @@ Edits reference lines by `LINE#HASH` anchors (copied from `read` output) instead
 
 ```
 src/foo.ts · 6 lines
-   1#aF3│import { compute } from "./util"
-   2#7Qk│
-   3#mP0│export function foo(x: number) {
+1#aF3│import { compute } from "./util"
+2#7Qk│
+3#mP0│export function foo(x: number) {
+```
+
+`grep` output (results grouped by file, each line anchored — copy `LINE#HASH` straight into an edit):
+
+```
+src/foo.ts · 2 matches
+3#mP0│export function foo(x: number) {
+4#kLp│  return x + 1
+src/util.ts · 1 match
+10#aF3│  const z = compute(x)
 ```
 
+
 `edit` takes `path` + `edits` (an array of ops, each with `op`, `anchor`/`end` `{line, hash}` from read, and `body` string[]):
 
 ```jsonc
@@ -37,6 +77,20 @@ src/foo.ts · 6 lines
 
 Ops: `replace` · `delete` · `insert_after` · `insert_before` · `append` · `prepend`. `anchor`/`end` = `{line, hash}` from read; `body` = new content lines (string[], omit for `delete`).
 
+## Configuration
+
+Add a `hashlineEdit` field to `~/.pi/agent/settings.json` (global) or `.pi/settings.json` in a project (project replaces global):
+
+```jsonc
+{
+  "hashlineEdit": {
+    "enabled": true,     // set false to fall back to the built-in read/edit
+    "hashLen": 4,        // hash length, 2–8 (default 4)
+    "shiftRadius": 15    // ±lines scanned to rescue a stale anchor (default 15; 0 disables)
+  }
+}
+```
+
 ## Installation
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-hashline-edit",
-  "version": "0.1.2",
+  "version": "0.2.0",
   "type": "module",
   "description": "Hashline-style file editing for pi — line-anchored edits verified by content hash, replacing oldText/newText matching",
   "keywords": [

package/src/core/apply.test.ts

@@ -103,14 +103,14 @@ test("anchor hash mismatch rejected (line changed)", () => {
 	const text = "a\nb\n";
 	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: "WRONG" }, body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "anchor");
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
 });
 
 test("line out of range rejected", () => {
 	const text = "a\n";
 	const r = applyEdits(text, [{ op: "replace", start: { line: 5, hash: computeLineHash(1, "a") }, body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "anchor");
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
 });
 
 test("anchor mismatch when the cited line's content differs (live verification)", () => {
@@ -118,14 +118,14 @@ test("anchor mismatch when the cited line's content differs (live verification)"
 	const text = "a\nb\n";
 	const r = applyEdits(text, [{ op: "replace", start: { line: 1, hash: computeLineHash(2, "b") }, body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "anchor");
+	if (!r.ok) assert.equal(r.failure.kind, "anchor");
 });
 
 test("reverse-order range rejected", () => {
 	const text = "a\nb\nc\n";
 	const r = applyEdits(text, [{ op: "replace", start: at(text, 3), end: at(text, 1), body: ["x"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("overlapping edits rejected", () => {
@@ -135,7 +135,7 @@ test("overlapping edits rejected", () => {
 		{ op: "replace", start: at(text, 3), body: ["y"] },
 	]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("conflict at the same insertion point rejected", () => {
@@ -145,14 +145,14 @@ test("conflict at the same insertion point rejected", () => {
 		{ op: "insert_after", anchor: at(text, 1), body: ["y"] },
 	]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "range");
+	if (!r.ok) assert.equal(r.failure.kind, "range");
 });
 
 test("noop (byte-identical body) rejected", () => {
 	const text = "a\nb\n";
 	const r = applyEdits(text, [{ op: "replace", start: at(text, 1), body: ["a"] }]);
 	assert.equal(r.ok, false);
-	if (!r.ok) assert.equal(r.error.kind, "noop");
+	if (!r.ok) assert.equal(r.failure.kind, "noop");
 });
 
 test("unrelated change elsewhere does NOT block the edit (no global stale check)", () => {
@@ -171,3 +171,94 @@ test("CRLF line endings preserved", () => {
 	if (r.ok) assert.equal(r.text, "A\r\nb\r\n");
 });
 
+// --- shifted-anchor recovery ---
+
+test("shifted recovery: content moved down → found with a fresh anchor", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n"; // inserted X after line 1 → "c" moved 3→4
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "found");
+		if (f.recovery.kind === "found") {
+			assert.equal(f.recovery.newLine, 4);
+			// the rescued anchor must verify against the current file
+			assert.equal(computeLineHash(4, splitLines(currentText)[3]), f.recovery.newHash);
+		}
+	}
+});
+
+test("rescued anchor lets the retry succeed without a re-read", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n";
+	// first attempt with a stale anchor → rescued
+	const r1 = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }]);
+	assert.equal(r1.ok, false);
+	if (r1.ok) return;
+	if (r1.failure.kind !== "anchor") return;
+	const f = r1.failure.failures[0];
+	assert.equal(f.recovery.kind, "found");
+	if (f.recovery.kind !== "found") return;
+	// retry with the rescued anchor → succeeds, file unchanged elsewhere
+	const r2 = applyEdits(currentText, [
+		{ op: "replace", start: { line: f.recovery.newLine, hash: f.recovery.newHash }, body: ["C"] },
+	]);
+	assert.equal(r2.ok, true);
+	if (r2.ok) assert.equal(r2.text, "a\nX\nb\nC\nd\ne\n");
+});
+
+test("shifted recovery: duplicate content → ambiguous candidates", () => {
+	const readText = "a\nx\nb\nx\nc\n";
+	const currentText = "a\nY\nx\nb\nx\nc\n"; // both "x" shifted
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 2), body: ["Z"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "ambiguous");
+		if (f.recovery.kind === "ambiguous") {
+			assert.deepEqual(
+				f.recovery.candidates.map((c) => c.line),
+				[3, 5],
+			);
+		}
+	}
+});
+
+test("shifted recovery: content genuinely changed → none, with live content", () => {
+	const readText = "a\nb\nc\n";
+	const currentText = "a\nBCHANGED\nc\n"; // "b" is gone
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 2), body: ["B"] }]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		const f = r.failure.failures[0];
+		assert.equal(f.recovery.kind, "none");
+		assert.equal(f.current?.content, "BCHANGED");
+	}
+});
+
+test("collect-all: two stale anchors in one batch → both failures returned", () => {
+	const readText = "a\nb\nc\nd\n";
+	const currentText = "X\na\nb\nc\nd\n"; // inserted X at top → all shifted +1
+	const r = applyEdits(currentText, [
+		{ op: "replace", start: at(readText, 2), body: ["B"] },
+		{ op: "replace", start: at(readText, 4), body: ["D"] },
+	]);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		assert.equal(r.failure.failures.length, 2);
+		const found = r.failure.failures.map((f) => (f.recovery.kind === "found" ? f.recovery.newLine : -1));
+		assert.deepEqual(found, [3, 5]);
+	}
+});
+
+test("shiftRadius=0 disables rescue (always none)", () => {
+	const readText = "a\nb\nc\nd\ne\n";
+	const currentText = "a\nX\nb\nc\nd\ne\n";
+	const r = applyEdits(currentText, [{ op: "replace", start: at(readText, 3), body: ["C"] }], 4, 0);
+	assert.equal(r.ok, false);
+	if (!r.ok && r.failure.kind === "anchor") {
+		assert.equal(r.failure.failures[0].recovery.kind, "none");
+	}
+});
+

package/src/core/apply.ts

@@ -7,6 +7,20 @@
  * misremembered) fails its own anchor; unchanged lines elsewhere never block
  * the edit.
  *
+ * Shifted-anchor recovery: when a cited anchor no longer matches, we rescan
+ * ±radius lines for the original content, holding the ORIGINAL line number fixed
+ * and re-hashing each candidate's content. On a unique hit the new anchor (with
+ * its freshly computed hash) is returned so the caller can retry without a
+ * re-read; on several hits they are reported as ambiguous; on none the live
+ * content at the cited line is returned to steer a re-read.
+ *
+ * Batch semantics: all ops are verified against the same current snapshot. If
+ * ANY anchor fails, EVERY failure (with recovery) is collected and returned
+ * together — nothing is written. This keeps the rescue report and the on-disk
+ * file in sync: a partial write would shift lines and invalidate the very
+ * recovery info we just returned. Range issues among the surviving ops are
+ * deferred until anchors are corrected.
+ *
  * Other strict semantics:
  * - Operation ranges must not overlap (including the same insertion point).
  * - body byte-identical to the whole-file result → `noop` error (guides the
@@ -17,7 +31,7 @@
 
 import { computeLineHash } from "./hash.ts";
 import { detectLineEnding, joinLines, splitLines } from "./lines.ts";
-import type { Anchor, ApplyResult, Edit, PatchError } from "./types.ts";
+import type { Anchor, AnchorFailure, AnchorRecovery, ApplyResult, Edit } from "./types.ts";
 
 /** Line-level operation: replace the raw lines in the `[lo, hi)` range (0-based, hi exclusive) with newLines. */
 interface SpanOp {
@@ -26,40 +40,94 @@ interface SpanOp {
 	newLines: string[];
 }
 
-/** Verify an anchor against the current file: line in range and hash matches the live content. */
-function checkAnchor(lines: readonly string[], line: number, hash: string, hashLen: number): PatchError | null {
-	if (line < 1 || line > lines.length) {
-		return {
-			kind: "anchor",
-			message: `line ${line} does not exist (file has ${lines.length} lines)`,
-		};
+/** Default ±line radius for shifted-anchor recovery. */
+const DEFAULT_SHIFT_RADIUS = 15;
+
+/**
+ * Verify an anchor against the live content; on mismatch, attempt shifted
+ * recovery. Returns null when the anchor matches, otherwise an
+ * {@link AnchorFailure} carrying the recovery outcome and the cited line's
+ * current snapshot.
+ *
+ * Recovery holds the ORIGINAL line number fixed and re-hashes each candidate's
+ * content: `computeLineHash(citedLine, candidateContent) === citedHash` holds
+ * iff the candidate IS the original content (modulo negligible hash collision).
+ * A returned candidate's anchor uses the candidate's real line number with a
+ * hash computed for that line, so it verifies on retry.
+ */
+function verifyAnchor(
+	lines: readonly string[],
+	cited: Anchor,
+	which: "anchor" | "end",
+	opIndex: number,
+	op: Edit["op"],
+	hashLen: number,
+	radius: number,
+): AnchorFailure | null {
+	const { line, hash } = cited;
+	if (line >= 1 && line <= lines.length && computeLineHash(line, lines[line - 1], hashLen) === hash) {
+		return null;
 	}
-	if (computeLineHash(line, lines[line - 1], hashLen) !== hash) {
-		return {
-			kind: "anchor",
-			message: `line ${line} changed or hash is wrong: re-read to get the current #HASH`,
-		};
+
+	// Shifted recovery: scan ±radius (excluding the already-failed cited line).
+	const candidates: { line: number; hash: string }[] = [];
+	const lo = Math.max(1, line - radius);
+	const hi = Math.min(lines.length, line + radius);
+	for (let c = lo; c <= hi; c++) {
+		if (c === line) continue;
+		if (computeLineHash(line, lines[c - 1], hashLen) === hash) {
+			candidates.push({ line: c, hash: computeLineHash(c, lines[c - 1], hashLen) });
+		}
+	}
+
+	let recovery: AnchorRecovery;
+	if (candidates.length === 1) {
+		recovery = { kind: "found", newLine: candidates[0].line, newHash: candidates[0].hash };
+	} else if (candidates.length > 1) {
+		recovery = { kind: "ambiguous", candidates };
+	} else {
+		recovery = { kind: "none" };
 	}
-	return null;
+
+	const current =
+		line >= 1 && line <= lines.length
+			? { hash: computeLineHash(line, lines[line - 1], hashLen), content: lines[line - 1] }
+			: null;
+
+	return { opIndex, which, op, cited, recovery, current };
 }
 
+type TranslateResult =
+	| { readonly ok: true; readonly op: SpanOp }
+	| { readonly ok: false; readonly anchorFailures: AnchorFailure[] }
+	| { readonly ok: false; readonly rangeError: string };
+
 /** Translate an Edit into a SpanOp, verifying anchors and ranges against the current lines. */
-function translateEdit(edit: Edit, lines: readonly string[], hashLen: number): { op: SpanOp } | { error: PatchError } {
+function translateEdit(
+	edit: Edit,
+	opIndex: number,
+	lines: readonly string[],
+	hashLen: number,
+	radius: number,
+): TranslateResult {
 	switch (edit.op) {
 		case "replace":
 		case "delete": {
-			const startErr = checkAnchor(lines, edit.start.line, edit.start.hash, hashLen);
-			if (startErr) return { error: startErr };
+			const failures: AnchorFailure[] = [];
+			const startF = verifyAnchor(lines, edit.start, "anchor", opIndex, edit.op, hashLen, radius);
+			if (startF) failures.push(startF);
 			let endLine = edit.start.line;
 			if (edit.end) {
-				const endErr = checkAnchor(lines, edit.end.line, edit.end.hash, hashLen);
-				if (endErr) return { error: endErr };
+				const endF = verifyAnchor(lines, edit.end, "end", opIndex, edit.op, hashLen, radius);
+				if (endF) failures.push(endF);
 				endLine = edit.end.line;
 			}
+			if (failures.length > 0) return { ok: false, anchorFailures: failures };
 			if (endLine < edit.start.line) {
-				return { error: { kind: "range", message: `range ${edit.start.line}..${endLine} ends before it starts` } };
+				return { ok: false, rangeError: `range ${edit.start.line}..${endLine} ends before it starts` };
 			}
 			return {
+				ok: true,
 				op: {
 					lo: edit.start.line - 1,
 					hi: endLine,
@@ -68,20 +136,20 @@ function translateEdit(edit: Edit, lines: readonly string[], hashLen: number): {
 			};
 		}
 		case "insert_after": {
-			const err = checkAnchor(lines, edit.anchor.line, edit.anchor.hash, hashLen);
-			if (err) return { error: err };
-			return { op: { lo: edit.anchor.line, hi: edit.anchor.line, newLines: edit.body } };
+			const f = verifyAnchor(lines, edit.anchor, "anchor", opIndex, edit.op, hashLen, radius);
+			if (f) return { ok: false, anchorFailures: [f] };
+			return { ok: true, op: { lo: edit.anchor.line, hi: edit.anchor.line, newLines: edit.body } };
 		}
 		case "insert_before": {
-			const err = checkAnchor(lines, edit.anchor.line, edit.anchor.hash, hashLen);
-			if (err) return { error: err };
-			return { op: { lo: edit.anchor.line - 1, hi: edit.anchor.line - 1, newLines: edit.body } };
+			const f = verifyAnchor(lines, edit.anchor, "anchor", opIndex, edit.op, hashLen, radius);
+			if (f) return { ok: false, anchorFailures: [f] };
+			return { ok: true, op: { lo: edit.anchor.line - 1, hi: edit.anchor.line - 1, newLines: edit.body } };
 		}
 		case "append": {
-			return { op: { lo: lines.length, hi: lines.length, newLines: edit.body } };
+			return { ok: true, op: { lo: lines.length, hi: lines.length, newLines: edit.body } };
 		}
 		case "prepend": {
-			return { op: { lo: 0, hi: 0, newLines: edit.body } };
+			return { ok: true, op: { lo: 0, hi: 0, newLines: edit.body } };
 		}
 	}
 }
@@ -94,21 +162,40 @@ function maxAffected(op: SpanOp): number {
 /**
  * Apply edits to `text`. Anchors are verified against the current content; on
  * success `touchedLines` gives the 0-based indices of the new-file lines this
- * edit produced.
+ * edit produced. On any anchor mismatch, all failures (with shifted recovery)
+ * are collected and returned together — nothing is written.
  *
- * @param text    current full file text
- * @param edits   parsed edit operations
- * @param hashLen hash length used to verify anchors (default 4)
+ * @param text        current full file text
+ * @param edits       parsed edit operations
+ * @param hashLen     hash length used to verify anchors (default 4)
+ * @param shiftRadius ±line radius for shifted-anchor recovery (default 15; 0 disables rescue)
  */
-export function applyEdits(text: string, edits: Edit[], hashLen = 4): ApplyResult {
+export function applyEdits(text: string, edits: Edit[], hashLen = 4, shiftRadius = DEFAULT_SHIFT_RADIUS): ApplyResult {
 	const lines = splitLines(text);
 	const ending = detectLineEnding(text);
 
 	const ops: SpanOp[] = [];
-	for (const edit of edits) {
-		const t = translateEdit(edit, lines, hashLen);
-		if ("error" in t) return { ok: false, error: t.error };
-		ops.push(t.op);
+	const anchorFailures: AnchorFailure[] = [];
+	let rangeError: string | null = null;
+
+	for (let i = 0; i < edits.length; i++) {
+		const t = translateEdit(edits[i], i, lines, hashLen, shiftRadius);
+		if (t.ok) {
+			ops.push(t.op);
+		} else if ("anchorFailures" in t) {
+			anchorFailures.push(...t.anchorFailures);
+		} else if (rangeError === null) {
+			rangeError = t.rangeError;
+		}
+	}
+
+	// Anchor failures take priority: the model must fix anchors first; range
+	// issues among surviving ops are premature until anchors are corrected.
+	if (anchorFailures.length > 0) {
+		return { ok: false, failure: { kind: "anchor", failures: anchorFailures } };
+	}
+	if (rangeError !== null) {
+		return { ok: false, failure: { kind: "range", message: rangeError } };
 	}
 
 	// Overlap check: sort ascending by lo; the next op's start must not fall inside the previous op's affected range
@@ -117,7 +204,7 @@ export function applyEdits(text: string, edits: Edit[], hashLen = 4): ApplyResul
 		if (sorted[k].lo <= maxAffected(sorted[k - 1])) {
 			return {
 				ok: false,
-				error: {
+				failure: {
 					kind: "range",
 					message: `overlapping edits near line ${sorted[k].lo + 1}; issue one edit per range`,
 				},
@@ -135,7 +222,7 @@ export function applyEdits(text: string, edits: Edit[], hashLen = 4): ApplyResul
 	if (newText === text) {
 		return {
 			ok: false,
-			error: {
+			failure: {
 				kind: "noop",
 				message: "edit parsed and applied cleanly but produced no change; body is byte-identical — the bug is elsewhere, re-read first",
 			},

package/src/core/hash.ts

@@ -18,10 +18,6 @@
  * - Content alone would leave identical lines (blank lines, `}`) sharing a
  *   hash; mixing the line number disambiguates them for free.
  *
- * Drift (file changed since read) is caught up-front by the global stale check
- * (`text !== snapshot.text`). This hash's job is to verify the model actually
- * read the line — it cannot forge a `(line, content)` hash without reading.
- *
  * @module pi-hashline-edit/core
  */
 

package/src/core/types.ts

@@ -25,22 +25,57 @@ export type Edit =
 
 export type LineEnding = "lf" | "crlf";
 
-/** Error kinds. */
-export type PatchErrorKind =
-	| "anchor" // anchor hash does not match the current line content (line changed, or model misremembered) or line out of range
-	| "range" // illegal operation range (overlap, reverse order, etc.)
-	| "noop"; // edit produced no change (body byte-identical to the target)
+/**
+ * Outcome of shifted-anchor recovery. When a cited anchor's hash no longer
+ * matches the live content, the applicator rescans ±radius lines for the
+ * original content — holding the ORIGINAL line number fixed and re-hashing each
+ * candidate's content (`computeLineHash(citedLine, candidateContent) === citedHash`
+ * iff the candidate is the original content). A ready-to-resend anchor (with the
+ * freshly computed hash) is returned so the model can retry without a re-read.
+ *
+ * - `found` — exactly one nearby line holds the original content; resend the op
+ *   with the provided anchor.
+ * - `ambiguous` — several nearby lines match (e.g. duplicate content); the model
+ *   picks the right one from the candidates (each carries its own new hash).
+ * - `none` — the content genuinely changed; re-read.
+ */
+export type AnchorRecovery =
+	| { readonly kind: "found"; readonly newLine: number; readonly newHash: string }
+	| {
+			readonly kind: "ambiguous";
+			readonly candidates: ReadonlyArray<{ readonly line: number; readonly hash: string }>;
+	  }
+	| { readonly kind: "none" };
 
-export interface PatchError {
-	readonly kind: PatchErrorKind;
-	readonly message: string;
+/**
+ * A single anchor that failed verification, with its recovery attempt.
+ *
+ * `opIndex` is the 0-based position in the input `edits[]`; `which` names the
+ * op's anchor (`"anchor"` = start, `"end"` = range end); `op` is the op kind.
+ * `current` is the cited line's live content + hash (null if the line number is
+ * out of range) — surfaced when recovery is `none` so the model can self-diagnose.
+ */
+export interface AnchorFailure {
+	readonly opIndex: number;
+	readonly which: "anchor" | "end";
+	readonly op: Edit["op"];
+	readonly cited: Anchor;
+	readonly recovery: AnchorRecovery;
+	readonly current: { readonly hash: string; readonly content: string } | null;
 }
 
+/** Batch-level failure. `anchor` carries every per-anchor failure collected across the batch. */
+export type ApplyFailure =
+	| { readonly kind: "anchor"; readonly failures: readonly AnchorFailure[] }
+	| { readonly kind: "range"; readonly message: string }
+	| { readonly kind: "noop"; readonly message: string };
+
 /**
  * Apply result. On success, `touchedLines` lists the 0-based line indices in
  * the NEW file that this edit produced (inserted or replaced) — callers use it
  * to surface fresh `LINE#HASH` anchors so the model can chain edits without a
- * re-read.
+ * re-read. On failure, `failure` is either the collected set of anchor failures
+ * (each with recovery) or a single range/noop error; nothing is written.
  */
 export type ApplyResult =
 	| {
@@ -49,4 +84,4 @@ export type ApplyResult =
 			readonly changed: boolean;
 			readonly touchedLines: readonly number[];
 	  }
-	| { readonly ok: false; readonly error: PatchError };
+	| { readonly ok: false; readonly failure: ApplyFailure };

package/src/index.ts

@@ -14,6 +14,7 @@ import { loadConfig } from "./pi/config.ts";
 import { getState } from "./pi/state.ts";
 import { makeEditOverride } from "./pi/edit-tool.ts";
 import { makeReadOverride } from "./pi/read-tool.ts";
+import { makeGrepOverride } from "./pi/grep-tool.ts";
 
 export default function (pi: ExtensionAPI) {
 	const cwd = process.cwd();
@@ -26,4 +27,5 @@ export default function (pi: ExtensionAPI) {
 
 	pi.registerTool(makeReadOverride(cwd));
 	pi.registerTool(makeEditOverride(cwd));
+	pi.registerTool(makeGrepOverride(cwd));
 }

package/src/pi/config.ts

@@ -15,9 +15,11 @@ export interface HashlineEditConfig {
 	enabled: boolean;
 	/** Line hash length (default 4). */
 	hashLen: number;
+	/** ±line radius for shifted-anchor recovery (default 15; 0 disables rescue). */
+	shiftRadius: number;
 }
 
-const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4 };
+const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4, shiftRadius: 15 };
 
 function getAgentDir(): string {
 	const envDir = process.env.PI_AGENT_DIR;
@@ -49,5 +51,9 @@ export function loadConfig(cwd?: string): HashlineEditConfig {
 			typeof raw.hashLen === "number" && raw.hashLen >= 2 && raw.hashLen <= 8
 				? raw.hashLen
 				: DEFAULT_CONFIG.hashLen,
+		shiftRadius:
+			typeof raw.shiftRadius === "number" && raw.shiftRadius >= 0 && raw.shiftRadius <= 100
+				? raw.shiftRadius
+				: DEFAULT_CONFIG.shiftRadius,
 	};
 }

package/src/pi/edit-tool.ts

@@ -25,7 +25,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { readFile, writeFile } from "node:fs/promises";
 import { applyEdits, hashFileLines } from "../core/index.ts";
 import { splitLines } from "../core/lines.ts";
-import type { Edit, PatchError } from "../core/types.ts";
+import type { ApplyFailure, Edit } from "../core/types.ts";
 import { canonicalPath } from "./read-tool.ts";
 import { getState } from "./state.ts";
 
@@ -61,16 +61,59 @@ const editSchema = Type.Object({
 
 type EditOpInput = Static<typeof editOpSchema>;
 
-/** Turn a PatchError into helpful hint text for the model. */
-function errorText(e: PatchError, path: string): string {
-	switch (e.kind) {
-		case "anchor":
-			return `Anchor mismatch: ${e.message}. Re-read ${path} to get current line hashes (LINE#HASH).`;
-		case "range":
-			return `Bad range: ${e.message}`;
-		case "noop":
-			return `Edit produced no change: ${e.message}`;
+/**
+ * Turn an ApplyFailure into LLM-facing text. The FIRST line is a terse summary
+ * (the TUI's renderResult shows only the first line of an error result); the
+ * remaining lines carry the structured detail the model needs to retry without a
+ * re-read — rescued anchors / ambiguous candidates / the cited line's live
+ * content. range/noop are already terse single-line messages.
+ */
+function formatFailure(failure: ApplyFailure, path: string): string {
+	if (failure.kind === "range") return failure.message;
+	if (failure.kind === "noop") return failure.message;
+
+	const lines: string[] = [];
+	let found = 0;
+	let ambiguous = 0;
+	let none = 0;
+	for (const f of failure.failures) {
+		const where = `op #${f.opIndex} ${f.op} ${f.which} (line ${f.cited.line})`;
+		switch (f.recovery.kind) {
+			case "found": {
+				found++;
+				lines.push(
+					`• ${where}: content shifted to line ${f.recovery.newLine}. Resend this op with ${f.which} { "line": ${f.recovery.newLine}, "hash": "${f.recovery.newHash}" }.`,
+				);
+				break;
+			}
+			case "ambiguous": {
+				ambiguous++;
+				const nums = f.recovery.candidates.map((c) => c.line).join(", ");
+				const list = f.recovery.candidates
+					.map((c) => `{ "line": ${c.line}, "hash": "${c.hash}" }`)
+					.join(" / ");
+				lines.push(
+					`• ${where}: ambiguous — same content at lines ${nums}. Pick the right one and resend ${f.which} ${list}.`,
+				);
+				break;
+			}
+			case "none": {
+				none++;
+				const cur =
+					f.current != null
+						? `current line ${f.cited.line}: ${f.cited.line}#${f.current.hash}│${f.current.content}`
+						: `line ${f.cited.line} is out of range`;
+				lines.push(`• ${where}: not found nearby — content changed. ${cur}. Re-read ${path} for fresh anchors.`);
+				break;
+			}
+		}
 	}
+	const parts: string[] = [];
+	if (found) parts.push(`${found} rescued`);
+	if (ambiguous) parts.push(`${ambiguous} ambiguous`);
+	if (none) parts.push(`${none} need re-read`);
+	const brief = `Anchor mismatch: ${parts.join(", ")}.`;
+	return `${brief}\n${lines.join("\n")}`;
 }
 
 /** Translate JSON edit ops into core Edit[]. Validates conditional required fields (anchor/body per op). */
@@ -103,13 +146,16 @@ function toCoreEdits(ops: readonly EditOpInput[]): { ok: true; edits: Edit[] } |
 	return { ok: true, edits };
 }
 
-/** Build an error result (isError: true so the TUI/agent loop treats it as a failure). */
-function errResult(text: string) {
-	return {
-		isError: true as const,
-		content: [{ type: "text" as const, text }],
-		details: undefined,
-	};
+/**
+ * Fail the edit by throwing. pi's contract: a tool failure is signaled by throwing,
+ * not by returning `{ isError: true }` — the framework derives `context.isError` from
+ * whether execute threw, and overwrites `result.isError` with it
+ * (`updateResult({ ...result, isError: event.isError })`). Returning an isError object
+ * left the TUI rendering failures as success (green). The thrown message reaches the
+ * LLM verbatim; renderResult shows its first line in red.
+ */
+function errResult(text: string): never {
+	throw new Error(text);
 }
 
 /**
@@ -198,7 +244,7 @@ export function makeEditOverride(cwd: string) {
 }
 
 async function runHashline(absPath: string, displayPath: string, editOps: readonly EditOpInput[], signal: AbortSignal | undefined) {
-	const hashLen = getState().config.hashLen;
+	const { hashLen, shiftRadius } = getState().config;
 
 	let currentText: string;
 	try {
@@ -214,11 +260,13 @@ async function runHashline(absPath: string, displayPath: string, editOps: readon
 	if (!translated.ok) return errResult(translated.error);
 
 	// Anchors are verified against the current content. A line that changed (or a
-	// hash the model didn't actually read) fails its own anchor — steering it to
-	// read first. Unrelated changes elsewhere never block the edit.
-	const result = applyEdits(currentText, translated.edits, hashLen);
+	// hash the model didn't actually read) fails its own anchor — but first we try
+	// shifted recovery: if the content merely moved within ±shiftRadius, a fresh
+	// anchor is returned so the model can retry without a re-read. All failures in
+	// the batch are collected (nothing written on any failure).
+	const result = applyEdits(currentText, translated.edits, hashLen, shiftRadius);
 	if (!result.ok) {
-		return errResult(errorText(result.error, displayPath));
+		return errResult(formatFailure(result.failure, displayPath));
 	}
 
 	// Check for cancel before write: if aborted, don't touch the disk; the file stays untouched

package/src/pi/grep-tool.ts

@@ -0,0 +1,335 @@
+/**
+ * Override grep: search results carry `LINE#HASH│` anchors (same format as
+ * read), grouped by file. The model can copy `LINE#HASH` straight into an edit
+ * anchor — no re-read needed. Context lines (`-C`) are anchored too.
+ *
+ * We run ripgrep directly (`--json`) rather than wrap the built-in grep, so we
+ * control formatting and can compute each line's hash from its FULL content
+ * while displaying a truncated copy. (The built-in grep truncates long lines
+ * before formatting; hashing that truncated text would not match what edit
+ * verifies against the full line — so the hash must be computed from the full
+ * content, independently of what is displayed.)
+ *
+ * Falls back to the built-in grep when: hashline disabled, aborted, or ripgrep
+ * cannot be located.
+ *
+ * @module pi-hashline-edit/pi
+ */
+
+import {
+	createGrepTool,
+	truncateHead,
+	truncateLine,
+	formatSize,
+	DEFAULT_MAX_BYTES,
+} from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline";
+import { access, constants, readFile, stat } from "node:fs/promises";
+import { basename, delimiter, join, relative } from "node:path";
+import { homedir } from "node:os";
+import { hashFileLines } from "../core/hash.ts";
+import { splitLines } from "../core/lines.ts";
+import { getState } from "./state.ts";
+import { canonicalPath } from "./read-tool.ts";
+
+const DEFAULT_LIMIT = 100;
+/** Max chars per result line for display (mirrors pi's truncate.ts; not exported there). */
+const GREP_MAX_LINE_LENGTH = 500;
+
+/** Locate ripgrep: pi's bundled bin first, then PATH. Returns null if not found. */
+async function findRg(): Promise<string | null> {
+	const agentDir = process.env.PI_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+	const piRg = join(agentDir, "bin", "rg");
+	try {
+		await access(piRg, constants.X_OK);
+		return piRg;
+	} catch {}
+	for (const dir of process.env.PATH?.split(delimiter) ?? []) {
+		if (!dir) continue;
+		const p = join(dir, "rg");
+		try {
+			await access(p, constants.X_OK);
+			return p;
+		} catch {}
+	}
+	return null;
+}
+
+interface RawMatch {
+	filePath: string;
+	lineNumber: number;
+	match: boolean;
+}
+
+/**
+ * Convert the anchored grep output (grouped, `LINE#HASH│`) into a human-readable
+ * form for the TUI: drop the hash, keep file headers and line numbers. The model
+ * still receives the anchored `content` text; this only affects what the user sees.
+ */
+function toDisplayLines(raw: string, theme: any): string[] {
+	const out: string[] = [];
+	for (const line of raw.split("\n")) {
+		// anchored line first: "lineNo#HASH│content" → "   lineNo: content"
+		const a = line.match(/^(\d+)#[A-Za-z0-9]+│(.*)$/);
+		if (a) {
+			out.push(theme.fg("dim", `   ${a[1]}:`) + theme.fg("toolOutput", ` ${a[2]}`));
+			continue;
+		}
+		// file header: "path · N match(es)" → path accent, count dim
+		const h = line.match(/^(.+?) · (\d+ match(?:es)?)$/);
+		if (h) {
+			out.push(theme.fg("success", h[1]) + theme.fg("dim", ` · ${h[2]}`));
+			continue;
+		}
+		// truncation notice block "[...]"
+		if (line.startsWith("[")) {
+			out.push(theme.fg("warning", line));
+			continue;
+		}
+		out.push(theme.fg("toolOutput", line));
+	}
+	return out;
+}
+
+/** Build the grep override (a ToolDefinition fragment for registerTool). */
+export function makeGrepOverride(cwd: string) {
+	const builtin = createGrepTool(cwd);
+	const delegate = (toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any) =>
+		builtin.execute(toolCallId, params, signal, onUpdate);
+
+	return {
+		name: "grep" as const,
+		label: "grep",
+		description:
+			"Search file contents for a pattern. Matches show per-line content hashes (LINE#HASH│content) grouped by file — copy LINE#HASH straight into an edit anchor, no re-read needed. Context lines (context) are anchored too. Respects .gitignore.",
+		promptSnippet: "Search file contents; results show LINE#HASH anchors usable directly in edit (no re-read needed)",
+		promptGuidelines: [
+			"Results are grouped by file under a `path · N matches` header; each line shows `LINE#HASH│content` (same format as read).",
+			"Copy `LINE#HASH` straight into an edit `anchor`/`end` — no re-read needed. Context lines (from `context`) are anchored and editable too.",
+			"Pass `pattern`; optionally `path`, `glob`, `ignoreCase`, `literal`, `context` (lines before+after each match), `limit` (max matches, default 100).",
+		],
+		parameters: builtin.parameters,
+
+		renderShell: "default" as const,
+
+		renderCall(args: any, theme: any) {
+			const pattern = args?.pattern ?? "";
+			const p = args?.path ?? ".";
+			let text =
+				theme.fg("toolTitle", theme.bold("grep ")) +
+				theme.fg("accent", `/${pattern}/`) +
+				theme.fg("toolOutput", ` in ${p}`);
+			if (args?.glob) text += theme.fg("toolOutput", ` (${args.glob})`);
+			if (args?.limit !== undefined) text += theme.fg("toolOutput", ` limit ${args.limit}`);
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result: any, { isPartial, expanded }: any, theme: any, context: any) {
+			if (isPartial) return new Text(theme.fg("warning", "Searching…"), 0, 0);
+			if (context?.isError) {
+				const t = result.content?.[0]?.type === "text" ? result.content[0].text.split("\n")[0] : "Error";
+				return new Text(theme.fg("error", t), 0, 0);
+			}
+			const out = result.content?.[0]?.type === "text" ? result.content[0].text : "";
+			const styled = toDisplayLines(out, theme);
+			const maxLines = expanded ? styled.length : 15;
+			const shown = styled.slice(0, maxLines);
+			const more =
+				!expanded && styled.length > maxLines
+					? `\n${theme.fg("muted", `… (${styled.length - maxLines} more lines)`)}`
+					: "";
+			return new Text(shown.join("\n") + more, 0, 0);
+		},
+
+		async execute(toolCallId: string, params: any, signal: AbortSignal | undefined, onUpdate: any): Promise<any> {
+			const state = getState();
+			// disabled or already aborted → built-in grep (it handles abort itself)
+			if (!state.config.enabled || signal?.aborted) return delegate(toolCallId, params, signal, onUpdate);
+
+			const rgPath = await findRg();
+			// ripgrep unavailable → degrade to the built-in (which can auto-download rg)
+			if (!rgPath) return delegate(toolCallId, params, signal, onUpdate);
+
+			const { pattern, path: searchDir, glob, ignoreCase, literal, context, limit } = params;
+			const searchPath = canonicalPath(cwd, searchDir || ".");
+			const hashLen = state.config.hashLen;
+
+			let isDir = true;
+			try {
+				isDir = (await stat(searchPath)).isDirectory();
+			} catch {
+				throw new Error(`Path not found: ${searchPath}`);
+			}
+
+			return new Promise((resolvePromise, reject) => {
+				if (signal?.aborted) {
+					reject(new Error("Operation aborted"));
+					return;
+				}
+
+				const args = ["--json", "--line-number", "--color=never", "--hidden"];
+				if (ignoreCase) args.push("--ignore-case");
+				if (literal) args.push("--fixed-strings");
+				if (glob) args.push("--glob", glob);
+				const ctx = context && context > 0 ? context : 0;
+				if (ctx > 0) args.push("--context", String(ctx));
+				args.push("--", String(pattern), searchPath);
+
+				const effectiveLimit = Math.max(1, limit ?? DEFAULT_LIMIT);
+				const child = spawn(rgPath, args, { stdio: ["ignore", "pipe", "pipe"] });
+				const rl = createInterface({ input: child.stdout });
+				let stderr = "";
+				let matchCount = 0;
+				let matchLimitReached = false;
+				let linesTruncated = false;
+				let aborted = false;
+				let killedDueToLimit = false;
+				const raw: RawMatch[] = [];
+
+				const cleanup = () => {
+					rl.close();
+					signal?.removeEventListener("abort", onAbort);
+				};
+				const stopChild = (dueToLimit = false) => {
+					if (!child.killed) {
+						killedDueToLimit = dueToLimit;
+						child.kill();
+					}
+				};
+				const onAbort = () => {
+					aborted = true;
+					stopChild();
+				};
+				signal?.addEventListener("abort", onAbort, { once: true });
+				child.stderr?.on("data", (chunk: Buffer) => {
+					stderr += chunk.toString();
+				});
+
+				rl.on("line", (line: string) => {
+					if (!line.trim() || matchCount >= effectiveLimit) return;
+					let event: any;
+					try {
+						event = JSON.parse(line);
+					} catch {
+						return;
+					}
+					if (event.type === "match") {
+						matchCount++;
+						const filePath = event.data?.path?.text;
+						const lineNumber = event.data?.line_number;
+						if (filePath && typeof lineNumber === "number") raw.push({ filePath, lineNumber, match: true });
+						if (matchCount >= effectiveLimit) {
+							matchLimitReached = true;
+							stopChild(true);
+						}
+					} else if (event.type === "context") {
+						const filePath = event.data?.path?.text;
+						const lineNumber = event.data?.line_number;
+						if (filePath && typeof lineNumber === "number") raw.push({ filePath, lineNumber, match: false });
+					}
+				});
+
+				child.on("error", (error) => {
+					cleanup();
+					reject(new Error(`Failed to run ripgrep: ${error.message}`));
+				});
+
+				child.on("close", async (code) => {
+					cleanup();
+					if (aborted) {
+						reject(new Error("Operation aborted"));
+						return;
+					}
+					if (!killedDueToLimit && code !== 0 && code !== 1) {
+						reject(new Error(stderr.trim() || `ripgrep exited with code ${code}`));
+						return;
+					}
+					if (raw.length === 0) {
+						resolvePromise({ content: [{ type: "text", text: "No matches found" }], details: undefined });
+						return;
+					}
+
+					// Dedupe by (file, line); a line that is both a match and a context line counts as a match.
+					const map = new Map<string, RawMatch>();
+					for (const m of raw) {
+						const key = `${m.filePath}:${m.lineNumber}`;
+						const prev = map.get(key);
+						if (!prev || (!prev.match && m.match)) map.set(key, m);
+					}
+
+					// Group by file, each group sorted by line number.
+					const byFile = new Map<string, RawMatch[]>();
+					for (const m of map.values()) {
+						const arr = byFile.get(m.filePath) ?? [];
+						arr.push(m);
+						byFile.set(m.filePath, arr);
+					}
+					for (const arr of byFile.values()) arr.sort((a, b) => a.lineNumber - b.lineNumber);
+
+					// Read each file once and hash all its lines; hash is computed from the FULL line.
+					const fileCache = new Map<string, { lines: string[]; hashes: string[] }>();
+					const getFile = async (fp: string) => {
+						let entry = fileCache.get(fp);
+						if (!entry) {
+							let content = "";
+							try {
+								content = (await readFile(fp)).toString("utf-8");
+							} catch {
+								content = "";
+							}
+							const lines = splitLines(content);
+							entry = { lines, hashes: hashFileLines(lines, hashLen) };
+							fileCache.set(fp, entry);
+						}
+						return entry;
+					};
+
+					const formatPath = (fp: string): string => {
+						if (isDir) {
+							const rel = relative(searchPath, fp).replace(/\\/g, "/");
+							if (rel && !rel.startsWith("..")) return rel;
+						}
+						return basename(fp);
+					};
+
+					const blocks: string[] = [];
+					for (const [fp, matches] of byFile) {
+						const { lines, hashes } = await getFile(fp);
+						const n = matches.filter((m) => m.match).length;
+						const header = `${formatPath(fp)} · ${n} match${n !== 1 ? "es" : ""}`;
+						const rows: string[] = [];
+						for (const m of matches) {
+							const content = lines[m.lineNumber - 1] ?? "";
+							const hash = hashes[m.lineNumber - 1] ?? "";
+							const { text: disp, wasTruncated } = truncateLine(content.replace(/\r/g, ""));
+							if (wasTruncated) linesTruncated = true;
+							rows.push(`${m.lineNumber}#${hash}│${disp}`);
+						}
+						blocks.push(`${header}\n${rows.join("\n")}`);
+					}
+
+					let output = blocks.join("\n\n");
+					const truncation = truncateHead(output, { maxBytes: DEFAULT_MAX_BYTES });
+					output = truncation.content;
+
+					const notices: string[] = [];
+					if (matchLimitReached)
+						notices.push(
+							`${effectiveLimit} matches limit reached. Use limit=${effectiveLimit * 2} for more, or refine pattern`,
+						);
+					if (truncation.truncated) notices.push(`${formatSize(DEFAULT_MAX_BYTES)} limit reached`);
+					if (linesTruncated)
+						notices.push(`Some lines truncated to ${GREP_MAX_LINE_LENGTH} chars. Use read to see full lines`);
+					if (notices.length) output += `\n\n[${notices.join(". ")}]`;
+
+					resolvePromise({
+						content: [{ type: "text" as const, text: output }],
+						details: undefined,
+					});
+				});
+			});
+		},
+	};
+}

package/src/pi/pi.test.ts

@@ -1,9 +1,16 @@
 import { test } from "node:test";
 import assert from "node:assert/strict";
 import { canonicalPath } from "./read-tool.ts";
+import { homedir } from "node:os";
 
 test("canonicalPath resolves relative and absolute", () => {
 	assert.equal(canonicalPath("/cwd", "foo.ts"), "/cwd/foo.ts");
 	assert.equal(canonicalPath("/cwd", "./foo.ts"), "/cwd/foo.ts");
 	assert.equal(canonicalPath("/cwd", "/abs/x.ts"), "/abs/x.ts");
 });
+
+test("canonicalPath expands ~ to home directory", () => {
+	const home = homedir();
+	assert.equal(canonicalPath("/cwd", "~"), home);
+	assert.equal(canonicalPath("/cwd", "~/foo.ts"), `${home}/foo.ts`);
+});

package/src/pi/read-tool.ts

@@ -11,7 +11,8 @@
 
 import { createReadTool } from "@earendil-works/pi-coding-agent";
 import { readFile } from "node:fs/promises";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
 import { hashFileLines } from "../core/hash.ts";
 import { splitLines } from "../core/lines.ts";
 import { getState } from "./state.ts";
@@ -19,9 +20,21 @@ import { getState } from "./state.ts";
 const MAX_LINES = 2000;
 const MAX_BYTES = 256 * 1024;
 
-/** canonical path: shared by read/edit to resolve a file consistently. */
+/**
+ * Canonical absolute path: shared by read/edit/grep to resolve a file consistently.
+ * Expands a leading `~` / `~/` to the user's home directory. (`~user` is not supported.)
+ */
 export function canonicalPath(cwd: string, p: string): string {
-	return resolve(cwd, p);
+	return resolve(cwd, expandTilde(p));
+}
+
+/** Mirrors pi core's `normalizePath` tilde handling: expands `~` / `~/` (and `~\` on Windows), leaves `~user` untouched. */
+function expandTilde(p: string): string {
+	if (p === "~") return homedir();
+	if (p.startsWith("~/") || (process.platform === "win32" && p.startsWith("~\\"))) {
+		return join(homedir(), p.slice(2));
+	}
+	return p;
 }
 
 /** Build the read override (a ToolDefinition fragment for registerTool). */

package/src/pi/state.ts

@@ -10,7 +10,7 @@
 import type { HashlineEditConfig } from "./config.ts";
 
 const GLOBAL_KEY = "__piHashlineEdit";
-const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4 };
+const DEFAULT_CONFIG: HashlineEditConfig = { enabled: true, hashLen: 4, shiftRadius: 15 };
 
 export interface HashlineEditState {
 	config: HashlineEditConfig;