@heyhuynhgiabuu/pi-pretty 0.4.0 → 0.4.2

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.0",
+	"version": "0.4.2",
 	"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.1.md

@@ -0,0 +1,28 @@
+# pi-pretty v0.4.1
+
+## Summary
+This patch release prevents `grep` from aborting Pi when FFF 0.5.2 indexes Unicode filenames and the grep call includes a `path` or `glob` constraint.
+
+## What changed
+- Constrained `grep` calls now bypass native FFF and use the SDK fallback path.
+- Unconstrained `grep` still uses FFF for the fast path.
+- Added regression tests for both `path` and `glob` constrained grep bypass behavior.
+
+## Why
+`@ff-labs/fff-node@0.5.2` can panic inside native Rust constraint matching when a byte-based slice lands inside a multi-byte UTF-8 character in an indexed filename, such as an en dash (`–`). Because that panic happens across FFI, JavaScript cannot catch it; the whole `pi` process aborts.
+
+This release avoids the crash-prone native constraint path until upstream FFF ships the Unicode boundary fix.
+
+## Files
+- `src/index.ts`
+- `test/fff-integration.test.ts`
+- `package.json`
+- `package-lock.json`
+
+## Verification
+- `npm run typecheck` ✅
+- `npm run lint` ✅
+- `npm test` ✅ (48 tests)
+
+## Upgrade notes
+No configuration changes required. After updating, file- or glob-scoped `grep` calls will prefer the SDK fallback for stability; broad unconstrained grep remains FFF-backed.

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);
@@ -146,6 +180,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(";");
@@ -614,7 +652,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 +793,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 +914,7 @@ type FindParams = FindToolInput;
 type GrepParams = GrepToolInput;
 type MultiGrepParams = {
 	patterns: string[];
+	path?: string;
 	constraints?: string;
 	context?: number;
 	limit?: number;
@@ -934,6 +974,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 +1053,7 @@ export interface PiPrettyDeps {
 	sdk: PiPrettySdk;
 	TextComponent: TextComponentCtor;
 	fffModule?: OptionalFffModule;
+	multiGrepRipgrepFallback?: MultiGrepRipgrepFallback;
 }
 
 export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps): void {
@@ -1028,12 +1097,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 {
@@ -1124,11 +1203,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,
 				});
