@d3ara1n/pi-hashline-edit 0.1.1 → 0.2.0

package/src/pi/execute.test.ts

@@ -1,7 +1,7 @@
 /**
- * Integration tests for the pi integration layer's execute: drives the real
- * makeReadOverride/makeEditOverride execute, covering text read with anchors,
- * the hashline edit closed loop, and error returns with isError.
+ * pi integration execute tests: drive the real makeReadOverride/makeEditOverride
+ * execute, covering text read with anchors, the hashline edit round-trip,
+ * chained edits via returned anchors, and error returns with isError.
  */
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -10,26 +10,36 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { makeEditOverride } from "./edit-tool.ts";
 import { makeReadOverride } from "./read-tool.ts";
-import { clearSnapshots, getSnapshot } from "./state.ts";
+import { computeLineHash } from "../core/hash.ts";
+import { splitLines } from "../core/lines.ts";
 
 async function withDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
 	const dir = await mkdtemp(join(tmpdir(), "hl-"));
-	clearSnapshots();
 	try {
 		return await fn(dir);
 	} finally {
 		await rm(dir, { recursive: true, force: true });
-		clearSnapshots();
 	}
 }
 
 const call = (tool: any, params: any) => tool.execute("0", params, undefined, undefined);
 
+/** Anchor a model would copy from read output for `line` of `text` (1-based). */
+function h(text: string, line: number) {
+	return { line, hash: computeLineHash(line, splitLines(text)[line - 1]) };
+}
+
+/** Extract a `LINE#HASH` anchor from a read/edit result text block. */
+function anchorLine(block: string, line: number) {
+	const m = new RegExp(`^${line}#([0-9A-Z]+)│`, "m").exec(block);
+	if (!m) throw new Error(`line ${line} anchor not found in block`);
+	return { line, hash: m[1] };
+}
+
 test("read execute: text outputs LINE#HASH│content", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "line1\nline2\n");
-		const read = makeReadOverride(dir);
-		const r: any = await call(read, { path: "f.txt" });
+		const r: any = await call(makeReadOverride(dir), { path: "f.txt" });
 		const text = r.content[0];
 		assert.equal(text.type, "text");
 		assert.match(text.text, /1#[0-9A-Z]+│line1/);
@@ -38,88 +48,224 @@ test("read execute: text outputs LINE#HASH│content", async () => {
 	});
 });
 
-test("read execute: records a snapshot for edit", async () => {
+test("edit execute: hashline round-trip (read → edit → file changed)", async () => {
 	await withDir(async (dir) => {
-		await writeFile(join(dir, "f.txt"), "a\nb\n");
-		const read = makeReadOverride(dir);
-		await call(read, { path: "f.txt" });
-		const snap = getSnapshot(join(dir, "f.txt"));
-		assert.ok(snap, "snapshot not recorded");
-		assert.equal(snap!.lineHashes.length, 2);
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
+		await call(makeReadOverride(dir), { path: "f.txt" });
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: h(text, 2), body: ["B"] }],
+		});
+		assert.equal(r.isError, undefined, "should not be an error");
+		assert.equal(await readFile(f, "utf-8"), "a\nB\nc\n");
 	});
 });
 
-test("edit execute: hashline closed loop (read → edit → file changed)", async () => {
+test("edit execute: multiple ops in one call", async () => {
 	await withDir(async (dir) => {
 		const f = join(dir, "f.txt");
-		await writeFile(f, "a\nb\nc\n");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
 		await call(makeReadOverride(dir), { path: "f.txt" });
-		const snap = getSnapshot(f)!;
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [
+				{ op: "insert_after", anchor: h(text, 3), body: ["z"] },
+				{ op: "replace", anchor: h(text, 1), body: ["A"] },
+			],
+		});
+		assert.equal(r.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "A\nb\nc\nz\n");
+	});
+});
+
+test("edit result returns Updated anchors that chain the next edit without a re-read", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
 		const edit = makeEditOverride(dir);
-		const r: any = await call(edit, {
+		// first edit (model cites the read anchor for line 1)
+		const r1: any = await call(edit, {
 			path: "f.txt",
-			input: `replace 2#${snap.lineHashes[1]}:\n+B`,
+			edits: [{ op: "replace", anchor: h(text, 1), body: ["A"] }],
 		});
-		assert.equal(r.isError, undefined, "should not be an error");
-		assert.equal(await readFile(f, "utf-8"), "a\nB\nc\n");
+		assert.equal(r1.isError, undefined);
+		const out: string = r1.content[0].text;
+		assert.match(out, /Updated anchors/);
+		// second edit chains on the anchor returned by the first edit — no read in between
+		const r2: any = await call(edit, {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: anchorLine(out, 1), body: ["AA"] }],
+		});
+		assert.equal(r2.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "AA\nb\nc\n");
 	});
 });
 
