pi-blackhole 0.2.3 → 0.3.1

package/index.ts

@@ -18,6 +18,51 @@ import { registerRecallTool } from "./src/tools/recall";
 import { Runtime } from "./src/om/runtime.js";
 
 export default (pi: ExtensionAPI) => {
+	// ── Bridge: capture custom provider stream functions for jiti-loaded agents ──
+	// pi-blackhole's consolidation agents are loaded via jiti with moduleCache: false,
+	// which creates a separate pi-ai instance whose apiProviderRegistry lacks custom
+	// providers (e.g., claude-bridge registered by other extensions). This bridge stores
+	// streamSimple functions in a Symbol.for() global so agents can access them without
+	// going through pi-ai's registry.
+	//
+	// There are two mechanisms:
+	// 1. Wrap pi.registerProvider to capture streamSimple at registration time.
+	//    This handles providers registered AFTER our factory runs.
+	// 2. On agent_start, scan modelRegistry.registeredProviders for any providers
+	//    that registered BEFORE our factory ran (different extension load order).
+	const PROVIDER_STREAMS_KEY = Symbol.for("pi-blackhole:provider-streams");
+	const providerStreams: Map<string, Function> = (globalThis as any)[PROVIDER_STREAMS_KEY] ??= new Map();
+
+	const origRegisterProvider = pi.registerProvider.bind(pi);
+	pi.registerProvider = (name: string, config: any) => {
+		if (config && config.streamSimple && config.api) {
+			providerStreams.set(config.api, config.streamSimple);
+		}
+		origRegisterProvider(name, config);
+	};
+
+	// Fallback: on agent_start, capture providers that registered before our wrapper
+	// (handles the case where pi-blackhole loads after another provider extension).
+	// Uses a dedicated flag instead of checking providerStreams.size so the scan
+	// always runs once even if the wrapper already captured some providers.
+	let hasScannedFallback = false;
+	pi.on("agent_start", (_event: unknown, ctx: any) => {
+		if (hasScannedFallback) return;
+		hasScannedFallback = true
+		// modelRegistry.registeredProviders is declared private in TypeScript but is a
+		// regular JS class field at runtime. We access it via bracket notation for
+		// future-proofing against potential #private migration.
+		const registry = (ctx as any)?.modelRegistry;
+		const registered: Map<string, any> | undefined = registry?.["registeredProviders"];
+		if (registered && typeof registered.forEach === "function") {
+			registered.forEach((config: any, _name: string) => {
+				if (config && config.streamSimple && config.api && !providerStreams.has(config.api)) {
+					providerStreams.set(config.api, config.streamSimple);
+				}
+			});
+		}
+	});
+
 	scaffoldSettings();
 
 	const omRuntime = new Runtime();

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "pi-blackhole",
-  "version": "0.2.3",
+  "version": "0.3.1",
+  "packageManager": "pnpm@11.2.2",
   "description": "Unified compaction + observational memory extension for Pi — compresses conversation context while preserving durable observations and reflections",
   "license": "MIT",
   "main": "index.ts",
@@ -14,7 +15,8 @@
     "example-config.json"
   ],
   "scripts": {
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "lint": "eslint src/"
   },
   "keywords": [
     "pi-package",
@@ -53,8 +55,13 @@
     "@earendil-works/pi-ai": "0.75.4",
     "@earendil-works/pi-coding-agent": "0.75.4",
     "@earendil-works/pi-tui": "0.75.5",
-    "typebox": "^1.1.38",
-    "typescript": "^5.7.3",
-    "vitest": "^4.1.7"
+    "@typescript-eslint/eslint-plugin": "8.60.0",
+    "@typescript-eslint/parser": "8.60.0",
+    "eslint": "9.39.4",
+    "husky": "9.1.7",
+    "lint-staged": "15.5.2",
+    "typebox": "1.1.38",
+    "typescript": "5.9.3",
+    "vitest": "4.1.7"
   }
 }

package/src/commands/pi-vcc.ts

