@edxeth/pi-fff 0.7.2-edxeth.0 → 0.7.3-nightly.7a199d8

package/README.md

@@ -86,6 +86,7 @@ Search file contents. Smart case, plain text by default, regex optional.
 Parameters:
 - `pattern` — search text or regex
 - `path` — directory/file constraint (e.g. `src/`, `*.ts`)
+- `includeIgnored` — include files matched by `.gitignore`, `.ignore`, git excludes, or global gitignore when intentionally inspecting ignored paths
 - `ignoreCase` — force case-insensitive
 - `literal` — treat as literal string (default: true)
 - `context` — context lines around matches
@@ -99,6 +100,7 @@ Fuzzy file name search. Frecency-ranked.
 Parameters:
 - `pattern` — fuzzy query (e.g. `main.ts`, `src/ config`)
 - `path` — directory constraint
+- `includeIgnored` — include files matched by `.gitignore`, `.ignore`, git excludes, or global gitignore when intentionally inspecting ignored paths
 - `limit` — max results (default: 200)
 
 ### `fff-multi-grep`
@@ -134,6 +136,7 @@ Mode precedence:
 - `--fff-mode <mode>` — set mode (see above)
 - `--fff-frecency-db <path>` — path to frecency database (also: `FFF_FRECENCY_DB` env)
 - `--fff-history-db <path>` — path to query history database (also: `FFF_HISTORY_DB` env)
+- `PI_FFF_MULTIGREP=0` — disable `fff-multi-grep` (enabled by default)
 
 ## Data
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@edxeth/pi-fff",
   "public": true,
-  "version": "0.7.2-edxeth.0",
+  "version": "0.7.3-nightly.7a199d8",
   "description": "pi extension: FFF-powered fuzzy file and content search",
   "type": "module",
   "license": "MIT",
@@ -43,8 +43,8 @@
     "@edxeth/fff-node": "0.7.2-edxeth.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
