@d3ara1n/pi-hashline-edit 0.1.2 → 0.3.0

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
@@ -231,11 +279,16 @@ async function runHashline(absPath: string, displayPath: string, editOps: readon
 		return errResult(`Error writing ${displayPath}: ${msg}`);
 	}
 
-	// pi's generateDiffString returns the display diff (colored by the renderer) and the first changed line
-	const { diff, firstChangedLine } = generateDiffString(currentText, result.text);
+	// generateDiffString / generateUnifiedPatch split on \n, so raw CRLF content would
+	// leave a trailing \r on every diff line — the TUI line-wrapper (wrapTextWithAnsi)
+	// then emits a spurious blank line per diff line. Normalize to LF for diff/patch
+	// only; the disk write above already preserved the original line endings.
+	const oldLf = currentText.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const newLf = result.text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const { diff, firstChangedLine } = generateDiffString(oldLf, newLf);
 	const details: EditToolDetails = {
 		diff,
-		patch: generateUnifiedPatch(displayPath, currentText, result.text),
+		patch: generateUnifiedPatch(displayPath, oldLf, newLf),
 		firstChangedLine,
 	};
 	const anchors = formatUpdatedAnchors(result.text, result.touchedLines, hashLen);

package/src/pi/execute.test.ts

@@ -150,44 +150,49 @@ test("edit on a line that changed externally → anchor mismatch", async () => {
 		const text = "a\nb\nc\n";
 		await writeFile(f, text);
 		await writeFile(f, "a\nBCHANGED\nc\n"); // line 2 changed
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: h(text, 2), body: ["x"] }],
-		});
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /anchor|re-read/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: h(text, 2), body: ["x"] }],
+			}),
+			/anchor|re-read/i,
+		);
 	});
 });
 
 test("edit execute: no read before edit → anchor verification fails", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\nb\n");
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
-		});
-		assert.equal(r.isError, true);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
+			}),
+			/anchor|re-read/i,
+		);
 	});
 });
 
-test("edit execute: empty edits → isError", async () => {
+test("edit execute: empty edits → throws", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
-		const r: any = await call(makeEditOverride(dir), { path: "f.txt", edits: [] });
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /empty|missing/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), { path: "f.txt", edits: [] }),
+			/empty|missing/i,
+		);
 	});
 });
 
-test("edit execute: malformed op (replace without body) → isError", async () => {
+test("edit execute: malformed op (replace without body) → throws", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
-		const r: any = await call(makeEditOverride(dir), {
-			path: "f.txt",
-			edits: [{ op: "replace", anchor: { line: 1, hash: "XX" } }],
-		});
-		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /body/i);
+		await assert.rejects(
+			call(makeEditOverride(dir), {
+				path: "f.txt",
+				edits: [{ op: "replace", anchor: { line: 1, hash: "XX" } }],
+			}),
+			/body/i,
+		);
 	});
 });
 
@@ -247,13 +252,21 @@ test("edit error: renderResult renders the error line without throwing", async (
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		const edit = makeEditOverride(dir);
-		const r: any = await call(edit, {
+		let thrown: any;
+		await call(edit, {
 			path: "f.txt",
 			edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
+		}).catch((e: any) => {
+			thrown = e;
 		});
-		assert.equal(r.isError, true);
-		// @ts-ignore
-		const comp: any = edit.renderResult({ content: r.content, details: r.details }, { isPartial: false, expanded: false }, stubTheme, { isError: r.isError ?? false });
+		assert.ok(thrown, "expected the edit to throw");
+		// @ts-ignore — simulate the framework handing the thrown message to renderResult
+		const comp: any = edit.renderResult(
+			{ content: [{ type: "text", text: thrown.message }] },
+			{ isPartial: false, expanded: false },
+			stubTheme,
+			{ isError: true },
+		);
 		assert.ok(typeof comp?.text === "string");
 	});
 });

package/src/pi/grep-tool.ts

@@ -0,0 +1,353 @@
+/**
+ * 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. Within each
+ * file group, the common leading whitespace shared by all matched lines is folded
+ * into a single marker (›) so deep, repeated indentation doesn't eat display width;
+ * each line's indentation relative to that common base is preserved. The model still
+ * receives the anchored `content` text verbatim — this only affects what the user sees.
+ */
+function countLeading(s: string): number {
+	const m = s.match(/^[ \t]*/);
+	return m ? m[0].length : 0;
+}
+
+function toDisplayLines(raw: string, theme: any): string[] {
+	const out: string[] = [];
+	const lines = raw.split("\n");
+	let i = 0;
+	while (i < lines.length) {
+		const line = lines[i];
+		const h = line.match(/^(.+?) · (\d+ match(?:es)?)$/);
+		if (h) {
+			out.push(theme.fg("success", h[1]) + theme.fg("dim", ` · ${h[2]}`));
+			// collect the anchor lines in this file group
+			const group: { lineNo: string; content: string }[] = [];
+			let j = i + 1;
+			while (j < lines.length) {
+				const a = lines[j].match(/^(\d+)#[A-Za-z0-9]+│(.*)$/);
+				if (!a) break;
+				group.push({ lineNo: a[1], content: a[2] });
+				j++;
+			}
+			// common base = min leading whitespace across the group; fold it into a marker
+			const base = group.length ? Math.min(...group.map((g) => countLeading(g.content))) : 0;
+			const marker = base > 0 ? theme.fg("dim", "›") + " " : "";
+			for (const g of group) {
+				const body = g.content.slice(base);
+				out.push(theme.fg("dim", `   ${g.lineNo}: `) + marker + theme.fg("toolOutput", body));
+			}
+			i = j;
+			continue;
+		}
+		if (line.startsWith("[")) out.push(theme.fg("warning", line));
+		else out.push(theme.fg("toolOutput", line));
+		i++;
+	}
+	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). */