@ff-labs/pi-fff 0.10.6-nightly.f4def12 → 0.10.6

package/README.md

@@ -116,7 +116,7 @@ Parameters:
 
 - `/fff-health` — show FFF status (indexed files, git info, frecency/history DB status)
 - `/fff-rescan` — trigger a file rescan
-- `/fff-mode <mode>` — switch mode (tool name change requires restart)
+- `/fff-mode <mode>` — switch mode (tool name changes require `/reload`)
 
 ## Modes
 
@@ -124,10 +124,47 @@ Parameters:
 - `tools-only`: additional tools only; keep pi's default `@` autocomplete
 - `override`: replaces pi's built-in `find`, `grep` and adds `multi_grep` + FFF-backed `@` autocomplete
 
-Mode precedence:
+Startup mode precedence:
 1. `--fff-mode <mode>` CLI flag
 2. `PI_FFF_MODE=<mode>` environment variable
-3. default (`tools-and-ui`)
+3. `mode` in the global config file
+4. default (`tools-and-ui`)
+
+When a session resumes, its most recent `/fff-mode` selection takes precedence over the startup resolution above. Switching to or from `override` takes effect after `/reload`, when the tools are registered again.
+
+## Configuration
+
+For persistent global configuration, create `pi-fff.json` in pi's agent directory (`~/.pi/agent/pi-fff.json` by default; `PI_CODING_AGENT_DIR` is respected):
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/dmtrKovalenko/fff/main/packages/pi-fff/pi-fff.schema.json",
+  "mode": "override",
+  "frecencyDbPath": "/path/to/frecency",
+  "historyDbPath": "/path/to/history",
+  "enableFsRootScanning": false,
+  "enableHomeDirScanning": true,
+  "warnOnHomeDirScan": true,
+  "followSymlinks": true
+}
+```
+
+All fields are optional:
+
+| Field | Type | Default |
+|---|---|---|
+| `$schema` | non-empty string | none |
+| `mode` | `tools-and-ui`, `tools-only`, or `override` | `tools-and-ui` |
+| `frecencyDbPath` | non-empty string | See [Data](#data) |
+| `historyDbPath` | non-empty string | See [Data](#data) |
+| `enableFsRootScanning` | boolean | `false` |
+| `enableHomeDirScanning` | boolean | `true` |
+| `warnOnHomeDirScan` | boolean | `true` |
+| `followSymlinks` | boolean | `true` |
+
+CLI flags take precedence over environment variables, which take precedence over this file. A missing file is ignored. Malformed JSON, unknown fields, and invalid values stop the extension from loading and report the file path and error. `/fff-mode` changes the current session; it does not edit this file.
+
+The file is global only. Project-level config cannot safely control tool names because pi decides which tools an extension registers before project configuration can be trusted.
 
 ## Flags
 
@@ -136,6 +173,8 @@ Mode precedence:
 - `--fff-history-db <path>` — path to query history database (also: `FFF_HISTORY_DB` env). Optional; see [Data](#data) for the default.
 - `--fff-enable-root-scan` — allow indexing when launched from `/` (also: `FFF_ENABLE_ROOT_SCAN=1` env). FFF refuses to init at the filesystem root by default.
 - `--fff-enable-home-scan` — index the home directory when launched from `$HOME` (also: `FFF_ENABLE_HOME_SCAN` env). Enabled by default. Disable with `--fff-enable-home-scan=false` or `FFF_ENABLE_HOME_SCAN=0` if your `$HOME` contains huge trees (toolchains, kernel sources, build outputs) that make the background index run for a long time. When launched from `$HOME` with this enabled, pi shows a warning that the whole home tree is being indexed.
+- `--fff-warn-home-scan` — show the warning notification when `$HOME` is indexed (also: `FFF_WARN_HOME_SCAN` env). Enabled by default. Disable with `--fff-warn-home-scan=false`, `FFF_WARN_HOME_SCAN=0`, or `"warnOnHomeDirScan": false` in `pi-fff.json`. Indexing and the footer status are unaffected.
+- `--fff-follow-symlinks` — index through directory symlinks (also: `FFF_FOLLOW_SYMLINKS` env, or `"followSymlinks"` in `pi-fff.json`). Enabled by default: trees that reach their real files through links — a git worktree whose `docs/` links back to the main checkout, or a stowed dotfiles layout — would otherwise be missing from `@`-mentions and from find/grep with no visible sign. Disable with `--fff-follow-symlinks=false` or `FFF_FOLLOW_SYMLINKS=0` to keep the walk inside the real tree, which is worth doing when a linked target pulls in a large tree outside the workspace. Symlink cycles are detected and broken by the walker.
 
 ## Data
 
@@ -147,11 +186,12 @@ Each path is resolved independently, in this order:
 
 1. CLI flag — `--fff-frecency-db` / `--fff-history-db`
 2. Env var — `FFF_FRECENCY_DB` / `FFF_HISTORY_DB`
-3. An existing [fff.nvim](https://github.com/dmtrKovalenko/fff.nvim) database, so pi reuses the frecency you built up in your editor:
+3. Global config — `frecencyDbPath` / `historyDbPath`
+4. An existing [fff.nvim](https://github.com/dmtrKovalenko/fff.nvim) database, so pi reuses the frecency you built up in your editor:
    - frecency: `$XDG_CACHE_HOME/nvim/fff_nvim`
    - history: `$XDG_DATA_HOME/nvim/fff_queries`
    - `XDG_CACHE_HOME` defaults to `~/.cache` and `XDG_DATA_HOME` to `~/.local/share`; on Windows both fall back under `%LOCALAPPDATA%\nvim-data`. Only directories count — a plain file at those paths is ignored.
-4. pi-local directory, created on demand — `$PI_CODING_AGENT_DIR/fff/{frecency,history}`, defaulting to `~/.pi/agent/fff/{frecency,history}`
+5. pi-local directory, created on demand — `$PI_CODING_AGENT_DIR/fff/{frecency,history}`, defaulting to `~/.pi/agent/fff/{frecency,history}`
 
 The extension only reads these databases; it never records the agent's own searches into your Neovim history. If a database cannot be opened, the finder starts without persistence and pi shows a warning instead of failing.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ff-labs/pi-fff",
   "public": true,
-  "version": "0.10.6-nightly.f4def12",
+  "version": "0.10.6",
   "description": "pi extension: FFF-powered fuzzy file and content search",
   "type": "module",
   "license": "MIT",
@@ -30,7 +30,8 @@
     ]
   },
   "files": [
-    "src"
+    "src",
+    "pi-fff.schema.json"
   ],
   "publishConfig": {
     "access": "public"
@@ -40,8 +41,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@ff-labs/fff-bun": "0.10.6-nightly.f4def12",
-    "@ff-labs/fff-node": "0.10.6-nightly.f4def12"
+    "@ff-labs/fff-bun": "0.10.6",
+    "@ff-labs/fff-node": "0.10.6"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/pi-fff.schema.json

@@ -0,0 +1,51 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/dmtrKovalenko/fff/main/packages/pi-fff/pi-fff.schema.json",
+  "title": "pi-fff configuration",
+  "description": "Global startup configuration for the pi-fff extension.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Schema URL used by editors for validation and completion."
+    },
+    "mode": {
+      "type": "string",
+      "enum": ["tools-and-ui", "tools-only", "override"],
+      "default": "tools-and-ui",
+      "description": "Controls which FFF tools and autocomplete integrations are enabled."
+    },
+    "frecencyDbPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the frecency database."
+    },
+    "historyDbPath": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Path to the query history database."
+    },
+    "enableFsRootScanning": {
+      "type": "boolean",
+      "default": false,
+      "description": "Allows indexing when pi is launched from the filesystem root."
+    },
+    "enableHomeDirScanning": {
+      "type": "boolean",
+      "default": true,
+      "description": "Allows indexing when pi is launched from the home directory."
+    },
+    "warnOnHomeDirScan": {
+      "type": "boolean",
+      "default": true,
+      "description": "Shows a warning notification when the home directory is indexed."
+    },
+    "followSymlinks": {
+      "type": "boolean",
+      "default": true,
+      "description": "Indexes through directory symlinks, e.g. a git worktree or stow layout whose files live behind links. Set to false to keep the walk inside the real tree."
+    }
+  }
+}

package/src/aux-finders.ts

@@ -16,6 +16,7 @@ interface AuxPicker {
 export interface AuxOpts {
   enableFsRootScanning: boolean;
   enableHomeDirScanning?: boolean;
+  followSymlinks?: boolean;
   pickers: FilePickerFactory;
   // Called before a newly spawned aux picker starts a scan that covers $HOME.
   onHomeDirScan?: (root: string) => void;
@@ -104,6 +105,7 @@ export class AuxFinderPool {
       basePath: root,
       enableHomeDirScanning,
       enableFsRootScanning: this.opts.enableFsRootScanning,
+      followSymlinks: this.opts.followSymlinks,
     });
 
     const entry: AuxPicker = { root, finder, lastUsed: Date.now() };

package/src/config.ts

@@ -0,0 +1,113 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { piDataDir } from "./paths";
+
+export const CONFIG_FILE_NAME = "pi-fff.json";
+export const VALID_MODES = ["tools-and-ui", "tools-only", "override"] as const;
+
+export type FffMode = (typeof VALID_MODES)[number];
+
+export interface FffConfig {
+  $schema?: string;
+  mode?: FffMode;
+  frecencyDbPath?: string;
+  historyDbPath?: string;
+  enableFsRootScanning?: boolean;
+  enableHomeDirScanning?: boolean;
+  warnOnHomeDirScan?: boolean;
+  followSymlinks?: boolean;
+}
+
+const CONFIG_KEYS = new Set<keyof FffConfig>([
+  "$schema",
+  "mode",
+  "frecencyDbPath",
+  "historyDbPath",
+  "enableFsRootScanning",
+  "enableHomeDirScanning",
+  "warnOnHomeDirScan",
+  "followSymlinks",
+]);
+
+export function loadConfig(agentDir = piDataDir()): FffConfig {
+  const configPath = join(agentDir, CONFIG_FILE_NAME);
+  let contents: string;
+
+  try {
+    contents = readFileSync(configPath, "utf8");
+  } catch (error: unknown) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return {};
+    throw new Error(
+      `Could not read pi-fff config at ${configPath}: ${errorMessage(error)}`,
+    );
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(contents);
+  } catch (error: unknown) {
+    throw invalidConfig(configPath, `not valid JSON (${errorMessage(error)})`);
+  }
+
+  if (!isRecord(parsed)) {
+    throw invalidConfig(configPath, "expected a JSON object");
+  }
+
+  for (const key of Object.keys(parsed)) {
+    if (!CONFIG_KEYS.has(key as keyof FffConfig)) {
+      throw invalidConfig(configPath, `unknown option "${key}"`);
+    }
+  }
+
+  if (parsed.mode !== undefined && !VALID_MODES.includes(parsed.mode as FffMode)) {
+    throw invalidConfig(configPath, `"mode" must be one of ${VALID_MODES.join(", ")}`);
+  }
+
+  validateString(configPath, parsed, "$schema");
+  validateString(configPath, parsed, "frecencyDbPath");
+  validateString(configPath, parsed, "historyDbPath");
+  validateBoolean(configPath, parsed, "enableFsRootScanning");
+  validateBoolean(configPath, parsed, "enableHomeDirScanning");
+  validateBoolean(configPath, parsed, "warnOnHomeDirScan");
+  validateBoolean(configPath, parsed, "followSymlinks");
+
+  return parsed as FffConfig;
+}
+
+function invalidConfig(configPath: string, reason: string): Error {
+  return new Error(`Invalid pi-fff config at ${configPath}: ${reason}`);
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function validateString(
+  configPath: string,
+  config: Record<string, unknown>,
+  key: "$schema" | "frecencyDbPath" | "historyDbPath",
+): void {
+  const value = config[key];
+  if (value !== undefined && (typeof value !== "string" || value.length === 0)) {
+    throw invalidConfig(configPath, `"${key}" must be a non-empty string`);
+  }
+}
+
+function validateBoolean(
+  configPath: string,
+  config: Record<string, unknown>,
+  key:
+    | "enableFsRootScanning"
+    | "enableHomeDirScanning"
+    | "warnOnHomeDirScan"
+    | "followSymlinks",
+): void {
+  const value = config[key];
+  if (value !== undefined && typeof value !== "boolean") {
+    throw invalidConfig(configPath, `"${key}" must be a boolean`);
+  }
+}

package/src/file-picker.ts

@@ -5,6 +5,7 @@ export interface PickerOptions {
   basePath: string;
   enableHomeDirScanning?: boolean;
   enableFsRootScanning?: boolean;
+  followSymlinks?: boolean;
 }
 
 /** Opens every picker in this pi process — the cwd picker and the aux pickers —

package/src/index.ts

@@ -6,7 +6,11 @@
  */
 
 import nodePath from "node:path";
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
 import {
   type AutocompleteItem,
   type AutocompleteProvider,
@@ -20,8 +24,9 @@ import type {
   MixedItem,
   SearchResult,
 } from "@ff-labs/fff-node";
-import { Type } from "@sinclair/typebox";
+import { Type, type TSchema } from "@sinclair/typebox";
 import { AuxFinderPool, routePathConstraint } from "./aux-finders";
+import { type FffMode, loadConfig, VALID_MODES } from "./config";
 import { FilePickerFactory } from "./file-picker";
 import { isHomeDir, resolveDbPaths } from "./paths";
 import { buildQuery } from "./query";
@@ -35,6 +40,10 @@ export { SCAN_TIMEOUT_MS } from "./sdk";
 const DEFAULT_GREP_LIMIT = 20;
 const DEFAULT_FIND_LIMIT = 30;
 const GREP_PAGE_SIZE_MAX = 50;
+// Per-file match cap. Must stay decoupled from pageSize: grep cursors advance by
+// file offset, so clamping this to pageSize makes same-file overflow unreachable
+// on later pages (#825). Matches the engine default.
+const GREP_MAX_MATCHES_PER_FILE = 200;
 const GREP_CONTEXT_MAX = 20;
 const GREP_MAX_LINE_LENGTH = 500;
 const MENTION_MAX_RESULTS = 20;
@@ -45,11 +54,8 @@ const GREP_TIME_BUDGET_MS = 10_000;
 const HOME_SCAN_STATUS_KEY = "fff";
 const HOME_SCAN_POLL_MS = 1_000;
 const HOME_SCAN_DISABLE_HINT =
-  "You can prevent home dir indexing with --fff-enable-home-scan=false (or FFF_ENABLE_HOME_SCAN=0).";
-
-type FffMode = "tools-and-ui" | "tools-only" | "override";
-
-const VALID_MODES: FffMode[] = ["tools-and-ui", "tools-only", "override"];
+  'You can prevent home dir indexing with --fff-enable-home-scan=false, FFF_ENABLE_HOME_SCAN=0, or "enableHomeDirScanning": false in pi-fff.json. ' +
+  'To keep indexing but silence this warning use --fff-warn-home-scan=false, FFF_WARN_HOME_SCAN=0, or "warnOnHomeDirScan": false in pi-fff.json.';
 
 interface ToolNames {
   grep: string;
@@ -299,52 +305,113 @@ export default function fffExtension(pi: ExtensionAPI) {
   let finderPromise: Promise<FileFinderApi> | null = null;
   let activeCwd = process.cwd();
 
-  // Mode resolution: flag > env > default
-  let currentMode: FffMode =
-    (pi.getFlag("fff-mode") as FffMode) ??
-    (process.env.PI_FFF_MODE as FffMode) ??
-    "tools-and-ui";
-
-  const toolNames = resolveToolNames(currentMode);
-
-  // DB path resolution: flag > env > existing fff.nvim db > pi-local data dir.
-  const resolvedDbPaths = resolveDbPaths({
-    frecency:
-      (pi.getFlag("fff-frecency-db") as string | undefined) ??
-      process.env.FFF_FRECENCY_DB,
-    history:
-      (pi.getFlag("fff-history-db") as string | undefined) ?? process.env.FFF_HISTORY_DB,
-  });
+  const config = loadConfig();
+
+  // All startup options use the same flag > env > file > fallback order.
+  function getConfigValue<T>(
+    flagName: string,
+    envName: string,
+    fileValue: T | undefined,
+    fallback: T,
+    parse: (value: unknown) => T | undefined = (value) => value as T,
+  ): T {
+    const flagValue = pi.getFlag(flagName);
+    if (flagValue !== undefined) {
+      const value = parse(flagValue);
+      if (value !== undefined) return value;
+    }
 
-  // flag (boolean) > env ("1"/"true", or "0"/"false") > default.
-  function resolveBoolOpt(flagName: string, envName: string, fallback = false): boolean {
-    const flag = pi.getFlag(flagName);
-    if (typeof flag === "boolean") return flag;
-    if (typeof flag === "string") return flag === "true" || flag === "1";
-    const env = process.env[envName];
-    if (env === "1" || env === "true") return true;
-    if (env === "0" || env === "false") return false;
-    return fallback;
+    const envValue = process.env[envName];
+    if (envValue !== undefined) {
+      const value = parse(envValue);
+      if (value !== undefined) return value;
+    }
+
+    return fileValue ?? fallback;
   }
-  // Root scanning opt-in: FFF refuses to init at / unless this is set.
-  const enableFsRootScanning = resolveBoolOpt(
-    "fff-enable-root-scan",
-    "FFF_ENABLE_ROOT_SCAN",
-  );
-  // Home dir scanning is on by default (launching pi from $HOME is a normal
-  // flow), but configurable so users with huge $HOME trees can opt out.
-  const enableHomeDirScanning = resolveBoolOpt(
-    "fff-enable-home-scan",
-    "FFF_ENABLE_HOME_SCAN",
-    true,
-  );
 
-  function getMode(): FffMode {
-    return currentMode;
+  function parseBoolean(value: unknown): boolean | undefined {
+    if (typeof value === "boolean") return value;
+    if (value === "1" || value === "true") return true;
+    if (value === "0" || value === "false") return false;
+    return undefined;
+  }
+
+  function parseMode(value: unknown): FffMode | undefined {
+    return typeof value === "string" && VALID_MODES.includes(value as FffMode)
+      ? (value as FffMode)
+      : undefined;
   }
 
+  let currentMode: FffMode = "tools-and-ui";
+  let toolNames = resolveToolNames(currentMode);
+  let resolvedDbPaths: ReturnType<typeof resolveDbPaths>;
+  let enableFsRootScanning = false;
+  let enableHomeDirScanning = true;
+  let warnOnHomeDirScan = true;
+  let followSymlinks = true;
+
   function setMode(mode: FffMode): void {
     currentMode = mode;
+    toolNames = resolveToolNames(mode);
+  }
+
+  function resolveStartupConfig(): void {
+    setMode(
+      getConfigValue("fff-mode", "PI_FFF_MODE", config.mode, "tools-and-ui", parseMode),
+    );
+    resolvedDbPaths = resolveDbPaths({
+      frecency: getConfigValue(
+        "fff-frecency-db",
+        "FFF_FRECENCY_DB",
+        config.frecencyDbPath,
+        undefined,
+      ),
+      history: getConfigValue(
+        "fff-history-db",
+        "FFF_HISTORY_DB",
+        config.historyDbPath,
+        undefined,
+      ),
+    });
+
+    // Root scanning opt-in: FFF refuses to init at / unless this is set.
+    enableFsRootScanning = getConfigValue(
+      "fff-enable-root-scan",
+      "FFF_ENABLE_ROOT_SCAN",
+      config.enableFsRootScanning,
+      false,
+      parseBoolean,
+    );
+    // Home dir scanning is on by default (launching pi from $HOME is a normal
+    // flow), but configurable so users with huge $HOME trees can opt out.
+    enableHomeDirScanning = getConfigValue(
+      "fff-enable-home-scan",
+      "FFF_ENABLE_HOME_SCAN",
+      config.enableHomeDirScanning,
+      true,
+      parseBoolean,
+    );
+    warnOnHomeDirScan = getConfigValue(
+      "fff-warn-home-scan",
+      "FFF_WARN_HOME_SCAN",
+      config.warnOnHomeDirScan,
+      true,
+      parseBoolean,
+    );
+    // On by default: worktree and stow layouts reach their files through links,
+    // and an agent silently missing them is worse than the extra walk.
+    followSymlinks = getConfigValue(
+      "fff-follow-symlinks",
+      "FFF_FOLLOW_SYMLINKS",
+      config.followSymlinks,
+      true,
+      parseBoolean,
+    );
+  }
+
+  function getMode(): FffMode {
+    return currentMode;
   }
 
   function shouldEnableMentions(): boolean {
@@ -362,28 +429,36 @@ export default function fffExtension(pi: ExtensionAPI) {
   let homeScanTimer: ReturnType<typeof setInterval> | null = null;
 
   function warnHomeDirScan(root: string): void {
+    if (!warnOnHomeDirScan) return;
     uiCtx?.ui.notify(
       `(fff): Your cwd (${root}) is too large. Indexing will take additional time and resources.\n${HOME_SCAN_DISABLE_HINT}`,
       "warning",
     );
   }
 
-  const pickers = new FilePickerFactory({
-    frecencyDbPath: resolvedDbPaths.frecency,
-    historyDbPath: resolvedDbPaths.history,
-    onDbFailure: (error) =>
-      uiCtx?.ui.notify(
-        `(fff): Failed to open frecency/history database (${error}). Continuing without frecency persistence.`,
-        "error",
-      ),
-  });
+  let pickers: FilePickerFactory | null = null;
+  let auxPool: AuxFinderPool | null = null;
 
-  const auxPool = new AuxFinderPool({
-    enableFsRootScanning,
-    enableHomeDirScanning,
-    onHomeDirScan: warnHomeDirScan,
-    pickers,
-  });
+  function initializeFinderFactories(): void {
+    if (pickers) return;
+
+    pickers = new FilePickerFactory({
+      frecencyDbPath: resolvedDbPaths.frecency,
+      historyDbPath: resolvedDbPaths.history,
+      onDbFailure: (error) =>
+        uiCtx?.ui.notify(
+          `(fff): Failed to open frecency/history database (${error}). Continuing without frecency persistence.`,
+          "error",
+        ),
+    });
+    auxPool = new AuxFinderPool({
+      enableFsRootScanning,
+      enableHomeDirScanning,
+      followSymlinks,
+      onHomeDirScan: warnHomeDirScan,
+      pickers,
+    });
+  }
 
   // in case cwd changes we need to figure this out
   function ensureFinder(cwd: string): Promise<FileFinderApi> {
@@ -401,10 +476,12 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       // if the dbs can't be opened the factory falls back to a db-less picker,
       // e.g. when some other process corrupts the lock
+      if (!pickers) throw new Error("FFF picker factory is not initialized");
       mainFinder = await pickers.create({
         basePath: cwd,
         enableHomeDirScanning,
         enableFsRootScanning,
+        followSymlinks,
       });
       finderCwd = cwd;
       return mainFinder;
@@ -455,9 +532,9 @@ export default function fffExtension(pi: ExtensionAPI) {
       finderCwd = null;
     }
 
-    if (auxPool) {
-      auxPool.destroy();
-    }
+    auxPool?.destroy();
+    auxPool = null;
+    pickers = null;
   }
 
   async function resolveFinderForPath(
@@ -467,6 +544,7 @@ export default function fffExtension(pi: ExtensionAPI) {
   ): Promise<{ finder: FileFinderApi; query: string; root: string } | null> {
     const route = routePathConstraint(pathParam, activeCwd);
     if (!route) return null;
+    if (!auxPool) throw new Error("FFF auxiliary finder pool is not initialized");
     const aux = await auxPool.acquire(route.root);
     // A broader covering picker may have been reused; rebase the suffix so the
     // constraint stays relative to the picker's actual root.
@@ -547,6 +625,45 @@ export default function fffExtension(pi: ExtensionAPI) {
     });
   }
 
+  type PendingToolDefinition<
+    TParams extends TSchema,
+    TDetails = unknown,
+    TState = any,
+  > = Omit<
+    ToolDefinition<TParams, TDetails, TState>,
+    "name" | "label" | "promptGuidelines"
+  > & {
+    promptGuidelines?: (names: ToolNames) => string[];
+  };
+
+  const pendingTools: (() => string)[] = [];
+  let toolsRegistered = false;
+
+  function queueTool<TParams extends TSchema, TDetails = unknown, TState = any>(
+    resolveName: () => string,
+    definition: PendingToolDefinition<TParams, TDetails, TState>,
+  ): void {
+    pendingTools.push(() => {
+      const { promptGuidelines, ...tool } = definition;
+      const resolvedName = resolveName();
+      pi.registerTool({
+        ...tool,
+        name: resolvedName,
+        label: resolvedName,
+        promptGuidelines: promptGuidelines?.(toolNames),
+      });
+      return resolvedName;
+    });
+  }
+
+  function registerPendingTools(): void {
+    if (toolsRegistered) return;
+
+    const registeredNames = pendingTools.map((register) => register());
+    pi.setActiveTools([...new Set([...pi.getActiveTools(), ...registeredNames])]);
+    toolsRegistered = true;
+  }
+
   // --- Flags / lifecycle ---
 
   pi.registerFlag("fff-mode", {
@@ -576,34 +693,60 @@ export default function fffExtension(pi: ExtensionAPI) {
     type: "boolean",
   });
 
-  pi.on("session_start", async (_event, ctx) => {
-    try {
-      activeCwd = ctx.cwd;
-      uiCtx = ctx as unknown as typeof uiCtx;
-
-      // Restore persisted mode from session entries. This handles session
-      // resume after process restart where env vars are lost, and ensures
-      // the env var is set for the next /reload in the same session.
-      const entries = ctx.sessionManager?.getEntries();
-      if (entries) {
-        const modeEntry = [...entries]
-          .reverse()
-          .find(
-            (e: { type: string; customType?: string }) =>
-              e.type === "custom" && e.customType === "fff-mode",
-          );
-        if (
-          modeEntry &&
-          typeof (modeEntry as any).data?.mode === "string" &&
-          VALID_MODES.includes((modeEntry as any).data.mode as FffMode)
-        ) {
-          const restored = (modeEntry as any).data.mode as FffMode;
-          if (restored !== currentMode) {
-            currentMode = restored;
-          }
-        }
+  pi.registerFlag("fff-follow-symlinks", {
+    description:
+      "Index through directory symlinks, e.g. a git worktree or stow layout (default true; disable with --fff-follow-symlinks=false or FFF_FOLLOW_SYMLINKS=0)",
+    type: "boolean",
+  });
+
+  pi.registerFlag("fff-warn-home-scan", {
+    description:
+      "Warn when indexing $HOME (default true; silence with --fff-warn-home-scan=false or FFF_WARN_HOME_SCAN=0)",
+    type: "boolean",
+  });
+
+  function reportInitFailure(ctx: ExtensionContext, error: unknown): void {
+    ctx.ui.notify(
+      `FFF init failed: ${error instanceof Error ? error.message : String(error)}`,
+      "error",
+    );
+  }
+
+  function prepareSession(ctx: ExtensionContext): void {
+    activeCwd = ctx.cwd;
+    uiCtx = ctx;
+    if (toolsRegistered) return;
+
+    // Pi populates extension flag values after loading extensions.
+    resolveStartupConfig();
+
+    // Restore persisted mode before registering tools so a saved override
+    // can safely change their names after /reload or session resume.
+    const entries = ctx.sessionManager?.getEntries();
+    if (entries) {
+      const modeEntry = [...entries]
+        .reverse()
+        .find(
+          (e: { type: string; customType?: string }) =>
+            e.type === "custom" && e.customType === "fff-mode",
+        );
+      if (
+        modeEntry &&
+        typeof (modeEntry as any).data?.mode === "string" &&
+        VALID_MODES.includes((modeEntry as any).data.mode as FffMode)
+      ) {
+        const restored = (modeEntry as any).data.mode as FffMode;
+        if (restored !== currentMode) setMode(restored);
       }
+    }
+
+    initializeFinderFactories();
+    registerPendingTools();
+  }
 
+  pi.on("session_start", async (_event, ctx) => {
+    try {
+      prepareSession(ctx);
       registerAutocompleteProvider(ctx);
       await ensureFinder(activeCwd);
 
@@ -621,11 +764,19 @@ export default function fffExtension(pi: ExtensionAPI) {
       // waitForScan() also resolves on timeout, so poll until the scan really
       // settles before clearing the footer.
       if (atHome) trackHomeScanStatus();
-    } catch (e: unknown) {
-      ctx.ui.notify(
-        `FFF init failed: ${e instanceof Error ? e.message : String(e)}`,
-        "error",
-      );
+    } catch (error: unknown) {
+      reportInitFailure(ctx, error);
+    }
+  });
+
+  // SDK callers can prompt without binding session_start. Prepare on the first
+  // agent turn as a fallback so the tools still reach that turn's tool set.
+  pi.on("before_agent_start", (_event, ctx) => {
+    if (toolsRegistered) return;
+    try {
+      prepareSession(ctx);
+    } catch (error: unknown) {
+      reportInitFailure(ctx, error);
     }
   });
 
@@ -701,16 +852,14 @@ export default function fffExtension(pi: ExtensionAPI) {
     ),
   });
 
-  pi.registerTool({
-    name: toolNames.grep,
-    label: toolNames.grep,
+  queueTool(() => toolNames.grep, {
     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: [
-      `${toolNames.grep}: prefer bare identifiers as patterns. Literal queries are most efficient.`,
-      `${toolNames.grep}: use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').`,
-      `${toolNames.grep}: caseSensitive: true when you need exact case (smart-case otherwise).`,
-      `${toolNames.grep}: after 1-2 greps, read the top match instead of more greps.`,
+    promptGuidelines: (names) => [
+      `${names.grep}: prefer bare identifiers as patterns. Literal queries are most efficient.`,
+      `${names.grep}: use path for include ('src/', '*.ts') and exclude for noise ('test/,*.min.js').`,
+      `${names.grep}: caseSensitive: true when you need exact case (smart-case otherwise).`,
+      `${names.grep}: after 1-2 greps, read the top match instead of more greps.`,
     ],
     parameters: grepSchema,
 