-    "@mariozechner/pi-tui": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
     "@sinclair/typebox": "*"
   },
   "devDependencies": {

package/src/index.ts

@@ -8,23 +8,24 @@
 import { execSync } from "node:child_process";
 import fs from "node:fs";
 import path from "node:path";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { CustomEditor } from "@earendil-works/pi-coding-agent";
+import {
+  Text,
+  type AutocompleteItem,
+  type AutocompleteProvider,
+} from "@earendil-works/pi-tui";
+import { Type } from "@sinclair/typebox";
 import type {
   GrepCursor,
   GrepMode,
   GrepResult,
+  InitOptions,
   MixedItem,
   SearchResult,
 } from "@edxeth/fff-node";
 import { FileFinder } from "@edxeth/fff-node";
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import { CustomEditor } from "@mariozechner/pi-coding-agent";
-import {
-  type AutocompleteItem,
-  type AutocompleteProvider,
-  Text,
-} from "@mariozechner/pi-tui";
-import { Type } from "@sinclair/typebox";
-import { buildQuery } from "./query";
+import { buildQuery, normalizeExcludes } from "./query";
 
 // ---------------------------------------------------------------------------
 // Constants
@@ -37,6 +38,7 @@ const GREP_MAX_LINE_LENGTH = 500;
 const MENTION_MAX_RESULTS = 20;
 
 type FffMode = "tools-and-ui" | "tools-only" | "override";
+type FffInitOptions = InitOptions & { includeIgnored?: boolean };
 
 const VALID_MODES: FffMode[] = ["tools-and-ui", "tools-only", "override"];
 
@@ -65,12 +67,17 @@ function resolveToolNames(mode: FffMode): ToolNames {
 // Cursor store — simple bounded Map for pagination cursors
 // ---------------------------------------------------------------------------
 
-const cursorCache = new Map<string, GrepCursor>();
+interface StoredGrepCursor {
+  cursor: GrepCursor;
+  includeIgnored: boolean;
+}
+
+const cursorCache = new Map<string, StoredGrepCursor>();
 let cursorCounter = 0;
 
-function storeCursor(cursor: GrepCursor): string {
+function storeCursor(cursor: GrepCursor, includeIgnored = false): string {
   const id = `fff_c${++cursorCounter}`;
-  cursorCache.set(id, cursor);
+  cursorCache.set(id, { cursor, includeIgnored });
   if (cursorCache.size > 200) {
     const first = cursorCache.keys().next().value;
     if (first) cursorCache.delete(first);
@@ -78,7 +85,7 @@ function storeCursor(cursor: GrepCursor): string {
   return id;
 }
 
-function getCursor(id: string): GrepCursor | undefined {
+function getCursor(id: string): StoredGrepCursor | undefined {
   return cursorCache.get(id);
 }
 
@@ -91,6 +98,7 @@ interface FindCursor {
   pattern: string;
   pageSize: number;
   nextPageIndex: number;
+  includeIgnored: boolean;
 }
 
 const findCursorCache = new Map<string, FindCursor>();
@@ -131,6 +139,7 @@ export function fffFileAnnotation(item: {
   gitStatus?: string;
   totalFrecencyScore?: number;
   accessFrecencyScore?: number;
+  patternIndices?: number[];
 }): string {
   const git = item.gitStatus;
   if (git && git !== "clean" && git !== "unknown" && git !== "") {
@@ -144,6 +153,15 @@ export function fffFileAnnotation(item: {
   return "";
 }
 
+/** Compact label for a single pattern index range. */
+function formatPatternLabel(indices: Set<number>): string {
+  if (indices.size === 0) return "";
+  if (indices.size === 1) return ` [${[...indices][0]}]`;
+  // Show sorted compact range
+  const sorted = [...indices].sort((a, b) => a - b);
+  return ` [${sorted.join(",")}]`;
+}
+
 // fff-core native definition classifier (byte-level scanner in Rust) is enabled
 // via GrepOptions.classifyDefinitions. Each GrepMatch carries isDefinition for
 // downstream consumers; pi-fff does NOT use it to re-sort.
@@ -155,19 +173,31 @@ export function fffFileAnnotation(item: {
 // engine emits them that way.
 
 function formatGrepOutput(result: GrepResult): string {
-  if (result.items.length === 0) return "No matches found";
+  if (result.items.length === 0) {
+    if (result.regexFallbackError) return result.regexFallbackError;
+    return "No matches found";
+  }
 
   // Build file-grouped output in the order files first appear in the result.
   // This preserves native frecency ordering across files without re-sorting.
   const lines: string[] = [];
   let currentFile = "";
+  let currentFilePatterns: Set<number> | null = null;
   let _shown = 0;
 
+  // Detect if this is a multi-pattern result by checking first match
+  const isMultiPattern = result.items[0]?.patternIndices !== undefined;
+
   for (const match of result.items) {
     if (match.relativePath !== currentFile) {
       if (lines.length > 0) lines.push("");
       currentFile = match.relativePath;
-      lines.push(`${currentFile}${fffFileAnnotation(match)}`);
+      currentFilePatterns = isMultiPattern ? new Set() : null;
+
+      let header = currentFile;
+      const annotation = fffFileAnnotation(match);
+      if (annotation) header += annotation;
+      lines.push(header);
     }
 
     match.contextBefore?.forEach((line: string, i: number) => {
@@ -175,7 +205,22 @@ function formatGrepOutput(result: GrepResult): string {
       lines.push(` ${lineNum}- ${truncateLine(line)}`);
     });
 
-    lines.push(` ${match.lineNumber}: ${truncateLine(match.lineContent)}`);
+    // Build pattern prefix for this match line
+    let patternPrefix = "";
+    if (isMultiPattern && match.patternIndices) {
+      const uniqueIndices = new Set(match.patternIndices);
+      if (uniqueIndices.size === 1) {
+        patternPrefix = `[${[...uniqueIndices][0]}] `;
+        currentFilePatterns?.add([...uniqueIndices][0]);
+      } else {
+        // Multiple patterns on same line — show all
+        const sorted = [...uniqueIndices].sort((a, b) => a - b);
+        patternPrefix = `[${sorted.join("+")}] `;
+        sorted.forEach((i) => currentFilePatterns?.add(i));
+      }
+    }
+
+    lines.push(` ${patternPrefix}${match.lineNumber}: ${truncateLine(match.lineContent)}`);
     _shown++;
 
     match.contextAfter?.forEach((line: string, i: number) => {
@@ -334,7 +379,7 @@ function createFffMentionProvider(
 
 export default function fffExtension(pi: ExtensionAPI) {
   const finders = new Map<string, FileFinder>();
-  let activeBasePath: string | null = null;
+  let activeFinderKey: string | null = null;
   // Concurrent ensureFinder() callers share in-flight promises by base path so
   // FileFinder.create() (which takes native DB locks) runs at most once per
   // base path at a time — otherwise parallel tool calls would race and
@@ -416,6 +461,27 @@ export default function fffExtension(pi: ExtensionAPI) {
       : `Path not found: ${statPath || pathConstraint}`;
   }
 
+  async function noResultsMessage(
+    base: string,
+    basePath: string,
+    pathConstraint: string | undefined,
+    includeIgnored: boolean,
+  ): Promise<string> {
+    if (includeIgnored || !pathConstraint) return base;
+
+    const ignored = await withFinderLease(basePath, (finder) => {
+      const checker = finder as FileFinder & {
+        isPathIgnored?: (path: string) => { ok: boolean; value?: boolean };
+      };
+      return checker.isPathIgnored?.(pathConstraint);
+    });
+
+    if (ignored?.ok && ignored.value === true) {
+      return `${base}. Path is ignored. Retry with \`includeIgnored: true\`.`;
+    }
+    return base;
+  }
+
   function absolutePathBase(pathConstraint: string): {
     basePath: string;
     pathConstraint?: string;
@@ -456,49 +522,58 @@ export default function fffExtension(pi: ExtensionAPI) {
     return { basePath: activeCwd, pathConstraint };
   }
 
+  function finderKey(basePath: string, includeIgnored: boolean): string {
+    return `${includeIgnored ? "ignored" : "normal"}:${basePath}`;
+  }
+
   function trimFinderCache() {
     while (finders.size >= MAX_CACHED_FINDERS) {
       const evictable = [...finders.entries()].find(
-        ([basePath]) => (finderActiveOps.get(basePath) ?? 0) === 0,
+        ([key]) => (finderActiveOps.get(key) ?? 0) === 0,
       );
       if (!evictable) return;
 
-      const [oldestBase, oldestFinder] = evictable;
+      const [oldestKey, oldestFinder] = evictable;
       if (!oldestFinder.isDestroyed) oldestFinder.destroy();
-      finders.delete(oldestBase);
-      if (activeBasePath === oldestBase) activeBasePath = null;
+      finders.delete(oldestKey);
+      if (activeFinderKey === oldestKey) activeFinderKey = null;
     }
   }
 
-  function ensureFinder(basePath: string): Promise<FileFinder> {
-    const existing = finders.get(basePath);
+  function ensureFinder(basePath: string, includeIgnored = false): Promise<FileFinder> {
+    const key = finderKey(basePath, includeIgnored);
+    const existing = finders.get(key);
     if (existing && !existing.isDestroyed) return Promise.resolve(existing);
-    const pending = finderPromises.get(basePath);
+    const pending = finderPromises.get(key);
     if (pending) return pending;
 
     const promise = (async () => {
       trimFinderCache();
-      const useDatabases = basePath === activeCwd;
+      const useDatabases = basePath === activeCwd && !includeIgnored;
+      const isWorkspace = basePath === activeCwd;
       const result = FileFinder.create({
         basePath,
         frecencyDbPath: useDatabases ? frecencyDbPath : undefined,
         historyDbPath: useDatabases ? historyDbPath : undefined,
-        aiMode: true,
-      });
+        aiMode: isWorkspace,
+        disableContentIndexing: !isWorkspace,
+        disableMmapCache: !isWorkspace,
+        includeIgnored,
+      } as FffInitOptions);
 
       if (!result.ok)
         throw new Error(`Failed to create FFF file finder: ${result.error}`);
 
       const finder = result.value;
-      finders.set(basePath, finder);
-      activeBasePath = basePath;
+      finders.set(key, finder);
+      if (!includeIgnored) activeFinderKey = key;
       await finder.waitForScan(15000);
       return finder;
     })().finally(() => {
-      finderPromises.delete(basePath);
+      finderPromises.delete(key);
     });
 
-    finderPromises.set(basePath, promise);
+    finderPromises.set(key, promise);
     return promise;
   }
 
@@ -509,20 +584,22 @@ export default function fffExtension(pi: ExtensionAPI) {
     finders.clear();
     finderLocks.clear();
     finderActiveOps.clear();
-    activeBasePath = null;
+    activeFinderKey = null;
   }
 
   async function withFinderLease<T>(
     basePath: string,
     work: (finder: FileFinder) => T | Promise<T>,
+    includeIgnored = false,
   ): Promise<T> {
-    const previous = finderLocks.get(basePath) ?? Promise.resolve();
+    const key = finderKey(basePath, includeIgnored);
+    const previous = finderLocks.get(key) ?? Promise.resolve();
     let release!: () => void;
     const current = new Promise<void>((resolve) => {
       release = resolve;
     });
     finderLocks.set(
-      basePath,
+      key,
       previous.then(
         () => current,
         () => current,
@@ -530,22 +607,22 @@ export default function fffExtension(pi: ExtensionAPI) {
     );
 
     await previous.catch(() => undefined);
-    finderActiveOps.set(basePath, (finderActiveOps.get(basePath) ?? 0) + 1);
+    finderActiveOps.set(key, (finderActiveOps.get(key) ?? 0) + 1);
     try {
-      const finder = await ensureFinder(basePath);
+      const finder = await ensureFinder(basePath, includeIgnored);
       return await work(finder);
     } finally {
-      const remaining = (finderActiveOps.get(basePath) ?? 1) - 1;
-      if (remaining > 0) finderActiveOps.set(basePath, remaining);
-      else finderActiveOps.delete(basePath);
+      const remaining = (finderActiveOps.get(key) ?? 1) - 1;
+      if (remaining > 0) finderActiveOps.set(key, remaining);
+      else finderActiveOps.delete(key);
       release();
-      if (finderLocks.get(basePath) === current) finderLocks.delete(basePath);
+      if (finderLocks.get(key) === current) finderLocks.delete(key);
     }
   }
 
   function getActiveFinder(): FileFinder | null {
-    if (!activeBasePath) return null;
-    const finder = finders.get(activeBasePath);
+    if (!activeFinderKey) return null;
+    const finder = finders.get(activeFinderKey);
     return finder && !finder.isDestroyed ? finder : null;
   }
 
@@ -729,6 +806,12 @@ export default function fffExtension(pi: ExtensionAPI) {
           "Exclude paths (comma/space-separated or array). Same syntax as path: directory prefix ('test/'), filename with extension ('config.json'), or glob ('*.min.js', '**/*.{rs,go}'). A leading '!' is optional and ignored — both 'test/' and '!test/' work. Example: 'test/,*.min.js,!vendor/'.",
       }),
     ),
+    includeIgnored: Type.Optional(
+      Type.Boolean({
+        description:
+          "Include files matched by .gitignore, .ignore, git excludes, and global gitignore. Default false. Use when the target file or directory exists but normal search cannot see it because it is ignored, such as node_modules or build output.",
+      }),
+    ),
     caseSensitive: Type.Optional(
       Type.Boolean({
         description:
@@ -754,11 +837,13 @@ export default function fffExtension(pi: ExtensionAPI) {
     description: `Grep file contents. Smart-case, auto-detects regex vs literal, git-aware. Results are ranked by frecency (most-accessed files first); matches within a file stay in source order. Default limit ${DEFAULT_GREP_LIMIT}.`,
     promptSnippet: "Grep contents",
     promptGuidelines: [
-      "Prefer bare identifiers as patterns. Literal queries are most efficient.",
-      "Use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').",
-      "caseSensitive: true when you need exact case (smart-case otherwise).",
-      "Never combine paths in one call. For multiple files, make separate grep calls.",
-      "After 1-2 greps, read the top match instead of more greps.",
+      "Use for content, not paths.",
+      "Use one literal identifier or phrase first; regex only when needed.",
+      "Use path for one scope and exclude for noise, e.g. path: 'src/', exclude: 'test/,*.min.js'.",
+      "Set includeIgnored only when intentionally searching ignored files such as node_modules or build output.",
+      "Set caseSensitive: true only when exact case matters; otherwise smart-case applies.",
+      "Use multi_grep for 2-6 literal identifiers or naming variants; grep regex alternation is OK for a simple 2-way OR.",
+      "After 1-2 greps, read the best match instead of widening search.",
     ],
     parameters: grepSchema,
 
@@ -818,17 +903,22 @@ export default function fffExtension(pi: ExtensionAPI) {
       // caseSensitive override flips smartCase off; omitting it keeps smart-case
       // (case-insensitive when pattern is all lowercase).
       const smartCase = params.caseSensitive !== true;
+      const storedCursor = params.cursor ? getCursor(params.cursor) : undefined;
+      const includeIgnored = storedCursor?.includeIgnored ?? params.includeIgnored === true;
 
-      const grepResult = await withFinderLease(searchBase.basePath, (finder) =>
-        finder.grep(query, {
-          mode,
-          smartCase,
-          maxMatchesPerFile: Math.min(effectiveLimit, 50),
-          cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
-          beforeContext: params.context ?? 0,
-          afterContext: params.context ?? 0,
-          classifyDefinitions: true,
-        }),
+      const grepResult = await withFinderLease(
+        searchBase.basePath,
+        (finder) =>
+          finder.grep(query, {
+            mode,
+            smartCase,
+            maxMatchesPerFile: Math.min(effectiveLimit, 50),
+            cursor: storedCursor?.cursor ?? null,
+            beforeContext: params.context ?? 0,
+            afterContext: params.context ?? 0,
+            classifyDefinitions: true,
+          }),
+        includeIgnored,
       );
 
       if (!grepResult.ok) throw new Error(grepResult.error);
@@ -843,16 +933,19 @@ export default function fffExtension(pi: ExtensionAPI) {
         !params.exclude &&
         mode !== "regex"
       ) {
-        const fuzzy = await withFinderLease(searchBase.basePath, (finder) =>
-          finder.grep(query, {
-            mode: "fuzzy",
-            smartCase,
-            maxMatchesPerFile: Math.min(effectiveLimit, 50),
-            cursor: null,
-            beforeContext: 0,
-            afterContext: 0,
-            classifyDefinitions: true,
-          }),
+        const fuzzy = await withFinderLease(
+          searchBase.basePath,
+          (finder) =>
+            finder.grep(query, {
+              mode: "fuzzy",
+              smartCase,
+              maxMatchesPerFile: Math.min(effectiveLimit, 50),
+              cursor: null,
+              beforeContext: 0,
+              afterContext: 0,
+              classifyDefinitions: true,
+            }),
+          includeIgnored,
         );
 
         if (fuzzy.ok && fuzzy.value.items.length > 0) {
@@ -861,7 +954,10 @@ export default function fffExtension(pi: ExtensionAPI) {
         }
       }
 
-      if (result.items.length === 0) throw new Error("No matches found");
+      if (result.items.length === 0)
+        throw new Error(
+          await noResultsMessage("No matches found", searchBase.basePath, params.path, includeIgnored),
+        );
 
       let output = formatGrepOutput(result);
       const notices: string[] = [];
@@ -869,8 +965,9 @@ export default function fffExtension(pi: ExtensionAPI) {
         notices.push(`Invalid regex: ${result.regexFallbackError}, used literal match`);
       }
       if (result.nextCursor) {
-        notices.push(`Continue with cursor="${storeCursor(result.nextCursor)}"`);
+        notices.push(`Continue with cursor="${storeCursor(result.nextCursor, includeIgnored)}"`);
       }
+      if (includeIgnored) notices.unshift("ignored files included");
 
       if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
       if (fuzzyNotice) output = `[${fuzzyNotice}]\n${output}`;
@@ -924,6 +1021,12 @@ export default function fffExtension(pi: ExtensionAPI) {
           "Exclude paths (comma/space-separated or array). Same syntax as path: directory prefix ('test/'), filename with extension ('config.json'), or glob ('*.min.js', '**/*.{rs,go}'). A leading '!' is optional and ignored — both 'test/' and '!test/' work. Example: 'test/,*.min.js,!vendor/'.",
       }),
     ),
+    includeIgnored: Type.Optional(
+      Type.Boolean({
+        description:
+          "Include files matched by .gitignore, .ignore, git excludes, and global gitignore. Default false. Use when the target file or directory exists but normal search cannot see it because it is ignored, such as node_modules or build output.",
+      }),
+    ),
     limit: Type.Optional(
       Type.Number({
         description: `Max results per page (default ${DEFAULT_FIND_LIMIT})`,
@@ -940,13 +1043,14 @@ export default function fffExtension(pi: ExtensionAPI) {
     description: `Fuzzy path search and glob search. Matches against the whole repo-relative path, not just the filename. Frecency-ranked, git-aware. Multi-word = narrower (AND). Default limit ${DEFAULT_FIND_LIMIT}.`,
     promptSnippet: "Find files by path or glob",
     promptGuidelines: [
-      "Matches the WHOLE path, not just the filename — `profile` hits `chrome/browser/profiles/x.cc` too.",
-      "Keep queries to 1-2 terms; extra words narrow.",
-      "Use one path constraint only: one file, directory, or glob.",
-      "Use for paths, not content. Use grep for content.",
-      "For exact path matches use a glob in `path` — e.g. path: '**/profile.h' for exact filename, or path: 'src/**/profile.h' scoped to a subtree. Bare patterns are fuzzy.",
-      "To list everything inside a directory, pass path: 'dir/**' with an empty or wildcard pattern instead of using pattern alone.",
-      "Use exclude: 'test/,*.min.js' to cut noise in large repos.",
+      "Use for paths, not content; use grep for content.",
+      "Pattern is fuzzy over the whole repo-relative path, not just the basename.",
+      "Keep pattern to 1-2 terms; extra words narrow results.",
+      "Put exact paths, directories, and globs in path, not pattern, e.g. path: '**/profile.h'.",
+      "Use only one path constraint: one file, directory, or glob.",
+      "For directory contents, use path: 'dir/**' with pattern: '' or '*'.",
+      "Use exclude to cut noise, e.g. 'test/,*.min.js'.",
+      "Set includeIgnored only when intentionally searching ignored files such as node_modules or build output.",
     ],
     parameters: findSchema,
 
@@ -981,12 +1085,16 @@ export default function fffExtension(pi: ExtensionAPI) {
         throw new Error(pathLikePatternMessage(pattern));
       }
       const pageIndex = resumed?.nextPageIndex ?? 0;
+      const includeIgnored = resumed?.includeIgnored ?? params.includeIgnored === true;
 
-      const searchResult = await withFinderLease(basePath, (finder) =>
-        finder.fileSearch(query, {
-          pageIndex,
-          pageSize: effectiveLimit,
-        }),
+      const searchResult = await withFinderLease(
+        basePath,
+        (finder) =>
+          finder.fileSearch(query, {
+            pageIndex,
+            pageSize: effectiveLimit,
+          }),
+        includeIgnored,
       );
       if (!searchResult.ok) throw new Error(searchResult.error);
 
@@ -998,11 +1106,14 @@ export default function fffExtension(pi: ExtensionAPI) {
           params.exclude,
           basePath,
         );
-        const fallback = await withFinderLease(basePath, (finder) =>
-          finder.fileSearch(scopedQuery, {
-            pageIndex: 0,
-            pageSize: Math.max(effectiveLimit, 500),
-          }),
+        const fallback = await withFinderLease(
+          basePath,
+          (finder) =>
+            finder.fileSearch(scopedQuery, {
+              pageIndex: 0,
+              pageSize: Math.max(effectiveLimit, 500),
+            }),
+          includeIgnored,
         );
         if (fallback.ok) {
           const needle = pattern.trim().toLowerCase();
@@ -1020,7 +1131,74 @@ export default function fffExtension(pi: ExtensionAPI) {
           }
         }
       }
-      if (result.items.length === 0) throw new Error("No files found matching pattern");
+
+      let regexFallbackUsed = false;
+      let regexFallbackAlts: string[] = [];
+
+      // Regex alternation recovery: models commonly write "foo|bar" expecting OR,
+      // but FFF fuzzy treats | as a literal character that no file path contains.
+      // When | is present, search each alternative independently and merge results,
+      // preserving true OR semantics instead of raw fuzzy matching.
+      if (!params.cursor && !resumed && pattern.includes("|")) {
+        const alternatives = pattern
+          .split("|")
+          .map((s) => s.trim().replace(/[()]/g, ""))
+          .filter(Boolean);
+        regexFallbackAlts = alternatives;
+        if (alternatives.length > 1) {
+          const seen = new Set<string>();
+          const merged: Array<{
+            relativePath: string;
+            fileName?: string;
+            gitStatus?: string;
+            totalFrecencyScore?: number;
+            accessFrecencyScore?: number;
+            [key: string]: unknown;
+          }> = [];
+          for (const alt of alternatives) {
+            const altQuery = buildQuery(
+              resolvedBase.pathConstraint,
+              alt,
+              params.exclude,
+              basePath,
+            );
+            const altResult = await withFinderLease(
+              basePath,
+              (finder) =>
+                finder.fileSearch(altQuery, {
+                  pageIndex: 0,
+                  pageSize: effectiveLimit,
+                }),
+              includeIgnored,
+            );
+            if (altResult.ok) {
+              for (const item of altResult.value.items) {
+                if (!seen.has(item.relativePath)) {
+                  seen.add(item.relativePath);
+                  merged.push(item);
+                }
+              }
+            }
+          }
+          if (merged.length > 0) {
+            result = {
+              items: merged,
+              totalMatched: merged.length,
+            } as typeof result;
+            // Scores from different alternative searches aren't cross-comparable,
+            // so fabricate above-threshold scores to avoid weak-match capping.
+            (result as Record<string, unknown>).scores = merged.map(() => ({
+              total: weakScoreThreshold(pattern) + 1,
+            }));
+            regexFallbackUsed = true;
+          }
+        }
+      }
+
+      if (result.items.length === 0)
+        throw new Error(
+          await noResultsMessage("No files found matching pattern", basePath, params.path, includeIgnored),
+        );
 
       const formatted = formatFindOutput(result, effectiveLimit, pattern);
       let output = formatted.output;
@@ -1041,7 +1219,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       if (formatted.literalTailSuppressed && hiddenFuzzyMatches >= 1000)
         notices.push(`${formatted.shownCount} exact matches shown. Fuzzy tail hidden`);
 
-      if (!formatted.weak && !formatted.literalTailSuppressed && hasMore) {
+      if (!formatted.weak && !formatted.literalTailSuppressed && hasMore && !regexFallbackUsed) {
         const remaining = result.totalMatched - shownSoFar;
         const cursorId = storeFindCursor({
           basePath,
@@ -1049,9 +1227,14 @@ export default function fffExtension(pi: ExtensionAPI) {
           pattern,
           pageSize: effectiveLimit,
           nextPageIndex: pageIndex + 1,
+          includeIgnored,
         });
         notices.push(`${remaining} more. Next page: find cursor="${cursorId}"`);
       }
+      if (regexFallbackUsed) {
+        notices.push(`Regex alternation (|) in pattern treated as ${regexFallbackAlts.length} searches: ${regexFallbackAlts.map((s) => `"${s}"`).join(", ")}`);
+      }
+      if (includeIgnored) notices.unshift("ignored files included");
 
       if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;
       return {
@@ -1087,15 +1270,35 @@ export default function fffExtension(pi: ExtensionAPI) {
   });
 
   // --- multi_grep tool ---
-  // My latest tests are showing that the multi grep tool is only harmful, trying to get rid of it
-  const enableMultiGrep = process.env.PI_FFF_MULTIGREP === "1";
+  // Enabled by default. Disable with `PI_FFF_MULTIGREP=0`
+  const enableMultiGrep = process.env.PI_FFF_MULTIGREP !== "0";
 
   if (enableMultiGrep) {
     const multiGrepSchema = Type.Object({
       patterns: Type.Array(Type.String(), {
         description:
           "Literal patterns (OR). Include snake_case/camelCase/PascalCase variants.",
+        minItems: 1,
+        maxItems: 20,
       }),
+      path: Type.Optional(
+        Type.String({
+          description:
+            "Single path constraint: one file, one directory, or one glob. Do not pass multiple paths. Applied to the full repo-relative path.",
+        }),
+      ),
+      exclude: Type.Optional(
+        Type.Union([Type.String(), Type.Array(Type.String())], {
+          description:
+            "Exclude paths (comma/space-separated or array). Same syntax as path: directory prefix ('test/'), filename with extension ('config.json'), or glob ('*.min.js', '**/*.{rs,go}'). A leading '!' is optional and ignored. Example: 'test/,*.min.js,!vendor/'.",
+        }),
+      ),
+      includeIgnored: Type.Optional(
+        Type.Boolean({
+          description:
+            "Include files matched by .gitignore, .ignore, git excludes, and global gitignore. Default false. Use when the target file or directory exists but normal search cannot see it because it is ignored, such as node_modules or build output.",
+        }),
+      ),
       constraints: Type.Optional(
         Type.String({ description: "File filter, e.g. '*.{ts,tsx} !test/'" }),
       ),
@@ -1112,12 +1315,15 @@ export default function fffExtension(pi: ExtensionAPI) {
       name: toolNames.multiGrep,
       label: toolNames.multiGrep,
       description:
-        "Search file contents for ANY of multiple literal patterns (OR, SIMD Aho-Corasick). Faster than regex alternation.",
+        "Search file contents for ANY of multiple literal patterns (OR logic). Faster than regex alternation for literal text.",
       promptSnippet: "Multi-pattern OR content search",
       promptGuidelines: [
-        "Use when searching for several identifiers at once.",
-        "Include all naming-convention variants (snake/camel/Pascal).",
-        "Patterns are literal. Use constraints for file filters.",
+        "Use for content searches with 2-6 literal identifiers or naming variants.",
+        "Patterns are ORed literals, not regexes or globs.",
+        "Do not use for broad concepts or unrelated keywords; run separate searches instead.",
+        "Use constraints for file filters, e.g. '*.{ts,tsx} !test/'.",
+        "Output tags each match with the pattern index.",
+        "Set includeIgnored only when intentionally searching ignored files such as node_modules or build output.",
       ],
       parameters: multiGrepSchema,
 
@@ -1125,25 +1331,48 @@ export default function fffExtension(pi: ExtensionAPI) {
         if (signal?.aborted) throw new Error("Operation aborted");
         if (!params.patterns?.length)
           throw new Error("patterns array must have at least 1 element");
+        if (params.path && pathLooksLikeMultiplePaths(params.path)) {
+          throw new Error(
+            "Path appears to contain multiple entries — multi_grep accepts a single path. Use separate calls or a glob pattern.",
+          );
+        }
+        const invalidPath = params.path ? invalidPathMessage(params.path) : null;
+        if (invalidPath) throw new Error(invalidPath);
 
         const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
-
-        const grepResult = await withFinderLease(activeCwd, (finder) =>
-          finder.multiGrep({
-            patterns: params.patterns,
-            constraints: params.constraints,
-            maxMatchesPerFile: Math.min(effectiveLimit, 50),
-            smartCase: true,
-            cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
-            beforeContext: params.context ?? 0,
-            afterContext: params.context ?? 0,
-          }),
+        const searchBase = resolveSearchBase(params.path);
+        const includeIgnored = params.includeIgnored === true;
+
+        // Build combined constraints from pathConstraint + exclude + explicit constraints
+        const constraintParts: string[] = [];
+        if (searchBase.pathConstraint) constraintParts.push(searchBase.pathConstraint);
+        constraintParts.push(...normalizeExcludes(params.exclude, searchBase.basePath));
+        if (params.constraints) constraintParts.push(params.constraints);
+        const effectiveConstraints = constraintParts.join(" ");
+
+        const grepResult = await withFinderLease(
+          searchBase.basePath,
+          (finder) =>
+            finder.multiGrep({
+              patterns: params.patterns,
+              constraints: effectiveConstraints,
+              maxMatchesPerFile: Math.min(effectiveLimit, 50),
+              smartCase: true,
+              cursor: (params.cursor ? getCursor(params.cursor)?.cursor : null) ?? null,
+              beforeContext: params.context ?? 0,
+              afterContext: params.context ?? 0,
+              classifyDefinitions: true,
+            }),
+          includeIgnored,
         );
 
         if (!grepResult.ok) throw new Error(grepResult.error);
 
         const result = grepResult.value;
-        if (result.items.length === 0) throw new Error("No matches found");
+        if (result.items.length === 0) {
+          if (result.regexFallbackError) throw new Error(result.regexFallbackError);
+          throw new Error("No matches found");
+        }
 
         let output = formatGrepOutput(result);
 
@@ -1152,8 +1381,9 @@ export default function fffExtension(pi: ExtensionAPI) {
           notices.push(`${effectiveLimit}+ matches (refine patterns)`);
         if (result.nextCursor)
           notices.push(
-            `More available. cursor="${storeCursor(result.nextCursor)}" to continue`,
+            `More available. cursor="${storeCursor(result.nextCursor, includeIgnored)}" to continue`,
           );
+        if (includeIgnored) notices.unshift("ignored files included");
 
         if (notices.length > 0) output += `\n\n[${notices.join(". ")}]`;