-test("edit execute: consecutive edits reuse the updated snapshot", async () => {
+test("edit result anchors cover an inserted block (chain an edit inside it)", async () => {
 	await withDir(async (dir) => {
 		const f = join(dir, "f.txt");
-		await writeFile(f, "a\nb\n");
-		const read = makeReadOverride(dir);
+		const text = "a\nb\n";
+		await writeFile(f, text);
 		const edit = makeEditOverride(dir);
-		await call(read, { path: "f.txt" });
-		let snap = getSnapshot(f)!;
-		await call(edit, { path: "f.txt", input: `replace 1#${snap.lineHashes[0]}:\n+A` });
-		// second edit: the snapshot was updated by the edit, use the new hash
-		snap = getSnapshot(f)!;
-		const r: any = await call(edit, { path: "f.txt", input: `replace 2#${snap.lineHashes[1]}:\n+B` });
+		const r1: any = await call(edit, {
+			path: "f.txt",
+			edits: [{ op: "insert_after", anchor: h(text, 2), body: ["c", "d", "e"] }],
+		});
+		assert.equal(r1.isError, undefined);
+		const out: string = r1.content[0].text;
+		// line 4 (d, one of the inserted lines) must be anchored in the result
+		const a4 = anchorLine(out, 4);
+		const r2: any = await call(edit, {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: a4, body: ["DD"] }],
+		});
+		assert.equal(r2.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "a\nb\nc\nDD\ne\n");
+	});
+});
+
+test("unrelated external change does NOT block an edit on a stable line", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
+		// simulate an external change at line 3 between read and edit
+		await writeFile(f, "a\nb\nCHANGED\n");
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: h(text, 1), body: ["A"] }],
+		});
 		assert.equal(r.isError, undefined);
-		assert.equal(await readFile(f, "utf-8"), "A\nB\n");
+		assert.equal(await readFile(f, "utf-8"), "A\nb\nCHANGED\n");
 	});
 });
 
-test("edit execute: edit without a prior read → anchor verification fails", async () => {
+test("edit on a line that changed externally → anchor mismatch", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		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);
+	});
+});
+
+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 edit = makeEditOverride(dir);
-		// never read, so the hash is made up
-		const r: any = await call(edit, { path: "f.txt", input: "replace 1#XXXX:\n+A" });
+		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);
 	});
 });
 
-test("edit execute: missing input → isError + missing hint", async () => {
+test("edit execute: empty edits → isError", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
-		const r: any = await call(makeEditOverride(dir), { path: "f.txt" });
+		const r: any = await call(makeEditOverride(dir), { path: "f.txt", edits: [] });
 		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /missing/);
+		assert.match(r.content[0].text, /empty|missing/i);
 	});
 });
 
-test("edit execute: legacy oldText/newText → isError + legacy hint", async () => {
+test("edit execute: malformed op (replace without body) → isError", async () => {
 	await withDir(async (dir) => {
 		await writeFile(join(dir, "f.txt"), "a\n");
 		const r: any = await call(makeEditOverride(dir), {
 			path: "f.txt",
-			edits: [{ oldText: "a", newText: "b" }],
+			edits: [{ op: "replace", anchor: { line: 1, hash: "XX" } }],
 		});
 		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /legacy/);
-		assert.match(r.content[0].text, /ONLY/);
+		assert.match(r.content[0].text, /body/i);
 	});
 });
 
-test("edit execute: parse error → isError", async () => {
+test("edit execute: delete op", async () => {
 	await withDir(async (dir) => {
-		await writeFile(join(dir, "f.txt"), "a\n");
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
 		await call(makeReadOverride(dir), { path: "f.txt" });
-		const r: any = await call(makeEditOverride(dir), { path: "f.txt", input: "SWAP 1#X:\n+a" });
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ op: "delete", anchor: h(text, 2) }],
+		});
+		assert.equal(r.isError, undefined);
+		assert.equal(await readFile(f, "utf-8"), "a\nc\n");
+	});
+});
+
+// --- renderer regression guards (details.diff must be a string, renderResult must not throw) ---
+
+const stubTheme = { fg: (_k: string, s: string) => s, bold: (s: string) => s };
+
+test("edit success: details.diff is a string (not the generateDiffString object)", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
+		await call(makeReadOverride(dir), { path: "f.txt" });
+		const r: any = await call(makeEditOverride(dir), {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: h(text, 2), body: ["B"] }],
+		});
+		assert.equal(typeof r.details.diff, "string", "details.diff must be a string");
+		assert.equal(typeof r.details.patch, "string");
+		assert.equal(typeof r.details.firstChangedLine, "number");
+	});
+});
+
+test("edit success: renderResult renders the diff without throwing", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		const text = "a\nb\nc\n";
+		await writeFile(f, text);
+		const edit = makeEditOverride(dir);
+		const r: any = await call(edit, {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: h(text, 2), body: ["B"] }],
+		});
+		// @ts-ignore — drive the renderer with a stub theme
+		const comp: any = edit.renderResult({ content: r.content, details: r.details }, { isPartial: false, expanded: true }, stubTheme, { isError: r.isError ?? false });
+		assert.ok(typeof comp?.text === "string");
+		assert.ok(comp.text.includes("B"), "rendered diff should contain the new content");
+	});
+});
+
+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, {
+			path: "f.txt",
+			edits: [{ op: "replace", anchor: { line: 1, hash: "XXXX" }, body: ["A"] }],
+		});
 		assert.equal(r.isError, true);
-		assert.match(r.content[0].text, /Parse error|unknown verb/);
+		// @ts-ignore
+		const comp: any = edit.renderResult({ content: r.content, details: r.details }, { isPartial: false, expanded: false }, stubTheme, { isError: r.isError ?? false });
+		assert.ok(typeof comp?.text === "string");
+	});
+});
+
+test("hash length stays 4 even for runs of identical lines (no explosion)", async () => {
+	await withDir(async (dir) => {
+		const f = join(dir, "f.txt");
+		await writeFile(f, "\n\n\n\ncode\n");
+		const r: any = await call(makeReadOverride(dir), { path: "f.txt" });
+		const text: string = r.content[0].text;
+		for (const m of text.matchAll(/\d+#([0-9A-Z]+)│/g)) {
+			assert.equal(m[1].length, 4, `anchor ${m[0]} hash is not 4 chars`);
+		}
 	});
 });

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,
+					});
+				});
+			});
+		},
+	};
+}