@@ -722,8 +871,9 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       const picker = aux ? aux.finder : await ensureFinder(activeCwd);
       const effectiveLimit = Math.max(1, params.limit ?? DEFAULT_GREP_LIMIT);
-      // pageSize caps TOTAL matches across all files; maxMatchesPerFile alone
-      // only caps per-file, so limit=5 could still return a full SDK page.
+      // pageSize caps TOTAL matches across all files (soft cap: the current file
+      // is always finished first). maxMatchesPerFile stays decoupled at the engine
+      // default so same-file overflow remains reachable via cursor (#825).
       const pageSize = Math.min(effectiveLimit, GREP_PAGE_SIZE_MAX);
       const context = clampContext(params.context);
       const query = aux
@@ -773,7 +923,7 @@ export default function fffExtension(pi: ExtensionAPI) {
       const grepResult = picker.grep(query, {
         mode,
         smartCase,
-        maxMatchesPerFile: pageSize,
+        maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
         pageSize,
         cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
         beforeContext: context,
@@ -806,7 +956,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         const fuzzy = picker.grep(fuzzyQuery, {
           mode: "fuzzy",
           smartCase,
-          maxMatchesPerFile: pageSize,
+          maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
           pageSize,
           cursor: null,
           beforeContext: 0,
@@ -892,18 +1042,16 @@ export default function fffExtension(pi: ExtensionAPI) {
     ),
   });
 
-  pi.registerTool({
-    name: toolNames.find,
-    label: toolNames.find,
+  queueTool(() => toolNames.find, {
     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: [
-      `${toolNames.find}: matches the WHOLE path, not just the filename — \`profile\` hits \`chrome/browser/profiles/x.cc\` too.`,
-      `${toolNames.find}: keep queries to 1-2 terms; extra words narrow.`,
-      `${toolNames.find}: use for paths, not content. Use ${toolNames.grep} for content.`,
-      `${toolNames.find}: 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.`,
-      `${toolNames.find}: to list everything inside a directory, pass path: 'dir/**' with an empty or wildcard pattern instead of using pattern alone.`,
-      `${toolNames.find}: use exclude: 'test/,*.min.js' to cut noise in large repos.`,
+    promptGuidelines: (names) => [
+      `${names.find}: matches the WHOLE path, not just the filename — \`profile\` hits \`chrome/browser/profiles/x.cc\` too.`,
+      `${names.find}: keep queries to 1-2 terms; extra words narrow.`,
+      `${names.find}: use for paths, not content. Use ${names.grep} for content.`,
+      `${names.find}: 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.`,
+      `${names.find}: to list everything inside a directory, pass path: 'dir/**' with an empty or wildcard pattern instead of using pattern alone.`,
+      `${names.find}: use exclude: 'test/,*.min.js' to cut noise in large repos.`,
     ],
     parameters: findSchema,
 
@@ -912,10 +1060,12 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       // if resumed we use the same picker as before
       const resumed = params.cursor ? getFindCursor(params.cursor) : undefined;
+      const pool = auxPool;
+      if (!pool) throw new Error("FFF auxiliary finder pool is not initialized");
       const aux = resumed
         ? resumed.auxRoot
           ? {
-              finder: (await auxPool.acquire(resumed.auxRoot, { exact: true })).finder,
+              finder: (await pool.acquire(resumed.auxRoot, { exact: true })).finder,
               root: resumed.auxRoot,
             }
           : null
@@ -1032,16 +1182,14 @@ export default function fffExtension(pi: ExtensionAPI) {
       cursor: Type.Optional(Type.String({ description: "Pagination cursor" })),
     });
 
-    pi.registerTool({
-      name: toolNames.multiGrep,
-      label: toolNames.multiGrep,
+    queueTool(() => toolNames.multiGrep, {
       description:
         "Search file contents for ANY of multiple literal patterns (OR, SIMD Aho-Corasick). Faster than regex alternation.",
       promptSnippet: "Multi-pattern OR content search",
-      promptGuidelines: [
-        `${toolNames.multiGrep}: use when searching for several identifiers at once.`,
-        `${toolNames.multiGrep}: include all naming-convention variants (snake/camel/Pascal).`,
-        `${toolNames.multiGrep}: patterns are literal. Use constraints for file filters.`,
+      promptGuidelines: (names) => [
+        `${names.multiGrep}: use when searching for several identifiers at once.`,
+        `${names.multiGrep}: include all naming-convention variants (snake/camel/Pascal).`,
+        `${names.multiGrep}: patterns are literal. Use constraints for file filters.`,
       ],
       parameters: multiGrepSchema,
 
@@ -1058,7 +1206,7 @@ export default function fffExtension(pi: ExtensionAPI) {
         const grepResult = f.multiGrep({
           patterns: params.patterns,
           constraints: params.constraints,
-          maxMatchesPerFile: pageSize,
+          maxMatchesPerFile: GREP_MAX_MATCHES_PER_FILE,
           pageSize,
           smartCase: true,
           cursor: (params.cursor ? getCursor(params.cursor) : null) ?? null,
@@ -1116,6 +1264,15 @@ export default function fffExtension(pi: ExtensionAPI) {
   pi.registerCommand("fff-mode", {
     description: "Show or set FFF mode: /fff-mode [tools-and-ui | tools-only | override]",
     handler: async (args, ctx) => {
+      if (!toolsRegistered) {
+        try {
+          prepareSession(ctx);
+        } catch (error: unknown) {
+          reportInitFailure(ctx, error);
+          return;
+        }
+      }
+
       const arg = (args || "").trim();
 
       // No args - show current mode
@@ -1134,15 +1291,18 @@ export default function fffExtension(pi: ExtensionAPI) {
 
       const newMode = arg as FffMode;
       const oldMode = getMode();
-      setMode(newMode);
-
       pi.appendEntry("fff-mode", { mode: newMode });
 
-      const note =
-        (oldMode === "override") !== (newMode === "override")
-          ? " (tool name change requires /reload)"
-          : "";
-      ctx.ui.notify(`Mode changed: '${oldMode}' → '${newMode}'${note}`, "info");
+      if ((oldMode === "override") !== (newMode === "override")) {
+        ctx.ui.notify(
+          `Mode '${newMode}' saved. Run /reload to apply the tool name change.`,
+          "info",
+        );
+        return;
+      }
+
+      setMode(newMode);
+      ctx.ui.notify(`Mode changed: '${oldMode}' → '${newMode}'`, "info");
     },
   });
 

package/src/paths.ts

@@ -52,7 +52,7 @@ function nvimDataDir(): string {
   return path.join(HOME_DIR, ".local", "share", "nvim");
 }
 
-function piDataDir(): string {
+export function piDataDir(): string {
   return process.env.PI_CODING_AGENT_DIR ?? path.join(HOME_DIR, ".pi", "agent");
 }