pi-readseek 0.3.19 → 0.3.21

package/src/grep.ts

@@ -6,9 +6,9 @@ import path from "path";
 import { defineToolPromptMetadata } from "./tool-prompt-metadata.js";
 import { normalizeToLF, stripBom, hasBareCarriageReturn } from "./edit-diff.js";
 import { looksLikeBinary } from "./binary-detect.js";
-import { ensureHashInit, formatHashlineDisplay, escapeControlCharsForDisplay } from "./hashline.js";
-import { buildReadseekLine, buildToolErrorResult } from "./readseek-value.js";
-import { buildGrepOutput } from "./grep-output.js";
+import { ensureHashInit, escapeControlCharsForDisplay } from "./hashline.js";
+import { buildReadseekLine, buildToolErrorResult, type ReadseekLine } from "./readseek-value.js";
+import { buildGrepOutput, type GrepOutputEntry, type GrepOutputGroup, type GrepOutputRecord, type GrepScopeWarning } from "./grep-output.js";
 
 import { getOrGenerateMap } from "./map-cache.js";
 import { scopeGrepGroupsToSymbols } from "./grep-symbol-scope.js";
@@ -18,6 +18,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { formatGrepCallText, formatGrepResultText } from "./grep-render-helpers.js";
 import { coerceObviousBase10Int } from "./coerce-obvious-int.js";
 import { clampLineToWidth, clampLinesToWidth, linkToolPath, renderToolLabel, resolveRenderResultContext, summaryLine } from "./tui-render-utils.js";