@@ -1277,9 +1357,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;
@@ -1516,13 +1597,13 @@ export default function piPrettyExtension(pi: PiPrettyApi, deps?: PiPrettyDeps):
 				upd: unknown,
 				ctx: ExtensionContext,
 			) {
-				// Try FFF first (SIMD-accelerated, frecency-ranked)
-				if (_fffFinder && !_fffFinder.isDestroyed) {
+				// Try FFF first (SIMD-accelerated, frecency-ranked).
+				// FFF 0.5.2 can abort the process when path/glob constraints meet
+				// Unicode filenames, so constrained searches use the SDK fallback.
+				if (_fffFinder && !_fffFinder.isDestroyed && !params.path && !params.glob) {
 					try {
 						const effectiveLimit = Math.max(1, params.limit ?? 100);
-						let query = params.pattern;
-						if (params.glob) query = `${params.glob} ${query}`;
-						else if (params.path) query = `${params.path} ${query}`;
+						const query = params.pattern;
 
 						const grepResult = _fffFinder.grep(query, {
 							mode: params.literal ? "plain" : "regex",
@@ -1559,7 +1640,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 +1715,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 +1749,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 +1770,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 +1782,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 +1898,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;
 			},
 

package/src/multi-grep-fallback.ts

@@ -0,0 +1,248 @@
+import { spawn } from "node:child_process";
+
+export type ConstraintParseResult = { ok: true; globs: string[]; tokens: string[] } | { ok: false; error: string };
+
+export type MultiGrepRipgrepFallbackParams = {
+	cwd: string;
+	patterns: string[];
+	path?: string;
+	constraints?: string;
+	context?: number;
+	limit: number;
+	ignoreCase: boolean;
+	signal?: AbortSignal;
+};
+
+export type MultiGrepRipgrepFallbackResult = {
+	text: string;
+	matchCount: number;
+	limitReached: boolean;
+};
+
+export type MultiGrepRipgrepFallback = (
+	params: MultiGrepRipgrepFallbackParams,
+) => Promise<MultiGrepRipgrepFallbackResult>;
+
+const GLOB_META_RE = /[*?[{]/;
+
+function trimSlashes(value: string): string {
+	return value.replace(/^\/+/, "").replace(/\/+$/, "");
+}
+
+function normalizeConstraintPath(value: string): string {
+	let normalized = value.replace(/\\/g, "/").trim();
+	while (normalized.startsWith("./")) normalized = normalized.slice(2);
+	return normalized;
+}
+
+function tokenizeConstraints(constraints: string): ConstraintParseResult {
+	const tokens: string[] = [];
+	let current = "";
+	let quote: '"' | "'" | null = null;
+
+	for (let i = 0; i < constraints.length; i++) {
+		const char = constraints[i];
+		if (quote) {
+			if (char === quote) quote = null;
+			else current += char;
+			continue;
+		}
+
+		if (char === '"' || char === "'") {
+			quote = char;
+			continue;
+		}
+
+		if (/\s/.test(char)) {
+			if (current) {
+				tokens.push(current);
+				current = "";
+			}
+			continue;
+		}
+
+		current += char;
+	}
+
+	if (quote) return { ok: false, error: "unterminated quoted constraint" };
+	if (current) tokens.push(current);
+
+	return { ok: true, globs: [], tokens };
+}
+
+function tokenToRipgrepGlob(token: string): { ok: true; glob: string } | { ok: false; error: string } {
+	let negated = false;
+	let body = token;
+
+	if (body.startsWith("!")) {
+		negated = true;
+		body = body.slice(1);
+	}
+
+	body = normalizeConstraintPath(body);
+	if (!body) return { ok: false, error: `empty constraint token: ${token}` };
+	if (body.includes("\0")) return { ok: false, error: `invalid NUL byte in constraint token: ${token}` };
+
+	let glob: string;
+	if (body.endsWith("/")) {
+		const dir = trimSlashes(body);
+		if (!dir) return { ok: false, error: `empty directory constraint: ${token}` };
+		glob = `**/${dir}/**`;
+	} else if (GLOB_META_RE.test(body) || body.includes("/")) {
+		glob = body.replace(/^\/+/, "");
+	} else if (body.includes(".")) {
+		glob = `**/${body}`;
+	} else {
+		glob = `**/${body}/**`;
+	}
+
+	return { ok: true, glob: negated ? `!${glob}` : glob };
+}
+
+export function parseMultiGrepConstraints(constraints: string | undefined): ConstraintParseResult {
+	const trimmed = constraints?.trim();
+	if (!trimmed) return { ok: true, globs: [], tokens: [] };
+
+	const tokenized = tokenizeConstraints(trimmed);
+	if (!tokenized.ok) return tokenized;
+
+	const globs: string[] = [];
+	for (const token of tokenized.tokens) {
+		const parsed = tokenToRipgrepGlob(token);
+		if (!parsed.ok) return parsed;
+		globs.push(parsed.glob);
+	}
+
+	return { ok: true, globs, tokens: tokenized.tokens };
+}
+
+function isRipgrepMatchLine(line: string): boolean {
+	return /^.+?:\d+:/.test(line);
+}
+
+function buildRipgrepArgs(params: MultiGrepRipgrepFallbackParams, globs: string[]): string[] {
+	const args = ["--line-number", "--with-filename", "--color=never", "--hidden", "--fixed-strings"];
+
+	if (params.ignoreCase) args.push("--ignore-case");
+	if (params.context && params.context > 0) args.push("--context", String(params.context));
+
+	for (const glob of globs) args.push("--glob", glob);
+	for (const pattern of params.patterns) args.push("-e", pattern);
+
+	const searchPath = params.path?.trim();
+	if (searchPath) args.push("--", searchPath);
+
+	return args;
+}
+
+export function getMultiGrepRipgrepArgs(
+	params: MultiGrepRipgrepFallbackParams,
+): ConstraintParseResult & { args?: string[] } {
+	const parsed = parseMultiGrepConstraints(params.constraints);
+	if (!parsed.ok) return parsed;
+	return { ...parsed, args: buildRipgrepArgs(params, parsed.globs) };
+}
+
+export async function runMultiGrepRipgrepFallback(
+	params: MultiGrepRipgrepFallbackParams,
+): Promise<MultiGrepRipgrepFallbackResult> {
+	const parsed = parseMultiGrepConstraints(params.constraints);
+	if (!parsed.ok) throw new Error(`unsupported constraints: ${parsed.error}`);
+
+	const args = buildRipgrepArgs(params, parsed.globs);
+
+	return new Promise((resolve, reject) => {
+		if (params.signal?.aborted) {
+			reject(new Error("Operation aborted"));
+			return;
+		}
+
+		const child = spawn("rg", args, { cwd: params.cwd, stdio: ["ignore", "pipe", "pipe"] });
+		const outputLines: string[] = [];
+		let stderr = "";
+		let buffer = "";
+		let matchCount = 0;
+		let limitReached = false;
+		let killedForLimit = false;
+		let settled = false;
+
+		const settle = (fn: () => void): void => {
+			if (settled) return;
+			settled = true;
+			fn();
+		};
+
+		const stopChild = (dueToLimit = false): void => {
+			if (!child.killed) {
+				killedForLimit = dueToLimit;
+				child.kill();
+			}
+		};
+
+		const onAbort = (): void => stopChild(false);
+		params.signal?.addEventListener("abort", onAbort, { once: true });
+
+		const cleanup = (): void => {
+			params.signal?.removeEventListener("abort", onAbort);
+		};
+
+		const handleLine = (line: string): void => {
+			if (limitReached) return;
+			outputLines.push(line);
+			if (isRipgrepMatchLine(line)) {
+				matchCount++;
+				if (matchCount >= params.limit) {
+					limitReached = true;
+					stopChild(true);
+				}
+			}
+		};
+
+		child.stdout?.on("data", (chunk: Buffer) => {
+			buffer += chunk.toString("utf8");
+			let newlineIndex = buffer.indexOf("\n");
+			while (newlineIndex >= 0) {
+				const line = buffer.slice(0, newlineIndex).replace(/\r$/, "");
+				buffer = buffer.slice(newlineIndex + 1);
+				handleLine(line);
+				newlineIndex = buffer.indexOf("\n");
+			}
+		});
+
+		child.stderr?.on("data", (chunk: Buffer) => {
+			stderr += chunk.toString("utf8");
+		});
+
+		child.on("error", (error: NodeJS.ErrnoException) => {
+			cleanup();
+			const message =
+				error.code === "ENOENT" ? "ripgrep (rg) is not available" : `Failed to run ripgrep: ${error.message}`;
+			settle(() => reject(new Error(message)));
+		});
+
+		child.on("close", (code) => {
+			cleanup();
+
+			if (params.signal?.aborted) {
+				settle(() => reject(new Error("Operation aborted")));
+				return;
+			}
+
+			if (buffer && !limitReached) handleLine(buffer.replace(/\r$/, ""));
+
+			if (!killedForLimit && code !== 0 && code !== 1) {
+				const message = stderr.trim() || `ripgrep exited with code ${code}`;
+				settle(() => reject(new Error(message)));
+				return;
+			}
+
+			settle(() =>
+				resolve({
+					text: outputLines.length ? outputLines.join("\n") : "No matches found",
+					matchCount,
+					limitReached,
+				}),
+			);
+		});
+	});
+}

package/test/bash-rendering.test.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from "vitest";
+
+import piPrettyExtension from "../src/index.js";
+
+class MockText {
+	private text = "";
+	constructor(_text = "", _x = 0, _y = 0) {}
+	setText(value: string) {
+		this.text = value;
+	}
+	getText() {
+		return this.text;
+	}
+}
+
+const mockTheme = {
+	fg: (_key: string, text: string) => text,
+	bold: (text: string) => text,
+};
+
+function mockToolFactory(exec: any) {
+	return (_cwd: string) => ({
+		name: "mock",
+		description: "mock",
+		parameters: { type: "object", properties: {} },
+		execute: exec,
+	});
+}
+
+function loadBashTool() {
+	const noopExec = async () => ({ content: [{ type: "text", text: "" }] });
+	const tools = new Map<string, any>();
+	const pi = {
+		registerTool: (tool: any) => tools.set(tool.name, tool),
+		registerCommand: () => {},
+		on: () => {},
+	};
+
+	piPrettyExtension(pi, {
+		sdk: {
+			createReadToolDefinition: mockToolFactory(noopExec),
+			createBashToolDefinition: mockToolFactory(noopExec),
+			createLsToolDefinition: mockToolFactory(noopExec),
+			createFindToolDefinition: mockToolFactory(noopExec),
+			createGrepToolDefinition: mockToolFactory(noopExec),
+			getAgentDir: () => "/tmp/pi-pretty-test",
+		},
+		TextComponent: MockText,
+	});
+
+	return tools.get("bash");
+}
+
+describe("bash renderCall expansion", () => {
+	it("truncates long commands when collapsed", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const rendered = bashTool.renderCall({ command }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain("bash");
+		expect(rendered.getText()).toContain("…");
+		expect(rendered.getText()).not.toContain(command);
+	});
+
+	it("shows the full command when expanded", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const rendered = bashTool.renderCall({ command }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: true,
+			invalidate: () => {},
+		});
+
+		expect(rendered.getText()).toContain(command);
+	});
+
+	it("preserves timeout text in both collapsed and expanded states", () => {
+		const bashTool = loadBashTool();
+		const command = `printf '${"x".repeat(120)}'`;
+
+		const collapsed = bashTool.renderCall({ command, timeout: 5 }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: false,
+			invalidate: () => {},
+		});
+		const expanded = bashTool.renderCall({ command, timeout: 5 }, mockTheme, {
+			lastComponent: new MockText(),
+			isError: false,
+			state: {},
+			expanded: true,
+			invalidate: () => {},
+		});
+
+		expect(collapsed.getText()).toContain("5s timeout");
+		expect(expanded.getText()).toContain("5s timeout");
+	});
+});

package/test/fff-integration.test.ts

@@ -8,9 +8,17 @@
  *    - Graceful degradation (FFF fails → SDK fallback)
  */
 
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import { describe, it, expect, vi, beforeEach } from "vitest";
 import { CursorStore, fffFormatGrepText } from "../src/fff-helpers.js";
 import piPrettyExtension, { type PiPrettyDeps } from "../src/index.js";
+import {
+	getMultiGrepRipgrepArgs,
+	parseMultiGrepConstraints,
+	runMultiGrepRipgrepFallback,
+} from "../src/multi-grep-fallback.js";
 
 // =========================================================================
 // 1. Unit tests — pure functions
@@ -109,6 +117,117 @@ describe("fffFormatGrepText", () => {
 		expect(lines[0]).toBe("a.ts:5:match");
 		expect(lines[1]).toBe("a.ts-6-after1");
 	});
+
+	it("sanitizes CRLF and CR without injecting grep record newlines", () => {
+		const items = [{
+			relativePath: "a.ts",
+			lineNumber: 5,
+			lineContent: "match\r\ncontinued\rtrail",
+			contextBefore: ["before\r\nline"],
+			contextAfter: ["after\rline"],
+		}];
+		const text = fffFormatGrepText(items, 100);
+		const lines = text.split("\n");
+
+		expect(lines).toEqual([
+			"a.ts-4-before\\nline",
+			"a.ts:5:match\\ncontinued\\rtrail",
+			"a.ts-6-after\\rline",
+		]);
+		expect(lines).toHaveLength(3);
+	});
+
+	it("strips trailing CR from CRLF-backed FFF records", () => {
+		const items = [{ relativePath: "a.ts", lineNumber: 5, lineContent: "match\r" }];
+		expect(fffFormatGrepText(items, 100)).toBe("a.ts:5:match");
+	});
+});
+
+describe("multi_grep constraint parsing", () => {
+	it("maps complex include/exclude constraints to ripgrep globs", () => {
+		expect(parseMultiGrepConstraints("*.{ts,tsx} !test/")).toEqual({
+			ok: true,
+			tokens: ["*.{ts,tsx}", "!test/"],
+			globs: ["*.{ts,tsx}", "!**/test/**"],
+		});
+	});
+
+	it("maps directory constraints as path components", () => {
+		expect(parseMultiGrepConstraints("src/ !src/generated/")).toEqual({
+			ok: true,
+			tokens: ["src/", "!src/generated/"],
+			globs: ["**/src/**", "!**/src/generated/**"],
+		});
+	});
+
+	it("builds literal ripgrep OR arguments with every constraint glob", () => {
+		const result = getMultiGrepRipgrepArgs({
+			cwd: "/repo",
+			patterns: ["foo", "bar"],
+			path: "src",
+			constraints: "*.ts !test/",
+			ignoreCase: true,
+			limit: 100,
+		});
+
+		expect(result.ok).toBe(true);
+		if (!result.ok) return;
+		expect(result.args).toEqual([
+			"--line-number",
+			"--with-filename",
+			"--color=never",
+			"--hidden",
+			"--fixed-strings",
+			"--ignore-case",
+			"--glob",
+			"*.ts",
+			"--glob",
+			"!**/test/**",
+			"-e",
+			"foo",
+			"-e",
+			"bar",
+			"--",
+			"src",
+		]);
+	});
+
+	it("ripgrep fallback enforces include/exclude constraints without widening", async () => {
+		const root = mkdtempSync(join(tmpdir(), "pi-pretty-mgrep-"));
+		try {
+			mkdirSync(join(root, "src", "test"), { recursive: true });
+			mkdirSync(join(root, "test"), { recursive: true });
+			writeFileSync(join(root, "src", "keep.ts"), "needle\n");
+			writeFileSync(join(root, "src", "keep.js"), "needle\n");
+			writeFileSync(join(root, "src", "test", "drop.ts"), "needle\n");
+			writeFileSync(join(root, "test", "drop.ts"), "needle\n");
+
+			const result = await runMultiGrepRipgrepFallback({
+				cwd: root,
+				patterns: ["needle"],
+				constraints: "*.ts !test/",
+				ignoreCase: true,
+				limit: 100,
+			});
+
+			expect(result.text).toContain("src/keep.ts");
+			expect(result.text).not.toContain("src/keep.js");
+			expect(result.text).not.toContain("src/test/drop.ts");
+			expect(result.text).not.toContain("test/drop.ts");
+		} catch (error) {
+			if (String(error).includes("ripgrep (rg) is not available")) return;
+			throw error;
+		} finally {
+			rmSync(root, { recursive: true, force: true });
+		}
+	});
+
+	it("rejects unsupported empty negation instead of ignoring it", () => {
+		expect(parseMultiGrepConstraints("*.ts !")).toEqual({
+			ok: false,
+			error: "empty constraint token: !",
+		});
+	});
 });
 
 // =========================================================================
@@ -172,6 +291,7 @@ describe("piPrettyExtension integration", () => {
 	const readExec = vi.fn();
 	const bashExec = vi.fn();
 	const lsExec = vi.fn();
+	const multiGrepRgExec = vi.fn();
 
 	function makeDeps(withFFF: boolean, finderOverrides?: Record<string, any>): PiPrettyDeps {
 		const finder = mkFinder(finderOverrides);
@@ -189,6 +309,7 @@ describe("piPrettyExtension integration", () => {
 			},
 			TextComponent: class { private t = ""; setText(v: string) { this.t = v; } getText() { return this.t; } },
 			fffModule: withFFF ? fffModule : undefined,
+			multiGrepRipgrepFallback: multiGrepRgExec,
 		};
 	}
 
@@ -201,12 +322,13 @@ describe("piPrettyExtension integration", () => {
 			on: vi.fn((e: string, h: Function) => events.set(e, h)),
 		};
 
-		for (const fn of [findExec, grepExec, readExec, bashExec, lsExec]) fn.mockReset();
+		for (const fn of [findExec, grepExec, readExec, bashExec, lsExec, multiGrepRgExec]) fn.mockReset();
 		findExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts\nsrc/main.ts" }] });
 		grepExec.mockResolvedValue({ content: [{ type: "text", text: "src/index.ts:10:const x = 1;" }] });
 		readExec.mockResolvedValue({ content: [{ type: "text", text: "content" }] });
 		bashExec.mockResolvedValue({ content: [{ type: "text", text: "output" }] });
 		lsExec.mockResolvedValue({ content: [{ type: "text", text: "f1\nf2" }] });
+		multiGrepRgExec.mockResolvedValue({ text: "src/index.ts:10:const x = 1;", matchCount: 1, limitReached: false });
 	});
 
 	function load(withFFF = false, finderOverrides?: Record<string, any>) {
@@ -236,9 +358,9 @@ describe("piPrettyExtension integration", () => {
 			expect(tools.has("multi_grep")).toBe(true);
 		});
 
-		it("NO multi_grep when FFF unavailable", () => {
+		it("registers multi_grep when grep SDK available", () => {
 			load(false);
-			expect(tools.has("multi_grep")).toBe(false);
+			expect(tools.has("multi_grep")).toBe(true);
 		});
 
 		it("registers session_start + session_shutdown", () => {
@@ -285,6 +407,32 @@ describe("piPrettyExtension integration", () => {
 			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
 			expect(r.details.matchCount).toBe(3);
 		});
+
+		it("normalizes CRLF in SDK text results", async () => {
+			grepExec.mockResolvedValue({
+				content: [{ type: "text", text: "a.ts:1:TODO\r\na.ts:5:TODO\rb.ts:10:TODO" }],
+			});
+			load(false);
+			const r = await tools.get("grep")!.execute("t1", { pattern: "TODO" }, null, null, {});
+			expect(r.content[0].text).toBe("a.ts:1:TODO\na.ts:5:TODO\nb.ts:10:TODO");
+			expect(r.details.text).toBe("a.ts:1:TODO\na.ts:5:TODO\nb.ts:10:TODO");
+			expect(r.details.matchCount).toBe(3);
+		});
+	});
+
+	// ---- read -----------------------------------------------------------
+
+	describe("read", () => {
+		it("normalizes CRLF in read details content", async () => {
+			readExec.mockResolvedValue({
+				content: [{ type: "text", text: "line1\r\nline2\rline3" }],
+			});
+			load(false);
+			const r = await tools.get("read")!.execute("t1", { path: "file.txt" }, null, null, {});
+			expect(r.details._type).toBe("readFile");
+			expect(r.details.content).toBe("line1\nline2\nline3");
+			expect(r.details.lineCount).toBe(3);
+		});
 	});
 
 	// ---- find: FFF path ------------------------------------------------
@@ -356,6 +504,22 @@ describe("piPrettyExtension integration", () => {
 			expect(r.content[0].text).toContain("src/index.ts:42:const x = 1;");
 		});
 
+		it("sanitizes CRLF in FFF grep output without extra records", async () => {
+			await loadWithFFF({
+				grep: vi.fn().mockReturnValue({
+					ok: true,
+					value: {
+						items: [{ relativePath: "src/index.ts", lineNumber: 42, lineContent: "const x = 1;\r\nconst y = 2;" }],
+						totalMatched: 1,
+						nextCursor: null,
+					},
+				}),
+			});
+			const r = await tools.get("grep")!.execute("t1", { pattern: "const" }, null, null, {});
+			expect(r.content[0].text).toBe("src/index.ts:42:const x = 1;\\nconst y = 2;");
+			expect(r.details.text.split("\n")).toHaveLength(1);
+		});
+
 		it("literal=true → mode=plain", async () => {
 			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
 			await loadWithFFF({ grep });
@@ -370,11 +534,20 @@ describe("piPrettyExtension integration", () => {
 			expect(grep).toHaveBeenCalledWith(expect.any(String), expect.objectContaining({ mode: "regex" }));
 		});
 
-		it("glob prepended to query", async () => {
+		it("glob constraints bypass FFF to avoid native Unicode path panic", async () => {
 			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
 			await loadWithFFF({ grep });
 			await tools.get("grep")!.execute("t1", { pattern: "TODO", glob: "*.ts" }, null, null, {});
-			expect(grep).toHaveBeenCalledWith("*.ts TODO", expect.any(Object));
+			expect(grep).not.toHaveBeenCalled();
+			expect(grepExec).toHaveBeenCalledOnce();
+		});
+
+		it("path constraints bypass FFF to avoid native Unicode path panic", async () => {
+			const grep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ grep });
+			await tools.get("grep")!.execute("t1", { pattern: "TODO", path: "file_reviewapp/static/app.js" }, null, null, {});
+			expect(grep).not.toHaveBeenCalled();
+			expect(grepExec).toHaveBeenCalledOnce();
 		});
 
 		it("falls back to SDK on throw", async () => {
@@ -406,10 +579,11 @@ describe("piPrettyExtension integration", () => {
 			expect(r.content[0].text).toContain("patterns array must have at least 1 element");
 		});
 
-		it("error when FFF not initialized (no session_start)", async () => {
+		it("falls back to SDK when FFF not initialized (no session_start)", async () => {
 			load(true);
 			const r = await tools.get("multi_grep")!.execute("t1", { patterns: ["foo"] }, null, null, null);
-			expect(r.content[0].text).toContain("FFF not initialized");
+			expect(grepExec).toHaveBeenCalledOnce();
+			expect(r.details._type).toBe("grepResult");
 		});
 
 		it("returns multiGrep results", async () => {
@@ -433,14 +607,96 @@ describe("piPrettyExtension integration", () => {
 			expect(r.content[0].text).toContain("compile failed");
 		});
 
-		it("passes constraints and context", async () => {
+		it("passes context to unconstrained FFF multiGrep", async () => {
 			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
 			await loadWithFFF({ multiGrep });
-			await tools.get("multi_grep")!.execute("t1", { patterns: ["a", "b"], constraints: "*.ts", context: 2 }, null, null, null);
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["a", "b"], context: 2 }, null, null, null);
 			expect(multiGrep).toHaveBeenCalledWith(expect.objectContaining({
-				patterns: ["a", "b"], constraints: "*.ts", beforeContext: 2, afterContext: 2,
+				patterns: ["a", "b"], beforeContext: 2, afterContext: 2,
+			}));
+			expect(multiGrep.mock.calls[0][0]).not.toHaveProperty("constraints");
+		});
+
+		it("glob constraints bypass FFF multiGrep and use ripgrep fallback", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["a", "b"], constraints: "*.ts", context: 2 }, null, null, {});
+			expect(multiGrep).not.toHaveBeenCalled();
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(multiGrepRgExec).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["a", "b"], constraints: "*.ts", context: 2, ignoreCase: true,
+			}));
+		});
+
+		it("path and constraints together bypass FFF multiGrep", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute(
+				"t1",
+				{ patterns: ["a", "b"], path: "src", constraints: "*.ts" },
+				null,
+				null,
+				{},
+			);
+			expect(multiGrep).not.toHaveBeenCalled();
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(multiGrepRgExec).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["a", "b"], path: "src", constraints: "*.ts",
 			}));
 		});
+
+		it("falls back to SDK when path is provided", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["foo", "bar"], path: "src" }, null, null, {});
+			expect(multiGrep).not.toHaveBeenCalled();
+			expect(grepExec).toHaveBeenCalledWith(
+				"t1",
+				expect.objectContaining({ pattern: "foo|bar", path: "src", ignoreCase: true }),
+				null,
+				null,
+				{},
+			);
+		});
+
+		it("uses path-backed ripgrep fallback for simple path constraints", async () => {
+			const multiGrep = vi.fn().mockReturnValue({ ok: true, value: { items: [], totalMatched: 0, nextCursor: null } });
+			await loadWithFFF({ multiGrep });
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["foo", "bar"], constraints: "src" }, null, null, {});
+			expect(multiGrep).not.toHaveBeenCalled();
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(multiGrepRgExec).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["foo", "bar"], path: "src", constraints: undefined,
+			}));
+		});
+
+		it("preserves complex constraints in ripgrep fallback", async () => {
+			await loadWithFFF();
+			const result = await tools.get("multi_grep")!.execute(
+				"t1",
+				{ patterns: ["foo", "bar"], path: "src", constraints: "*.ts !test/" },
+				null,
+				null,
+				{},
+			);
+			expect(grepExec).not.toHaveBeenCalled();
+			expect(multiGrepRgExec).toHaveBeenCalledWith(expect.objectContaining({
+				patterns: ["foo", "bar"], path: "src", constraints: "*.ts !test/",
+			}));
+			expect(result.content[0].text).not.toContain("ignored unsupported constraints");
+		});
+
+		it("uses case-sensitive SDK fallback when any pattern contains uppercase", async () => {
+			await loadWithFFF();
+			await tools.get("multi_grep")!.execute("t1", { patterns: ["foo", "Bar"], path: "src" }, null, null, {});
+			expect(grepExec).toHaveBeenCalledWith(
+				"t1",
+				expect.objectContaining({ pattern: "foo|Bar", ignoreCase: false }),
+				null,
+				null,
+				{},
+			);
+		});
 	});
 
 	// ---- session lifecycle ---------------------------------------------