@@ -35,19 +35,29 @@ export const registerPiVccCommand = (pi: ExtensionAPI, runtime: Runtime) => {
 			if (trimmed === "om-off") {
 				const saved = saveUnifiedConfig({ memory: false });
 				runtime.config.memory = false;
-				ctx.ui.notify(
-					saved ? "Observational memory disabled. Use /blackhole om-on to re-enable." : "Failed to save config.",
-					"info",
-				);
+				if (saved) {
+					ctx.ui.notify("Observational memory disabled. Use /blackhole om-on to re-enable.", "info");
+				} else {
+					ctx.ui.notify(
+						"Failed to save config — the config file may be read-only (e.g., managed by Nix). " +
+						"Runtime state updated for this session only.",
+						"warning",
+					);
+				}
 				return;
 			}
 			if (trimmed === "om-on") {
 				const saved = saveUnifiedConfig({ memory: true });
 				runtime.config.memory = true;
-				ctx.ui.notify(
-					saved ? "Observational memory enabled." : "Failed to save config.",
-					"info",
-				);
+				if (saved) {
+					ctx.ui.notify("Observational memory enabled.", "info");
+				} else {
+					ctx.ui.notify(
+						"Failed to save config — the config file may be read-only (e.g., managed by Nix). " +
+						"Runtime state updated for this session only.",
+						"warning",
+					);
+				}
 				return;
 			}
 

package/src/commands/vcc-recall.ts

@@ -41,7 +41,7 @@ async function augmentWithObservations(
 export const registerVccRecallCommand = (pi: ExtensionAPI) => {
 	pi.registerCommand("blackhole-recall", {
 		description:
-			"Search session history. Defaults to active lineage; add scope:all for off-lineage branches. Usage: /blackhole-recall <query> [page:N] [scope:all]",
+			"Search session history. Defaults to active lineage. Usage: /blackhole-recall <query> [page:N] [scope:all] [mode:file|transcript]",
 		handler: async (args: string, ctx) => {
 			const sessionFile = ctx.sessionManager.getSessionFile();
 			if (!sessionFile) {
@@ -55,6 +55,7 @@ export const registerVccRecallCommand = (pi: ExtensionAPI) => {
 				parsed.scope === "lineage"
 					? getActiveLineageEntryIds(ctx.sessionManager)
 					: undefined;
+			const mode = parsed.mode;
 
 			if (!parsed.text) {
 				// No query: show recent entries
@@ -87,7 +88,7 @@ export const registerVccRecallCommand = (pi: ExtensionAPI) => {
 			}
 
 			const { rendered, rawMessages } = loadAllMessages(sessionFile, false, lineageEntryIds);
-			const allResults = searchEntries(rendered, rawMessages, query);
+			const allResults = searchEntries(rendered, rawMessages, query, undefined, mode);
 
 			const start = (page - 1) * PAGE_SIZE;
 			const pageResults = allResults.slice(start, start + PAGE_SIZE);

package/src/core/build-sections.ts

@@ -5,7 +5,7 @@
  * Unmodified.
  */
 import type { NormalizedBlock } from "../types";
-import { clip, clipSentence, firstLine, nonEmptyLines } from "./content";
+import { clipSentence, firstLine, nonEmptyLines } from "./content";
 import type { SectionData } from "../sections";
 import { extractGoals } from "../extract/goals";
 import { extractFiles } from "../extract/files";

package/src/core/content.ts

@@ -48,6 +48,76 @@ export const textParts = (content: Message["content"]): string[] => {
 export const textOf = (content: Message["content"]): string =>
   textParts(content).join("\n");
 
+/**
+ * Check if tool call arguments contain content-bearing data.
+ *
+ * A call is content-bearing if it has a path argument AND at least one
+ * large string/array field (content, edits, oldText, newText).
+ * This is a generic heuristic — not dependent on tool names.
+ */
+export const isContentBearing = (args: Record<string, unknown>): boolean => {
+  if (!args || typeof args !== "object") return false;
+  // Must have a path in one of the known keys
+  const hasPath = ["path", "filePath", "file_path", "file"].some((k) => typeof args[k] === "string");
+  if (!hasPath) return false;
+  // Must have at least one content-bearing field
+  if (typeof args.content === "string" && args.content.length > 0) return true;
+  if (Array.isArray(args.edits) && args.edits.length > 0) return true;
+  if (typeof args.oldText === "string" && args.oldText.length > 0 && !Array.isArray(args.edits)) return true;
+  if (typeof args.newText === "string" && args.newText.length > 0 && !Array.isArray(args.edits)) return true;
+  return false;
+};
+
+/**
+ * Extract textual content from tool call arguments (write, edit, hex_edit).
+ *
+ * Looks for content-bearing tool calls (those with a `path` argument and
+ * at least one large string/array field like `content`, `edits`, `oldText`, `newText`).
+ * Each call is capped at `maxBytesPerCall` to avoid inflating the search index.
+ */
+export const toolCallArgsText = (
+  content: Message["content"],
+  maxBytesPerCall = 10_240,
+): string => {
+  if (!content || typeof content === "string") return "";
+  const parts: string[] = [];
+  for (const part of content) {
+    if (!part || typeof part !== "object" || part.type !== "toolCall") continue;
+    const args = part.arguments as Record<string, unknown>;
+    if (!isContentBearing(args)) continue;
+
+    let extracted = "";
+    if (typeof args.content === "string") {
+      extracted += args.content.slice(0, maxBytesPerCall) + "\n";
+    }
+    if (Array.isArray(args.edits)) {
+      for (const edit of args.edits) {
+        if (extracted.length >= maxBytesPerCall) break;
+        if (edit && typeof edit === "object") {
+          if (typeof edit.oldText === "string") {
+            extracted += edit.oldText.slice(0, Math.floor(maxBytesPerCall / 2)) + "\n";
+          }
+          if (extracted.length >= maxBytesPerCall) break;
+          if (typeof edit.newText === "string") {
+            extracted += edit.newText.slice(0, Math.floor(maxBytesPerCall / 2)) + "\n";
+          }
+        }
+      }
+    }
+    if (typeof args.oldText === "string" && !Array.isArray(args.edits)) {
+      extracted += args.oldText.slice(0, maxBytesPerCall) + "\n";
+    }
+    if (typeof args.newText === "string" && !Array.isArray(args.edits)) {
+      extracted += args.newText.slice(0, maxBytesPerCall) + "\n";
+    }
+
+    if (extracted) {
+      parts.push(extracted.slice(0, maxBytesPerCall));
+    }
+  }
+  return parts.join("\n");
+};
+
 /** Extract a snippet of ~`radius` chars around the first match of `term` in `text`. */
 export const snippet = (text: string, term: string, radius = 60): string | null => {
   const idx = text.toLowerCase().indexOf(term.toLowerCase());

package/src/core/drill-down.ts

@@ -0,0 +1,273 @@
+/**
+ * Drill-down: resolve #N:path syntax to tool call file content.
+ *
+ * Phase 3 of recall-progressive-discovery.
+ * Supports: #42:auth.ts (preview), #42:auth.ts:full (full content), #42:file (auto-select).
+ *
+ * Path matching notes:
+ * - The regex uses $ anchor so lazy .+? consumes the full path — spaces, dots, and
+ *   Windows drive-letter colons (C:\) all work correctly.
+ * - One edge case: a file path literally ending in ":full" (e.g. C:\file:full)
+ *   would be misinterpreted as the :full flag. This is extremely unlikely.
+ * - Inline queries like "check #42:auth.ts" are NOT drill-down — the ^ anchor
+ *   requires the entire query to be the drill-down pattern.
+ */
+import { isContentBearing } from "./content.js";
+import { loadAllMessages } from "./load-messages.js";
+
+// ── Types ─────────────────────────────────────────────────────────────────
+
+interface ContentBearingCall {
+  name: string;
+  path: string;
+  content?: string;
+  oldText?: string;
+  newText?: string;
+  edits?: Array<{ oldText?: string; newText?: string }>;
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────
+
+/** Extract the file path from tool call args, checking all known keys. */
+function extractPathFromArgs(args: Record<string, unknown>): string | null {
+  for (const key of ["path", "filePath", "file_path", "file"]) {
+    if (typeof args[key] === "string") return args[key] as string;
+  }
+  return null;
+}
+
+/**
+ * Find content-bearing tool calls that have a `path` argument and at least
+ * one content field (content, edits, oldText, newText).
+ * Uses the shared isContentBearing() heuristic from content.ts.
+ */
+function findContentBearingCalls(content: unknown[]): ContentBearingCall[] {
+  if (!Array.isArray(content)) return [];
+  const results: ContentBearingCall[] = [];
+  for (const part of content) {
+    if (!part || (part as any).type !== "toolCall") continue;
+    const args = (part as any).arguments ?? {};
+    if (!isContentBearing(args)) continue;
+    const path = extractPathFromArgs(args);
+    if (!path) continue;
+    const entry: ContentBearingCall = { name: (part as any).name ?? "", path };
+    if (typeof args.content === "string") entry.content = args.content;
+    if (Array.isArray(args.edits)) {
+      entry.edits = args.edits.filter((e: unknown): e is { oldText?: string; newText?: string } => e !== null && typeof e === "object");
+    }
+    if (typeof args.oldText === "string" && !Array.isArray(args.edits)) entry.oldText = args.oldText;
+    if (typeof args.newText === "string" && !Array.isArray(args.edits)) entry.newText = args.newText;
+    results.push(entry);
+  }
+  return results;
+}
+
+/** Format content for display with optional offset/limit slicing.
+ *
+ * When full=true, shows everything ignoring offset/limit.
+ * When offset/limit given, shows a window with "Lines X-Y (of Z)" header.
+ * When neither, shows preview (first 30 lines) with truncation hint.
+ */
+function formatToolCallContent(
+  tc: ContentBearingCall,
+  entryIndex: number,
+  options?: { full?: boolean; offset?: number; limit?: number },
+): string {
+  let body: string;
+  if (tc.content) {
+    body = tc.content;
+  } else if (tc.edits) {
+    body = tc.edits
+      .map((e, i) => `--- edit ${i + 1} ---\n${e.oldText ?? ""}\n--- becomes ---\n${e.newText ?? ""}`)
+      .join("\n\n");
+  } else if (tc.oldText && tc.newText) {
+    body = `--- old ---\n${tc.oldText}\n--- new ---\n${tc.newText}`;
+  } else {
+    body = "(no file content found in tool call arguments)";
+  }
+
+  const full = options?.full ?? false;
+  const offset = options?.offset;
+  const limit = options?.limit;
+  const allLines = body.split("\n");
+  const totalLines = allLines.length;
+  const previewLimit = 30;
+  const MAX_FULL_BYTES = 50 * 1024;
+
+  if (full) {
+    // Full content: capped at 50KB
+    if (Buffer.byteLength(body, "utf8") > MAX_FULL_BYTES) {
+      const truncated = body.slice(0, MAX_FULL_BYTES);
+      return `File: ${tc.path}
+Tool: ${tc.name}
+
+${truncated}
+
+... (${Buffer.byteLength(body, "utf8") - MAX_FULL_BYTES} more bytes — file exceeds 50KB display limit. Use #${entryIndex}:${tc.path}:${previewLimit} for next page.)`;
+    }
+    return `File: ${tc.path}
+Tool: ${tc.name}
+
+${body}`;
+  }
+
+  if (offset !== undefined) {
+    // Offset-based window: show slice
+    const startLine = Math.max(0, offset);
+    const maxLines = limit ?? 30;
+    const endLine = Math.min(startLine + maxLines, totalLines);
+    const visible = allLines.slice(startLine, endLine);
+    const displayStart = startLine + 1; // 1-indexed for user display
+
+    if (visible.length === 0) {
+      return `Offset ${startLine} is beyond file length ${totalLines}. Use #${entryIndex}:${tc.path} for the first ${previewLimit} lines.`;
+    }
+
+    let result = `File: ${tc.path}
+Tool: ${tc.name}
+Lines ${displayStart}-${endLine} (of ${totalLines}):
+
+`;
+    result += visible.join("\n");
+
+    if (endLine < totalLines) {
+      result += `\n\n--- Use #${entryIndex}:${tc.path}:${endLine} or #${entryIndex}:${tc.path}:${endLine}:${maxLines} for next ${maxLines} lines, #${entryIndex}:${tc.path}:full for complete ---`;
+    } else if (offset > 0) {
+      result += `\n\n(End of file)`;
+    }
+
+    return result;
+  }
+
+  // Default preview mode: first ${previewLimit} lines
+  if (totalLines > previewLimit) {
+    const preview = allLines.slice(0, previewLimit).join("\n");
+    return `File: ${tc.path}
+Tool: ${tc.name}
+
+${preview}
+
+...(${totalLines - previewLimit} more lines — use #${entryIndex}:${tc.path}:full for complete content, or #${entryIndex}:${tc.path}:${previewLimit} for next ${previewLimit} lines)`;
+  }
+
+  return `File: ${tc.path}
+Tool: ${tc.name}
+
+${body}`;
+}
+
+// ── Parse drill-down query ────────────────────────────────────────────────
+
+/**
+ * Pattern: #N:path, #N:path:full, #N:path:offset, or #N:path:offset:limit
+ * Group 1: index number
+ * Group 2: path (consumed lazily, expanded until suffix can match)
+ * Group 3: suffix — "full", a number (offset), or "offset:limit"
+ */
+const DRILLDOWN_PATTERN = /^#(\d+):(.+?)(?::(full|\d+(?::\d+)?))?$/;
+
+/**
+ * Parse a drill-down query like #42:auth.ts or #42:auth.ts:full.
+ * Returns null if the query doesn't match the drill-down pattern.
+ *
+ * Suffixes:
+ *   :full       → full content (no truncation)
+ *   :30         → offset 30 lines, default limit (30)
+ *   :30:20      → offset 30 lines, limit 20 lines
+ *   (none)      → preview first 30 lines
+ */
+export function parseDrillDown(
+  query: string,
+): { index: number; pathPattern: string; full: boolean; offset?: number; limit?: number } | null {
+  const match = query.match(DRILLDOWN_PATTERN);
+  if (!match) return null;
+  const index = parseInt(match[1], 10);
+  const pathPattern = match[2];
+  const suffix = match[3];
+
+  if (suffix === "full") {
+    return { index, pathPattern, full: true, offset: undefined, limit: undefined };
+  }
+
+  if (suffix !== undefined) {
+    // Parse "offset" or "offset:limit"
+    const parts = suffix.split(":");
+    const offset = parseInt(parts[0], 10);
+    const limit = parts[1] !== undefined ? parseInt(parts[1], 10) : undefined;
+    if (!Number.isNaN(offset)) {
+      return { index, pathPattern, full: false, offset, limit };
+    }
+  }
+
+  return { index, pathPattern, full: false, offset: undefined, limit: undefined };
+}
+
+// ── Main export ───────────────────────────────────────────────────────────
+
+/**
+ * Expand a drill-down query (#N:path) to tool call content.
+ *
+ * Offset/limit let you page through file content incrementally (like pi's read tool):
+ *   #42:auth.ts         → first 30 lines (preview)
+ *   #42:auth.ts:full    → all content
+ *   #42:auth.ts:30      → lines 31-60 (default limit 30)
+ *   #42:auth.ts:30:20   → lines 31-50 (custom limit 20)
+ *
+ * @param sessionFile - Path to the JSONL session file
+ * @param entryIndex - The message index (#N)
+ * @param pathPattern - File path substring to match (or "file" keyword)
+ * @param full - If true, return complete content without truncation
+ * @param offset - Line offset (0-indexed) for windowed content
+ * @param limit - Max lines to show (default 30 for windowed, ignored if full=true)
+ * @returns Formatted content string
+ */
+export function expandEntryFile(
+  sessionFile: string,
+  entryIndex: number,
+  pathPattern: string,
+  full = false,
+  offset?: number,
+  limit?: number,
+): string {
+  const { rawMessages } = loadAllMessages(sessionFile, true);
+
+  if (entryIndex < 0 || entryIndex >= rawMessages.length) {
+    return `Entry #${entryIndex} not found in session history.`;
+  }
+
+  const msg = rawMessages[entryIndex];
+  const content = msg.content as unknown[];
+  const calls = findContentBearingCalls(content);
+
+  // Special case: #42:file keyword
+  if (pathPattern === "file") {
+    if (calls.length === 0) {
+      return `No file content found in entry #${entryIndex}.`;
+    }
+    if (calls.length === 1) {
+      return formatToolCallContent(calls[0], entryIndex, { full, offset, limit });
+    }
+    // Multiple content-bearing calls — list them
+    const items = calls.map((tc) => `  [#${entryIndex}:${tc.path}] ${tc.name}(${tc.path})`);
+    return `Entry #${entryIndex} has ${calls.length} file operations:\n${items.join("\n")}\n\nUse #${entryIndex}:path to drill into a specific file.`;
+  }
+
+  const matched = calls.filter((tc) => tc.path.includes(pathPattern));
+
+  if (matched.length === 0) {
+    return `No file content found in entry #${entryIndex} for "${pathPattern}".`;
+  }
+
+  if (matched.length > 1) {
+    // Ambiguous match — list options instead of silently picking the first
+    const items = matched.map(
+      (tc) => `  [#${entryIndex}:${tc.path}] ${tc.name}(${tc.path})`,
+    );
+    return `Entry #${entryIndex} has ${matched.length} file operations matching "${pathPattern}":
+${items.join("\n")}
+
+Use #${entryIndex}:<more-specific-path> to drill into a specific file.`;
+  }
+
+  return formatToolCallContent(matched[0], entryIndex, { full, offset, limit });
+}

package/src/core/format-recall.ts

@@ -1,4 +1,86 @@
-import type { SearchHit } from "./search-entries";
+import type { SearchHit, FileMatch, TouchedFile } from "./search-entries";
+
+// ── Path shortening ───────────────────────────────────────────────────────
+
+const CWD = process.cwd();
+
+/**
+ * Shorten an absolute file path for display:
+ * - If within cwd, return `./relative/path`
+ * - Otherwise, show last 3 path components with `.../` prefix
+ * - Short paths (≤3 components) returned as-is
+ */
+export function shortPath(fullPath: string): string {
+  // Normalize backslashes to forward slashes for cross-platform path handling
+  const normalized = fullPath.replace(/\\/g, "/");
+  const cwdNormalized = CWD.replace(/\\/g, "/");
+  if (normalized.startsWith(cwdNormalized + "/")) {
+    return "." + normalized.slice(cwdNormalized.length);
+  }
+  const parts = normalized.split("/");
+  if (parts.length > 3) {
+    return ".../" + parts.slice(-3).join("/");
+  }
+  return normalized;
+}
+
+// ── File indicator formatting ─────────────────────────────────────────────
+
+/** Render one file indicator line with shortened path. */
+function formatFileMatch(fm: FileMatch, index: number, isQuery: boolean): string {
+  const label = isQuery
+    ? (fm.lineCount === 1 ? "match" : "matches")
+    : (fm.lineCount === 1 ? "line" : "lines");
+  const displayPath = shortPath(fm.path);
+  let line = `  [${fm.toolName}] ${displayPath} — ${fm.lineCount} ${label}    use #${index}:${fm.path}`;
+  if (fm.snippet) {
+    line += `\n    | ${fm.snippet}`;
+  }
+  return line;
+}
+
+// ── Touched file output ───────────────────────────────────────────────────
+
+const TOUCHED_PAGE_SIZE = 5;
+
+/**
+ * Format aggregated "files touched" output.
+ */
+export function formatTouchedOutput(
+  touched: TouchedFile[],
+  page?: number,
+  pageSize?: number,
+): string {
+  if (touched.length === 0) {
+    return "No file operations found in session history.";
+  }
+
+  const ps = pageSize ?? TOUCHED_PAGE_SIZE;
+  const totalPages = Math.ceil(touched.length / ps);
+  const currentPage = Math.max(1, page ?? 1);
+  const start = (currentPage - 1) * ps;
+  const pageFiles = touched.slice(start, start + ps);
+
+  const header = totalPages > 1
+    ? `Page ${currentPage}/${totalPages} (${touched.length} total files)`
+    : `${touched.length} files touched`;
+
+  const lines = pageFiles.map((tf) => {
+    const displayPath = shortPath(tf.path);
+    const indices = tf.entries
+      .map((e) => `#${e.index} (${e.toolName})`)
+      .join(", ");
+    return `  ${displayPath}    ${indices}`;
+  });
+
+  let result = `${header}:\n\n${lines.join("\n")}`;
+
+  if (currentPage < totalPages) {
+    result += `\n\n--- Use page:${currentPage + 1} for more results ---`;
+  }
+
+  return result;
+}
 
 export const formatRecallOutput = (
   entries: SearchHit[],
@@ -18,9 +100,31 @@ export const formatRecallOutput = (
       : `Session history (${entries.length} entries):`;
 
   const lines = entries.map((e) => {
-    const fileSuffix = e.files?.length ? ` files:[${e.files.join(", ")}]` : "";
     const body = query && e.snippet ? e.snippet : e.summary;
-    return `#${e.index} [${e.role}]${fileSuffix} ${body}`;
+    let line = `#${e.index} [${e.role}]`;
+
+    // Entry text on next line if it's long or has fileMatches
+    if (e.fileMatches?.length) {
+      line += `\n  ${body}`;
+      // Only show top 3 file matches
+      const isQuery = Boolean(query);
+      const topFileMatches = e.fileMatches.slice(0, 3);
+      for (const fm of topFileMatches) {
+        line += `\n${formatFileMatch(fm, e.index, isQuery)}`;
+      }
+      if (e.fileMatches.length > 3) {
+        line += `\n  ...(${e.fileMatches.length - 3} more file matches)`;
+      }
+    } else if (e.files?.length) {
+      // Fallback: entries without fileMatches (e.g. expand-only path) still have
+      // the legacy .files array from renderMessage — show it in old format.
+      const fileSuffix = ` files:[${e.files.join(", ")}]`;
+      line += `${fileSuffix} ${body}`;
+    } else {
+      line += ` ${body}`;
+    }
+
+    return line;
   });
 
   return `${header}\n\n${lines.join("\n\n")}`;

package/src/core/load-messages.ts

@@ -34,9 +34,10 @@ export const loadAllMessages = (
 
     const allowed = !allowedEntryIds || allowedEntryIds.has(e.id);
     if (allowed) {
-      rendered.push(renderMessage(e.message, messageIndex, String(e.id), full));
+      const entryId = e.id != null ? String(e.id) : "";
+      rendered.push(renderMessage(e.message, messageIndex, entryId, full));
       rawMessages.push(e.message);
-      entryIds.push(String(e.id));
+      entryIds.push(entryId);
     }
     messageIndex++;
   }

package/src/core/recall-scope.ts

@@ -1,14 +1,25 @@
 export type RecallScope = "lineage" | "all";
+export type RecallMode = "hybrid" | "file" | "transcript" | "touched";
 
 const SCOPE_RE = /\bscope:(lineage|all)\b/i;
+const MODE_RE = /\bmode:(hybrid|file|transcript|touched)\b/i;
+
+const VALID_MODES = new Set(["hybrid", "file", "transcript", "touched"]);
 
 export const normalizeRecallScope = (scope?: unknown): RecallScope =>
   typeof scope === "string" && scope.toLowerCase() === "all" ? "all" : "lineage";
 
-export const parseRecallScope = (text: string): { scope: RecallScope; text: string } => {
-  const match = text.match(SCOPE_RE);
+export const normalizeRecallMode = (mode?: unknown): RecallMode =>
+  typeof mode === "string" && VALID_MODES.has(mode.toLowerCase())
+    ? (mode.toLowerCase() as RecallMode)
+    : "hybrid";
+
+export const parseRecallScope = (text: string): { scope: RecallScope; mode: RecallMode; text: string } => {
+  const scopeMatch = text.match(SCOPE_RE);
+  const modeMatch = text.match(MODE_RE);
   return {
-    scope: normalizeRecallScope(match?.[1]),
-    text: text.replace(SCOPE_RE, "").replace(/\s+/g, " ").trim(),
+    scope: normalizeRecallScope(scopeMatch?.[1]),
+    mode: normalizeRecallMode(modeMatch?.[1]),
+    text: text.replace(SCOPE_RE, "").replace(MODE_RE, "").replace(/\s+/g, " ").trim(),
   };
 };