@heyhuynhgiabuu/pi-pretty 0.4.1 → 0.4.3

package/README.md

@@ -135,7 +135,7 @@ Use them when:
 
 Optional environment variables:
 
-- `PRETTY_THEME` (default: `github-dark`)
+- `PRETTY_THEME` (overrides `~/.pi/agent/settings.json` `theme`; otherwise pi-pretty falls back to that setting before `github-dark`)
 - `PRETTY_MAX_HL_CHARS` (default: `80000`)
 - `PRETTY_MAX_PREVIEW_LINES` (default: `80`)
 - `PRETTY_CACHE_LIMIT` (default: `128`)

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@heyhuynhgiabuu/pi-pretty",
-	"version": "0.4.1",
+	"version": "0.4.3",
 	"description": "Pretty terminal output for pi — syntax-highlighted file reads, colored bash output, tree-view directory listings, and more.",
 	"author": "huynhgiabuu",
 	"license": "MIT",

package/release-notes/v0.4.2.md

@@ -0,0 +1,36 @@
+# pi-pretty 0.4.2
+
+## Summary
+This patch release merges the reviewed `customizations` PR into `main` and ships safer `multi_grep` fallback behavior, improved theme resolution, normalized output handling, and clearer bash command rendering.
+
+## What changed
+- `multi_grep` now preserves constrained searches by routing them through a dedicated ripgrep fallback instead of silently dropping complex constraints.
+- Complex constraint expressions such as `*.ts !test/` are converted into ripgrep `--glob` filters, while invalid constraint syntax now returns an error instead of being ignored.
+- Constrained `grep` safety from `0.4.1` remains intact: `path`/`glob` constrained searches still avoid native FFF.
+- pi-pretty now reads `~/.pi/agent/settings.json` theme settings by default, while `PRETTY_THEME` continues to override explicitly.
+- Expanded bash tool rendering so expanded tool calls show the full command instead of the truncated preview.
+- Normalized read/grep output handling and tightened single-line-safe FFF grep record formatting.
+- Added test coverage for bash rendering, constrained grep and multi_grep fallback behavior, CRLF handling, and ripgrep constraint preservation.
+
+## Files
+- `src/index.ts`
+- `src/fff-helpers.ts`
+- `src/multi-grep-fallback.ts`
+- `test/bash-rendering.test.ts`
+- `test/fff-integration.test.ts`
+- `README.md`
+- `package.json`
+- `package-lock.json`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm run lint` ✅
+- `npm test` ✅ (67 tests)
+
+## Upgrade notes
+No configuration changes are required.
+
+After updating:
+- constrained `grep` and `multi_grep` searches prefer safe fallback paths instead of unsafe native constrained matching
+- complex `multi_grep` constraints are preserved instead of being widened silently
+- theme selection can follow Pi settings automatically unless `PRETTY_THEME` is set

package/src/fff-helpers.ts

@@ -6,6 +6,19 @@
 
 import type { GrepCursor, GrepMatch } from "@ff-labs/fff-node";
 
+function sanitizeGrepRecordContent(text: string): string {
+	let content = text;
+	if (content.endsWith("\r\n")) content = content.slice(0, -2);
+	else if (content.endsWith("\r") || content.endsWith("\n")) content = content.slice(0, -1);
+
+	return content.replace(/\r\n/g, "\\n").replace(/\r/g, "\\r").replace(/\n/g, "\\n");
+}
+
+function truncateGrepRecordContent(text: string): string {
+	const content = sanitizeGrepRecordContent(text);
+	return content.length > 500 ? `${content.slice(0, 500)}...` : content;
+}
+
 /**
  * Store for FFF grep pagination cursors.
  * Evicts oldest entry when exceeding maxSize.
@@ -57,15 +70,14 @@ export function fffFormatGrepText(items: GrepMatch[], limit: number): string {
 		if (match.contextBefore?.length) {
 			const startLine = match.lineNumber - match.contextBefore.length;
 			for (let i = 0; i < match.contextBefore.length; i++) {
-				lines.push(`${match.relativePath}-${startLine + i}-${match.contextBefore[i]}`);
+				lines.push(`${match.relativePath}-${startLine + i}-${truncateGrepRecordContent(match.contextBefore[i] ?? "")}`);
 			}
 		}
-		const content = match.lineContent.length > 500 ? `${match.lineContent.slice(0, 500)}...` : match.lineContent;
-		lines.push(`${match.relativePath}:${match.lineNumber}:${content}`);
+		lines.push(`${match.relativePath}:${match.lineNumber}:${truncateGrepRecordContent(match.lineContent)}`);
 		if (match.contextAfter?.length) {
 			const startLine = match.lineNumber + 1;
 			for (let i = 0; i < match.contextAfter.length; i++) {
-				lines.push(`${match.relativePath}-${startLine + i}-${match.contextAfter[i]}`);
+				lines.push(`${match.relativePath}-${startLine + i}-${truncateGrepRecordContent(match.contextAfter[i] ?? "")}`);
 			}
 		}
 	}

package/src/index.ts

@@ -24,7 +24,7 @@
  */
 
 import * as childProcess from "node:child_process";
-import { mkdirSync } from "node:fs";
+import { mkdirSync, readFileSync } from "node:fs";
 import { basename, dirname, extname, join, relative } from "node:path";
 
 import type { FileFinder, FileItem, GrepResult, SearchResult } from "@ff-labs/fff-node";
@@ -45,12 +45,46 @@ import { codeToANSI } from "@shikijs/cli";
 import type { BundledLanguage, BundledTheme } from "shiki";
 
 import { CursorStore, fffFormatGrepText } from "./fff-helpers.js";
+import { type MultiGrepRipgrepFallback, runMultiGrepRipgrepFallback } from "./multi-grep-fallback.js";
 
 // ---------------------------------------------------------------------------
 // Config
 // ---------------------------------------------------------------------------
 
-const THEME: BundledTheme = (process.env.PRETTY_THEME as BundledTheme | undefined) ?? "github-dark";
+const DEFAULT_THEME: BundledTheme = "github-dark";
+
+function getDefaultAgentDir(): string | undefined {
+	const home = process.env.HOME ?? "";
+	return home ? join(home, ".pi/agent") : undefined;
+}
+
+function readThemeFromSettings(agentDir?: string): BundledTheme | undefined {
+	const resolvedAgentDir = agentDir ?? getDefaultAgentDir();
+	if (!resolvedAgentDir) return undefined;
+
+	try {
+		const settings = JSON.parse(readFileSync(join(resolvedAgentDir, "settings.json"), "utf8")) as {
+			theme?: unknown;
+		};
+		return typeof settings.theme === "string" ? (settings.theme as BundledTheme) : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+function resolvePrettyTheme(agentDir?: string): BundledTheme {
+	return (process.env.PRETTY_THEME as BundledTheme | undefined) ?? readThemeFromSettings(agentDir) ?? DEFAULT_THEME;
+}
+
+let THEME: BundledTheme = resolvePrettyTheme();
+
+function setPrettyTheme(agentDir?: string): void {
+	const resolvedTheme = resolvePrettyTheme(agentDir);
+	if (resolvedTheme === THEME) return;
+	THEME = resolvedTheme;
+	_cache.clear();
+	codeToANSI("", "typescript", THEME).catch(() => {});
+}
 
 function envInt(name: string, fallback: number): number {
 	const v = Number.parseInt(process.env[name] ?? "", 10);
@@ -100,13 +134,11 @@ function getThemeBgAnsi(theme: BgTheme, key: string): string | null {
 }
 
 /** Read themed tool backgrounds and update BG_BASE / BG_ERROR + RST.
- *  Call once when theme is first available. Idempotent. */
-let _bgBaseResolved = false;
+ *  Recompute on each render so runtime theme changes are respected. */
 function resolveBaseBackground(theme: BgTheme | null | undefined): void {
-	if (_bgBaseResolved || !theme?.getBgAnsi) return;
-	_bgBaseResolved = true;
+	if (!theme?.getBgAnsi) return;
 
-	BG_BASE = getThemeBgAnsi(theme, "toolSuccessBg") ?? BG_DEFAULT;
+	BG_BASE = getThemeBgAnsi(theme, "toolBg") ?? getThemeBgAnsi(theme, "background") ?? BG_DEFAULT;
 	BG_ERROR = getThemeBgAnsi(theme, "toolErrorBg") ?? BG_BASE;
 	RST = `\x1b[0m${BG_BASE}`;
 }
@@ -146,6 +178,10 @@ function strip(s: string): string {
 	return s.replace(ANSI_RE, "");
 }
 
+function normalizeLineEndings(text: string): string {
+	return text.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+}
+
 function preserveToolBackground(ansi: string, bg: string): string {
 	return ansi.replace(ANSI_CAPTURE_RE, (seq, params: string) => {
 		const codes = params.split(";");
@@ -402,47 +438,6 @@ export const __imageInternals = {
 	},
 };
 
-/**
- * Render base64 image inline using iTerm2 inline image protocol.
- * Protocol: ESC ] 1337 ; File=[args] : base64data BEL
- */
-function renderIterm2Image(base64Data: string, opts: { width?: string; name?: string } = {}): string {
-	const args: string[] = ["inline=1", "preserveAspectRatio=1"];
-	if (opts.width) args.push(`width=${opts.width}`);
-	if (opts.name) args.push(`name=${Buffer.from(opts.name).toString("base64")}`);
-	const byteSize = Math.ceil((base64Data.length * 3) / 4);
-	args.push(`size=${byteSize}`);
-	const seq = `\x1b]1337;File=${args.join(";")}:${base64Data}\x07`;
-	return tmuxWrap(seq);
-}
-
-/**
- * Render base64 image inline using Kitty graphics protocol.
- * Protocol: ESC _G <key>=<value>,...; <base64data> ESC \
- * Chunked in 4096-byte pieces as required by protocol.
- * Supported by: Kitty, Ghostty
- */
-function renderKittyImage(base64Data: string, opts: { cols?: number } = {}): string {
-	const chunks: string[] = [];
-	const CHUNK_SIZE = 4096;
-
-	for (let i = 0; i < base64Data.length; i += CHUNK_SIZE) {
-		const chunk = base64Data.slice(i, i + CHUNK_SIZE);
-		const isFirst = i === 0;
-		const isLast = i + CHUNK_SIZE >= base64Data.length;
-		const more = isLast ? 0 : 1;
-
-		if (isFirst) {
-			const colPart = opts.cols ? `,c=${opts.cols}` : "";
-			chunks.push(tmuxWrap(`\x1b_Ga=T,f=100,t=d,m=${more}${colPart};${chunk}\x1b\\`));
-		} else {
-			chunks.push(tmuxWrap(`\x1b_Gm=${more};${chunk}\x1b\\`));
-		}
-	}
-
-	return chunks.join("");
-}
-
 /**
  * Get human-readable file size
  */
@@ -614,7 +609,8 @@ async function renderFileContent(
 	offset = 1,
 	maxLines = MAX_PREVIEW_LINES,
 ): Promise<string> {
-	const lines = content.split("\n");
+	const normalizedContent = normalizeLineEndings(content);
+	const lines = normalizedContent.split("\n");
 	const total = lines.length;
 	const show = lines.slice(0, maxLines);
 	const lg = lang(filePath);
@@ -754,7 +750,7 @@ function renderFindResults(text: string): string {
 
 /** Render grep results with highlighted matches and line numbers. */
 async function renderGrepResults(text: string, pattern: string): Promise<string> {
-	const lines = text.split("\n");
+	const lines = normalizeLineEndings(text).split("\n");
 	if (!lines.length || (lines.length === 1 && !lines[0].trim())) return `${FG_DIM}(no matches)${RST}`;
 
 	const out: string[] = [];
@@ -875,6 +871,7 @@ type FindParams = FindToolInput;
 type GrepParams = GrepToolInput;
 type MultiGrepParams = {
 	patterns: string[];
+	path?: string;
 	constraints?: string;
 	context?: number;
 	limit?: number;
@@ -934,6 +931,34 @@ function getErrorMessage(error: unknown): string {
 	return error instanceof Error ? error.message : String(error);
 }
 
+function trimToUndefined(value: string | undefined): string | undefined {
+	const trimmed = value?.trim();
+	return trimmed ? trimmed : undefined;
+}
+
+function escapeRegexLiteral(text: string): string {
+	return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function buildLiteralAlternationPattern(patterns: string[]): string {
+	return patterns
+		.map(escapeRegexLiteral)
+		.sort((a, b) => b.length - a.length)
+		.join("|");
+}
+
+function shouldIgnoreCaseForPatterns(patterns: string[]): boolean {
+	return patterns.every((pattern) => pattern.toLowerCase() === pattern);
+}
+
+function getConstraintBackedPath(constraints: string | undefined): string | undefined {
+	const trimmed = trimToUndefined(constraints);
+	if (!trimmed || /\s/.test(trimmed) || trimmed.includes("!") || trimmed.endsWith("/") || /[*?[{]/.test(trimmed)) {
+		return undefined;
+	}
+	return trimmed;
+}
+
 const _cursorStore = new CursorStore();
 let _fffModule: OptionalFffModule | null = null;
 let _fffFinder: FffBackedFinder | null = null;
@@ -985,6 +1010,7 @@ export interface PiPrettyDeps {
 	sdk: PiPrettySdk;
 	TextComponent: TextComponentCtor;
 	fffModule?: OptionalFffModule;
+	multiGrepRipgrepFallback?: MultiGrepRipgrepFallback;
 }
 
 export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps): void {
@@ -1028,12 +1054,22 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 	const cwd = process.cwd();
 	const home = process.env.HOME ?? "";
 	const sp = (p: string) => shortPath(cwd, home, p);
+	const multiGrepRipgrepFallback = deps?.multiGrepRipgrepFallback ?? runMultiGrepRipgrepFallback;
 
 	// ===================================================================
 	// FFF initialization (optional — graceful fallback to SDK)
 	// ===================================================================
 
 	const getAgentDir = sdk.getAgentDir;
+	setPrettyTheme(
+		(() => {
+			try {
+				return getAgentDir?.() ?? getDefaultAgentDir();
+			} catch {
+				return getDefaultAgentDir();
+			}
+		})(),
+	);
 	if (!deps) {
 		// Only try require() in production — tests inject fffModule via deps
 		try {
@@ -1077,8 +1113,9 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 			if (_fffPartialIndex) {
 				ctx.ui?.notify?.("FFF: scan timed out — using partial index. Run /fff-rescan when ready.", "warning");
 			} else {
-				ctx.ui?.setStatus?.("fff", "FFF indexed");
-				setTimeout(() => ctx.ui?.setStatus?.("fff", undefined), 3000);
+				const ui = ctx.ui;
+				ui?.setStatus?.("fff", "FFF indexed");
+				setTimeout(() => ui?.setStatus?.("fff", undefined), 3000);
 			}
 		} catch (error: unknown) {
 			ctx.ui?.notify?.(`FFF init failed: ${getErrorMessage(error)}`, "error");
@@ -1124,11 +1161,12 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 
 			const textContent = getTextContent(result);
 			if (textContent && fp) {
-				const lineCount = textContent.split("\n").length;
+				const normalizedContent = normalizeLineEndings(textContent);
+				const lineCount = normalizedContent.split("\n").length;
 				setResultDetails(result, {
 					_type: "readFile",
 					filePath: fp,
-					content: textContent,
+					content: normalizedContent,
 					offset,
 					lineCount,
 				});
@@ -1162,45 +1200,15 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 
 			const d = result.details as RenderDetails | undefined;
 
-			// Image rendering
+			// Image reads keep the original image content so Pi's native TUI renderer
+			// can display it exactly once. pi-pretty only renders metadata here;
+			// rendering another inline image caused duplicate previews.
 			if (d?._type === "readImage") {
-				const tw = termW();
-				const out: string[] = [];
-				const fname = basename(d.filePath);
 				const byteSize = Math.ceil(((d.data as string).length * 3) / 4);
 				const sizeStr = humanSize(byteSize);
 				const mimeStr = d.mimeType ?? "image";
 
-				out.push(`  ${fileIcon(d.filePath)}${FG_DIM}${mimeStr} · ${sizeStr}${RST}`);
-				out.push(rule(tw));
-
-				const protocol = detectImageProtocol();
-				const passthroughWarning = getTmuxPassthroughWarning(protocol);
-				if (passthroughWarning) {
-					out.push(`  ${FG_YELLOW}${passthroughWarning}${RST}`);
-				} else if (protocol === "kitty") {
-					if (d.mimeType && d.mimeType !== "image/png") {
-						out.push(
-							`  ${FG_YELLOW}Kitty/Ghostty inline preview currently supports PNG payloads (got ${d.mimeType})${RST}`,
-						);
-					} else {
-						const imgCols = Math.min(tw - 4, 80);
-						out.push(renderKittyImage(d.data, { cols: imgCols }));
-					}
-				} else if (protocol === "iterm2") {
-					const imgWidth = Math.min(tw - 4, 80);
-					out.push(
-						renderIterm2Image(d.data, {
-							width: `${imgWidth}`,
-							name: fname,
-						}),
-					);
-				} else {
-					out.push(`  ${FG_DIM}(Inline image preview requires Ghostty, iTerm2, WezTerm, or Kitty)${RST}`);
-				}
-
-				out.push(rule(tw));
-				text.setText(fillToolBackground(out.join("\n")));
+				text.setText(fillToolBackground(`  ${fileIcon(d.filePath)}${FG_DIM}${mimeStr} · ${sizeStr}${RST}`));
 				return text;
 			}
 
@@ -1277,9 +1285,10 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 				const cmd = args.command ?? "";
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				const timeout = args.timeout ? ` ${theme.fg("muted", `(${args.timeout}s timeout)`)}` : "";
+				const displayCmd = ctx.expanded || cmd.length <= 80 ? cmd : `${cmd.slice(0, 77)}…`;
 				text.setText(
 					fillToolBackground(
-						`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", cmd.length > 80 ? `${cmd.slice(0, 77)}…` : cmd)}${timeout}`,
+						`${theme.fg("toolTitle", theme.bold("bash"))} ${theme.fg("accent", displayCmd)}${timeout}`,
 					),
 				);
 				return text;