+import type { FileAnchoredCallback } from "./tool-types.js";
 
 const GREP_PROMPT_METADATA = defineToolPromptMetadata({
 	promptUrl: new URL("../prompts/grep.md", import.meta.url),
@@ -99,177 +100,76 @@ function parseGrepOutputLine(line: string):
 	return null;
 }
 
-export interface GrepIRLine {
-	kind: "match" | "context" | "separator";
-	raw: string;
-}
-
-export interface GrepIRFile {
-	path: string;
-	matchCount: number;
-	lines: GrepIRLine[];
-}
-
-export interface GrepIR {
-	totalMatches: number;
-	files: GrepIRFile[];
-}
+const GREP_TRUNCATION_THRESHOLD = 50;
+const GREP_MAX_MATCHES_PER_FILE = 10;
 
-interface GrepReadseekRecord {
-	path: string;
-	line: number;
-	hash: string;
-	anchor: string;
-	kind: "match" | "context";
-	raw: string;
-	display: string;
-}
+type GrepAnchoredEntry = Extract<GrepOutputEntry, { kind: "match" | "context" }>;
 
-function collectReadseekRecordsFromIR(
-	ir: GrepIR,
-	recordByRenderedLine: Map<string, GrepReadseekRecord>,
-): GrepReadseekRecord[] {
-	const records: GrepReadseekRecord[] = [];
-	for (const file of ir.files) {
-		for (const line of file.lines) {
-			if (line.kind === "separator") continue;
-			const record = recordByRenderedLine.get(line.raw);
-			if (record) records.push(record);
+/**
+ * Collapse context lines that duplicate a match line by line number (a match
+ * supersedes a context entry at the same line), then sort ascending and insert
+ * a `--` separator across each line-number gap.
+ */
+function dedupeContextEntries(entries: GrepOutputEntry[]): GrepOutputEntry[] {
+	if (entries.length === 0) return entries;
+
+	const byLine = new Map<number, GrepAnchoredEntry>();
+	for (const entry of entries) {
+		if (entry.kind === "separator") continue;
+		const existing = byLine.get(entry.line.line);
+		if (!existing || (entry.kind === "match" && existing.kind === "context")) {
+			byLine.set(entry.line.line, entry);
 		}
 	}
-	return records;
-}
 
-const IR_MATCH_LINE_RE = /^(.+?):>>/;
-const IR_CONTEXT_LINE_RE = /^(.+?):  /;
-
-export function parseGrepIR(lines: string[]): GrepIR {
-	const fileMap = new Map<string, GrepIRFile>();
-	let totalMatches = 0;
-
-	for (const line of lines) {
-		const matchResult = line.match(IR_MATCH_LINE_RE);
-		let filePath: string | undefined;
-		let kind: "match" | "context" = "context";
-
-		if (matchResult) {
-			filePath = matchResult[1];
-			kind = "match";
-			totalMatches++;
-		} else {
-			const contextResult = line.match(IR_CONTEXT_LINE_RE);
-			if (contextResult) {
-				filePath = contextResult[1];
-				kind = "context";
-			}
-		}
-
-		if (!filePath) continue;
-
-		let file = fileMap.get(filePath);
-		if (!file) {
-			file = { path: filePath, matchCount: 0, lines: [] };
-			fileMap.set(filePath, file);
+	const sorted = [...byLine.entries()].sort(([a], [b]) => a - b);
+	const result: GrepOutputEntry[] = [];
+	for (let i = 0; i < sorted.length; i++) {
+		if (i > 0 && sorted[i][0] > sorted[i - 1][0] + 1) {
+			result.push({ kind: "separator", text: "--" });
 		}
-
-		file.lines.push({ kind, raw: line });
-		if (kind === "match") file.matchCount++;
+		result.push(sorted[i][1]);
 	}
 
-	return { totalMatches, files: [...fileMap.values()] };
+	return result;
 }
 
-export function formatGrepOutput(ir: GrepIR, options?: { summary?: boolean; limit?: number }): string {
-	const header = `[${ir.totalMatches} matches in ${ir.files.length} files]`;
-	if (ir.files.length === 0) return header;
-	let output: string;
-	if (options?.summary) {
-		const fileLines = [...ir.files]
-			.sort((a, b) => b.matchCount - a.matchCount)
-			.map((f) => `${f.path}: ${f.matchCount} matches`);
-		output = [header, ...fileLines].join("\n");
-	} else {
-		const blocks: string[] = [header];
-		for (const file of ir.files) {
-			blocks.push(`--- ${file.path} (${file.matchCount} matches) ---`);
-			for (const line of file.lines) {
-				blocks.push(line.raw);
+/**
+ * Keep at most {@link GREP_MAX_MATCHES_PER_FILE} matches (with their context)
+ * per file, appending a `... +N more matches` separator when matches are
+ * dropped. The group's `matchCount` retains the pre-truncation total.
+ */
+function truncateGroupEntries(group: GrepOutputGroup): GrepOutputGroup {
+	let matchesSeen = 0;
+	let truncatedCount = 0;
+	const kept: GrepOutputEntry[] = [];
+
+	for (const entry of group.entries) {
+		if (entry.kind === "match") {
+			matchesSeen++;
+			if (matchesSeen <= GREP_MAX_MATCHES_PER_FILE) {
+				kept.push(entry);
+			} else {
+				truncatedCount++;
 			}
+		} else if (matchesSeen <= GREP_MAX_MATCHES_PER_FILE) {
+			kept.push(entry);
 		}
-		output = blocks.join("\n");
 	}
 
-	if (options?.limit !== undefined && ir.totalMatches === options.limit) {
-		output += `\n\n[Results truncated at ${options.limit} matches — refine pattern or increase limit]`;
+	if (truncatedCount > 0) {
+		kept.push({ kind: "separator", text: `... +${truncatedCount} more matches` });
 	}
 
-	return output;
-}
-
-const GREP_TRUNCATION_THRESHOLD = 50;
-const GREP_MAX_MATCHES_PER_FILE = 10;
-
-export function truncateGrepIR(ir: GrepIR): GrepIR {
-	if (ir.totalMatches <= GREP_TRUNCATION_THRESHOLD) return ir;
-
-	const files = ir.files.map((file) => {
-		let matchesSeen = 0;
-		const keptLines: GrepIRLine[] = [];
-		let truncatedCount = 0;
-
-		for (const line of file.lines) {
-			if (line.kind === "match") {
-				matchesSeen++;
-				if (matchesSeen <= GREP_MAX_MATCHES_PER_FILE) {
-					keptLines.push(line);
-				} else {
-					truncatedCount++;
-				}
-			} else if (matchesSeen <= GREP_MAX_MATCHES_PER_FILE) {
-				keptLines.push(line);
-			}
-		}
-
-		if (truncatedCount > 0) {
-			keptLines.push({
-				kind: "separator",
-				raw: `... +${truncatedCount} more matches`,
-			});
-		}
-
-		return { ...file, lines: keptLines };
-	});
-
-	return { ...ir, files };
+	return { ...group, entries: kept };
 }
 
-const LINE_NUM_RE = /(?:>>|  )(\d+):/;
-
-export function deduplicateContext(lines: GrepIRLine[]): GrepIRLine[] {
-	if (lines.length === 0) return lines;
-
-	const byLineNum = new Map<number, GrepIRLine>();
-	for (const line of lines) {
-		const match = line.raw.match(LINE_NUM_RE);
-		if (!match) continue;
-		const lineNum = Number.parseInt(match[1], 10);
-		const existing = byLineNum.get(lineNum);
-		if (!existing || (line.kind === "match" && existing.kind === "context")) {
-			byLineNum.set(lineNum, line);
-		}
-	}
-
-	const sorted = [...byLineNum.entries()].sort(([a], [b]) => a - b);
-	const result: GrepIRLine[] = [];
-
-	for (let i = 0; i < sorted.length; i++) {
-		if (i > 0 && sorted[i][0] > sorted[i - 1][0] + 1) {
-			result.push({ kind: "separator", raw: "--" });
-		}
-		result.push(sorted[i][1]);
-	}
-
-	return result;
+function recordsFromGroups(groups: GrepOutputGroup[]): GrepOutputRecord[] {
+	return groups.flatMap((group) =>
+		group.entries.flatMap((entry) =>
+			entry.kind === "separator" ? [] : [{ path: group.absolutePath, ...entry.line, kind: entry.kind }],
+		),
+	);
 }
 
 /**
@@ -281,241 +181,90 @@ function escapeForRegex(s: string): string {
 
 interface GrepToolOptions {
 	searchGuideline?: string;
-	onFileAnchored?: (absolutePath: string) => void;
+	onFileAnchored?: FileAnchoredCallback;
 }
 
-export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
-	const toolConfig = {
-		callable: true,
-		enabled: true,
-		policy: "read-only" as const,
-		readOnly: true,
-		pythonName: "grep",
-		defaultExposure: "safe-by-default" as const,
-	};
-
-	const tool = {
-		name: "grep",
-		label: "grep",
-		description: GREP_PROMPT_METADATA.description,
-		parameters: grepSchema,
-		ptc: toolConfig,
-		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
-		promptGuidelines: options.searchGuideline
-			? [GREP_PROMPT_METADATA.promptGuidelines[0], options.searchGuideline]
-			: GREP_PROMPT_METADATA.promptGuidelines,
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			await ensureHashInit();
-			const rawParams = params as GrepParams;
-			const context = coerceObviousBase10Int(rawParams.context, "context");
-			if (!context.ok) {
-				return buildToolErrorResult("grep", "invalid-params-combo", context.message);
-			}
-			const limit = coerceObviousBase10Int(rawParams.limit, "limit");
-			if (!limit.ok) {
-				return buildToolErrorResult("grep", "invalid-limit", limit.message);
-			}
-			const scopeContext = coerceObviousBase10Int(rawParams.scopeContext, "scopeContext");
-			if (!scopeContext.ok) {
-				return buildToolErrorResult("grep", "invalid-params-combo", scopeContext.message);
-			}
-			if (scopeContext.value !== undefined && rawParams.scope !== "symbol") {
-				const message = 'Invalid scopeContext: requires scope: "symbol". For normal surrounding-line context outside symbol scope, use the `context` parameter.';
-				return buildToolErrorResult("grep", "invalid-params-combo", message);
-			}
-			if (scopeContext.value !== undefined && scopeContext.value < 0) {
-				const message = `Invalid scopeContext: expected a non-negative integer, received ${scopeContext.value}.`;
-				return buildToolErrorResult("grep", "invalid-params-combo", message);
-			}
-			const p: GrepParams = {
-				...rawParams,
-				context: context.value,
-				limit: limit.value,
-				scopeContext: scopeContext.value,
-			};
-			const builtin = createGrepTool(ctx.cwd);
-			const result = await builtin.execute(
-				toolCallId,
-				{
-					...p,
-					context: context.value,
-					limit: limit.value,
-				},
-				signal,
-				onUpdate,
-			);
-
-			const textBlock = result.content?.find(
-				(item): item is { type: "text"; text: string } =>
-					item.type === "text" && "text" in item && typeof (item as { text?: unknown }).text === "string",
-			);
-			if (!textBlock?.text) return result;
+export interface ExecuteGrepOptions {
+	toolCallId: string;
+	params: unknown;
+	signal: AbortSignal | undefined;
+	onUpdate: any;
+	cwd: string;
+	onFileAnchored?: FileAnchoredCallback;
+}
 
-			const { path: rawSearchPath } = p;
-			const searchPath = resolveToCwd(rawSearchPath || ".", ctx.cwd);
+export async function executeGrep(opts: ExecuteGrepOptions): Promise<any> {
+	const { toolCallId, params, signal, onUpdate, cwd, onFileAnchored } = opts;
+	await ensureHashInit();
+	const rawParams = params as GrepParams;
+	const context = coerceObviousBase10Int(rawParams.context, "context");
+	if (!context.ok) {
+		return buildToolErrorResult("grep", "invalid-params-combo", context.message);
+	}
+	const limit = coerceObviousBase10Int(rawParams.limit, "limit");
+	if (!limit.ok) {
+		return buildToolErrorResult("grep", "invalid-limit", limit.message);
+	}
+	const scopeContext = coerceObviousBase10Int(rawParams.scopeContext, "scopeContext");
+	if (!scopeContext.ok) {
+		return buildToolErrorResult("grep", "invalid-params-combo", scopeContext.message);
+	}
+	if (scopeContext.value !== undefined && rawParams.scope !== "symbol") {
+		const message = 'Invalid scopeContext: requires scope: "symbol". For normal surrounding-line context outside symbol scope, use the `context` parameter.';
+		return buildToolErrorResult("grep", "invalid-params-combo", message);
+	}
+	if (scopeContext.value !== undefined && scopeContext.value < 0) {
+		const message = `Invalid scopeContext: expected a non-negative integer, received ${scopeContext.value}.`;
+		return buildToolErrorResult("grep", "invalid-params-combo", message);
+	}
+	const p: GrepParams = {
+		...rawParams,
+		context: context.value,
+		limit: limit.value,
+		scopeContext: scopeContext.value,
+	};
+	const builtin = createGrepTool(cwd);
+	const result = await builtin.execute(
+		toolCallId,
+		{
+			...p,
+			context: context.value,
+			limit: limit.value,
+		},
+		signal,
+		onUpdate,
+	);
 
-			let searchPathIsDirectory = false;
-			try {
-				searchPathIsDirectory = (await fsStat(searchPath)).isDirectory();
-			} catch {
-				searchPathIsDirectory = false;
-			}
-			// Warn when the user targets a single binary file directly — grep
-			// silently skips binary files and would return 0 matches with no
-			// indication of why.
-			if (!searchPathIsDirectory) {
-				try {
-					const buf = await fsReadFile(searchPath);
-					if (looksLikeBinary(buf)) {
-						const warning = `[Warning: '${p.path ?? searchPath}' appears to be a binary file — grep skips binary files by default. Use a hex tool or the read tool to inspect it.]`;
-						return {
-							...result,
-							content: result.content.map((item) =>
-								item === textBlock ? ({ ...item, text: warning } as typeof item) : item,
-							),
-							details: {
-								...(typeof result.details === "object" && result.details !== null ? result.details : {}),
-								readseekValue: {
-									tool: "grep",
-									summary: !!p.summary,
-									totalMatches: 0,
-									records: [],
-								},
-							},
-						};
-					}
-				} catch {
-					// can't read file — let normal flow continue
-				}
-			}
+	const textBlock = result.content?.find(
+		(item): item is { type: "text"; text: string } =>
+			item.type === "text" && "text" in item && typeof (item as { text?: unknown }).text === "string",
+	);
+	if (!textBlock?.text) return result;
 
-			const fileCache = new Map<string, string[] | undefined>();
-			const bareCRFiles = new Set<string>();
-			const getFileLines = async (absolutePath: string): Promise<string[] | undefined> => {
-				throwIfAborted(signal);
-				if (fileCache.has(absolutePath)) return fileCache.get(absolutePath);
-				try {
-					const rawBuffer = await fsReadFile(absolutePath);
-					if (looksLikeBinary(rawBuffer)) {
-						fileCache.set(absolutePath, undefined);
-						return undefined;
-					}
-					const raw = rawBuffer.toString("utf-8");
-					if (hasBareCarriageReturn(raw)) bareCRFiles.add(absolutePath);
-					const lines = normalizeToLF(stripBom(raw).text).split("\n");
-					fileCache.set(absolutePath, lines);
-					return lines;
-				} catch {
-					fileCache.set(absolutePath, undefined);
-					return undefined;
-				}
-			};
-
-			const toAbsolutePath = (displayPath: string): string => {
-				if (searchPathIsDirectory) return path.resolve(searchPath, displayPath);
-				return searchPath;
-			};
-
-			const transformed: string[] = [];
-			const passthroughLines: string[] = [];
-			const recordByRenderedLine = new Map<string, GrepReadseekRecord>();
-			let parsedCount = 0;
-			let candidateUnparsedCount = 0;
-			const candidateLinePattern = /^.+(?::|-)\d+(?::|-)\s/;
-
-			for (const line of textBlock.text.split("\n")) {
-				throwIfAborted(signal);
-				const parsed = parseGrepOutputLine(line);
-				if (!parsed || !Number.isFinite(parsed.lineNumber) || parsed.lineNumber < 1) {
-					if (candidateLinePattern.test(line)) {
-						candidateUnparsedCount++;
-					}
-					const trimmed = line.trim();
-					if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
-						passthroughLines.push(trimmed);
-					}
-					transformed.push(line);
-					continue;
-				}
-				parsedCount++;
-				const absolute = toAbsolutePath(parsed.displayPath);
-				const fileLines = await getFileLines(absolute);
-				if (fileLines === undefined) continue;
-				// Bare-CR remapping: rg treats the entire bare-CR file as line 1, and the
-				// builtin grep tool may strip \r before this code sees the output. So
-				// parsed.text is just the first CR-separated fragment and parsed.lineNumber
-				// is always 1 — both are wrong for match lines. Only remap when
-				// parsed.kind === "match"; context lines are irrelevant here (rg won’t
-				// produce them for bare-CR files in any meaningful way).
-				if (parsed.kind === "match" && bareCRFiles.has(absolute)) {
-					const gp = p;
-					const flags = gp.ignoreCase ? "i" : "";
-					let patternRe: RegExp | null = null;
-					try {
-						patternRe = gp.literal
-							? new RegExp(escapeForRegex(gp.pattern), flags)
-							: new RegExp(gp.pattern, flags);
-					} catch {
-						// Malformed regex — fall through to normal anchor path
-					}
-					if (patternRe !== null) {
-						let emitted = false;
-						for (let i = 0; i < fileLines.length; i++) {
-							if (!patternRe.test(fileLines[i])) continue;
-							const lineNum = i + 1;
-							const marker = ">>";
-							const renderedLine = `${parsed.displayPath}:${marker}${formatHashlineDisplay(lineNum, fileLines[i])}`;
-							transformed.push(renderedLine);
-							const built = buildReadseekLine(lineNum, fileLines[i]);
-							recordByRenderedLine.set(renderedLine, {
-								path: toAbsolutePath(parsed.displayPath),
-								line: built.line,
-								hash: built.hash,
-								anchor: built.anchor,
-								kind: "match",
-								raw: built.raw,
-								display: built.display,
-							});
-							emitted = true;
-						}
-						if (emitted) continue;
-						// No lines matched — fall through to normal path
-					}
-				}
-				// Normal (non-bare-CR) path
-				const sourceLine = fileLines?.[parsed.lineNumber - 1] ?? parsed.text;
-				const built = buildReadseekLine(parsed.lineNumber, sourceLine);
-				const marker = parsed.kind === "match" ? ">>" : "  ";
-				const renderedDisplay = escapeControlCharsForDisplay(parsed.text);
-				const renderedLine = `${parsed.displayPath}:${marker}${built.anchor}|${renderedDisplay}`;
-				transformed.push(renderedLine);
-				recordByRenderedLine.set(renderedLine, {
-					path: toAbsolutePath(parsed.displayPath),
-					line: built.line,
-					hash: built.hash,
-					anchor: built.anchor,
-					kind: parsed.kind,
-					raw: built.raw,
-					display: renderedDisplay,
-				});
-			}
+	const { path: rawSearchPath } = p;
+	const searchPath = resolveToCwd(rawSearchPath || ".", cwd);
 
-			if (parsedCount === 0 && candidateUnparsedCount > 0) {
-				const warning =
-					"[hashline grep passthrough] Unparsed grep format; returned original output.";
-				const passthroughDetails =
-					typeof result.details === "object" && result.details !== null
-						? (result.details as Record<string, unknown>)
-						: {};
+	let searchPathIsDirectory = false;
+	try {
+		searchPathIsDirectory = (await fsStat(searchPath)).isDirectory();
+	} catch {
+		searchPathIsDirectory = false;
+	}
+	// Warn when the user targets a single binary file directly — grep
+	// silently skips binary files and would return 0 matches with no
+	// indication of why.
+	if (!searchPathIsDirectory) {
+		try {
+			const buf = await fsReadFile(searchPath);
+			if (looksLikeBinary(buf)) {
+				const warning = `[Warning: '${p.path ?? searchPath}' appears to be a binary file — grep skips binary files by default. Use a hex tool or the read tool to inspect it.]`;
 				return {
 					...result,
 					content: result.content.map((item) =>
-						item === textBlock ? ({ ...item, text: `${textBlock.text}\n\n${warning}` } as typeof item) : item,
+						item === textBlock ? ({ ...item, text: warning } as typeof item) : item,
 					),
 					details: {
-						...passthroughDetails,
-						hashlinePassthrough: true,
-						hashlineWarning: warning,
+						...(typeof result.details === "object" && result.details !== null ? result.details : {}),
 						readseekValue: {
 							tool: "grep",
 							summary: !!p.summary,
@@ -525,119 +274,233 @@ export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}
 					},
 				};
 			}
+		} catch {
+			// can't read file — let normal flow continue
+		}
+	}
 
-			const grepIR = parseGrepIR(transformed);
-			for (const file of grepIR.files) {
-				file.lines = deduplicateContext(file.lines);
+	const fileCache = new Map<string, string[] | undefined>();
+	const bareCRFiles = new Set<string>();
+	const getFileLines = async (absolutePath: string): Promise<string[] | undefined> => {
+		throwIfAborted(signal);
+		if (fileCache.has(absolutePath)) return fileCache.get(absolutePath);
+		try {
+			const rawBuffer = await fsReadFile(absolutePath);
+			if (looksLikeBinary(rawBuffer)) {
+				fileCache.set(absolutePath, undefined);
+				return undefined;
 			}
-			const truncatedIR = truncateGrepIR(grepIR);
-			const summary = p.summary;
-			const effectiveLimit = typeof p.limit === "number" ? p.limit : 100;
-			const outputIR = summary
-				? {
-					...truncatedIR,
-					files: truncatedIR.files.map((file) => ({ ...file, path: toAbsolutePath(file.path) })),
-				}
-				: truncatedIR;
-let renderedGroups = outputIR.files.map((file) => ({
-	displayPath: file.path,
-	absolutePath: summary ? file.path : toAbsolutePath(file.path),
-	matchCount: file.matchCount,
-	entries: file.lines.map((line) => {
-		if (line.kind === "separator") {
-			return { kind: "separator" as const, text: line.raw };
+			const raw = rawBuffer.toString("utf-8");
+			if (hasBareCarriageReturn(raw)) bareCRFiles.add(absolutePath);
+			const lines = normalizeToLF(stripBom(raw).text).split("\n");
+			fileCache.set(absolutePath, lines);
+			return lines;
+		} catch {
+			fileCache.set(absolutePath, undefined);
+			return undefined;
+		}
+	};
+
+	const toAbsolutePath = (displayPath: string): string => {
+		if (searchPathIsDirectory) return path.resolve(searchPath, displayPath);
+		return searchPath;
+	};
+
+	const groupsByPath = new Map<string, GrepOutputGroup>();
+	const passthroughLines: string[] = [];
+	let totalMatches = 0;
+	let parsedCount = 0;
+	let candidateUnparsedCount = 0;
+	const candidateLinePattern = /^.+(?::|-)\d+(?::|-)\s/;
+
+	const addEntry = (displayPath: string, absolutePath: string, kind: "match" | "context", line: ReadseekLine) => {
+		let group = groupsByPath.get(displayPath);
+		if (!group) {
+			group = { displayPath, absolutePath, matchCount: 0, entries: [] };
+			groupsByPath.set(displayPath, group);
+		}
+		group.entries.push({ kind, line });
+		if (kind === "match") {
+			group.matchCount++;
+			totalMatches++;
+		}
+	};
+
+	for (const line of textBlock.text.split("\n")) {
+		throwIfAborted(signal);
+		const parsed = parseGrepOutputLine(line);
+		if (!parsed || !Number.isFinite(parsed.lineNumber) || parsed.lineNumber < 1) {
+			if (candidateLinePattern.test(line)) {
+				candidateUnparsedCount++;
+			}
+			const trimmed = line.trim();
+			if (trimmed.startsWith("[") && trimmed.endsWith("]")) {
+				passthroughLines.push(trimmed);
+			}
+			continue;
 		}
-		const record = recordByRenderedLine.get(line.raw);
-		if (!record) {
-			throw new Error(`Missing grep record for rendered line: ${line.raw}`);
+		parsedCount++;
+		const absolute = toAbsolutePath(parsed.displayPath);
+		const fileLines = await getFileLines(absolute);
+		if (fileLines === undefined) continue;
+		// Bare-CR remapping: rg treats the entire bare-CR file as line 1, and the
+		// builtin grep tool may strip \r before this code sees the output. So
+		// parsed.text is just the first CR-separated fragment and parsed.lineNumber
+		// is always 1 — both are wrong for match lines. Only remap when
+		// parsed.kind === "match"; context lines are irrelevant here (rg won’t
+		// produce them for bare-CR files in any meaningful way).
+		if (parsed.kind === "match" && bareCRFiles.has(absolute)) {
+			const flags = p.ignoreCase ? "i" : "";
+			let patternRe: RegExp | null = null;
+			try {
+				patternRe = p.literal
+					? new RegExp(escapeForRegex(p.pattern), flags)
+					: new RegExp(p.pattern, flags);
+			} catch {
+				// Malformed regex — fall through to normal anchor path
+			}
+			if (patternRe !== null) {
+				let emitted = false;
+				for (let i = 0; i < fileLines.length; i++) {
+					if (!patternRe.test(fileLines[i])) continue;
+					addEntry(parsed.displayPath, absolute, "match", buildReadseekLine(i + 1, fileLines[i]));
+					emitted = true;
+				}
+				if (emitted) continue;
+				// No lines matched — fall through to normal path
+			}
 		}
+		// Normal (non-bare-CR) path
+		const sourceLine = fileLines[parsed.lineNumber - 1] ?? parsed.text;
+		const built = buildReadseekLine(parsed.lineNumber, sourceLine);
+		addEntry(parsed.displayPath, absolute, parsed.kind, {
+			...built,
+			display: escapeControlCharsForDisplay(parsed.text),
+		});
+	}
+
+	if (parsedCount === 0 && candidateUnparsedCount > 0) {
+		const warning =
+			"[hashline grep passthrough] Unparsed grep format; returned original output.";
+		const passthroughDetails =
+			typeof result.details === "object" && result.details !== null
+				? (result.details as Record<string, unknown>)
+				: {};
 		return {
-			kind: record.kind,
-			line: {
-				line: record.line,
-				hash: record.hash,
-				anchor: record.anchor,
-				raw: record.raw,
-				display: record.display,
+			...result,
+			content: result.content.map((item) =>
+				item === textBlock ? ({ ...item, text: `${textBlock.text}\n\n${warning}` } as typeof item) : item,
+			),
+			details: {
+				...passthroughDetails,
+				hashlinePassthrough: true,
+				hashlineWarning: warning,
+				readseekValue: {
+					tool: "grep",
+					summary: !!p.summary,
+					totalMatches: 0,
+					records: [],
+				},
 			},
 		};
-	}),
-}));
+	}
 
-let readseekRecords = collectReadseekRecordsFromIR(outputIR, recordByRenderedLine);
-let scopeWarnings: import("./grep-output.js").GrepScopeWarning[] = [];
+	const summary = p.summary;
+	const effectiveLimit = typeof p.limit === "number" ? p.limit : 100;
+	const groups = [...groupsByPath.values()];
+	for (const group of groups) {
+		group.entries = dedupeContextEntries(group.entries);
+	}
+	let renderedGroups: GrepOutputGroup[] =
+		totalMatches > GREP_TRUNCATION_THRESHOLD ? groups.map(truncateGroupEntries) : groups;
+	let scopeWarnings: GrepScopeWarning[] = [];
+
+	if (p.scope === "symbol" && !summary) {
+		const fileLinesByPath = new Map<string, string[]>();
+		const fileMapsByPath = new Map<string, Awaited<ReturnType<typeof getOrGenerateMap>>>();
+
+		for (const group of renderedGroups) {
+			const lines = await getFileLines(group.absolutePath);
+			if (lines) fileLinesByPath.set(group.absolutePath, lines);
+			fileMapsByPath.set(group.absolutePath, await getOrGenerateMap(group.absolutePath));
+		}
 
-if (p.scope === "symbol" && !summary) {
-	const fileLinesByPath = new Map<string, string[]>();
-	const fileMapsByPath = new Map<string, Awaited<ReturnType<typeof getOrGenerateMap>>>();
+		const scoped = scopeGrepGroupsToSymbols({
+			groups: renderedGroups,
+			fileLinesByPath,
+			fileMapsByPath,
+			contextLines: typeof p.context === "number" ? p.context : 0,
+			scopeContext: typeof p.scopeContext === "number" ? p.scopeContext : undefined,
+		});
 
-	for (const group of renderedGroups) {
-		const lines = await getFileLines(group.absolutePath);
-		if (lines) fileLinesByPath.set(group.absolutePath, lines);
-		fileMapsByPath.set(group.absolutePath, await getOrGenerateMap(group.absolutePath));
+		renderedGroups = scoped.groups;
+		scopeWarnings = scoped.warnings;
 	}
-
-	const scoped = scopeGrepGroupsToSymbols({
+	const readseekRecords = recordsFromGroups(renderedGroups);
+	const builtOutput = buildGrepOutput({
+		summary: !!summary,
+		totalMatches,
 		groups: renderedGroups,
-		fileLinesByPath,
-		fileMapsByPath,
-		contextLines: typeof p.context === "number" ? p.context : 0,
-		scopeContext: typeof p.scopeContext === "number" ? p.scopeContext : undefined,
+		limit: effectiveLimit,
+		records: readseekRecords,
+		scopeMode: p.scope === "symbol" && !summary ? "symbol" : undefined,
+		scopeWarnings,
+		passthroughLines,
 	});
 
-	renderedGroups = scoped.groups;
-	scopeWarnings = scoped.warnings;
-	readseekRecords = renderedGroups.flatMap((group) =>
-		group.entries.flatMap((entry) =>
-			entry.kind === "separator"
-				? []
-				: [
-					{
-						path: group.absolutePath,
-						kind: entry.kind,
-						line: entry.line.line,
-						hash: entry.line.hash,
-						anchor: entry.line.anchor,
-						raw: entry.line.raw,
-						display: entry.line.display,
-					},
-				],
+	if (!summary && readseekRecords.length > 0) {
+		const anchoredPaths = new Set(readseekRecords.map((record) => record.path));
+		for (const absolutePath of anchoredPaths) {
+			onFileAnchored?.(absolutePath);
+		}
+	}
+
+	const existingDetails =
+		typeof result.details === "object" && result.details !== null
+			? (result.details as Record<string, unknown>)
+			: {};
+	const { linesTruncated: _ignoredLinesTruncated, truncation: _ignoredTruncation, ...compactDetails } = existingDetails;
+	return {
+		...result,
+		content: result.content.map((item) =>
+			item === textBlock ? ({ ...item, text: builtOutput.text } as typeof item) : item,
 		),
-	);
+		details: {
+			...compactDetails,
+			readseekValue: builtOutput.readseekValue,
+		},
+	};
 }
-			const builtOutput = buildGrepOutput({
-				summary: !!summary,
-				totalMatches: grepIR.totalMatches,
-				groups: renderedGroups,
-				limit: effectiveLimit,
-				records: readseekRecords,
-				scopeMode: p.scope === "symbol" && !summary ? "symbol" : undefined,
-				scopeWarnings,
-				passthroughLines,
-			});
 
-			if (!summary && readseekRecords.length > 0) {
-				const anchoredPaths = new Set(readseekRecords.map((record) => record.path));
-				for (const absolutePath of anchoredPaths) {
-					options.onFileAnchored?.(absolutePath);
-				}
-			}
+export function registerGrepTool(pi: ExtensionAPI, options: GrepToolOptions = {}) {
+	const toolConfig = {
+		callable: true,
+		enabled: true,
+		policy: "read-only" as const,
+		readOnly: true,
+		pythonName: "grep",
+		defaultExposure: "safe-by-default" as const,
+	};
 
-			const existingDetails =
-				typeof result.details === "object" && result.details !== null
-					? (result.details as Record<string, unknown>)
-					: {};
-			const { linesTruncated: _ignoredLinesTruncated, truncation: _ignoredTruncation, ...compactDetails } = existingDetails;
-			return {
-				...result,
-				content: result.content.map((item) =>
-					item === textBlock ? ({ ...item, text: builtOutput.text } as typeof item) : item,
-				),
-				details: {
-					...compactDetails,
-					readseekValue: builtOutput.readseekValue,
-				},
-			};
+	const tool = {
+		name: "grep",
+		label: "grep",
+		description: GREP_PROMPT_METADATA.description,
+		parameters: grepSchema,
+		ptc: toolConfig,
+		promptSnippet: GREP_PROMPT_METADATA.promptSnippet,
+		promptGuidelines: options.searchGuideline
+			? [GREP_PROMPT_METADATA.promptGuidelines[0], options.searchGuideline]
+			: GREP_PROMPT_METADATA.promptGuidelines,
+		async execute(toolCallId, params, signal, onUpdate, ctx) {
+			return executeGrep({
+				toolCallId,
+				params,
+				signal,
+				onUpdate,
+				cwd: ctx.cwd,
+				onFileAnchored: options.onFileAnchored,
+			});
 		},
 		renderCall(args: any, theme: any, ...rest: any[]) {
 			const context = rest[0] ?? {};