@@ -1559,7 +1568,12 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 
 				// SDK fallback
 				const result = await origGrep.execute(tid, params, sig, upd as never, ctx);
-				const textContent = getTextContent(result);
+				const textContent = normalizeLineEndings(getTextContent(result));
+				if (result.content) {
+					for (const content of result.content) {
+						if (isTextContent(content)) content.text = normalizeLineEndings(content.text || "");
+					}
+				}
 				const matchCount = textContent ? countRipgrepMatches(textContent) : 0;
 
 				setResultDetails<GrepResultDetails>(result, {
@@ -1629,25 +1643,30 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 	}
 
 	// ===================================================================
-	// multi_grep — FFF-only OR-logic multi-pattern search
+	// multi_grep — OR-logic multi-pattern search (FFF when available,
+	// SDK grep fallback otherwise)
 	// ===================================================================
 
-	if (_fffModule) {
+	if (_fffModule || createGrepTool) {
+		const multiGrepFallback = createGrepTool ? createGrepTool(cwd) : null;
+
 		pi.registerTool({
 			name: "multi_grep",
-			label: "multi_grep (fff)",
+			label: "multi_grep",
 			description: [
 				"Search file contents for lines matching ANY of multiple patterns (OR logic).",
-				"Uses SIMD-accelerated Aho-Corasick multi-pattern matching. Faster than regex alternation.",
+				"Uses SIMD-accelerated Aho-Corasick multi-pattern matching when FFF is available.",
+				"Falls back to ripgrep while preserving literal OR semantics and file constraints when needed.",
 				"Patterns are literal text — never escape special characters.",
-				"Use the constraints parameter for file filtering ('*.rs', 'src/', '!test/').",
+				"Use path to scope a directory/file and constraints for file filtering ('*.rs', 'src/', '!test/').",
 			].join(" "),
-			promptSnippet: "Multi-pattern OR search across file contents (FFF: SIMD-accelerated, frecency-ranked)",
+			promptSnippet: "Multi-pattern OR search across file contents (FFF-accelerated with grep fallback)",
 			promptGuidelines: [
 				"Use multi_grep when you need to find multiple identifiers at once (OR logic).",
 				"Include all naming conventions: snake_case, PascalCase, camelCase variants.",
 				"Patterns are literal text. Never escape special characters.",
-				"Use the constraints parameter for file type/path filtering, not inside patterns.",
+				"Use path to scope a directory or file when you need fresh on-disk results.",
+				"Use the constraints parameter for additional file filtering, not inside patterns.",
 			],
 
 			parameters: {
@@ -1658,6 +1677,10 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 						items: { type: "string" },
 						description: "Patterns to search for (OR logic — matches lines containing ANY pattern).",
 					},
+					path: {
+						type: "string",
+						description: "Directory or file path to search (default: current directory)",
+					},
 					constraints: {
 						type: "string",
 						description: "File constraints, e.g. '*.{ts,tsx} !test/' to filter files.",
@@ -1675,11 +1698,11 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 			},
 
 			async execute(
-				_tid: string,
+				tid: string,
 				params: MultiGrepParams,
 				sig: AbortSignal | undefined,
-				_upd: unknown,
-				_ctx: ExtensionContext,
+				upd: unknown,
+				ctx: ExtensionContext,
 			) {
 				if (sig?.aborted) return makeTextResult("Aborted", {});
 
@@ -1687,42 +1710,112 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 					return makeTextResult("Error: patterns array must have at least 1 element", { error: "empty patterns" });
 				}
 
-				if (!_fffFinder || _fffFinder.isDestroyed) {
-					return makeTextResult("FFF not initialized. Wait for session start or run /fff-rescan.", {});
-				}
+				const effectiveLimit = Math.max(1, params.limit ?? 100);
+				const pattern = buildLiteralAlternationPattern(params.patterns);
+				const requestedPath = trimToUndefined(params.path);
+				const requestedConstraints = trimToUndefined(params.constraints);
+				const effectivePath = requestedPath ?? getConstraintBackedPath(requestedConstraints);
+				const hasNativeConstraints = Boolean(requestedPath || requestedConstraints);
 
-				try {
-					const effectiveLimit = Math.max(1, params.limit ?? 100);
-
-					const grepResult = _fffFinder.multiGrep({
-						patterns: params.patterns,
-						constraints: params.constraints,
-						maxMatchesPerFile: Math.min(effectiveLimit, 50),
-						smartCase: true,
-						cursor: null,
-						beforeContext: params.context ?? 0,
-						afterContext: params.context ?? 0,
-					});
+				if (_fffFinder && !_fffFinder.isDestroyed && !hasNativeConstraints) {
+					try {
+						const grepResult = _fffFinder.multiGrep({
+							patterns: params.patterns,
+							maxMatchesPerFile: Math.min(effectiveLimit, 50),
+							smartCase: true,
+							cursor: null,
+							beforeContext: params.context ?? 0,
+							afterContext: params.context ?? 0,
+						});
+
+						if (!grepResult.ok) {
+							return makeTextResult(`multi_grep error: ${grepResult.error}`, { error: grepResult.error });
+						}
+
+						const grep: GrepResult = grepResult.value;
+						const notices: string[] = [];
+						if (_fffPartialIndex) notices.push("Warning: partial file index");
+						if (grep.items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
+						if (grep.nextCursor) {
+							const cursorId = _cursorStore.store(grep.nextCursor);
+							notices.push(`More results: cursor="${cursorId}"`);
+						}
 
-					if (!grepResult.ok) {
-						return makeTextResult(`multi_grep error: ${grepResult.error}`, { error: grepResult.error });
+						const textContent = appendNotices(fffFormatGrepText(grep.items, effectiveLimit), notices);
+						return makeTextResult<GrepResultDetails>(textContent, {
+							_type: "grepResult",
+							text: textContent,
+							pattern,
+							matchCount: Math.min(grep.items.length, effectiveLimit),
+						});
+					} catch {
+						/* fall through to SDK */
 					}
+				}
 
-					const grep: GrepResult = grepResult.value;
-					const notices: string[] = [];
-					if (_fffPartialIndex) notices.push("Warning: partial file index");
-					if (grep.items.length >= effectiveLimit) notices.push(`${effectiveLimit} limit reached`);
-					if (grep.nextCursor) {
-						const cursorId = _cursorStore.store(grep.nextCursor);
-						notices.push(`More results: cursor="${cursorId}"`);
+				if (requestedConstraints || !multiGrepFallback) {
+					try {
+						const pathBackedConstraint = Boolean(
+							requestedConstraints && !requestedPath && requestedConstraints === effectivePath,
+						);
+						const constraintsForRipgrep = pathBackedConstraint ? undefined : requestedConstraints;
+						const notices: string[] = [];
+
+						if (!_fffFinder || _fffFinder.isDestroyed) notices.push("FFF unavailable, used ripgrep fallback");
+						else if (hasNativeConstraints) notices.push("Used ripgrep fallback for constrained search");
+						else notices.push("Used ripgrep fallback");
+
+						const rgResult = await multiGrepRipgrepFallback({
+							cwd,
+							patterns: params.patterns,
+							path: effectivePath,
+							constraints: constraintsForRipgrep,
+							ignoreCase: shouldIgnoreCaseForPatterns(params.patterns),
+							context: params.context,
+							limit: effectiveLimit,
+							signal: sig,
+						});
+						const textContent = normalizeLineEndings(rgResult.text) || "No matches found";
+						if (rgResult.limitReached) notices.push(`${effectiveLimit} limit reached`);
+						const finalText = appendNotices(textContent, notices);
+
+						return makeTextResult<GrepResultDetails>(finalText, {
+							_type: "grepResult",
+							text: finalText,
+							pattern,
+							matchCount: rgResult.matchCount,
+						});
+					} catch (error: unknown) {
+						const message = getErrorMessage(error);
+						return makeTextResult(`multi_grep error: ${message}`, { error: message });
 					}
+				}
 
-					const textContent = appendNotices(fffFormatGrepText(grep.items, effectiveLimit), notices);
-					return makeTextResult<GrepResultDetails>(textContent, {
+				try {
+					const notices: string[] = [];
+					if (!_fffFinder || _fffFinder.isDestroyed) notices.push("FFF unavailable, used SDK grep fallback");
+
+					const result = await multiGrepFallback.execute(
+						tid,
+						{
+							pattern,
+							path: effectivePath,
+							ignoreCase: shouldIgnoreCaseForPatterns(params.patterns),
+							context: params.context,
+							limit: params.limit,
+						},
+						sig,
+						upd as never,
+						ctx,
+					);
+					const textContent = normalizeLineEndings(getTextContent(result)) || "No matches found";
+					const finalText = appendNotices(textContent, notices);
+
+					return makeTextResult<GrepResultDetails>(finalText, {
 						_type: "grepResult",
-						text: textContent,
-						pattern: params.patterns.join(" | "),
-						matchCount: Math.min(grep.items.length, effectiveLimit),
+						text: finalText,
+						pattern,
+						matchCount: textContent ? countRipgrepMatches(textContent) : 0,
 					});
 				} catch (error: unknown) {
 					const message = getErrorMessage(error);
@@ -1733,14 +1826,16 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 			renderCall(args: MultiGrepParams, theme: ThemeLike, ctx: RenderContextLike) {
 				resolveBaseBackground(theme);
 				const patterns = args.patterns ?? [];
+				const path = args.path ? ` ${theme.fg("muted", `in ${sp(args.path)}`)}` : "";
 				const constraints = args.constraints;
 				const text = ctx.lastComponent ?? new TextComponent("", 0, 0);
 				let content =
 					theme.fg("toolTitle", theme.bold("multi_grep")) +
 					" " +
 					theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "));
+				content += path;
 				if (constraints) content += theme.fg("muted", ` (${constraints})`);
-				text.setText(content);
+				text.setText(fillToolBackground(content));
 				return text;
 			},