@diegopetrucci/pi-extensions 0.1.74 → 0.1.78

package/extensions/librarian/index.ts

@@ -1,20 +1,27 @@
 import { randomUUID } from "node:crypto";
 import type { Dirent, Stats } from "node:fs";
+import { realpathSync } from "node:fs";
 import type { FileHandle } from "node:fs/promises";
 import * as fs from "node:fs/promises";
 import * as os from "node:os";
 import * as path from "node:path";
+import { fileURLToPath } from "node:url";
 
-import type { ExtensionAPI, ExtensionContext, ExtensionFactory } from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+  ExtensionFactory,
+} from "@earendil-works/pi-coding-agent";
 import type { Usage } from "@earendil-works/pi-ai";
 import {
-	DefaultResourceLoader,
-	SessionManager,
-	SettingsManager,
-	createAgentSession,
-	getAgentDir,
-	getMarkdownTheme,
+  DefaultResourceLoader,
+  SessionManager,
+  SettingsManager,
+  createAgentSession,
+  getAgentDir,
+  getMarkdownTheme,
 } from "@earendil-works/pi-coding-agent";
+import * as piCodingAgent from "@earendil-works/pi-coding-agent";
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
@@ -41,692 +48,825 @@ type CacheMode = "disabled" | "enabled";
 type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 type ThinkingLevelMap = Partial<Record<ThinkingLevel, unknown | null>>;
 type PiModel = {
-	provider: string;
-	id: string;
-	reasoning?: boolean;
-	thinkingLevelMap?: ThinkingLevelMap;
+  provider: string;
+  id: string;
+  reasoning?: boolean;
+  thinkingLevelMap?: ThinkingLevelMap;
 };
 
 type ModelSelectionContext = {
-	model?: any;
-	modelRegistry: { getAvailable(): any[] | Promise<any[]> };
-	scopedModels?: ReadonlyArray<{ model: any; thinkingLevel?: ThinkingLevel }>;
+  model?: any;
+  modelRegistry: { getAvailable(): any[] | Promise<any[]> };
+  scopedModels?: ReadonlyArray<{ model: any; thinkingLevel?: ThinkingLevel }>;
 };
 
 function modelKey(model: any): string {
-	return `${model.provider}/${model.id}`.toLowerCase();
+  return `${model.provider}/${model.id}`.toLowerCase();
 }
 
 function hasModelScope(ctx: ModelSelectionContext): boolean {
-	return Array.isArray(ctx.scopedModels) && ctx.scopedModels.length > 0;
+  return Array.isArray(ctx.scopedModels) && ctx.scopedModels.length > 0;
 }
 
 function isModelInScope(ctx: ModelSelectionContext, model: any): boolean {
-	if (!hasModelScope(ctx)) return true;
-	const key = modelKey(model);
-	return ctx.scopedModels!.some((entry) => modelKey(entry.model) === key);
+  if (!hasModelScope(ctx)) return true;
+  const key = modelKey(model);
+  return ctx.scopedModels!.some((entry) => modelKey(entry.model) === key);
 }
 
 async function getAutoSelectableModels(ctx: ModelSelectionContext): Promise<any[]> {
-	const available = await ctx.modelRegistry.getAvailable();
-	return hasModelScope(ctx) ? available.filter((model) => isModelInScope(ctx, model)) : available;
+  const available = await ctx.modelRegistry.getAvailable();
+  return hasModelScope(ctx) ? available.filter((model) => isModelInScope(ctx, model)) : available;
 }
 
 type CreateAgentSessionOptions = NonNullable<Parameters<typeof createAgentSession>[0]>;
 
-function getModelRuntimeOption(ctx: { modelRegistry?: unknown }): Pick<CreateAgentSessionOptions, "modelRuntime"> {
-	const modelRuntime = (ctx.modelRegistry as { runtime?: CreateAgentSessionOptions["modelRuntime"] } | undefined)?.runtime;
-	return modelRuntime ? { modelRuntime } : {};
+function getModelRuntimeOption(ctx: {
+  modelRegistry?: unknown;
+}): Pick<CreateAgentSessionOptions, "modelRuntime"> {
+  const modelRuntime = (
+    ctx.modelRegistry as { runtime?: CreateAgentSessionOptions["modelRuntime"] } | undefined
+  )?.runtime;
+  return modelRuntime ? { modelRuntime } : {};
 }
 
 const DEFAULT_CACHE_MODE: CacheMode = "disabled";
 const DEFAULT_THINKING_LEVEL: ThinkingLevel = "low";
 const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+const SUBAGENT_MCP_TOOLS = [
+  "mcp__*",
+  "tool_search",
+  "list_mcp_resources",
+  "list_mcp_resource_templates",
+  "read_mcp_resource",
+];
+
+// Derive project-trust for the isolated subagent session from the host tool context.
+// Fails closed: returns false if the host has not trusted the project, or if the subagent
+// runs in a different directory (e.g. a temp workspace), preventing an untrusted project's
+// .pi/mcp.json from being loaded by the MCP extension.
+function resolveSubagentProjectTrusted(
+  ctx: { cwd: string; isProjectTrusted(): boolean },
+  subagentCwd: string,
+): boolean {
+  // Feature-detected for older Pi hosts that may lack isProjectTrusted.
+  const hostTrusted =
+    typeof (ctx as { isProjectTrusted?: unknown }).isProjectTrusted === "function"
+      ? ctx.isProjectTrusted()
+      : false;
+  if (!hostTrusted) return false;
+  try {
+    return realpathSync(subagentCwd) === realpathSync(ctx.cwd);
+  } catch {
+    return false; // fail closed if realpath resolution fails
+  }
+}
+
+/** Returns true when v is a semver string >=1.0.4 (ignores prerelease; missing/garbage → false). */
+function isMcpCompatibleVersion(v: string | undefined): boolean {
+  if (!v) return false;
+  const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v);
+  if (!m) return false;
+  const major = Number(m[1]),
+    minor = Number(m[2]),
+    patch = Number(m[3]);
+  if (major !== 1) return major > 1;
+  if (minor !== 0) return minor > 0;
+  return patch >= 4;
+}
+
+// Safe runtime access to MCP/tool-search factories — feature-detected for Pi >=0.99.0 hosts.
+// Additionally gated on VERSION >=1.0.4: on older hosts mcp__* allowlist entries are exact-name
+// matches that resolve nothing, so spawning MCP servers provides no benefit.
+function createMcpSubagentFactories(): ExtensionFactory[] {
+  const ns = piCodingAgent as Record<string, unknown>;
+  if (!isMcpCompatibleVersion(ns["VERSION"] as string | undefined)) return [];
+  const factories: ExtensionFactory[] = [];
+  const mcp = ns["createMcpExtension"];
+  const toolSearch = ns["createToolSearchExtension"];
+  if (typeof mcp === "function") factories.push((mcp as () => ExtensionFactory)());
+  if (typeof toolSearch === "function") factories.push((toolSearch as () => ExtensionFactory)());
+  return factories;
+}
+
+// Emit session_shutdown before dispose so MCP closes server connections (no leaked child processes).
+async function disposeSubagentSession(
+  session: { extensionRunner?: unknown; dispose(): void } | undefined,
+): Promise<void> {
+  if (!session) return;
+  try {
+    const runner = session.extensionRunner as
+      | {
+          hasHandlers(n: string): boolean;
+          emit(e: { type: string; reason: string }): Promise<unknown>;
+        }
+      | undefined;
+    if (runner?.hasHandlers("session_shutdown")) {
+      await runner.emit({ type: "session_shutdown", reason: "quit" });
+    }
+  } catch {
+    // Shutdown errors must not prevent dispose.
+  }
+  session.dispose();
+}
 
 const PREFERRED_FAST_MODEL_PATTERNS = [
-	/\bgpt[-_. ]?5\.5(?:[-_. ].*)?\b(?:mini|nano|fast|lite)\b/,
-	/\bgpt[-_. ]?5(?:[-_. ].*)?\b(?:mini|nano|fast|lite)\b/,
-	/\bgpt[-_. ]?4(?:\.1|o)?(?:[-_. ].*)?\b(?:mini|nano)\b/,
-	/\bgemini\b.*\b(?:flash|flash-lite|lite)\b/,
-	/\bclaude\b.*\bhaiku\b/,
-	/\b(?:mistral|codestral)\b.*\b(?:small|mini|lite)\b/,
+  /\bgpt[-_. ]?5\.5(?:[-_. ].*)?\b(?:mini|nano|fast|lite)\b/,
+  /\bgpt[-_. ]?5(?:[-_. ].*)?\b(?:mini|nano|fast|lite)\b/,
+  /\bgpt[-_. ]?4(?:\.1|o)?(?:[-_. ].*)?\b(?:mini|nano)\b/,
+  /\bgemini\b.*\b(?:flash|flash-lite|lite)\b/,
+  /\bclaude\b.*\bhaiku\b/,
+  /\b(?:mistral|codestral)\b.*\b(?:small|mini|lite)\b/,
 ];
 
 const HEAVY_MODEL_PATTERN = /\b(?:opus|pro|ultra|max)\b/;
 
 type ToolCall = {
-	id: string;
-	name: string;
-	args: unknown;
-	startedAt: number;
-	endedAt?: number;
-	isError?: boolean;
+  id: string;
+  name: string;
+  args: unknown;
+  startedAt: number;
+  endedAt?: number;
+  isError?: boolean;
 };
 
 type CacheDetails = {
-	mode: CacheMode;
-	root: string;
-	ttlDays: number;
-	cleanupDeleted: number;
-	cleanupErrors: string[];
-	decisionReason: string;
+  mode: CacheMode;
+  root: string;
+  ttlDays: number;
+  cleanupDeleted: number;
+  cleanupErrors: string[];
+  decisionReason: string;
 };
 
 type LibrarianModelDetails = {
-	modelRef: string;
-	modelId: string;
-	provider: string;
-	thinkingLevel: ThinkingLevel;
-	autoSelected: boolean;
-	selectionReason: string;
+  modelRef: string;
+  modelId: string;
+  provider: string;
+  thinkingLevel: ThinkingLevel;
+  autoSelected: boolean;
+  selectionReason: string;
 };
 
 type LibrarianDetails = {
-	status: LibrarianStatus;
-	workspace: string;
-	cache: CacheDetails;
-	model: LibrarianModelDetails;
-	turns: number;
-	toolCalls: ToolCall[];
-	startedAt: number;
-	endedAt?: number;
-	error?: string;
+  status: LibrarianStatus;
+  workspace: string;
+  cache: CacheDetails;
+  model: LibrarianModelDetails;
+  turns: number;
+  toolCalls: ToolCall[];
+  startedAt: number;
+  endedAt?: number;
+  error?: string;
 };
 
 const LibrarianParams = Type.Object({
-	query: Type.String({
-		description: [
-			"Describe exactly what to find in GitHub code.",
-			"Include known context in the query when you have it (symbols/behavior, repo or owner hints, refs/branches, paths, and desired output).",
-			"Do not guess unknown details; if scope is uncertain, say that explicitly and let Librarian discover it.",
-			"Librarian returns concise path-first findings with line-ranged evidence from GitHub files.",
-		].join("\n"),
-	}),
-	repos: Type.Optional(
-		Type.Array(Type.String({ description: "Optional owner/repo filters (e.g. octocat/hello-world)" }), {
-			description: "Optional explicit repository scope.",
-			maxItems: 30,
-		}),
-	),
-	owners: Type.Optional(
-		Type.Array(Type.String({ description: "Optional owner/org filters" }), {
-			description: "Optional owner/org scope.",
-			maxItems: 30,
-		}),
-	),
-	maxSearchResults: Type.Optional(
-		Type.Number({
-			description: `Maximum GitHub search hits per query (1-${MAX_SEARCH_RESULTS}, default ${DEFAULT_MAX_SEARCH_RESULTS})`,
-			minimum: 1,
-			maximum: MAX_SEARCH_RESULTS,
-			default: DEFAULT_MAX_SEARCH_RESULTS,
-		}),
-	),
-	model: Type.Optional(
-		Type.String({
-			description: "Optional model override for the internal librarian subagent. Use provider/model or auto.",
-		}),
-	),
-	thinkingLevel: Type.Optional(
-		Type.String({
-			description: `Optional thinking override for the internal librarian subagent (${THINKING_LEVELS.join(" | ")}). Default ${DEFAULT_THINKING_LEVEL}.`,
-		}),
-	),
+  query: Type.String({
+    description: [
+      "Describe exactly what to find in GitHub code.",
+      "Include known context in the query when you have it (symbols/behavior, repo or owner hints, refs/branches, paths, and desired output).",
+      "Do not guess unknown details; if scope is uncertain, say that explicitly and let Librarian discover it.",
+      "Librarian returns concise path-first findings with line-ranged evidence from GitHub files.",
+    ].join("\n"),
+  }),
+  repos: Type.Optional(
+    Type.Array(
+      Type.String({ description: "Optional owner/repo filters (e.g. octocat/hello-world)" }),
+      {
+        description: "Optional explicit repository scope.",
+        maxItems: 30,
+      },
+    ),
+  ),
+  owners: Type.Optional(
+    Type.Array(Type.String({ description: "Optional owner/org filters" }), {
+      description: "Optional owner/org scope.",
+      maxItems: 30,
+    }),
+  ),
+  maxSearchResults: Type.Optional(
+    Type.Number({
+      description: `Maximum GitHub search hits per query (1-${MAX_SEARCH_RESULTS}, default ${DEFAULT_MAX_SEARCH_RESULTS})`,
+      minimum: 1,
+      maximum: MAX_SEARCH_RESULTS,
+      default: DEFAULT_MAX_SEARCH_RESULTS,
+    }),
+  ),
+  model: Type.Optional(
+    Type.String({
+      description:
+        "Optional model override for the internal librarian subagent. Use provider/model or auto.",
+    }),
+  ),
+  thinkingLevel: Type.Optional(
+    Type.String({
+      description: `Optional thinking override for the internal librarian subagent (${THINKING_LEVELS.join(" | ")}). Default ${DEFAULT_THINKING_LEVEL}.`,
+    }),
+  ),
 });
 
 function asStringArray(value: unknown, maxItems = 30): string[] {
-	if (!Array.isArray(value)) return [];
-	const out: string[] = [];
-	for (const item of value) {
-		if (typeof item !== "string") continue;
-		const trimmed = item.trim();
-		if (!trimmed) continue;
-		out.push(trimmed);
-		if (out.length >= maxItems) break;
-	}
-	return out;
+  if (!Array.isArray(value)) return [];
+  const out: string[] = [];
+  for (const item of value) {
+    if (typeof item !== "string") continue;
+    const trimmed = item.trim();
+    if (!trimmed) continue;
+    out.push(trimmed);
+    if (out.length >= maxItems) break;
+  }
+  return out;
 }
 
 function clampNumber(value: unknown, min: number, max: number, fallback: number): number {
-	const parsed = typeof value === "number" ? value : Number(value);
-	if (!Number.isFinite(parsed)) return fallback;
-	return Math.min(max, Math.max(min, Math.floor(parsed)));
+  const parsed = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.min(max, Math.max(min, Math.floor(parsed)));
 }
 
 function shorten(text: string, max: number): string {
-	const oneLine = text.replace(/\s+/g, " ").trim();
-	if (oneLine.length <= max) return oneLine;
-	return `${oneLine.slice(0, Math.max(1, max - 1))}…`;
+  const oneLine = text.replace(/\s+/g, " ").trim();
+  if (oneLine.length <= max) return oneLine;
+  return `${oneLine.slice(0, Math.max(1, max - 1))}…`;
 }
 
 function getUserCacheReposRoot(): string {
-	if (process.env.PI_LIBRARIAN_CACHE_ROOT?.trim()) {
-		return path.resolve(expandHome(process.env.PI_LIBRARIAN_CACHE_ROOT.trim()));
-	}
+  if (process.env.PI_LIBRARIAN_CACHE_ROOT?.trim()) {
+    return path.resolve(expandHome(process.env.PI_LIBRARIAN_CACHE_ROOT.trim()));
+  }
 
-	if (process.platform === "darwin") {
-		return path.join(os.homedir(), "Library", "Caches", "pi-librarian", "repos");
-	}
+  if (process.platform === "darwin") {
+    return path.join(os.homedir(), "Library", "Caches", "pi-librarian", "repos");
+  }
 
-	if (process.platform === "win32") {
-		const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
-		return path.join(localAppData, "pi-librarian", "repos");
-	}
+  if (process.platform === "win32") {
+    const localAppData = process.env.LOCALAPPDATA || path.join(os.homedir(), "AppData", "Local");
+    return path.join(localAppData, "pi-librarian", "repos");
+  }
 
-	const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
-	return path.join(xdgCacheHome, "pi-librarian", "repos");
+  const xdgCacheHome = process.env.XDG_CACHE_HOME?.trim() || path.join(os.homedir(), ".cache");
+  return path.join(xdgCacheHome, "pi-librarian", "repos");
 }
 
 function expandHome(value: string): string {
-	if (value === "~") return os.homedir();
-	if (value.startsWith(`~${path.sep}`)) return path.join(os.homedir(), value.slice(2));
-	if (path.sep === "/" && value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
-	return value;
+  if (value === "~") return os.homedir();
+  if (value.startsWith(`~${path.sep}`)) return path.join(os.homedir(), value.slice(2));
+  if (path.sep === "/" && value.startsWith("~/")) return path.join(os.homedir(), value.slice(2));
+  return value;
 }
 
 async function pathExists(filePath: string): Promise<boolean> {
-	try {
-		await fs.access(filePath);
-		return true;
-	} catch {
-		return false;
-	}
+  try {
+    await fs.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
 }
 
 async function safeReadDir(dir: string): Promise<Dirent[]> {
-	try {
-		return await fs.readdir(dir, { withFileTypes: true });
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
-		throw error;
-	}
+  try {
+    return await fs.readdir(dir, { withFileTypes: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
 }
 
 function isInside(parent: string, child: string): boolean {
-	const parentResolved = path.resolve(parent);
-	const childResolved = path.resolve(child);
-	return childResolved === parentResolved || childResolved.startsWith(`${parentResolved}${path.sep}`);
+  const parentResolved = path.resolve(parent);
+  const childResolved = path.resolve(child);
+  return (
+    childResolved === parentResolved || childResolved.startsWith(`${parentResolved}${path.sep}`)
+  );
 }
 
 function parseLastUsedAt(value: unknown): number | undefined {
-	if (typeof value === "number" && Number.isFinite(value)) return value;
-	if (typeof value === "string") {
-		const numeric = Number(value);
-		if (Number.isFinite(numeric)) return numeric;
-		const parsed = Date.parse(value);
-		if (Number.isFinite(parsed)) return parsed;
-	}
-	return undefined;
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string") {
+    const numeric = Number(value);
+    if (Number.isFinite(numeric)) return numeric;
+    const parsed = Date.parse(value);
+    if (Number.isFinite(parsed)) return parsed;
+  }
+  return undefined;
 }
 
 async function getRepoLastUsedAt(repoDir: string): Promise<number | undefined> {
-	const metadataPath = path.join(repoDir, CACHE_METADATA_FILE);
-	try {
-		const raw = await fs.readFile(metadataPath, "utf8");
-		const parsed = JSON.parse(raw) as { lastUsedAt?: unknown; updatedAt?: unknown; createdAt?: unknown };
-		const fromMetadata =
-			parseLastUsedAt(parsed.lastUsedAt) ?? parseLastUsedAt(parsed.updatedAt) ?? parseLastUsedAt(parsed.createdAt);
-		if (fromMetadata !== undefined) return fromMetadata;
-	} catch {
-		// Fall through to marker mtime for older managed caches.
-	}
-
-	const markerPath = path.join(repoDir, CACHE_MARKER_FILE);
-	try {
-		return (await fs.stat(markerPath)).mtimeMs;
-	} catch {
-		return undefined;
-	}
+  const metadataPath = path.join(repoDir, CACHE_METADATA_FILE);
+  try {
+    const raw = await fs.readFile(metadataPath, "utf8");
+    const parsed = JSON.parse(raw) as {
+      lastUsedAt?: unknown;
+      updatedAt?: unknown;
+      createdAt?: unknown;
+    };
+    const fromMetadata =
+      parseLastUsedAt(parsed.lastUsedAt) ??
+      parseLastUsedAt(parsed.updatedAt) ??
+      parseLastUsedAt(parsed.createdAt);
+    if (fromMetadata !== undefined) return fromMetadata;
+  } catch {
+    // Fall through to marker mtime for older managed caches.
+  }
+
+  const markerPath = path.join(repoDir, CACHE_MARKER_FILE);
+  try {
+    return (await fs.stat(markerPath)).mtimeMs;
+  } catch {
+    return undefined;
+  }
 }
 
 async function isManagedRepoCache(repoDir: string): Promise<boolean> {
-	return (await pathExists(path.join(repoDir, ".git"))) &&
-		((await pathExists(path.join(repoDir, CACHE_METADATA_FILE))) ||
-			(await pathExists(path.join(repoDir, CACHE_MARKER_FILE))));
+  return (
+    (await pathExists(path.join(repoDir, ".git"))) &&
+    ((await pathExists(path.join(repoDir, CACHE_METADATA_FILE))) ||
+      (await pathExists(path.join(repoDir, CACHE_MARKER_FILE))))
+  );
 }
 
 type CleanupLockOwner = {
-	pid: number;
-	hostname: string;
-	token: string;
-	acquiredAt: string;
+  pid: number;
+  hostname: string;
+  token: string;
+  acquiredAt: string;
 };
 
 type CleanupLock = {
-	handle: FileHandle;
-	path: string;
-	owner: CleanupLockOwner;
-	identity: Pick<Stats, "dev" | "ino">;
+  handle: FileHandle;
+  path: string;
+  owner: CleanupLockOwner;
+  identity: Pick<Stats, "dev" | "ino">;
 };
 
-function sameFileIdentity(left: Pick<Stats, "dev" | "ino">, right: Pick<Stats, "dev" | "ino">): boolean {
-	return left.dev === right.dev && left.ino === right.ino;
+function sameFileIdentity(
+  left: Pick<Stats, "dev" | "ino">,
+  right: Pick<Stats, "dev" | "ino">,
+): boolean {
+  return left.dev === right.dev && left.ino === right.ino;
 }
 
 function parseCleanupLockOwner(value: string): CleanupLockOwner | undefined {
-	try {
-		const owner = JSON.parse(value) as Partial<CleanupLockOwner>;
-		if (!Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0) return undefined;
-		if (typeof owner.hostname !== "string" || !owner.hostname) return undefined;
-		if (typeof owner.token !== "string" || !owner.token) return undefined;
-		if (typeof owner.acquiredAt !== "string" || !owner.acquiredAt) return undefined;
-		if (!Number.isFinite(Date.parse(owner.acquiredAt))) return undefined;
-		return owner as CleanupLockOwner;
-	} catch {
-		return undefined;
-	}
+  try {
+    const owner = JSON.parse(value) as Partial<CleanupLockOwner>;
+    if (!Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0) return undefined;
+    if (typeof owner.hostname !== "string" || !owner.hostname) return undefined;
+    if (typeof owner.token !== "string" || !owner.token) return undefined;
+    if (typeof owner.acquiredAt !== "string" || !owner.acquiredAt) return undefined;
+    if (!Number.isFinite(Date.parse(owner.acquiredAt))) return undefined;
+    return owner as CleanupLockOwner;
+  } catch {
+    return undefined;
+  }
 }
 
 function isCleanupLockLeaseExpired(owner: CleanupLockOwner | undefined, now = Date.now()): boolean {
-	if (!owner) return true;
-	const acquiredAt = Date.parse(owner.acquiredAt);
-	if (!Number.isFinite(acquiredAt)) return true;
-	return Math.max(0, now - acquiredAt) > CLEANUP_LOCK_MAX_LEASE_MS;
+  if (!owner) return true;
+  const acquiredAt = Date.parse(owner.acquiredAt);
+  if (!Number.isFinite(acquiredAt)) return true;
+  return Math.max(0, now - acquiredAt) > CLEANUP_LOCK_MAX_LEASE_MS;
 }
 
 function isRecordedOwnerAlive(owner: CleanupLockOwner | undefined): boolean {
-	if (!owner || owner.hostname !== os.hostname()) return false;
-	try {
-		process.kill(owner.pid, 0);
-		return true;
-	} catch (error) {
-		return (error as NodeJS.ErrnoException).code === "EPERM";
-	}
+  if (!owner || owner.hostname !== os.hostname()) return false;
+  try {
+    process.kill(owner.pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
 }
 
 async function restoreMovedLock(movedPath: string, lockPath: string): Promise<void> {
-	try {
-		// link() restores only when lockPath is still absent; unlike rename(), it cannot overwrite a newer owner.
-		await fs.link(movedPath, lockPath);
-		await fs.rm(movedPath, { force: true });
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-		// Preserve both owners rather than deleting the moved lock when another owner won the canonical path.
-	}
-}
-
-async function removeLockPathIfOwned(lockPath: string, identity: Pick<Stats, "dev" | "ino">): Promise<void> {
-	const currentStat = await fs.stat(lockPath).catch(() => undefined);
-	if (!currentStat || !sameFileIdentity(identity, currentStat)) return;
-	await fs.rm(lockPath, { force: true }).catch(() => undefined);
-}
-
-async function getCleanupLockPathIdentity(lockPath: string): Promise<Pick<Stats, "dev" | "ino"> | undefined> {
-	const canonicalPath = await fs.realpath(lockPath).catch((error: NodeJS.ErrnoException) => {
-		if (error.code === "ENOENT") return undefined;
-		throw error;
-	});
-	if (!canonicalPath) return undefined;
-	const currentStat = await fs.stat(canonicalPath).catch((error: NodeJS.ErrnoException) => {
-		if (error.code === "ENOENT") return undefined;
-		throw error;
-	});
-	return currentStat ? { dev: currentStat.dev, ino: currentStat.ino } : undefined;
-}
-
-async function cleanupLockOwnershipError(lock: CleanupLock, stage: string): Promise<string | undefined> {
-	const currentIdentity = await getCleanupLockPathIdentity(lock.path);
-	if (currentIdentity && sameFileIdentity(lock.identity, currentIdentity)) return undefined;
-	return `cleanup lock ownership lost before ${stage}; stopping cleanup.`;
+  try {
+    // link() restores only when lockPath is still absent; unlike rename(), it cannot overwrite a newer owner.
+    await fs.link(movedPath, lockPath);
+    await fs.rm(movedPath, { force: true });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    // Preserve both owners rather than deleting the moved lock when another owner won the canonical path.
+  }
+}
+
+async function removeLockPathIfOwned(
+  lockPath: string,
+  identity: Pick<Stats, "dev" | "ino">,
+): Promise<void> {
+  const currentStat = await fs.stat(lockPath).catch(() => undefined);
+  if (!currentStat || !sameFileIdentity(identity, currentStat)) return;
+  await fs.rm(lockPath, { force: true }).catch(() => undefined);
+}
+
+async function getCleanupLockPathIdentity(
+  lockPath: string,
+): Promise<Pick<Stats, "dev" | "ino"> | undefined> {
+  const canonicalPath = await fs.realpath(lockPath).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  if (!canonicalPath) return undefined;
+  const currentStat = await fs.stat(canonicalPath).catch((error: NodeJS.ErrnoException) => {
+    if (error.code === "ENOENT") return undefined;
+    throw error;
+  });
+  return currentStat ? { dev: currentStat.dev, ino: currentStat.ino } : undefined;
+}
+
+async function cleanupLockOwnershipError(
+  lock: CleanupLock,
+  stage: string,
+): Promise<string | undefined> {
+  const currentIdentity = await getCleanupLockPathIdentity(lock.path);
+  if (currentIdentity && sameFileIdentity(lock.identity, currentIdentity)) return undefined;
+  return `cleanup lock ownership lost before ${stage}; stopping cleanup.`;
 }
 
 async function tryAcquireCleanupLock(root: string): Promise<CleanupLock | undefined> {
-	const lockPath = path.join(root, CLEANUP_LOCK_FILE);
-	for (let attempt = 0; attempt < 3; attempt += 1) {
-		const owner: CleanupLockOwner = {
-			pid: process.pid,
-			hostname: os.hostname(),
-			token: randomUUID(),
-			acquiredAt: new Date().toISOString(),
-		};
-		try {
-			const handle = await fs.open(lockPath, "wx");
-			const identity = await handle.stat();
-			try {
-				await handle.writeFile(JSON.stringify(owner), "utf8");
-				await handle.sync();
-				return { handle, path: lockPath, owner, identity };
-			} catch (error) {
-				await handle.close().catch(() => undefined);
-				await removeLockPathIfOwned(lockPath, identity);
-				throw error;
-			}
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
-		}
-
-		let existing: FileHandle | undefined;
-		try {
-			existing = await fs.open(lockPath, "r");
-		} catch (error) {
-			if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
-			throw error;
-		}
-		try {
-			const stat = await existing.stat();
-			const recordedOwner = parseCleanupLockOwner(await existing.readFile("utf8"));
-			const now = Date.now();
-			const ageMs = Math.max(0, now - stat.mtimeMs);
-			if (!recordedOwner) {
-				if (ageMs <= CLEANUP_LOCK_STALE_MS) return undefined;
-			} else {
-				const leaseExpired = isCleanupLockLeaseExpired(recordedOwner, now);
-				if (isRecordedOwnerAlive(recordedOwner) && !leaseExpired) return undefined;
-				if (!leaseExpired && ageMs <= CLEANUP_LOCK_STALE_MS) return undefined;
-			}
-
-			const stalePath = path.join(root, `${CLEANUP_LOCK_FILE}.stale-${process.pid}-${randomUUID()}`);
-			try {
-				await fs.rename(lockPath, stalePath);
-			} catch (renameError) {
-				if ((renameError as NodeJS.ErrnoException).code === "ENOENT") continue;
-				throw renameError;
-			}
-			const movedStat = await fs.stat(stalePath).catch(() => undefined);
-			if (!movedStat || !sameFileIdentity(stat, movedStat)) {
-				await restoreMovedLock(stalePath, lockPath);
-				return undefined;
-			}
-			await fs.rm(stalePath, { force: true });
-		} finally {
-			await existing.close().catch(() => undefined);
-		}
-	}
-	return undefined;
+  const lockPath = path.join(root, CLEANUP_LOCK_FILE);
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const owner: CleanupLockOwner = {
+      pid: process.pid,
+      hostname: os.hostname(),
+      token: randomUUID(),
+      acquiredAt: new Date().toISOString(),
+    };
+    try {
+      const handle = await fs.open(lockPath, "wx");
+      const identity = await handle.stat();
+      try {
+        await handle.writeFile(JSON.stringify(owner), "utf8");
+        await handle.sync();
+        return { handle, path: lockPath, owner, identity };
+      } catch (error) {
+        await handle.close().catch(() => undefined);
+        await removeLockPathIfOwned(lockPath, identity);
+        throw error;
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+
+    let existing: FileHandle | undefined;
+    try {
+      existing = await fs.open(lockPath, "r");
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") continue;
+      throw error;
+    }
+    try {
+      const stat = await existing.stat();
+      const recordedOwner = parseCleanupLockOwner(await existing.readFile("utf8"));
+      const now = Date.now();
+      const ageMs = Math.max(0, now - stat.mtimeMs);
+      if (!recordedOwner) {
+        if (ageMs <= CLEANUP_LOCK_STALE_MS) return undefined;
+      } else {
+        const leaseExpired = isCleanupLockLeaseExpired(recordedOwner, now);
+        if (isRecordedOwnerAlive(recordedOwner) && !leaseExpired) return undefined;
+        if (!leaseExpired && ageMs <= CLEANUP_LOCK_STALE_MS) return undefined;
+      }
+
+      const stalePath = path.join(
+        root,
+        `${CLEANUP_LOCK_FILE}.stale-${process.pid}-${randomUUID()}`,
+      );
+      try {
+        await fs.rename(lockPath, stalePath);
+      } catch (renameError) {
+        if ((renameError as NodeJS.ErrnoException).code === "ENOENT") continue;
+        throw renameError;
+      }
+      const movedStat = await fs.stat(stalePath).catch(() => undefined);
+      if (!movedStat || !sameFileIdentity(stat, movedStat)) {
+        await restoreMovedLock(stalePath, lockPath);
+        return undefined;
+      }
+      await fs.rm(stalePath, { force: true });
+    } finally {
+      await existing.close().catch(() => undefined);
+    }
+  }
+  return undefined;
 }
 
 async function heartbeatCleanupLock(lock: CleanupLock): Promise<void> {
-	const now = new Date();
-	await lock.handle.utimes(now, now);
+  const now = new Date();
+  await lock.handle.utimes(now, now);
 }
 
 async function releaseCleanupLock(lock: CleanupLock): Promise<void> {
-	await lock.handle.close().catch(() => undefined);
-	const currentStat = await fs.stat(lock.path).catch(() => undefined);
-	if (!currentStat || !sameFileIdentity(lock.identity, currentStat)) return;
-	const releasePath = `${lock.path}.release-${process.pid}-${lock.owner.token}`;
-	try {
-		await fs.rename(lock.path, releasePath);
-	} catch (error) {
-		if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
-		throw error;
-	}
-	const movedStat = await fs.stat(releasePath).catch(() => undefined);
-	if (!movedStat || !sameFileIdentity(lock.identity, movedStat)) {
-		await restoreMovedLock(releasePath, lock.path);
-		return;
-	}
-	await fs.rm(releasePath, { force: true });
-}
-
-async function cleanupExpiredRepos(root: string, now: number, lock: CleanupLock): Promise<{ deleted: number; errors: string[] }> {
-	const errors: string[] = [];
-	let deleted = 0;
-	const ownershipBeforeScan = await cleanupLockOwnershipError(lock, "cache scan");
-	if (ownershipBeforeScan) return { deleted, errors: [ownershipBeforeScan] };
-
-	const hosts = await safeReadDir(root);
-	for (const host of hosts) {
-		if (!host.isDirectory()) continue;
-		const hostDir = path.join(root, host.name);
-		const owners = await safeReadDir(hostDir);
-		for (const owner of owners) {
-			if (!owner.isDirectory()) continue;
-			const ownerDir = path.join(hostDir, owner.name);
-			const repos = await safeReadDir(ownerDir);
-			for (const repo of repos) {
-				if (!repo.isDirectory()) continue;
-				const repoDir = path.join(ownerDir, repo.name);
-				if (!isInside(root, repoDir)) continue;
-
-				try {
-					if (!(await isManagedRepoCache(repoDir))) continue;
-					const lastUsedAt = await getRepoLastUsedAt(repoDir);
-					if (lastUsedAt === undefined || now - lastUsedAt <= CACHE_TTL_MS) continue;
-					const ownershipBeforeDelete = await cleanupLockOwnershipError(lock, `deleting ${repoDir}`);
-					if (ownershipBeforeDelete) return { deleted, errors: [...errors, ownershipBeforeDelete] };
-					await fs.rm(repoDir, { recursive: true, force: true });
-					deleted += 1;
-				} catch (error) {
-					const message = error instanceof Error ? error.message : String(error);
-					errors.push(`${repoDir}: ${message}`);
-				}
-			}
-		}
-	}
-
-	return { deleted, errors };
-}
-
-async function cleanupExpiredCache(cacheRoot: string): Promise<{ deleted: number; errors: string[] }> {
-	const now = Date.now();
-	const root = path.resolve(cacheRoot);
-	let lock: CleanupLock | undefined;
-	let heartbeat: NodeJS.Timeout | undefined;
-
-	try {
-		lock = await tryAcquireCleanupLock(root);
-		if (!lock) return { deleted: 0, errors: [] };
-		heartbeat = setInterval(() => {
-			if (lock) void heartbeatCleanupLock(lock).catch(() => undefined);
-		}, CLEANUP_LOCK_HEARTBEAT_MS);
-		heartbeat.unref?.();
-		return await cleanupExpiredRepos(root, now, lock);
-	} finally {
-		if (heartbeat) clearInterval(heartbeat);
-		if (lock) await releaseCleanupLock(lock).catch(() => undefined);
-	}
+  await lock.handle.close().catch(() => undefined);
+  const currentStat = await fs.stat(lock.path).catch(() => undefined);
+  if (!currentStat || !sameFileIdentity(lock.identity, currentStat)) return;
+  const releasePath = `${lock.path}.release-${process.pid}-${lock.owner.token}`;
+  try {
+    await fs.rename(lock.path, releasePath);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return;
+    throw error;
+  }
+  const movedStat = await fs.stat(releasePath).catch(() => undefined);
+  if (!movedStat || !sameFileIdentity(lock.identity, movedStat)) {
+    await restoreMovedLock(releasePath, lock.path);
+    return;
+  }
+  await fs.rm(releasePath, { force: true });
+}
+
+async function cleanupExpiredRepos(
+  root: string,
+  now: number,
+  lock: CleanupLock,
+): Promise<{ deleted: number; errors: string[] }> {
+  const errors: string[] = [];
+  let deleted = 0;
+  const ownershipBeforeScan = await cleanupLockOwnershipError(lock, "cache scan");
+  if (ownershipBeforeScan) return { deleted, errors: [ownershipBeforeScan] };
+
+  const hosts = await safeReadDir(root);
+  for (const host of hosts) {
+    if (!host.isDirectory()) continue;
+    const hostDir = path.join(root, host.name);
+    const owners = await safeReadDir(hostDir);
+    for (const owner of owners) {
+      if (!owner.isDirectory()) continue;
+      const ownerDir = path.join(hostDir, owner.name);
+      const repos = await safeReadDir(ownerDir);
+      for (const repo of repos) {
+        if (!repo.isDirectory()) continue;
+        const repoDir = path.join(ownerDir, repo.name);
+        if (!isInside(root, repoDir)) continue;
+
+        try {
+          if (!(await isManagedRepoCache(repoDir))) continue;
+          const lastUsedAt = await getRepoLastUsedAt(repoDir);
+          if (lastUsedAt === undefined || now - lastUsedAt <= CACHE_TTL_MS) continue;
+          const ownershipBeforeDelete = await cleanupLockOwnershipError(
+            lock,
+            `deleting ${repoDir}`,
+          );
+          if (ownershipBeforeDelete) return { deleted, errors: [...errors, ownershipBeforeDelete] };
+          await fs.rm(repoDir, { recursive: true, force: true });
+          deleted += 1;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          errors.push(`${repoDir}: ${message}`);
+        }
+      }
+    }
+  }
+
+  return { deleted, errors };
+}
+
+async function cleanupExpiredCache(
+  cacheRoot: string,
+): Promise<{ deleted: number; errors: string[] }> {
+  const now = Date.now();
+  const root = path.resolve(cacheRoot);
+  let lock: CleanupLock | undefined;
+  let heartbeat: NodeJS.Timeout | undefined;
+
+  try {
+    lock = await tryAcquireCleanupLock(root);
+    if (!lock) return { deleted: 0, errors: [] };
+    heartbeat = setInterval(() => {
+      if (lock) void heartbeatCleanupLock(lock).catch(() => undefined);
+    }, CLEANUP_LOCK_HEARTBEAT_MS);
+    heartbeat.unref?.();
+    return await cleanupExpiredRepos(root, now, lock);
+  } finally {
+    if (heartbeat) clearInterval(heartbeat);
+    if (lock) await releaseCleanupLock(lock).catch(() => undefined);
+  }
 }
 
 function getCacheConfigPath(): string {
-	return path.join(getAgentDir(), "extensions", CACHE_CONFIG_FILE);
+  return path.join(getAgentDir(), "extensions", CACHE_CONFIG_FILE);
 }
 
 type LibrarianPreferences = {
-	cacheMode: CacheMode;
-	model?: string;
-	thinkingLevel: ThinkingLevel;
+  cacheMode: CacheMode;
+  model?: string;
+  thinkingLevel: ThinkingLevel;
 };
 
 function parseCacheMode(value: unknown): CacheMode | undefined {
-	if (typeof value === "string") {
-		const normalized = value.trim().toLowerCase();
-		if (normalized === "enabled" || normalized === "on" || normalized === "true") return "enabled";
-		if (normalized === "disabled" || normalized === "off" || normalized === "false") return "disabled";
-	}
-	if (value === true) return "enabled";
-	if (value === false) return "disabled";
-	return undefined;
+  if (typeof value === "string") {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "enabled" || normalized === "on" || normalized === "true") return "enabled";
+    if (normalized === "disabled" || normalized === "off" || normalized === "false")
+      return "disabled";
+  }
+  if (value === true) return "enabled";
+  if (value === false) return "disabled";
+  return undefined;
 }
 
 function parseThinkingLevel(value: unknown): ThinkingLevel | undefined {
-	if (typeof value !== "string") return undefined;
-	const normalized = value.trim().toLowerCase();
-	return (THINKING_LEVELS as readonly string[]).includes(normalized) ? (normalized as ThinkingLevel) : undefined;
+  if (typeof value !== "string") return undefined;
+  const normalized = value.trim().toLowerCase();
+  return (THINKING_LEVELS as readonly string[]).includes(normalized)
+    ? (normalized as ThinkingLevel)
+    : undefined;
 }
 
 function isThinkingLevelSupported(model: PiModel, level: ThinkingLevel): boolean {
-	if (!model.reasoning) return level === "off";
-	const map = model.thinkingLevelMap;
-	if (level === "xhigh" || level === "max") {
-		return !!map && Object.prototype.hasOwnProperty.call(map, level) && map[level] != null;
-	}
-	return map?.[level] !== null;
+  if (!model.reasoning) return level === "off";
+  const map = model.thinkingLevelMap;
+  if (level === "xhigh" || level === "max") {
+    return !!map && Object.prototype.hasOwnProperty.call(map, level) && map[level] != null;
+  }
+  return map?.[level] !== null;
 }
 
 function resolveThinkingLevel(model: PiModel, requested: ThinkingLevel): ThinkingLevel {
-	if (isThinkingLevelSupported(model, requested)) return requested;
-	const requestedIndex = THINKING_LEVELS.indexOf(requested);
-	for (let index = requestedIndex + 1; index < THINKING_LEVELS.length; index += 1) {
-		const level = THINKING_LEVELS[index];
-		if (isThinkingLevelSupported(model, level)) return level;
-	}
-	for (let index = requestedIndex - 1; index >= 0; index -= 1) {
-		const level = THINKING_LEVELS[index];
-		if (isThinkingLevelSupported(model, level)) return level;
-	}
-	return "off";
+  if (isThinkingLevelSupported(model, requested)) return requested;
+  const requestedIndex = THINKING_LEVELS.indexOf(requested);
+  for (let index = requestedIndex + 1; index < THINKING_LEVELS.length; index += 1) {
+    const level = THINKING_LEVELS[index];
+    if (isThinkingLevelSupported(model, level)) return level;
+  }
+  for (let index = requestedIndex - 1; index >= 0; index -= 1) {
+    const level = THINKING_LEVELS[index];
+    if (isThinkingLevelSupported(model, level)) return level;
+  }
+  return "off";
 }
 
 function normalizeModelPreference(value: unknown): string | undefined {
-	if (typeof value !== "string") return undefined;
-	const trimmed = value.trim();
-	const normalized = trimmed.toLowerCase();
-	if (!trimmed || normalized === "auto" || normalized === "current") return undefined;
-	return trimmed;
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  const normalized = trimmed.toLowerCase();
+  if (!trimmed || normalized === "auto" || normalized === "current") return undefined;
+  return trimmed;
 }
 
 function parseModelPreference(value: unknown): { model?: string; thinkingLevel?: ThinkingLevel } {
-	const model = normalizeModelPreference(value);
-	if (!model) return {};
-	const match = model.match(/^(.*):(off|minimal|low|medium|high|xhigh|max)$/i);
-	if (!match?.[1]) return { model };
-	const baseModel = match[1].trim();
-	if (!baseModel || baseModel.toLowerCase() === "auto" || baseModel.toLowerCase() === "current") {
-		return { thinkingLevel: parseThinkingLevel(match[2]) };
-	}
-	return { model: baseModel, thinkingLevel: parseThinkingLevel(match[2]) };
+  const model = normalizeModelPreference(value);
+  if (!model) return {};
+  const match = model.match(/^(.*):(off|minimal|low|medium|high|xhigh|max)$/i);
+  if (!match?.[1]) return { model };
+  const baseModel = match[1].trim();
+  if (!baseModel || baseModel.toLowerCase() === "auto" || baseModel.toLowerCase() === "current") {
+    return { thinkingLevel: parseThinkingLevel(match[2]) };
+  }
+  return { model: baseModel, thinkingLevel: parseThinkingLevel(match[2]) };
 }
 
 async function readLibrarianPreferences(): Promise<LibrarianPreferences> {
-	try {
-		const raw = await fs.readFile(getCacheConfigPath(), "utf8");
-		const parsed = JSON.parse(raw) as {
-			cacheMode?: unknown;
-			cacheEnabled?: unknown;
-			cache?: { mode?: unknown; enabled?: unknown };
-			model?: unknown;
-			defaultModel?: unknown;
-			thinkingLevel?: unknown;
-			defaultThinkingLevel?: unknown;
-		};
-		return {
-			cacheMode:
-				parseCacheMode(parsed.cacheMode) ??
-				parseCacheMode(parsed.cache?.mode) ??
-				parseCacheMode(parsed.cacheEnabled) ??
-				parseCacheMode(parsed.cache?.enabled) ??
-				DEFAULT_CACHE_MODE,
-			model: parseModelPreference(parsed.model).model ?? parseModelPreference(parsed.defaultModel).model,
-			thinkingLevel:
-				parseThinkingLevel(parsed.thinkingLevel) ??
-				parseThinkingLevel(parsed.defaultThinkingLevel) ??
-				parseModelPreference(parsed.model).thinkingLevel ??
-				parseModelPreference(parsed.defaultModel).thinkingLevel ??
-				DEFAULT_THINKING_LEVEL,
-		};
-	} catch (error) {
-		return {
-			cacheMode: (error as NodeJS.ErrnoException).code === "ENOENT" ? DEFAULT_CACHE_MODE : "disabled",
-			thinkingLevel: DEFAULT_THINKING_LEVEL,
-		};
-	}
+  try {
+    const raw = await fs.readFile(getCacheConfigPath(), "utf8");
+    const parsed = JSON.parse(raw) as {
+      cacheMode?: unknown;
+      cacheEnabled?: unknown;
+      cache?: { mode?: unknown; enabled?: unknown };
+      model?: unknown;
+      defaultModel?: unknown;
+      thinkingLevel?: unknown;
+      defaultThinkingLevel?: unknown;
+    };
+    return {
+      cacheMode:
+        parseCacheMode(parsed.cacheMode) ??
+        parseCacheMode(parsed.cache?.mode) ??
+        parseCacheMode(parsed.cacheEnabled) ??
+        parseCacheMode(parsed.cache?.enabled) ??
+        DEFAULT_CACHE_MODE,
+      model:
+        parseModelPreference(parsed.model).model ?? parseModelPreference(parsed.defaultModel).model,
+      thinkingLevel:
+        parseThinkingLevel(parsed.thinkingLevel) ??
+        parseThinkingLevel(parsed.defaultThinkingLevel) ??
+        parseModelPreference(parsed.model).thinkingLevel ??
+        parseModelPreference(parsed.defaultModel).thinkingLevel ??
+        DEFAULT_THINKING_LEVEL,
+    };
+  } catch (error) {
+    return {
+      cacheMode:
+        (error as NodeJS.ErrnoException).code === "ENOENT" ? DEFAULT_CACHE_MODE : "disabled",
+      thinkingLevel: DEFAULT_THINKING_LEVEL,
+    };
+  }
 }
 
 async function writeLibrarianPreferences(preferences: LibrarianPreferences): Promise<void> {
-	const configPath = getCacheConfigPath();
-	const config = {
-		cacheMode: preferences.cacheMode,
-		cacheEnabled: preferences.cacheMode === "enabled",
-		...(preferences.model ? { model: preferences.model } : {}),
-		thinkingLevel: preferences.thinkingLevel,
-		updatedAt: new Date().toISOString(),
-	};
+  const configPath = getCacheConfigPath();
+  const config = {
+    cacheMode: preferences.cacheMode,
+    cacheEnabled: preferences.cacheMode === "enabled",
+    ...(preferences.model ? { model: preferences.model } : {}),
+    thinkingLevel: preferences.thinkingLevel,
+    updatedAt: new Date().toISOString(),
+  };
 
-	await fs.mkdir(path.dirname(configPath), { recursive: true });
-	await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+  await fs.mkdir(path.dirname(configPath), { recursive: true });
+  await fs.writeFile(configPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
 }
 
 async function writeCachePreference(preference: CacheMode): Promise<void> {
-	const preferences = await readLibrarianPreferences();
-	await writeLibrarianPreferences({ ...preferences, cacheMode: preference });
+  const preferences = await readLibrarianPreferences();
+  await writeLibrarianPreferences({ ...preferences, cacheMode: preference });
 }
 
 function resolveCacheDecision(preference: CacheMode): { enabled: boolean; reason: string } {
-	if (preference === "enabled") {
-		return { enabled: true, reason: "cache preference enabled; using cached local checkouts" };
-	}
+  if (preference === "enabled") {
+    return { enabled: true, reason: "cache preference enabled; using cached local checkouts" };
+  }
 
-	return { enabled: false, reason: "cache preference disabled; using GitHub API/temp files only" };
+  return { enabled: false, reason: "cache preference disabled; using GitHub API/temp files only" };
 }
 
 function formatCachePreference(preference: CacheMode): string {
-	return preference === "enabled" ? "on" : "off";
+  return preference === "enabled" ? "on" : "off";
 }
 
 function formatLibrarianPreferences(preferences: LibrarianPreferences): string {
-	return `Librarian defaults: cache=${formatCachePreference(preferences.cacheMode)}, model=${preferences.model ?? "auto"}, thinkingLevel=${preferences.thinkingLevel}. Config: ${getCacheConfigPath()}`;
+  return `Librarian defaults: cache=${formatCachePreference(preferences.cacheMode)}, model=${preferences.model ?? "auto"}, thinkingLevel=${preferences.thinkingLevel}. Config: ${getCacheConfigPath()}`;
 }
 
-function notifyCommand(ctx: ExtensionContext, message: string, type: "info" | "warning" | "error" = "info"): void {
-	if (ctx.hasUI) {
-		ctx.ui.notify(message, type);
-		return;
-	}
+function notifyCommand(
+  ctx: ExtensionContext,
+  message: string,
+  type: "info" | "warning" | "error" = "info",
+): void {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, type);
+    return;
+  }
 
-	console.error(message);
+  console.error(message);
 }
 
 function modelRef(model: any): string {
-	return `${model.provider}/${model.id}`;
+  return `${model.provider}/${model.id}`;
 }
 
 function modelCostScore(model: any): number {
-	const cost = model.cost ?? {};
-	const input = typeof cost.input === "number" ? cost.input : 0;
-	const output = typeof cost.output === "number" ? cost.output : 0;
-	return input + output;
+  const cost = model.cost ?? {};
+  const input = typeof cost.input === "number" ? cost.input : 0;
+  const output = typeof cost.output === "number" ? cost.output : 0;
+  return input + output;
 }
 
 function rankLibrarianModel(model: any): number {
-	const text = `${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
-	let score = modelCostScore(model) * 1_000_000;
-	if (model.reasoning) score += 50;
-	if (/\b(?:mini|nano|haiku|flash|lite|small|fast|instant)\b/.test(text)) score -= 10;
-	if (HEAVY_MODEL_PATTERN.test(text)) score += 1_000;
-	if ((model.contextWindow ?? 0) < 32_000) score += 100;
-	return score;
+  const text = `${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
+  let score = modelCostScore(model) * 1_000_000;
+  if (model.reasoning) score += 50;
+  if (/\b(?:mini|nano|haiku|flash|lite|small|fast|instant)\b/.test(text)) score -= 10;
+  if (HEAVY_MODEL_PATTERN.test(text)) score += 1_000;
+  if ((model.contextWindow ?? 0) < 32_000) score += 100;
+  return score;
 }
 
 function isPreferredFastLibrarianModel(model: any): boolean {
-	const text = `${model.provider ?? ""} ${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
-	if (HEAVY_MODEL_PATTERN.test(text)) return false;
-	return PREFERRED_FAST_MODEL_PATTERNS.some((pattern) => pattern.test(text));
+  const text = `${model.provider ?? ""} ${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
+  if (HEAVY_MODEL_PATTERN.test(text)) return false;
+  return PREFERRED_FAST_MODEL_PATTERNS.some((pattern) => pattern.test(text));
 }
 
 function rankPreferredFastLibrarianModel(model: any): number {
-	const text = `${model.provider ?? ""} ${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
-	let score = rankLibrarianModel(model);
-	const patternIndex = PREFERRED_FAST_MODEL_PATTERNS.findIndex((pattern) => pattern.test(text));
-	if (patternIndex >= 0) score += patternIndex * 100;
-	return score;
+  const text = `${model.provider ?? ""} ${model.id ?? ""} ${model.name ?? ""}`.toLowerCase();
+  let score = rankLibrarianModel(model);
+  const patternIndex = PREFERRED_FAST_MODEL_PATTERNS.findIndex((pattern) => pattern.test(text));
+  if (patternIndex >= 0) score += patternIndex * 100;
+  return score;
 }
 
 async function findAvailableModel(
-	ctx: ModelSelectionContext,
-	modelPreference: string,
+  ctx: ModelSelectionContext,
+  modelPreference: string,
 ): Promise<any | undefined> {
-	const available = await ctx.modelRegistry.getAvailable();
-	const trimmed = modelPreference.trim();
-	const provider = trimmed.includes("/") ? trimmed.split("/")[0].toLowerCase() : ctx.model?.provider?.toLowerCase();
-	const id = trimmed.includes("/") ? trimmed.split("/").slice(1).join("/").toLowerCase() : trimmed.toLowerCase();
-
-	const exact = available.find(
-		(model) => model.id.toLowerCase() === id && (!provider || model.provider.toLowerCase() === provider),
-	);
-	if (exact) return exact;
-
-	const partial = available.find(
-		(model) => model.id.toLowerCase().includes(id) && (!provider || model.provider.toLowerCase() === provider),
-	);
-	if (partial) return partial;
-
-	if (!provider) {
-		const uniqueById = available.filter((model) => model.id.toLowerCase() === id);
-		if (uniqueById.length === 1) return uniqueById[0];
-	}
-
-	return undefined;
+  const available = await ctx.modelRegistry.getAvailable();
+  const trimmed = modelPreference.trim();
+  const provider = trimmed.includes("/")
+    ? trimmed.split("/")[0].toLowerCase()
+    : ctx.model?.provider?.toLowerCase();
+  const id = trimmed.includes("/")
+    ? trimmed.split("/").slice(1).join("/").toLowerCase()
+    : trimmed.toLowerCase();
+
+  const exact = available.find(
+    (model) =>
+      model.id.toLowerCase() === id && (!provider || model.provider.toLowerCase() === provider),
+  );
+  if (exact) return exact;
+
+  const partial = available.find(
+    (model) =>
+      model.id.toLowerCase().includes(id) &&
+      (!provider || model.provider.toLowerCase() === provider),
+  );
+  if (partial) return partial;
+
+  if (!provider) {
+    const uniqueById = available.filter((model) => model.id.toLowerCase() === id);
+    if (uniqueById.length === 1) return uniqueById[0];
+  }
+
+  return undefined;
 }
 
 // A model the catalog advertises but the active provider/subscription cannot
@@ -734,23 +874,26 @@ async function findAvailableModel(
 // access-gated tiers). These are NOT transient: the same model keeps failing,
 // so we fall back to the next candidate instead of retrying it.
 const MODEL_AVAILABILITY_ERROR_PATTERN =
-	/\b(?:404|403|not[_ ]?found(?:[_ ]?error)?|model[_ ]?not[_ ]?found(?:[_ ]?error)?|no such model|unknown model|does not exist|is not available|not available|model[_ ]?not[_ ]?available|unsupported model|invalid model|forbidden|access[ _-]?denied|permission[ _-]?denied|not[ _-]?entitled|do(?:es)? not have access)\b/i;
+  /\b(?:404|403|not[_ ]?found(?:[_ ]?error)?|model[_ ]?not[_ ]?found(?:[_ ]?error)?|no such model|unknown model|does not exist|is not available|not available|model[_ ]?not[_ ]?available|unsupported model|invalid model|forbidden|access[ _-]?denied|permission[ _-]?denied|not[ _-]?entitled|do(?:es)? not have access)\b/i;
 
 function isModelAvailabilityError(message: string | undefined): boolean {
-	if (!message) return false;
-	return MODEL_AVAILABILITY_ERROR_PATTERN.test(message);
+  if (!message) return false;
+  return MODEL_AVAILABILITY_ERROR_PATTERN.test(message);
 }
 
 type LibrarianCandidate = { model: any; details: LibrarianModelDetails };
 
-function withLibrarianFallbackReason(candidate: LibrarianCandidate, previous: LibrarianCandidate): LibrarianCandidate {
-	return {
-		model: candidate.model,
-		details: {
-			...candidate.details,
-			selectionReason: `${candidate.details.selectionReason} (Fell back from ${previous.details.modelRef} after a model-availability error.)`,
-		},
-	};
+function withLibrarianFallbackReason(
+  candidate: LibrarianCandidate,
+  previous: LibrarianCandidate,
+): LibrarianCandidate {
+  return {
+    model: candidate.model,
+    details: {
+      ...candidate.details,
+      selectionReason: `${candidate.details.selectionReason} (Fell back from ${previous.details.modelRef} after a model-availability error.)`,
+    },
+  };
 }
 
 // Build an ordered list of model candidates to try. The catalog can advertise
@@ -758,953 +901,1268 @@ function withLibrarianFallbackReason(candidate: LibrarianCandidate, previous: Li
 // these in order and skip ones that fail with a model-availability error,
 // ultimately falling back to the known-good current session model.
 async function buildLibrarianCandidates(
-	ctx: ModelSelectionContext,
-	modelPreference: string | undefined,
-	thinkingLevel: ThinkingLevel,
+  ctx: ModelSelectionContext,
+  modelPreference: string | undefined,
+  thinkingLevel: ThinkingLevel,
 ): Promise<LibrarianCandidate[]> {
-	const candidates: LibrarianCandidate[] = [];
-	const seen = new Set<string>();
-	const push = (model: any, details: LibrarianModelDetails) => {
-		if (!model) return;
-		const key = `${model.provider}/${model.id}`.toLowerCase();
-		if (seen.has(key)) return;
-		seen.add(key);
-		candidates.push({ model, details });
-	};
-
-	const normalized = modelPreference?.trim();
-	let configuredMatched: any | undefined;
-	if (normalized) {
-		configuredMatched = await findAvailableModel(ctx, normalized);
-		if (configuredMatched) {
-			push(configuredMatched, {
-				modelRef: modelRef(configuredMatched),
-				provider: configuredMatched.provider,
-				modelId: configuredMatched.id,
-				thinkingLevel: resolveThinkingLevel(configuredMatched, thinkingLevel),
-				autoSelected: false,
-				selectionReason: "Using the configured librarian model.",
-			});
-		}
-	}
-
-	const available = await getAutoSelectableModels(ctx);
-	const preferred = available.filter(isPreferredFastLibrarianModel);
-	const ranked = preferred.length > 0
-		? [...preferred].sort((a, b) => rankPreferredFastLibrarianModel(a) - rankPreferredFastLibrarianModel(b))
-		: [...available].sort((a, b) => rankLibrarianModel(a) - rankLibrarianModel(b));
-	const fallbackText = normalized && !configuredMatched
-		? ` Configured model ${normalized} was unavailable, so Librarian fell back to auto-selection.`
-		: "";
-	ranked.forEach((model, index) => {
-		const topReason = preferred.length > 0
-			? `Selected a preferred fast Librarian model.${fallbackText}`
-			: `Selected the cheapest available model because no preferred fast Librarian model was available.${fallbackText}`;
-		push(model, {
-			modelRef: modelRef(model),
-			provider: model.provider,
-			modelId: model.id,
-			thinkingLevel: resolveThinkingLevel(model, thinkingLevel),
-			autoSelected: true,
-			selectionReason: index === 0 ? topReason : `Auto-selected ${modelRef(model)} as a lower-ranked fallback.`,
-		});
-	});
-
-	// Final fallback: the active session model is known to be servable.
-	if (ctx.model && isModelInScope(ctx, ctx.model)) {
-		push(ctx.model, {
-			modelRef: modelRef(ctx.model),
-			provider: ctx.model.provider,
-			modelId: ctx.model.id,
-			thinkingLevel: resolveThinkingLevel(ctx.model, thinkingLevel),
-			autoSelected: true,
-			selectionReason: `Used the current session model ${modelRef(ctx.model)} as a final fallback.`,
-		});
-	}
-
-	if (candidates.length === 0) {
-		throw new Error(
-			hasModelScope(ctx)
-				? "No authenticated models are available for Librarian in the current session model scope. Adjust the scope, log in, or configure an API key."
-				: "No authenticated models are available for Librarian. Log in or configure an API key first.",
-		);
-	}
-
-	return candidates;
+  const candidates: LibrarianCandidate[] = [];
+  const seen = new Set<string>();
+  const push = (model: any, details: LibrarianModelDetails) => {
+    if (!model) return;
+    const key = `${model.provider}/${model.id}`.toLowerCase();
+    if (seen.has(key)) return;
+    seen.add(key);
+    candidates.push({ model, details });
+  };
+
+  const normalized = modelPreference?.trim();
+  let configuredMatched: any | undefined;
+  if (normalized) {
+    configuredMatched = await findAvailableModel(ctx, normalized);
+    if (configuredMatched) {
+      push(configuredMatched, {
+        modelRef: modelRef(configuredMatched),
+        provider: configuredMatched.provider,
+        modelId: configuredMatched.id,
+        thinkingLevel: resolveThinkingLevel(configuredMatched, thinkingLevel),
+        autoSelected: false,
+        selectionReason: "Using the configured librarian model.",
+      });
+    }
+  }
+
+  const available = await getAutoSelectableModels(ctx);
+  const preferred = available.filter(isPreferredFastLibrarianModel);
+  const ranked =
+    preferred.length > 0
+      ? [...preferred].sort(
+          (a, b) => rankPreferredFastLibrarianModel(a) - rankPreferredFastLibrarianModel(b),
+        )
+      : [...available].sort((a, b) => rankLibrarianModel(a) - rankLibrarianModel(b));
+  const fallbackText =
+    normalized && !configuredMatched
+      ? ` Configured model ${normalized} was unavailable, so Librarian fell back to auto-selection.`
+      : "";
+  ranked.forEach((model, index) => {
+    const topReason =
+      preferred.length > 0
+        ? `Selected a preferred fast Librarian model.${fallbackText}`
+        : `Selected the cheapest available model because no preferred fast Librarian model was available.${fallbackText}`;
+    push(model, {
+      modelRef: modelRef(model),
+      provider: model.provider,
+      modelId: model.id,
+      thinkingLevel: resolveThinkingLevel(model, thinkingLevel),
+      autoSelected: true,
+      selectionReason:
+        index === 0 ? topReason : `Auto-selected ${modelRef(model)} as a lower-ranked fallback.`,
+    });
+  });
+
+  // Final fallback: the active session model is known to be servable.
+  if (ctx.model && isModelInScope(ctx, ctx.model)) {
+    push(ctx.model, {
+      modelRef: modelRef(ctx.model),
+      provider: ctx.model.provider,
+      modelId: ctx.model.id,
+      thinkingLevel: resolveThinkingLevel(ctx.model, thinkingLevel),
+      autoSelected: true,
+      selectionReason: `Used the current session model ${modelRef(ctx.model)} as a final fallback.`,
+    });
+  }
+
+  if (candidates.length === 0) {
+    throw new Error(
+      hasModelScope(ctx)
+        ? "No authenticated models are available for Librarian in the current session model scope. Adjust the scope, log in, or configure an API key."
+        : "No authenticated models are available for Librarian. Log in or configure an API key first.",
+    );
+  }
+
+  return candidates;
+}
+
+const UNICODE_SPACES_PATTERN = /[\u00A0\u2000-\u200A\u202F\u205F\u3000]/g;
+
+/**
+ * Mirrors normalizeWindowsShellPath from dist/utils/paths.js. No-op on
+ * non-win32 paths.
+ */
+function normalizeWindowsShellPathLocal(filePath: string): string {
+  if (!filePath.startsWith("/") || filePath.startsWith("//") || filePath.includes("\\"))
+    return filePath;
+  const match = filePath.match(/^\/(?:mnt\/|cygdrive\/)?([a-z])(?:\/(.*))?$/i);
+  if (!match) return filePath;
+  const suffix = match[2]?.replaceAll("/", "\\");
+  return `${match[1].toUpperCase()}:\\${suffix ?? ""}`;
+}
+
+/**
+ * Mirrors Pi's normalizePath (dist/utils/paths.js). On win32, Git Bash / WSL
+ * drive-path normalisation always runs; only tilde expansion is gated by
+ * expandTilde.
+ */
+function normalizePath(
+  input: string,
+  opts: { normalizeUnicodeSpaces?: boolean; stripAtPrefix?: boolean; expandTilde?: boolean } = {},
+): string {
+  const { normalizeUnicodeSpaces = false, stripAtPrefix = false, expandTilde = true } = opts;
+  let p = input;
+  if (normalizeUnicodeSpaces) p = p.replace(UNICODE_SPACES_PATTERN, " ");
+  if (stripAtPrefix && p.startsWith("@")) p = p.slice(1);
+  if (process.platform === "win32") p = normalizeWindowsShellPathLocal(p);
+  if (expandTilde) {
+    const home = os.homedir();
+    if (p === "~") p = home;
+    else if (p.startsWith("~/") || (process.platform === "win32" && p.startsWith("~\\")))
+      p = path.join(home, p.slice(2));
+  }
+  if (/^file:\/\//.test(p)) p = fileURLToPath(p);
+  return p;
+}
+
+/**
+ * Mirrors Pi's resolveToCwd (dist/core/tools/path-utils.js). Exposed via
+ * __test__ for parity tests; not imported by other extensions.
+ */
+function resolveToCwd(rawPath: string, cwd: string): string {
+  const normalized = normalizePath(rawPath, { normalizeUnicodeSpaces: true, stripAtPrefix: true });
+  const base = normalizePath(cwd);
+  return path.isAbsolute(normalized) ? path.resolve(normalized) : path.resolve(base, normalized);
+}
+
+/** Mirrors tryMacOSScreenshotPath from dist/core/tools/path-utils.js */
+function tryMacOSScreenshotPathVariant(filePath: string): string {
+  return filePath.replace(/ (AM|PM)\./gi, " $1.");
+}
+/** Mirrors tryNFDVariant from dist/core/tools/path-utils.js */
+function tryNFDPathVariant(filePath: string): string {
+  return filePath.normalize("NFD");
+}
+/** Mirrors tryCurlyQuoteVariant from dist/core/tools/path-utils.js */
+function tryCurlyQuotePathVariant(filePath: string): string {
+  return filePath.replace(/'/g, "’");
+}
+/**
+ * Returns all read path candidates including Pi's resolveReadPathAsync fallback
+ * variants. Used only for the read tool guard; grep/find/ls use resolveToCwd only.
+ */
+function getReadPathCandidates(resolved: string): string[] {
+  const nfd = tryNFDPathVariant(resolved);
+  return [
+    resolved,
+    tryMacOSScreenshotPathVariant(resolved),
+    nfd,
+    tryCurlyQuotePathVariant(resolved),
+    tryCurlyQuotePathVariant(nfd),
+  ];
 }
 
 function resolveToolPath(cwd: string, rawPath: string): string {
-	const normalized = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
-	return path.isAbsolute(normalized) ? path.resolve(normalized) : path.resolve(cwd, normalized);
-}
-
-function getBlockedBashReason(command: string, options: { workspace: string; cacheRoot: string; cacheEnabled: boolean }): string | undefined {
-	if (!options.cacheEnabled && command.includes(options.cacheRoot)) {
-		return "Local repo checkout cache is disabled for this Librarian call.";
-	}
-
-	let scan = command.split(options.workspace).join("<WORKSPACE>");
-	if (options.cacheEnabled) scan = scan.split(options.cacheRoot).join("<CACHE>");
-	if (/(^|[\n;&|()])\s*\//.test(scan)) return "Librarian bash blocks absolute-path executables.";
-
-	const destructiveLocal = /(^|[\n;&|()])\s*(?:sudo|su|rm|rmdir|mv|cp|chmod|chown|dd|truncate|killall|pkill|launchctl|osascript|pbcopy|pbpaste|eval|exec|xargs)(?=$|[\s;&|()])/;
-	if (destructiveLocal.test(scan)) return "Librarian bash blocks destructive/local side-effect commands.";
-
-	const extraNetworkOrShell = /(^|[\n;&|()])\s*(?:curl|wget|nc|netcat|ssh|scp|sftp|rsync|bash|sh|zsh|fish|python|python3|perl|ruby|node|deno)(?=$|[\s;&|()])/;
-	if (extraNetworkOrShell.test(scan)) return "Librarian bash is limited to gh/git and simple local inspection commands.";
-
-	if (/(^|[\s"'=])(?:~\/|\$HOME\b|\/etc\/|\/var\/|\/private\/|\/root\/|\/Users\/|\/home\/|\/opt\/)/.test(scan)) {
-		return "Librarian bash may only access its workspace and approved cache root.";
-	}
-
-	if (/\bgh\s+auth\s+token\b/.test(scan) || /(^|[\n;&|()])\s*(?:env|printenv|set|export|declare|echo|printf)(?=$|[\s;&|()])/.test(scan)) {
-		return "Librarian bash blocks credential/environment inspection.";
-	}
-
-	if (/\bgh\s+api\b(?=.*(?:(?:-X|--method)\s*(?:POST|PUT|PATCH|DELETE)\b|(?:-f|--field|-F|--raw-field|--input)\b))/i.test(scan)) {
-		return "Librarian bash allows read-only GitHub API calls only.";
-	}
-
-	if (/\bgh\s+(?:repo\s+(?:delete|edit|archive|fork|create)|pr\s+(?:merge|close|edit)|issue\s+(?:close|edit|delete)|release\s+(?:create|delete|upload)|workflow\s+run|gist\s+(?:create|delete|edit))\b/.test(scan)) {
-		return "Librarian bash blocks mutating gh commands.";
-	}
-
-	if (/\bgit\b[^\n;&|]*\b(?:push|commit|merge|rebase|clean|reset|tag)\b/.test(scan)) {
-		return "Librarian bash blocks mutating git commands except local checkout/fetch for cache use.";
-	}
-
-	return undefined;
+  const normalized = rawPath.startsWith("@") ? rawPath.slice(1) : rawPath;
+  return path.isAbsolute(normalized) ? path.resolve(normalized) : path.resolve(cwd, normalized);
+}
+
+function getBlockedBashReason(
+  command: string,
+  options: { workspace: string; cacheRoot: string; cacheEnabled: boolean },
+): string | undefined {
+  if (!options.cacheEnabled && command.includes(options.cacheRoot)) {
+    return "Local repo checkout cache is disabled for this Librarian call.";
+  }
+
+  let scan = command.split(options.workspace).join("<WORKSPACE>");
+  if (options.cacheEnabled) scan = scan.split(options.cacheRoot).join("<CACHE>");
+  if (/(^|[\n;&|()])\s*\//.test(scan)) return "Librarian bash blocks absolute-path executables.";
+
+  const destructiveLocal =
+    /(^|[\n;&|()])\s*(?:sudo|su|rm|rmdir|mv|cp|chmod|chown|dd|truncate|killall|pkill|launchctl|osascript|pbcopy|pbpaste|eval|exec|xargs)(?=$|[\s;&|()])/;
+  if (destructiveLocal.test(scan))
+    return "Librarian bash blocks destructive/local side-effect commands.";
+
+  const extraNetworkOrShell =
+    /(^|[\n;&|()])\s*(?:curl|wget|nc|netcat|ssh|scp|sftp|rsync|bash|sh|zsh|fish|python|python3|perl|ruby|node|deno)(?=$|[\s;&|()])/;
+  if (extraNetworkOrShell.test(scan))
+    return "Librarian bash is limited to gh/git and simple local inspection commands.";
+
+  if (
+    /(^|[\s"'=])(?:~\/|\$HOME\b|\/etc\/|\/var\/|\/private\/|\/root\/|\/Users\/|\/home\/|\/opt\/)/.test(
+      scan,
+    )
+  ) {
+    return "Librarian bash may only access its workspace and approved cache root.";
+  }
+
+  if (
+    /\bgh\s+auth\s+token\b/.test(scan) ||
+    /(^|[\n;&|()])\s*(?:env|printenv|set|export|declare|echo|printf)(?=$|[\s;&|()])/.test(scan)
+  ) {
+    return "Librarian bash blocks credential/environment inspection.";
+  }
+
+  if (
+    /\bgh\s+api\b(?=.*(?:(?:-X|--method)\s*(?:POST|PUT|PATCH|DELETE)\b|(?:-f|--field|-F|--raw-field|--input)\b))/i.test(
+      scan,
+    )
+  ) {
+    return "Librarian bash allows read-only GitHub API calls only.";
+  }
+
+  if (
+    /\bgh\s+(?:repo\s+(?:delete|edit|archive|fork|create)|pr\s+(?:merge|close|edit)|issue\s+(?:close|edit|delete)|release\s+(?:create|delete|upload)|workflow\s+run|gist\s+(?:create|delete|edit))\b/.test(
+      scan,
+    )
+  ) {
+    return "Librarian bash blocks mutating gh commands.";
+  }
+
+  if (/\bgit\b[^\n;&|]*\b(?:push|commit|merge|rebase|clean|reset|tag)\b/.test(scan)) {
+    return "Librarian bash blocks mutating git commands except local checkout/fetch for cache use.";
+  }
+
+  return undefined;
 }
 
 function createLibrarianRuntimeGuardExtension(options: {
-	maxTurns: number;
-	workspace: string;
-	cacheRoot: string;
-	cacheEnabled: boolean;
+  maxTurns: number;
+  workspace: string;
+  cacheRoot: string;
+  cacheEnabled: boolean;
 }): ExtensionFactory {
-	return (pi) => {
-		let currentTurn = 0;
-
-		pi.on("turn_start", async (event) => {
-			currentTurn = event.turnIndex;
-		});
-
-		pi.on("tool_call", async (event) => {
-			if (currentTurn >= options.maxTurns - 1) {
-				return {
-					block: true,
-					reason: `Tool use is disabled on final Librarian turn ${options.maxTurns}/${options.maxTurns}. Answer now with the evidence already gathered.`,
-				};
-			}
-
-			if (event.toolName === "read") {
-				const input = event.input as { path?: unknown };
-				if (typeof input.path !== "string") return undefined;
-				const resolved = resolveToolPath(options.workspace, input.path);
-				const realPath = await fs.realpath(resolved).catch(() => resolved);
-				const allowed =
-					isInside(options.workspace, realPath) ||
-					(options.cacheEnabled && isInside(options.cacheRoot, realPath));
-				if (!allowed) return { block: true, reason: `Librarian read is limited to its workspace/cache: ${realPath}` };
-			}
-
-			if (event.toolName === "bash") {
-				const input = event.input as { command?: unknown; timeout?: unknown };
-				if (typeof input.timeout !== "number") input.timeout = DEFAULT_BASH_TIMEOUT_SECONDS;
-
-				const command = typeof input.command === "string" ? input.command : "";
-				if (!options.cacheEnabled && /\b(?:git\s+clone|gh\s+repo\s+clone)\b/.test(command)) {
-					return { block: true, reason: "Local repo checkout cache is disabled for this Librarian call." };
-				}
-
-				const blockedReason = getBlockedBashReason(command, options);
-				if (blockedReason) return { block: true, reason: blockedReason };
-			}
-
-			return undefined;
-		});
-
-		pi.on("tool_result", async (event) => ({
-			content: [
-				...(event.content ?? []),
-				{
-					type: "text",
-					text: `\n\n[librarian turn budget] turn ${Math.min(currentTurn + 1, options.maxTurns)}/${options.maxTurns}`,
-				},
-			],
-		}));
-	};
+  return (pi) => {
+    let currentTurn = 0;
+
+    pi.on("turn_start", async (event) => {
+      currentTurn = event.turnIndex;
+    });
+
+    pi.on("tool_call", async (event) => {
+      if (currentTurn >= options.maxTurns - 1) {
+        return {
+          block: true,
+          reason: `Tool use is disabled on final Librarian turn ${options.maxTurns}/${options.maxTurns}. Answer now with the evidence already gathered.`,
+        };
+      }
+
+      if (event.toolName === "read") {
+        const input = event.input as { path?: unknown };
+        if (typeof input.path !== "string") return undefined;
+        // Canonicalize allowed roots. A path is allowed if it is inside EITHER
+        // the original root (options.workspace / options.cacheRoot) OR its
+        // realpath'd form. This handles both: a realpath'd file under a
+        // symlinked alias workspace (lexical match on original root) and an
+        // existing file canonicalized beyond the alias (match on real root).
+        const realWorkspace = await fs
+          .realpath(options.workspace)
+          .catch(() => path.resolve(options.workspace));
+        const realCacheRoot = await fs
+          .realpath(options.cacheRoot)
+          .catch(() => path.resolve(options.cacheRoot));
+        function isAllowedPath(p: string): boolean {
+          return (
+            isInside(options.workspace, p) ||
+            isInside(realWorkspace, p) ||
+            (options.cacheEnabled && (isInside(options.cacheRoot, p) || isInside(realCacheRoot, p)))
+          );
+        }
+        const resolved = resolveToolPath(options.workspace, input.path);
+        const realPath = await fs.realpath(resolved).catch(() => resolved);
+        if (!isAllowedPath(realPath))
+          return {
+            block: true,
+            reason: `Librarian read is limited to its workspace/cache: ${realPath}`,
+          };
+        // Pi-effective path check (monotonic: block if either resolution is
+        // outside). For the read tool, also check Pi's resolveReadPathAsync
+        // fallback variants so a missing file whose variant resolves outside is
+        // not silently allowed.
+        try {
+          const piResolved = resolveToCwd(input.path, options.workspace);
+          const candidates = getReadPathCandidates(piResolved);
+          // Deliberate policy: all candidates are checked regardless of existence (not
+          // Pi's existence-ordered selection) so the guard cannot be raced by creating
+          // a variant between the hook and the read. Trade-off: a read is blocked when
+          // an escaping variant symlink sits next to a safe primary file.
+          for (const candidate of candidates) {
+            const candidateRealPath = await fs.realpath(candidate).catch(() => candidate);
+            if (!isAllowedPath(candidateRealPath))
+              return {
+                block: true,
+                reason: `Librarian read is limited to its workspace/cache: ${candidateRealPath}`,
+              };
+          }
+        } catch {
+          return { block: true, reason: "Librarian read path could not be resolved safely." };
+        }
+      }
+
+      if (event.toolName === "bash") {
+        const input = event.input as { command?: unknown; timeout?: unknown };
+        if (typeof input.timeout !== "number") input.timeout = DEFAULT_BASH_TIMEOUT_SECONDS;
+
+        const command = typeof input.command === "string" ? input.command : "";
+        if (!options.cacheEnabled && /\b(?:git\s+clone|gh\s+repo\s+clone)\b/.test(command)) {
+          return {
+            block: true,
+            reason: "Local repo checkout cache is disabled for this Librarian call.",
+          };
+        }
+
+        const blockedReason = getBlockedBashReason(command, options);
+        if (blockedReason) return { block: true, reason: blockedReason };
+      }
+
+      return undefined;
+    });
+
+    pi.on("tool_result", async (event) => ({
+      content: [
+        ...(event.content ?? []),
+        {
+          type: "text",
+          text: `\n\n[librarian turn budget] turn ${Math.min(currentTurn + 1, options.maxTurns)}/${options.maxTurns}`,
+        },
+      ],
+    }));
+  };
 }
 
 function buildSystemPrompt(options: {
-	workspace: string;
-	maxSearchResults: number;
-	cacheEnabled: boolean;
-	cacheRoot: string;
+  workspace: string;
+  maxSearchResults: number;
+  cacheEnabled: boolean;
+  cacheRoot: string;
 }): string {
-	const cacheSection = options.cacheEnabled
-		? `\nLocal checkout cache is ENABLED for this call.\n- Cache root: ${options.cacheRoot}\n- Use checkout path pattern: ${options.cacheRoot}/github.com/<owner>/<repo>\n- Reuse an existing checkout when it has a .git directory. Fetch/prune before relying on it: git -C "$DIR" fetch --all --prune --tags --quiet\n- If missing, clone with gh repo clone "$REPO" "$DIR" (or git clone https://github.com/$REPO.git "$DIR").\n- If a ref/branch/SHA is requested, fetch it and check it out locally before citing files from that ref.\n- After using a checkout, update its cache marker: touch "$DIR/${CACHE_MARKER_FILE}"\n- Prefer local rg/read inside cached checkouts once a repo is cloned, and cite absolute cached paths with line ranges.\n- Clone only repositories that are relevant to the query; do not bulk-clone broad owner/org scopes unless necessary.`
-		: `\nLocal checkout cache is DISABLED for this call.\n- Do not clone repositories.\n- Use gh search/API/tree/contents calls and cache only necessary proof files under ${options.workspace}/repos/<owner>/<repo>/<path>.`;
+  const cacheSection = options.cacheEnabled
+    ? `\nLocal checkout cache is ENABLED for this call.\n- Cache root: ${options.cacheRoot}\n- Use checkout path pattern: ${options.cacheRoot}/github.com/<owner>/<repo>\n- Reuse an existing checkout when it has a .git directory. Fetch/prune before relying on it: git -C "$DIR" fetch --all --prune --tags --quiet\n- If missing, clone with gh repo clone "$REPO" "$DIR" (or git clone https://github.com/$REPO.git "$DIR").\n- If a ref/branch/SHA is requested, fetch it and check it out locally before citing files from that ref.\n- After using a checkout, update its cache marker: touch "$DIR/${CACHE_MARKER_FILE}"\n- Prefer local rg/read inside cached checkouts once a repo is cloned, and cite absolute cached paths with line ranges.\n- Clone only repositories that are relevant to the query; do not bulk-clone broad owner/org scopes unless necessary.`
+    : `\nLocal checkout cache is DISABLED for this call.\n- Do not clone repositories.\n- Use gh search/API/tree/contents calls and cache only necessary proof files under ${options.workspace}/repos/<owner>/<repo>/<path>.`;
 
-	return `You are Librarian, an evidence-first GitHub code scout running inside pi.\n\nUse only the available bash/read tools. Use gh, jq, rg, find/fd, ls, stat, mkdir, base64, and nl -ba for GitHub reconnaissance and numbered evidence. Use read for focused local file inspection.\n\nWorkspace: ${options.workspace}\nDefault gh search limit: ${options.maxSearchResults}\nTurn budget: ${MAX_TURNS} turns total, including your final answer. Stop searching once you have enough evidence.\n${cacheSection}\n\nPerformance guidance:\n- Prefer fast, parallel exploration. When probes are independent, issue multiple separate tool calls in the same assistant turn instead of waiting for each result one-by-one.\n- Aim for 4-8 independent bash/read calls in an exploration turn when useful: parallel gh searches, tree probes, contents fetches, and targeted file reads.\n- Keep dependent work sequential, and avoid concurrent writes to the same file, checkout, or cache directory.\n\nNon-negotiable constraints:\n- Never treat gh search snippets as proof by themselves. Use fetched files or local checkouts for code-content claims.\n- Keep temporary workspace writes under ${options.workspace}/repos unless local checkout cache is enabled, in which case writes under the cache root are also allowed.
+  return `You are Librarian, an evidence-first GitHub code scout running inside pi.\n\nUse the available bash and read tools for local inspection, and any configured MCP tools for additional context (MCP tools run without confirmation inside this subagent; use them only to gather evidence, not for state-changing actions unless the task explicitly asks; MCP access requires host Pi >=1.0.4, older hosts degrade to no MCP). Use gh, jq, rg, find/fd, ls, stat, mkdir, base64, and nl -ba for GitHub reconnaissance and numbered evidence. Use read for focused local file inspection.\n\nWorkspace: ${options.workspace}\nDefault gh search limit: ${options.maxSearchResults}\nTurn budget: ${MAX_TURNS} turns total, including your final answer. Stop searching once you have enough evidence.\n${cacheSection}\n\nPerformance guidance:\n- Prefer fast, parallel exploration. When probes are independent, issue multiple separate tool calls in the same assistant turn instead of waiting for each result one-by-one.\n- Aim for 4-8 independent bash/read calls in an exploration turn when useful: parallel gh searches, tree probes, contents fetches, and targeted file reads.\n- Keep dependent work sequential, and avoid concurrent writes to the same file, checkout, or cache directory.\n\nNon-negotiable constraints:\n- Never treat gh search snippets as proof by themselves. Use fetched files or local checkouts for code-content claims.\n- Keep temporary workspace writes under ${options.workspace}/repos unless local checkout cache is enabled, in which case writes under the cache root are also allowed.
 - A runtime guard blocks destructive shell commands, credential/environment inspection, and reads outside the workspace/cache.\n- Never paste whole files. Use short snippets only when they clarify the evidence.\n- If evidence is partial or access fails (404/403), state the limitation clearly.\n- Do not present anything as fact unless it appeared in tool output or in a file you read.\n\nRecommended search flow:\n1. If symbols/text are known, start with gh search code and the provided repo/owner filters.\n2. If a repo is known but paths are unclear, resolve the default branch and inspect the git tree or contents API.\n3. Fetch or clone only the files/repos required to prove the answer.\n4. Use rg/read/nl -ba locally to produce stable path and line evidence.\n\nUseful gh patterns:\n- gh repo view "$REPO" --json defaultBranchRef --jq '.defaultBranchRef.name'\n- gh search code '<terms>' --json path,repository,sha,url,textMatches --limit ${options.maxSearchResults}\n- gh api "repos/$REPO/git/trees/$REF?recursive=1" > tree.json\n- gh api "repos/$REPO/contents/$FILE?ref=$REF" --jq .content | tr -d '\\n' | base64 --decode > "repos/$REPO/$FILE"\n- rg -n '<pattern>' '<local path>'\n- nl -ba '<local file>' | sed -n '10,30p'\n\nOutput format, exact order:\n## Summary\n1-3 concise sentences.\n## Locations\n- \`path\` or \`path:lineStart-lineEnd\` — what is here and why it matters; include GitHub URL when useful. If nothing relevant is found, write \`- (none)\`.\n## Evidence\n- \`path\` or \`path:lineStart-lineEnd\` — what this proves. Include concise snippets only if useful.\n## Searched\nOnly include when incomplete/not found or when the search path matters. List queries, filters, and probes used.\n## Next steps\nOptional: 1-3 narrow follow-up checks for remaining ambiguity.`;
 }
 
-function buildUserPrompt(query: string, repos: string[], owners: string[], maxSearchResults: number, cache: CacheDetails): string {
-	return `Task: locate and cite exact GitHub code locations that answer the query.\n\nQuery: ${query}\nRepository filters: ${repos.length ? repos.join(", ") : "(none)"}\nOwner filters: ${owners.length ? owners.join(", ") : "(none)"}\nMax search results per gh search call: ${maxSearchResults}\nLocal checkout cache: ${cache.mode === "enabled" ? `enabled at ${cache.root}` : "disabled"}\nCache decision: ${cache.decisionReason}\n\nRespond directly with concise, citation-heavy findings. Always pass --limit ${maxSearchResults} to gh search code unless a narrower command is clearly better.`;
+function buildUserPrompt(
+  query: string,
+  repos: string[],
+  owners: string[],
+  maxSearchResults: number,
+  cache: CacheDetails,
+): string {
+  return `Task: locate and cite exact GitHub code locations that answer the query.\n\nQuery: ${query}\nRepository filters: ${repos.length ? repos.join(", ") : "(none)"}\nOwner filters: ${owners.length ? owners.join(", ") : "(none)"}\nMax search results per gh search call: ${maxSearchResults}\nLocal checkout cache: ${cache.mode === "enabled" ? `enabled at ${cache.root}` : "disabled"}\nCache decision: ${cache.decisionReason}\n\nRespond directly with concise, citation-heavy findings. Always pass --limit ${maxSearchResults} to gh search code unless a narrower command is clearly better.`;
 }
 
 function createEmptyUsage(): Usage {
-	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, totalTokens: 0, cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 } };
+  return {
+    input: 0,
+    output: 0,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: 0,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
 }
 
 function addUsage(total: Usage, usage: Usage): void {
-	total.input += usage.input || 0;
-	total.output += usage.output || 0;
-	total.cacheRead += usage.cacheRead || 0;
-	total.cacheWrite += usage.cacheWrite || 0;
-	if (usage.cacheWrite1h !== undefined) total.cacheWrite1h = (total.cacheWrite1h ?? 0) + usage.cacheWrite1h;
-	if (usage.reasoning !== undefined) total.reasoning = (total.reasoning ?? 0) + usage.reasoning;
-	total.totalTokens += usage.totalTokens || 0;
-	total.cost.input += usage.cost?.input || 0;
-	total.cost.output += usage.cost?.output || 0;
-	total.cost.cacheRead += usage.cost?.cacheRead || 0;
-	total.cost.cacheWrite += usage.cost?.cacheWrite || 0;
-	total.cost.total += usage.cost?.total || 0;
-}
-
-type AssistantLikeMessage = { role?: string; content?: unknown; stopReason?: unknown; errorMessage?: unknown; usage?: unknown };
+  total.input += usage.input || 0;
+  total.output += usage.output || 0;
+  total.cacheRead += usage.cacheRead || 0;
+  total.cacheWrite += usage.cacheWrite || 0;
+  if (usage.cacheWrite1h !== undefined)
+    total.cacheWrite1h = (total.cacheWrite1h ?? 0) + usage.cacheWrite1h;
+  if (usage.reasoning !== undefined) total.reasoning = (total.reasoning ?? 0) + usage.reasoning;
+  total.totalTokens += usage.totalTokens || 0;
+  total.cost.input += usage.cost?.input || 0;
+  total.cost.output += usage.cost?.output || 0;
+  total.cost.cacheRead += usage.cost?.cacheRead || 0;
+  total.cost.cacheWrite += usage.cost?.cacheWrite || 0;
+  total.cost.total += usage.cost?.total || 0;
+}
+
+type AssistantLikeMessage = {
+  role?: string;
+  content?: unknown;
+  stopReason?: unknown;
+  errorMessage?: unknown;
+  usage?: unknown;
+};
 
 function addAssistantMessageUsage(total: Usage, message: unknown): void {
-	const assistant = message as AssistantLikeMessage;
-	if (assistant?.role !== "assistant" || !assistant.usage || typeof assistant.usage !== "object") return;
-	addUsage(total, assistant.usage as Usage);
+  const assistant = message as AssistantLikeMessage;
+  if (assistant?.role !== "assistant" || !assistant.usage || typeof assistant.usage !== "object")
+    return;
+  addUsage(total, assistant.usage as Usage);
 }
 
 function aggregateAssistantUsage(messages: unknown[]): Usage {
-	const total = createEmptyUsage();
-	for (const message of messages) addAssistantMessageUsage(total, message);
-	return total;
+  const total = createEmptyUsage();
+  for (const message of messages) addAssistantMessageUsage(total, message);
+  return total;
 }
 
 function addSessionEventUsage(total: Usage, event: unknown): void {
-	const sessionEvent = event as { type?: string; message?: unknown; result?: { usage?: Usage } };
-	if (sessionEvent?.type === "message_end") return void addAssistantMessageUsage(total, sessionEvent.message);
-	if (sessionEvent?.type === "compaction_end" && sessionEvent.result?.usage) addUsage(total, sessionEvent.result.usage);
+  const sessionEvent = event as { type?: string; message?: unknown; result?: { usage?: Usage } };
+  if (sessionEvent?.type === "message_end")
+    return void addAssistantMessageUsage(total, sessionEvent.message);
+  if (sessionEvent?.type === "compaction_end" && sessionEvent.result?.usage)
+    addUsage(total, sessionEvent.result.usage);
 }
 
 function getLastAssistantMessage(messages: unknown[]): AssistantLikeMessage | undefined {
-	for (let i = messages.length - 1; i >= 0; i--) {
-		const message = messages[i] as AssistantLikeMessage;
-		if (message?.role === "assistant") return message;
-	}
-	return undefined;
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i] as AssistantLikeMessage;
+    if (message?.role === "assistant") return message;
+  }
+  return undefined;
 }
 
 function inspectFinalAssistant(messages: unknown[]):
-	| { ok: true; answer: string; message: AssistantLikeMessage; stopReason?: string }
-	| { ok: false; reason: string; message?: AssistantLikeMessage; stopReason?: string; errorMessage?: string } {
-	const message = getLastAssistantMessage(messages);
-	if (!message) return { ok: false, reason: "the internal subagent produced no assistant message" };
-	const stopReason = typeof message.stopReason === "string" ? message.stopReason.trim() : "";
-	const errorMessage = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
-	const answer = Array.isArray(message.content)
-		? message.content
-			.map((part) => (part && typeof part === "object" && (part as { type?: string }).type === "text" && typeof (part as { text?: unknown }).text === "string"
-				? (part as { text: string }).text
-				: ""))
-			.join("")
-			.trim()
-		: "";
-	if (stopReason === "error") {
-		return {
-			ok: false,
-			reason: `the internal subagent stopped with an error: ${errorMessage || "provider/model error"}`,
-			message,
-			stopReason,
-			errorMessage: errorMessage || undefined,
-		};
-	}
-	if (stopReason === "aborted") {
-		return { ok: false, reason: "the internal subagent was aborted before producing an answer", message, stopReason };
-	}
-	if (answer) return { ok: true, answer, message, stopReason: stopReason || undefined };
-	return { ok: false, reason: describeNoAnswerReason(message, 0), message, stopReason: stopReason || undefined };
-}
-
-function classifyRunFailure(error: unknown, callerAborted: boolean): { status: "aborted" | "error"; message: string; error?: string } {
-	const message = callerAborted ? "Aborted" : error instanceof Error ? error.message : String(error);
-	return { status: callerAborted ? "aborted" : "error", message, error: callerAborted ? undefined : message };
+  | { ok: true; answer: string; message: AssistantLikeMessage; stopReason?: string }
+  | {
+      ok: false;
+      reason: string;
+      message?: AssistantLikeMessage;
+      stopReason?: string;
+      errorMessage?: string;
+    } {
+  const message = getLastAssistantMessage(messages);
+  if (!message) return { ok: false, reason: "the internal subagent produced no assistant message" };
+  const stopReason = typeof message.stopReason === "string" ? message.stopReason.trim() : "";
+  const errorMessage = typeof message.errorMessage === "string" ? message.errorMessage.trim() : "";
+  const answer = Array.isArray(message.content)
+    ? message.content
+        .map((part) =>
+          part &&
+          typeof part === "object" &&
+          (part as { type?: string }).type === "text" &&
+          typeof (part as { text?: unknown }).text === "string"
+            ? (part as { text: string }).text
+            : "",
+        )
+        .join("")
+        .trim()
+    : "";
+  if (stopReason === "error") {
+    return {
+      ok: false,
+      reason: `the internal subagent stopped with an error: ${errorMessage || "provider/model error"}`,
+      message,
+      stopReason,
+      errorMessage: errorMessage || undefined,
+    };
+  }
+  if (stopReason === "aborted") {
+    return {
+      ok: false,
+      reason: "the internal subagent was aborted before producing an answer",
+      message,
+      stopReason,
+    };
+  }
+  if (answer) return { ok: true, answer, message, stopReason: stopReason || undefined };
+  return {
+    ok: false,
+    reason: describeNoAnswerReason(message, 0),
+    message,
+    stopReason: stopReason || undefined,
+  };
+}
+
+function classifyRunFailure(
+  error: unknown,
+  callerAborted: boolean,
+): { status: "aborted" | "error"; message: string; error?: string } {
+  const message = callerAborted
+    ? "Aborted"
+    : error instanceof Error
+      ? error.message
+      : String(error);
+  return {
+    status: callerAborted ? "aborted" : "error",
+    message,
+    error: callerAborted ? undefined : message,
+  };
 }
 
 function resolveLibrarianTerminalOutcome(
-	outcome: ReturnType<typeof inspectFinalAssistant> | undefined,
-	callerAborted: boolean,
-	turns: number,
-	fallbackReason?: string,
-): { status: "done"; content: string } | { status: "aborted"; content: "Aborted" } | { status: "error"; reason: string } {
-	if (callerAborted) return { status: "aborted", content: "Aborted" };
-	if (outcome?.ok) return { status: "done", content: outcome.answer };
-	const reason = fallbackReason ?? (outcome?.stopReason ? outcome.reason : describeNoAnswerReason(outcome?.message, turns));
-	return { status: "error", reason };
+  outcome: ReturnType<typeof inspectFinalAssistant> | undefined,
+  callerAborted: boolean,
+  turns: number,
+  fallbackReason?: string,
+):
+  | { status: "done"; content: string }
+  | { status: "aborted"; content: "Aborted" }
+  | { status: "error"; reason: string } {
+  if (callerAborted) return { status: "aborted", content: "Aborted" };
+  if (outcome?.ok) return { status: "done", content: outcome.answer };
+  const reason =
+    fallbackReason ??
+    (outcome?.stopReason ? outcome.reason : describeNoAnswerReason(outcome?.message, turns));
+  return { status: "error", reason };
 }
 
 function createLibrarianAbortController(abortChild: () => void, onCallerAbort: () => void) {
-	let callerAborted = false;
-	return {
-		get callerAborted() {
-			return callerAborted;
-		},
-		abortForCleanup() {
-			abortChild();
-		},
-		abortFromCaller() {
-			callerAborted = true;
-			onCallerAbort();
-			abortChild();
-		},
-	};
+  let callerAborted = false;
+  return {
+    get callerAborted() {
+      return callerAborted;
+    },
+    abortForCleanup() {
+      abortChild();
+    },
+    abortFromCaller() {
+      callerAborted = true;
+      onCallerAbort();
+      abortChild();
+    },
+  };
 }
 
 function describeNoAnswerReason(message: AssistantLikeMessage | undefined, turns: number): string {
-	if (!message) return "the internal subagent produced no assistant message";
-	if (message.stopReason === "error") {
-		const errorMessage = typeof message.errorMessage === "string" && message.errorMessage.trim()
-			? message.errorMessage.trim()
-			: "provider/model error";
-		return `the internal subagent stopped with an error: ${errorMessage}`;
-	}
-	if (message.stopReason === "aborted") return "the internal subagent was aborted before producing an answer";
-	if (turns >= MAX_TURNS) return `the internal subagent reached the ${MAX_TURNS}-turn budget without producing a final answer`;
-	const stopReason = typeof message.stopReason === "string" && message.stopReason.trim()
-		? ` (stopReason: ${message.stopReason.trim()})`
-		: "";
-	return `the internal subagent completed without final assistant text${stopReason}`;
+  if (!message) return "the internal subagent produced no assistant message";
+  if (message.stopReason === "error") {
+    const errorMessage =
+      typeof message.errorMessage === "string" && message.errorMessage.trim()
+        ? message.errorMessage.trim()
+        : "provider/model error";
+    return `the internal subagent stopped with an error: ${errorMessage}`;
+  }
+  if (message.stopReason === "aborted")
+    return "the internal subagent was aborted before producing an answer";
+  if (turns >= MAX_TURNS)
+    return `the internal subagent reached the ${MAX_TURNS}-turn budget without producing a final answer`;
+  const stopReason =
+    typeof message.stopReason === "string" && message.stopReason.trim()
+      ? ` (stopReason: ${message.stopReason.trim()})`
+      : "";
+  return `the internal subagent completed without final assistant text${stopReason}`;
 }
 
 function formatInternalFailure(details: LibrarianDetails, reason: string): string {
-	return [
-		`Internal librarian run failed: ${reason}.`,
-		`Diagnostics: status=${details.status}; model=${details.model.modelRef}; thinking=${details.model.thinkingLevel}; modelSelection=${details.model.autoSelected ? "auto" : "configured"}; turns=${details.turns}; toolCalls=${details.toolCalls.length}.`,
-		"No answer was produced. This is not a reliable \"no results found\" signal; retry later or configure a different Librarian model with /librarian-config.",
-	].join("\n");
+  return [
+    `Internal librarian run failed: ${reason}.`,
+    `Diagnostics: status=${details.status}; model=${details.model.modelRef}; thinking=${details.model.thinkingLevel}; modelSelection=${details.model.autoSelected ? "auto" : "configured"}; turns=${details.turns}; toolCalls=${details.toolCalls.length}.`,
+    'No answer was produced. This is not a reliable "no results found" signal; retry later or configure a different Librarian model with /librarian-config.',
+  ].join("\n");
 }
 
 function formatToolCall(call: ToolCall): string {
-	const args = call.args && typeof call.args === "object" ? (call.args as Record<string, unknown>) : {};
-	if (call.name === "read") {
-		const readPath = typeof args.path === "string" ? args.path : "";
-		const offset = typeof args.offset === "number" ? args.offset : undefined;
-		const limit = typeof args.limit === "number" ? args.limit : undefined;
-		const range = offset || limit ? `:${offset ?? 1}${limit ? `-${(offset ?? 1) + limit - 1}` : ""}` : "";
-		return `read ${readPath}${range}`.trim();
-	}
-	if (call.name === "bash") {
-		const command = typeof args.command === "string" ? args.command : "";
-		return `bash ${shorten(command, 120)}`.trim();
-	}
-	return call.name;
+  const args =
+    call.args && typeof call.args === "object" ? (call.args as Record<string, unknown>) : {};
+  if (call.name === "read") {
+    const readPath = typeof args.path === "string" ? args.path : "";
+    const offset = typeof args.offset === "number" ? args.offset : undefined;
+    const limit = typeof args.limit === "number" ? args.limit : undefined;
+    const range =
+      offset || limit ? `:${offset ?? 1}${limit ? `-${(offset ?? 1) + limit - 1}` : ""}` : "";
+    return `read ${readPath}${range}`.trim();
+  }
+  if (call.name === "bash") {
+    const command = typeof args.command === "string" ? args.command : "";
+    return `bash ${shorten(command, 120)}`.trim();
+  }
+  return call.name;
 }
 
 function renderAnswer(details: LibrarianDetails): string {
-	if (details.error) return details.error;
-	return details.status === "running" ? "(searching GitHub...)" : "(no output)";
+  if (details.error) return details.error;
+  return details.status === "running" ? "(searching GitHub...)" : "(no output)";
 }
 
 export const __test__ = {
-	buildLibrarianCandidates,
-	findAvailableModel,
-	isModelAvailabilityError,
-	parseModelPreference,
-	resolveThinkingLevel,
-	aggregateAssistantUsage,
-	addAssistantMessageUsage,
-	addSessionEventUsage,
-	inspectFinalAssistant,
-	classifyRunFailure,
-	resolveLibrarianTerminalOutcome,
-	createLibrarianAbortController,
-	cleanupExpiredCache,
-	cleanupExpiredRepos,
-	cleanupLockOwnershipError,
-	tryAcquireCleanupLock,
-	heartbeatCleanupLock,
-	releaseCleanupLock,
-	CLEANUP_LOCK_FILE,
-	CLEANUP_LOCK_STALE_MS,
-	CLEANUP_LOCK_MAX_LEASE_MS,
-	isCleanupLockLeaseExpired,
+  SUBAGENT_MCP_TOOLS,
+  isMcpCompatibleVersion,
+  resolveSubagentProjectTrusted,
+  createMcpSubagentFactories,
+  disposeSubagentSession,
+  createLibrarianRuntimeGuardExtension,
+  resolveToCwd,
+  buildLibrarianCandidates,
+  findAvailableModel,
+  isModelAvailabilityError,
+  parseModelPreference,
+  resolveThinkingLevel,
+  aggregateAssistantUsage,
+  addAssistantMessageUsage,
+  addSessionEventUsage,
+  inspectFinalAssistant,
+  classifyRunFailure,
+  resolveLibrarianTerminalOutcome,
+  createLibrarianAbortController,
+  cleanupExpiredCache,
+  cleanupExpiredRepos,
+  cleanupLockOwnershipError,
+  tryAcquireCleanupLock,
+  heartbeatCleanupLock,
+  releaseCleanupLock,
+  CLEANUP_LOCK_FILE,
+  CLEANUP_LOCK_STALE_MS,
+  CLEANUP_LOCK_MAX_LEASE_MS,
+  isCleanupLockLeaseExpired,
 };
 
 export default function librarianExtension(pi: ExtensionAPI) {
-	let cachePreference: CacheMode = DEFAULT_CACHE_MODE;
-	let modelPreference: string | undefined;
-	let thinkingPreference: ThinkingLevel = DEFAULT_THINKING_LEVEL;
-
-	pi.on("session_start", async () => {
-		const preferences = await readLibrarianPreferences();
-		cachePreference = preferences.cacheMode;
-		modelPreference = preferences.model;
-		thinkingPreference = preferences.thinkingLevel;
-	});
-
-	const currentPreferences = (): LibrarianPreferences => ({
-		cacheMode: cachePreference,
-		...(modelPreference ? { model: modelPreference } : {}),
-		thinkingLevel: thinkingPreference,
-	});
-
-	const savePreferences = async (preferences: LibrarianPreferences): Promise<string | undefined> => {
-		cachePreference = preferences.cacheMode;
-		modelPreference = preferences.model;
-		thinkingPreference = preferences.thinkingLevel;
-		try {
-			await writeLibrarianPreferences(preferences);
-			return undefined;
-		} catch (error) {
-			const message = error instanceof Error ? error.message : String(error);
-			return `Preference changed for this process, but could not save ${getCacheConfigPath()}: ${message}`;
-		}
-	};
-
-	pi.registerCommand("librarian-config", {
-		description: "Configure Librarian subagent model and thinking defaults",
-		getArgumentCompletions: (prefix) => {
-			const parts = prefix.trim().split(/\s+/).filter(Boolean);
-			if (parts.length <= 1) {
-				const commands = ["status", "model", "thinking", "clear"];
-				const query = parts[0]?.toLowerCase() ?? "";
-				return commands.filter((command) => command.startsWith(query)).map((value) => ({ value, label: value }));
-			}
-			if (parts[0]?.toLowerCase() === "thinking") {
-				const query = parts[1]?.toLowerCase() ?? "";
-				return [...THINKING_LEVELS, "auto"].filter((level) => level.startsWith(query)).map((value) => ({ value, label: value }));
-			}
-			return null;
-		},
-		handler: async (args, ctx) => {
-			const tokens = args.trim().split(/\s+/).filter(Boolean);
-			const [command = "status", ...rest] = tokens;
-			const action = command.toLowerCase();
-
-			if (action === "status" || action === "show") {
-				notifyCommand(ctx, formatLibrarianPreferences(currentPreferences()));
-				return;
-			}
-
-			if (action === "model") {
-				const value = rest.join(" ").trim();
-				if (!value) {
-					notifyCommand(ctx, "Usage: /librarian-config model <provider/model|auto>", "warning");
-					return;
-				}
-				const normalized = value.toLowerCase();
-				if (normalized === "current" || normalized.startsWith("current:")) {
-					notifyCommand(ctx, "Librarian model=current is no longer supported. Use /librarian-config model auto or choose an explicit provider/model.", "warning");
-					return;
-				}
-				const parsedModel = parseModelPreference(value);
-				const next = normalized === "auto" || normalized === "clear" || normalized === "default"
-					? { ...currentPreferences(), model: undefined }
-					: {
-						...currentPreferences(),
-						model: parsedModel.model,
-						thinkingLevel: parsedModel.thinkingLevel ?? thinkingPreference,
-					};
-				const warning = await savePreferences(next);
-				notifyCommand(ctx, `Librarian model default updated. ${warning ?? formatLibrarianPreferences(currentPreferences())}`, warning ? "warning" : "info");
-				return;
-			}
-
-			if (action === "thinking" || action === "think" || action === "thinking-level") {
-				const value = rest[0]?.trim().toLowerCase();
-				if (!value) {
-					notifyCommand(ctx, `Usage: /librarian-config thinking ${THINKING_LEVELS.join(" | ")} | auto`, "warning");
-					return;
-				}
-				const thinkingLevel = value === "auto" || value === "clear" || value === "default"
-					? DEFAULT_THINKING_LEVEL
-					: parseThinkingLevel(value);
-				if (!thinkingLevel) {
-					notifyCommand(ctx, `Usage: /librarian-config thinking ${THINKING_LEVELS.join(" | ")} | auto`, "warning");
-					return;
-				}
-				const warning = await savePreferences({ ...currentPreferences(), thinkingLevel });
-				notifyCommand(ctx, `Librarian thinking default set to ${thinkingLevel}. ${warning ?? formatLibrarianPreferences(currentPreferences())}`, warning ? "warning" : "info");
-				return;
-			}
-
-			if (action === "clear" || action === "reset") {
-				const target = rest[0]?.trim().toLowerCase() || "all";
-				let next: LibrarianPreferences;
-				if (target === "all") next = { cacheMode: cachePreference, thinkingLevel: DEFAULT_THINKING_LEVEL };
-				else if (target === "model") next = { ...currentPreferences(), model: undefined };
-				else if (target === "thinking" || target === "thinking-level") next = { ...currentPreferences(), thinkingLevel: DEFAULT_THINKING_LEVEL };
-				else {
-					notifyCommand(ctx, "Usage: /librarian-config clear [all|model|thinking]", "warning");
-					return;
-				}
-				const warning = await savePreferences(next);
-				notifyCommand(ctx, `Librarian defaults cleared (${target}). ${warning ?? formatLibrarianPreferences(currentPreferences())}`, warning ? "warning" : "info");
-				return;
-			}
-
-			notifyCommand(ctx, "Usage: /librarian-config status | model <provider/model|auto> | thinking <off|minimal|low|medium|high|xhigh|max|auto> | clear [all|model|thinking]", "warning");
-		},
-	});
-
-	pi.registerCommand("librarian-cache", {
-		description: "Toggle Librarian local checkout cache for future librarian calls",
-		getArgumentCompletions: (prefix) => {
-			const commands = ["on", "off", "toggle", "status"];
-			const query = prefix.trim().toLowerCase();
-			const matches = commands.filter((command) => command.startsWith(query));
-			return matches.length > 0 ? matches.map((value) => ({ value, label: value })) : null;
-		},
-		handler: async (args, ctx) => {
-			const action = args.trim().toLowerCase() || "status";
-			const cacheRoot = getUserCacheReposRoot();
-			const configPath = getCacheConfigPath();
-
-			const setPreference = async (mode: CacheMode): Promise<string | undefined> => {
-				cachePreference = mode;
-				try {
-					await writeCachePreference(mode);
-					return undefined;
-				} catch (error) {
-					const message = error instanceof Error ? error.message : String(error);
-					return `Preference changed for this process, but could not save ${configPath}: ${message}`;
-				}
-			};
-
-			const formatSetMessage = (mode: CacheMode, warning?: string): string => {
-				const main = mode === "enabled"
-					? `Librarian cache enabled. Future librarian calls will reuse local checkouts under ${cacheRoot}.`
-					: "Librarian cache disabled. Future librarian calls will use GitHub API/search and temporary fetched files only.";
-				return warning ? `${main} ${warning}` : main;
-			};
-
-			if (action === "on" || action === "enable") {
-				const warning = await setPreference("enabled");
-				notifyCommand(ctx, formatSetMessage("enabled", warning), warning ? "warning" : "info");
-				return;
-			}
-
-			if (action === "off" || action === "disable") {
-				const warning = await setPreference("disabled");
-				notifyCommand(ctx, formatSetMessage("disabled", warning), warning ? "warning" : "info");
-				return;
-			}
-
-			if (action === "toggle") {
-				const next = cachePreference === "enabled" ? "disabled" : "enabled";
-				const warning = await setPreference(next);
-				notifyCommand(ctx, formatSetMessage(next, warning), warning ? "warning" : "info");
-				return;
-			}
-
-			if (action === "status") {
-				notifyCommand(
-					ctx,
-					`Librarian cache is ${formatCachePreference(cachePreference)}. Cache directory: ${cacheRoot}. Config: ${configPath}. Repos unused for ${CACHE_TTL_DAYS} days are removed lazily.`,
-				);
-				return;
-			}
-
-			notifyCommand(ctx, "Usage: /librarian-cache on | off | toggle | status", "warning");
-		},
-	});
-
-	pi.on("tool_result", async (event) => {
-		if (event.toolName !== "librarian") return undefined;
-		const details = event.details as LibrarianDetails | undefined;
-		if (details?.status !== "error") return undefined;
-		return { isError: true };
-	});
-
-	pi.registerTool({
-		name: "librarian",
-		label: "Librarian",
-		description:
-			"GitHub research scout for coding and personal-assistant tasks. Use when the answer likely lives in GitHub repos, exact repo/path locations are unknown, or you'd otherwise do exploratory gh search/tree probes plus local rg/read inspection. Librarian uses an optional 7-day local checkout cache that is disabled by default; toggle it with /librarian-cache. Configure its internal subagent defaults with /librarian-config.",
-		promptSnippet:
-			"Research GitHub repositories with evidence-first path and line citations; local checkout cache is disabled by default and user-toggleable with /librarian-cache. Internal subagent defaults are user-configurable with /librarian-config and default to low thinking.",
-		promptGuidelines: [
-			"Use librarian when the answer likely requires exploratory GitHub repository search or line-cited evidence from external repos.",
-			"Do not use librarian for files already present in the current workspace unless the user asks for external GitHub research.",
-			"Use model or thinkingLevel only when the user explicitly asks for a non-default internal librarian model or thinking level.",
-		],
-		parameters: LibrarianParams,
-
-		async execute(_toolCallId, params, signal, onUpdate, ctx) {
-			const rawQuery = (params as { query?: unknown }).query;
-			const query = typeof rawQuery === "string" ? rawQuery.trim() : "";
-			if (!query) throw new Error("Invalid parameters: expected query to be a non-empty string.");
-
-			const repos = asStringArray((params as { repos?: unknown }).repos);
-			const owners = asStringArray((params as { owners?: unknown }).owners);
-			const maxSearchResults = clampNumber(
-				(params as { maxSearchResults?: unknown }).maxSearchResults,
-				1,
-				MAX_SEARCH_RESULTS,
-				DEFAULT_MAX_SEARCH_RESULTS,
-			);
-			const explicitModel = parseModelPreference((params as { model?: unknown }).model);
-			const thinkingLevel =
-				parseThinkingLevel((params as { thinkingLevel?: unknown }).thinkingLevel) ??
-				explicitModel.thinkingLevel ??
-				thinkingPreference;
-			const candidates = await buildLibrarianCandidates(ctx, explicitModel.model ?? modelPreference, thinkingLevel);
-			const selectedModel = candidates[0];
-
-			const workspaceBase = path.join(os.tmpdir(), "pi-librarian");
-			await fs.mkdir(workspaceBase, { recursive: true });
-			const workspace = await fs.mkdtemp(path.join(workspaceBase, "run-"));
-			await fs.mkdir(path.join(workspace, "repos"), { recursive: true });
-
-			const cacheRoot = getUserCacheReposRoot();
-			let cacheDecision = resolveCacheDecision(cachePreference);
-			let cleanup: { deleted: number; errors: string[] } = { deleted: 0, errors: [] };
-			if (cacheDecision.enabled) {
-				try {
-					await fs.mkdir(cacheRoot, { recursive: true });
-					cleanup = await cleanupExpiredCache(cacheRoot);
-				} catch (error) {
-					const message = error instanceof Error ? error.message : String(error);
-					cacheDecision = {
-						enabled: false,
-						reason: `cache setup failed (${message}); using GitHub API/temp files only`,
-					};
-					cleanup = { deleted: 0, errors: [`cache setup: ${message}`] };
-				}
-			}
-
-			const details: LibrarianDetails = {
-				status: "running",
-				workspace,
-				cache: {
-					mode: cacheDecision.enabled ? "enabled" : "disabled",
-					root: cacheRoot,
-					ttlDays: CACHE_TTL_DAYS,
-					cleanupDeleted: cleanup.deleted,
-					cleanupErrors: cleanup.errors,
-					decisionReason: cacheDecision.reason,
-				},
-				model: selectedModel.details,
-				turns: 0,
-				toolCalls: [],
-				startedAt: Date.now(),
-			};
-
-			let lastContent = "(searching GitHub...)";
-			let session: { abort: () => Promise<void>; dispose: () => void; state: { messages: unknown[] }; prompt: Function } | undefined;
-			let unsubscribe: (() => void) | undefined;
-			let runTimeout: NodeJS.Timeout | undefined;
-			let abortListenerAdded = false;
-			const usage = createEmptyUsage();
-
-			const emit = (force = false) => {
-				void force;
-				onUpdate?.({ content: [{ type: "text", text: lastContent }], details });
-			};
-
-			const abortController = createLibrarianAbortController(
-				() => void session?.abort(),
-				() => {
-					details.status = "aborted";
-					details.endedAt = Date.now();
-					lastContent = "Aborted";
-					emit(true);
-				},
-			);
-			const abortFromCaller = () => abortController.abortFromCaller();
-
-			if (signal?.aborted) abortFromCaller();
-			if (signal && !signal.aborted) {
-				signal.addEventListener("abort", abortFromCaller);
-				abortListenerAdded = true;
-			}
-
-			try {
-				emit(true);
-
-				const systemPrompt = buildSystemPrompt({
-					workspace,
-					maxSearchResults,
-					cacheEnabled: cacheDecision.enabled,
-					cacheRoot,
-				});
-
-				// Keep the research session from inheriting user/project tool, shell,
-				// retry, or provider-request settings. The host model runtime is still
-				// passed explicitly below so the selected provider/auth policy is kept.
-				const isolatedSettingsManager = SettingsManager.inMemory({});
-				const resourceLoader = new DefaultResourceLoader({
-					cwd: workspace,
-					agentDir: getAgentDir(),
-					settingsManager: isolatedSettingsManager,
-					noExtensions: true,
-					noSkills: true,
-					noPromptTemplates: true,
-					noThemes: true,
-					noContextFiles: true,
-					extensionFactories: [
-						createLibrarianRuntimeGuardExtension({
-							maxTurns: MAX_TURNS,
-							workspace,
-							cacheRoot,
-							cacheEnabled: cacheDecision.enabled,
-						}),
-					],
-					systemPromptOverride: () => systemPrompt,
-					skillsOverride: () => ({ skills: [], diagnostics: [] }),
-					agentsFilesOverride: () => ({ agentsFiles: [] }),
-				});
-
-				await resourceLoader.reload();
-
-				const runAttempt = async (
-					candidate: LibrarianCandidate,
-				): Promise<ReturnType<typeof inspectFinalAssistant>> => {
-					details.model = candidate.details;
-					details.turns = 0;
-					details.toolCalls = [];
-					emit(true);
-
-					const created = await createAgentSession({
-						cwd: workspace,
-						...getModelRuntimeOption(ctx),
-						resourceLoader,
-						settingsManager: isolatedSettingsManager,
-						sessionManager: SessionManager.inMemory(workspace),
-						model: candidate.model,
-						thinkingLevel: candidate.details.thinkingLevel,
-						tools: ["read", "bash"],
-					});
-
-					session = created.session as typeof session;
-					if (abortController.callerAborted) abortController.abortForCleanup();
-					unsubscribe = (created.session as any).subscribe((event: any) => {
-						addSessionEventUsage(usage, event);
-						switch (event.type) {
-							case "turn_end":
-								details.turns += 1;
-								emit();
-								break;
-							case "tool_execution_start":
-								details.toolCalls.push({
-									id: event.toolCallId,
-									name: event.toolName,
-									args: event.args,
-									startedAt: Date.now(),
-								});
-								if (details.toolCalls.length > MAX_TOOL_CALLS_TO_KEEP) {
-									details.toolCalls.splice(0, details.toolCalls.length - MAX_TOOL_CALLS_TO_KEEP);
-								}
-								emit(true);
-								break;
-							case "tool_execution_end": {
-								const call = details.toolCalls.find((item) => item.id === event.toolCallId);
-								if (call) {
-									call.endedAt = Date.now();
-									call.isError = event.isError;
-								}
-								emit(true);
-								break;
-							}
-						}
-					});
-
-					try {
-						if (!abortController.callerAborted) {
-							const promptPromise = created.session.prompt(buildUserPrompt(query, repos, owners, maxSearchResults, details.cache), {
-								expandPromptTemplates: false,
-							});
-							const timeoutPromise = new Promise<never>((_resolve, reject) => {
-								runTimeout = setTimeout(() => {
-									abortController.abortForCleanup();
-									reject(new Error(`Librarian timed out after ${Math.round(MAX_RUN_MS / 1000)} seconds.`));
-								}, MAX_RUN_MS);
-							});
-							await Promise.race([promptPromise, timeoutPromise]);
-						}
-
-						return inspectFinalAssistant(session?.state.messages ?? []);
-					} finally {
-						if (runTimeout) {
-							clearTimeout(runTimeout);
-							runTimeout = undefined;
-						}
-						unsubscribe?.();
-						unsubscribe = undefined;
-						session?.dispose();
-						session = undefined;
-					}
-				};
-
-				let lastOutcome: ReturnType<typeof inspectFinalAssistant> | undefined;
-				let attemptErrorReason: string | undefined;
-				for (let index = 0; index < candidates.length; index++) {
-					if (abortController.callerAborted) break;
-					const candidate =
-						index === 0 ? candidates[index] : withLibrarianFallbackReason(candidates[index], candidates[index - 1]);
-
-					let attempt: ReturnType<typeof inspectFinalAssistant>;
-					try {
-						attempt = await runAttempt(candidate);
-					} catch (error) {
-						if (abortController.callerAborted) throw error;
-						// Some providers throw (rather than carry the error on the assistant
-						// message) when a model is unavailable; treat that like a
-						// message-carried availability error and fall back to the next model.
-						const message = error instanceof Error ? error.message : String(error);
-						if (index < candidates.length - 1 && isModelAvailabilityError(message)) {
-							lastOutcome = undefined;
-							attemptErrorReason = `the internal subagent stopped with an error: ${message}`;
-							continue;
-						}
-						throw error;
-					}
-
-					lastOutcome = attempt;
-					if (abortController.callerAborted || attempt.ok) break;
-
-					attemptErrorReason = attempt.stopReason ? attempt.reason : describeNoAnswerReason(attempt.message, details.turns);
-					const canFallBack =
-						index < candidates.length - 1 &&
-						attempt.stopReason === "error" &&
-						isModelAvailabilityError(attempt.errorMessage);
-					if (!canFallBack) break;
-				}
-
-				const terminal = resolveLibrarianTerminalOutcome(lastOutcome, abortController.callerAborted, details.turns, attemptErrorReason);
-				details.status = terminal.status;
-				if (terminal.status === "error") {
-					lastContent = formatInternalFailure(details, terminal.reason);
-					details.error = terminal.reason;
-				} else {
-					lastContent = terminal.content;
-				}
-				details.endedAt = Date.now();
-				emit(true);
-
-				return {
-					content: [{ type: "text", text: lastContent }],
-					details,
-					usage,
-				};
-			} catch (error) {
-				const failure = classifyRunFailure(error, abortController.callerAborted);
-				const { message } = failure;
-				details.status = failure.status;
-				details.error = failure.error;
-				details.endedAt = Date.now();
-				lastContent = message;
-				emit(true);
-
-				return {
-					content: [{ type: "text", text: message }],
-					details,
-					usage,
-				};
-			} finally {
-				if (runTimeout) clearTimeout(runTimeout);
-				if (signal && abortListenerAdded) signal.removeEventListener("abort", abortFromCaller);
-				unsubscribe?.();
-				session?.dispose();
-			}
-		},
-
-		renderCall(args, theme) {
-			const query = typeof (args as { query?: unknown })?.query === "string" ? (args as { query: string }).query : "";
-			const repos = Array.isArray((args as { repos?: unknown })?.repos) ? (args as { repos: unknown[] }).repos.length : 0;
-			const owners = Array.isArray((args as { owners?: unknown })?.owners)
-				? (args as { owners: unknown[] }).owners.length
-				: 0;
-			return new Text(
-				`${theme.fg("muted", `repos:${repos} owners:${owners}`)} · ${theme.fg("toolOutput", shorten(query, 80))}`,
-				0,
-				0,
-			);
-		},
-
-		renderResult(result, { expanded, isPartial }, theme) {
-			const details = result.details as LibrarianDetails | undefined;
-			if (!details) {
-				const first = result.content[0];
-				return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
-			}
-
-			const status = isPartial ? "running" : details.status;
-			const icon =
-				status === "done"
-					? theme.fg("success", "✓")
-					: status === "error"
-						? theme.fg("error", "✗")
-						: status === "aborted"
-							? theme.fg("warning", "◼")
-							: theme.fg("warning", "⏳");
-
-			const cacheLabel =
-				details.cache.mode === "enabled"
-					? theme.fg("success", "cache:on")
-					: theme.fg("muted", "cache:off");
-			const header = `${icon} ${theme.fg("toolTitle", theme.bold("librarian "))}${theme.fg(
-				"dim",
-				`${details.turns} turns • ${details.toolCalls.length} tools • `,
-			)}${cacheLabel}`;
-
-			const workspaceLine = `${theme.fg("muted", "workspace: ")}${theme.fg("toolOutput", details.workspace)}`;
-			const modelLine = `${theme.fg("muted", "model: ")}${theme.fg("toolOutput", details.model.modelRef)} ${theme.fg(
-				"dim",
-				`(${details.model.thinkingLevel}, ${details.model.autoSelected ? "auto" : "configured"})`,
-			)}`;
-			const cacheLine = `${theme.fg("muted", "cache: ")}${theme.fg("toolOutput", details.cache.root)} ${theme.fg(
-				"dim",
-				`(${details.cache.mode}, ${details.cache.ttlDays}d TTL, cleaned ${details.cache.cleanupDeleted})`,
-			)}`;
-
-			const answer =
-				(result.content[0]?.type === "text" ? result.content[0].text : renderAnswer(details)).trim() || "(no output)";
-
-			const toolLines = details.toolCalls.slice(expanded ? 0 : -6).map((call) => {
-				const callIcon = call.isError ? theme.fg("error", "✗") : theme.fg("dim", "→");
-				return `${callIcon} ${theme.fg("toolOutput", formatToolCall(call))}`;
-			});
-			if (!expanded && details.toolCalls.length > 6) toolLines.unshift(theme.fg("muted", "…"));
-
-			if (status === "running") {
-				const parts = [header, workspaceLine, modelLine, cacheLine];
-				if (toolLines.length) parts.push("", theme.fg("muted", "Tools:"), ...toolLines);
-				parts.push("", theme.fg("muted", "Searching GitHub…"));
-				return new Text(parts.join("\n"), 0, 0);
-			}
-
-			if (!expanded) {
-				const previewLines = answer.split("\n").slice(0, 18);
-				const parts = [header, workspaceLine, modelLine, cacheLine, "", theme.fg("toolOutput", previewLines.join("\n"))];
-				if (answer.split("\n").length > previewLines.length) parts.push(theme.fg("muted", "(Ctrl+O to expand)"));
-				if (toolLines.length) parts.push("", theme.fg("muted", "Tools:"), ...toolLines);
-				return new Text(parts.join("\n"), 0, 0);
-			}
-
-			const container = new Container();
-			container.addChild(new Text(header, 0, 0));
-			container.addChild(new Text(workspaceLine, 0, 0));
-			container.addChild(new Text(modelLine, 0, 0));
-			container.addChild(new Text(cacheLine, 0, 0));
-			if (details.cache.cleanupErrors.length) {
-				container.addChild(
-					new Text(theme.fg("warning", `cache cleanup warnings: ${details.cache.cleanupErrors.length}`), 0, 0),
-				);
-			}
-			if (toolLines.length) {
-				container.addChild(new Spacer(1));
-				container.addChild(new Text([theme.fg("muted", "Tools:"), ...toolLines].join("\n"), 0, 0));
-			}
-			container.addChild(new Spacer(1));
-			container.addChild(new Markdown(answer, 0, 0, getMarkdownTheme()));
-			return container;
-		},
-	});
+  let cachePreference: CacheMode = DEFAULT_CACHE_MODE;
+  let modelPreference: string | undefined;
+  let thinkingPreference: ThinkingLevel = DEFAULT_THINKING_LEVEL;
+
+  pi.on("session_start", async () => {
+    const preferences = await readLibrarianPreferences();
+    cachePreference = preferences.cacheMode;
+    modelPreference = preferences.model;
+    thinkingPreference = preferences.thinkingLevel;
+  });
+
+  const currentPreferences = (): LibrarianPreferences => ({
+    cacheMode: cachePreference,
+    ...(modelPreference ? { model: modelPreference } : {}),
+    thinkingLevel: thinkingPreference,
+  });
+
+  const savePreferences = async (
+    preferences: LibrarianPreferences,
+  ): Promise<string | undefined> => {
+    cachePreference = preferences.cacheMode;
+    modelPreference = preferences.model;
+    thinkingPreference = preferences.thinkingLevel;
+    try {
+      await writeLibrarianPreferences(preferences);
+      return undefined;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return `Preference changed for this process, but could not save ${getCacheConfigPath()}: ${message}`;
+    }
+  };
+
+  pi.registerCommand("librarian-config", {
+    description: "Configure Librarian subagent model and thinking defaults",
+    getArgumentCompletions: (prefix) => {
+      const parts = prefix.trim().split(/\s+/).filter(Boolean);
+      if (parts.length <= 1) {
+        const commands = ["status", "model", "thinking", "clear"];
+        const query = parts[0]?.toLowerCase() ?? "";
+        return commands
+          .filter((command) => command.startsWith(query))
+          .map((value) => ({ value, label: value }));
+      }
+      if (parts[0]?.toLowerCase() === "thinking") {
+        const query = parts[1]?.toLowerCase() ?? "";
+        return [...THINKING_LEVELS, "auto"]
+          .filter((level) => level.startsWith(query))
+          .map((value) => ({ value, label: value }));
+      }
+      return null;
+    },
+    handler: async (args, ctx) => {
+      const tokens = args.trim().split(/\s+/).filter(Boolean);
+      const [command = "status", ...rest] = tokens;
+      const action = command.toLowerCase();
+
+      if (action === "status" || action === "show") {
+        notifyCommand(ctx, formatLibrarianPreferences(currentPreferences()));
+        return;
+      }
+
+      if (action === "model") {
+        const value = rest.join(" ").trim();
+        if (!value) {
+          notifyCommand(ctx, "Usage: /librarian-config model <provider/model|auto>", "warning");
+          return;
+        }
+        const normalized = value.toLowerCase();
+        if (normalized === "current" || normalized.startsWith("current:")) {
+          notifyCommand(
+            ctx,
+            "Librarian model=current is no longer supported. Use /librarian-config model auto or choose an explicit provider/model.",
+            "warning",
+          );
+          return;
+        }
+        const parsedModel = parseModelPreference(value);
+        const next =
+          normalized === "auto" || normalized === "clear" || normalized === "default"
+            ? { ...currentPreferences(), model: undefined }
+            : {
+                ...currentPreferences(),
+                model: parsedModel.model,
+                thinkingLevel: parsedModel.thinkingLevel ?? thinkingPreference,
+              };
+        const warning = await savePreferences(next);
+        notifyCommand(
+          ctx,
+          `Librarian model default updated. ${warning ?? formatLibrarianPreferences(currentPreferences())}`,
+          warning ? "warning" : "info",
+        );
+        return;
+      }
+
+      if (action === "thinking" || action === "think" || action === "thinking-level") {
+        const value = rest[0]?.trim().toLowerCase();
+        if (!value) {
+          notifyCommand(
+            ctx,
+            `Usage: /librarian-config thinking ${THINKING_LEVELS.join(" | ")} | auto`,
+            "warning",
+          );
+          return;
+        }
+        const thinkingLevel =
+          value === "auto" || value === "clear" || value === "default"
+            ? DEFAULT_THINKING_LEVEL
+            : parseThinkingLevel(value);
+        if (!thinkingLevel) {
+          notifyCommand(
+            ctx,
+            `Usage: /librarian-config thinking ${THINKING_LEVELS.join(" | ")} | auto`,
+            "warning",
+          );
+          return;
+        }
+        const warning = await savePreferences({ ...currentPreferences(), thinkingLevel });
+        notifyCommand(
+          ctx,
+          `Librarian thinking default set to ${thinkingLevel}. ${warning ?? formatLibrarianPreferences(currentPreferences())}`,
+          warning ? "warning" : "info",
+        );
+        return;
+      }
+
+      if (action === "clear" || action === "reset") {
+        const target = rest[0]?.trim().toLowerCase() || "all";
+        let next: LibrarianPreferences;
+        if (target === "all")
+          next = { cacheMode: cachePreference, thinkingLevel: DEFAULT_THINKING_LEVEL };
+        else if (target === "model") next = { ...currentPreferences(), model: undefined };
+        else if (target === "thinking" || target === "thinking-level")
+          next = { ...currentPreferences(), thinkingLevel: DEFAULT_THINKING_LEVEL };
+        else {
+          notifyCommand(ctx, "Usage: /librarian-config clear [all|model|thinking]", "warning");
+          return;
+        }
+        const warning = await savePreferences(next);
+        notifyCommand(
+          ctx,
+          `Librarian defaults cleared (${target}). ${warning ?? formatLibrarianPreferences(currentPreferences())}`,
+          warning ? "warning" : "info",
+        );
+        return;
+      }
+
+      notifyCommand(
+        ctx,
+        "Usage: /librarian-config status | model <provider/model|auto> | thinking <off|minimal|low|medium|high|xhigh|max|auto> | clear [all|model|thinking]",
+        "warning",
+      );
+    },
+  });
+
+  pi.registerCommand("librarian-cache", {
+    description: "Toggle Librarian local checkout cache for future librarian calls",
+    getArgumentCompletions: (prefix) => {
+      const commands = ["on", "off", "toggle", "status"];
+      const query = prefix.trim().toLowerCase();
+      const matches = commands.filter((command) => command.startsWith(query));
+      return matches.length > 0 ? matches.map((value) => ({ value, label: value })) : null;
+    },
+    handler: async (args, ctx) => {
+      const action = args.trim().toLowerCase() || "status";
+      const cacheRoot = getUserCacheReposRoot();
+      const configPath = getCacheConfigPath();
+
+      const setPreference = async (mode: CacheMode): Promise<string | undefined> => {
+        cachePreference = mode;
+        try {
+          await writeCachePreference(mode);
+          return undefined;
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          return `Preference changed for this process, but could not save ${configPath}: ${message}`;
+        }
+      };
+
+      const formatSetMessage = (mode: CacheMode, warning?: string): string => {
+        const main =
+          mode === "enabled"
+            ? `Librarian cache enabled. Future librarian calls will reuse local checkouts under ${cacheRoot}.`
+            : "Librarian cache disabled. Future librarian calls will use GitHub API/search and temporary fetched files only.";
+        return warning ? `${main} ${warning}` : main;
+      };
+
+      if (action === "on" || action === "enable") {
+        const warning = await setPreference("enabled");
+        notifyCommand(ctx, formatSetMessage("enabled", warning), warning ? "warning" : "info");
+        return;
+      }
+
+      if (action === "off" || action === "disable") {
+        const warning = await setPreference("disabled");
+        notifyCommand(ctx, formatSetMessage("disabled", warning), warning ? "warning" : "info");
+        return;
+      }
+
+      if (action === "toggle") {
+        const next = cachePreference === "enabled" ? "disabled" : "enabled";
+        const warning = await setPreference(next);
+        notifyCommand(ctx, formatSetMessage(next, warning), warning ? "warning" : "info");
+        return;
+      }
+
+      if (action === "status") {
+        notifyCommand(
+          ctx,
+          `Librarian cache is ${formatCachePreference(cachePreference)}. Cache directory: ${cacheRoot}. Config: ${configPath}. Repos unused for ${CACHE_TTL_DAYS} days are removed lazily.`,
+        );
+        return;
+      }
+
+      notifyCommand(ctx, "Usage: /librarian-cache on | off | toggle | status", "warning");
+    },
+  });
+
+  pi.on("tool_result", async (event) => {
+    if (event.toolName !== "librarian") return undefined;
+    const details = event.details as LibrarianDetails | undefined;
+    if (details?.status !== "error") return undefined;
+    return { isError: true };
+  });
+
+  pi.registerTool({
+    name: "librarian",
+    label: "Librarian",
+    description:
+      "GitHub research scout for coding and personal-assistant tasks. Use when the answer likely lives in GitHub repos, exact repo/path locations are unknown, or you'd otherwise do exploratory gh search/tree probes plus local rg/read inspection. Librarian uses an optional 7-day local checkout cache that is disabled by default; toggle it with /librarian-cache. Configure its internal subagent defaults with /librarian-config.",
+    promptSnippet:
+      "Research GitHub repositories with evidence-first path and line citations; local checkout cache is disabled by default and user-toggleable with /librarian-cache. Internal subagent defaults are user-configurable with /librarian-config and default to low thinking.",
+    promptGuidelines: [
+      "Use librarian when the answer likely requires exploratory GitHub repository search or line-cited evidence from external repos.",
+      "Do not use librarian for files already present in the current workspace unless the user asks for external GitHub research.",
+      "Use model or thinkingLevel only when the user explicitly asks for a non-default internal librarian model or thinking level.",
+    ],
+    parameters: LibrarianParams,
+
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const rawQuery = (params as { query?: unknown }).query;
+      const query = typeof rawQuery === "string" ? rawQuery.trim() : "";
+      if (!query) throw new Error("Invalid parameters: expected query to be a non-empty string.");
+
+      const repos = asStringArray((params as { repos?: unknown }).repos);
+      const owners = asStringArray((params as { owners?: unknown }).owners);
+      const maxSearchResults = clampNumber(
+        (params as { maxSearchResults?: unknown }).maxSearchResults,
+        1,
+        MAX_SEARCH_RESULTS,
+        DEFAULT_MAX_SEARCH_RESULTS,
+      );
+      const explicitModel = parseModelPreference((params as { model?: unknown }).model);
+      const thinkingLevel =
+        parseThinkingLevel((params as { thinkingLevel?: unknown }).thinkingLevel) ??
+        explicitModel.thinkingLevel ??
+        thinkingPreference;
+      const candidates = await buildLibrarianCandidates(
+        ctx,
+        explicitModel.model ?? modelPreference,
+        thinkingLevel,
+      );
+      const selectedModel = candidates[0];
+
+      const workspaceBase = path.join(os.tmpdir(), "pi-librarian");
+      await fs.mkdir(workspaceBase, { recursive: true });
+      const workspace = await fs.mkdtemp(path.join(workspaceBase, "run-"));
+      await fs.mkdir(path.join(workspace, "repos"), { recursive: true });
+
+      const cacheRoot = getUserCacheReposRoot();
+      let cacheDecision = resolveCacheDecision(cachePreference);
+      let cleanup: { deleted: number; errors: string[] } = { deleted: 0, errors: [] };
+      if (cacheDecision.enabled) {
+        try {
+          await fs.mkdir(cacheRoot, { recursive: true });
+          cleanup = await cleanupExpiredCache(cacheRoot);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          cacheDecision = {
+            enabled: false,
+            reason: `cache setup failed (${message}); using GitHub API/temp files only`,
+          };
+          cleanup = { deleted: 0, errors: [`cache setup: ${message}`] };
+        }
+      }
+
+      const details: LibrarianDetails = {
+        status: "running",
+        workspace,
+        cache: {
+          mode: cacheDecision.enabled ? "enabled" : "disabled",
+          root: cacheRoot,
+          ttlDays: CACHE_TTL_DAYS,
+          cleanupDeleted: cleanup.deleted,
+          cleanupErrors: cleanup.errors,
+          decisionReason: cacheDecision.reason,
+        },
+        model: selectedModel.details,
+        turns: 0,
+        toolCalls: [],
+        startedAt: Date.now(),
+      };
+
+      let lastContent = "(searching GitHub...)";
+      let session:
+        | {
+            abort: () => Promise<void>;
+            dispose: () => void;
+            state: { messages: unknown[] };
+            prompt: Function;
+          }
+        | undefined;
+      let unsubscribe: (() => void) | undefined;
+      let runTimeout: NodeJS.Timeout | undefined;
+      let abortListenerAdded = false;
+      const usage = createEmptyUsage();
+
+      const emit = () => {
+        onUpdate?.({ content: [{ type: "text", text: lastContent }], details });
+      };
+
+      const abortController = createLibrarianAbortController(
+        () => void session?.abort(),
+        () => {
+          details.status = "aborted";
+          details.endedAt = Date.now();
+          lastContent = "Aborted";
+          emit();
+        },
+      );
+      const abortFromCaller = () => abortController.abortFromCaller();
+
+      if (signal?.aborted) abortFromCaller();
+      if (signal && !signal.aborted) {
+        signal.addEventListener("abort", abortFromCaller);
+        abortListenerAdded = true;
+      }
+
+      try {
+        emit();
+
+        const systemPrompt = buildSystemPrompt({
+          workspace,
+          maxSearchResults,
+          cacheEnabled: cacheDecision.enabled,
+          cacheRoot,
+        });
+
+        // Keep the research session from inheriting user/project tool, shell,
+        // retry, or provider-request settings. The host model runtime is still
+        // passed explicitly below so the selected provider/auth policy is kept.
+        // workspace is a temp clone dir — always a different dir from ctx.cwd,
+        // so projectTrusted is always false here (project .pi/mcp.json is never loaded).
+        const projectTrusted = resolveSubagentProjectTrusted(ctx, workspace);
+        const isolatedSettingsManager = SettingsManager.inMemory({}, { projectTrusted });
+        const resourceLoader = new DefaultResourceLoader({
+          cwd: workspace,
+          agentDir: getAgentDir(),
+          settingsManager: isolatedSettingsManager,
+          noExtensions: true,
+          noSkills: true,
+          noPromptTemplates: true,
+          noThemes: true,
+          noContextFiles: true,
+          extensionFactories: [
+            createLibrarianRuntimeGuardExtension({
+              maxTurns: MAX_TURNS,
+              workspace,
+              cacheRoot,
+              cacheEnabled: cacheDecision.enabled,
+            }),
+            ...createMcpSubagentFactories(),
+          ],
+          systemPromptOverride: () => systemPrompt,
+          skillsOverride: () => ({ skills: [], diagnostics: [] }),
+          agentsFilesOverride: () => ({ agentsFiles: [] }),
+        });
+
+        await resourceLoader.reload();
+
+        const runAttempt = async (
+          candidate: LibrarianCandidate,
+        ): Promise<ReturnType<typeof inspectFinalAssistant>> => {
+          details.model = candidate.details;
+          details.turns = 0;
+          details.toolCalls = [];
+          emit();
+
+          const created = await createAgentSession({
+            cwd: workspace,
+            ...getModelRuntimeOption(ctx),
+            resourceLoader,
+            settingsManager: isolatedSettingsManager,
+            sessionManager: SessionManager.inMemory(workspace),
+            model: candidate.model,
+            thinkingLevel: candidate.details.thinkingLevel,
+            tools: ["read", "bash", ...SUBAGENT_MCP_TOOLS],
+          });
+
+          // Assign session BEFORE bindExtensions so the finally block can dispose it
+          // even if binding fails partway through (e.g. a server starts then an
+          // extension's session_start throws).
+          session = created.session as typeof session;
+          try {
+            // Connect extensions (MCP servers) before prompting. Feature-detected: Pi >=0.99.0.
+            await (created.session as any).bindExtensions?.({ mode: "json" });
+            if (abortController.callerAborted) abortController.abortForCleanup();
+            unsubscribe = (created.session as any).subscribe((event: any) => {
+              addSessionEventUsage(usage, event);
+              switch (event.type) {
+                case "turn_end":
+                  details.turns += 1;
+                  emit();
+                  break;
+                case "tool_execution_start":
+                  details.toolCalls.push({
+                    id: event.toolCallId,
+                    name: event.toolName,
+                    args: event.args,
+                    startedAt: Date.now(),
+                  });
+                  if (details.toolCalls.length > MAX_TOOL_CALLS_TO_KEEP) {
+                    details.toolCalls.splice(0, details.toolCalls.length - MAX_TOOL_CALLS_TO_KEEP);
+                  }
+                  emit();
+                  break;
+                case "tool_execution_end": {
+                  const call = details.toolCalls.find((item) => item.id === event.toolCallId);
+                  if (call) {
+                    call.endedAt = Date.now();
+                    call.isError = event.isError;
+                  }
+                  emit();
+                  break;
+                }
+              }
+            });
+
+            if (!abortController.callerAborted) {
+              const promptPromise = created.session.prompt(
+                buildUserPrompt(query, repos, owners, maxSearchResults, details.cache),
+                {
+                  expandPromptTemplates: false,
+                },
+              );
+              const timeoutPromise = new Promise<never>((_resolve, reject) => {
+                runTimeout = setTimeout(() => {
+                  abortController.abortForCleanup();
+                  reject(
+                    new Error(
+                      `Librarian timed out after ${Math.round(MAX_RUN_MS / 1000)} seconds.`,
+                    ),
+                  );
+                }, MAX_RUN_MS);
+              });
+              await Promise.race([promptPromise, timeoutPromise]);
+            }
+
+            return inspectFinalAssistant(session?.state.messages ?? []);
+          } finally {
+            if (runTimeout) {
+              clearTimeout(runTimeout);
+              runTimeout = undefined;
+            }
+            unsubscribe?.();
+            unsubscribe = undefined;
+            await disposeSubagentSession(session);
+            session = undefined;
+          }
+        };
+
+        let lastOutcome: ReturnType<typeof inspectFinalAssistant> | undefined;
+        let attemptErrorReason: string | undefined;
+        for (let index = 0; index < candidates.length; index++) {
+          if (abortController.callerAborted) break;
+          const candidate =
+            index === 0
+              ? candidates[index]
+              : withLibrarianFallbackReason(candidates[index], candidates[index - 1]);
+
+          let attempt: ReturnType<typeof inspectFinalAssistant>;
+          try {
+            attempt = await runAttempt(candidate);
+          } catch (error) {
+            if (abortController.callerAborted) throw error;
+            // Some providers throw (rather than carry the error on the assistant
+            // message) when a model is unavailable; treat that like a
+            // message-carried availability error and fall back to the next model.
+            const message = error instanceof Error ? error.message : String(error);
+            if (index < candidates.length - 1 && isModelAvailabilityError(message)) {
+              lastOutcome = undefined;
+              attemptErrorReason = `the internal subagent stopped with an error: ${message}`;
+              continue;
+            }
+            throw error;
+          }
+
+          lastOutcome = attempt;
+          if (abortController.callerAborted || attempt.ok) break;
+
+          attemptErrorReason = attempt.stopReason
+            ? attempt.reason
+            : describeNoAnswerReason(attempt.message, details.turns);
+          const canFallBack =
+            index < candidates.length - 1 &&
+            attempt.stopReason === "error" &&
+            isModelAvailabilityError(attempt.errorMessage);
+          if (!canFallBack) break;
+        }
+
+        const terminal = resolveLibrarianTerminalOutcome(
+          lastOutcome,
+          abortController.callerAborted,
+          details.turns,
+          attemptErrorReason,
+        );
+        details.status = terminal.status;
+        if (terminal.status === "error") {
+          lastContent = formatInternalFailure(details, terminal.reason);
+          details.error = terminal.reason;
+        } else {
+          lastContent = terminal.content;
+        }
+        details.endedAt = Date.now();
+        emit();
+
+        return {
+          content: [{ type: "text", text: lastContent }],
+          details,
+          usage,
+        };
+      } catch (error) {
+        const failure = classifyRunFailure(error, abortController.callerAborted);
+        const { message } = failure;
+        details.status = failure.status;
+        details.error = failure.error;
+        details.endedAt = Date.now();
+        lastContent = message;
+        emit();
+
+        return {
+          content: [{ type: "text", text: message }],
+          details,
+          usage,
+        };
+      } finally {
+        if (runTimeout) clearTimeout(runTimeout);
+        if (signal && abortListenerAdded) signal.removeEventListener("abort", abortFromCaller);
+        unsubscribe?.();
+        await disposeSubagentSession(session);
+      }
+    },
+
+    renderCall(args, theme) {
+      const query =
+        typeof (args as { query?: unknown })?.query === "string"
+          ? (args as { query: string }).query
+          : "";
+      const repos = Array.isArray((args as { repos?: unknown })?.repos)
+        ? (args as { repos: unknown[] }).repos.length
+        : 0;
+      const owners = Array.isArray((args as { owners?: unknown })?.owners)
+        ? (args as { owners: unknown[] }).owners.length
+        : 0;
+      return new Text(
+        `${theme.fg("muted", `repos:${repos} owners:${owners}`)} · ${theme.fg("toolOutput", shorten(query, 80))}`,
+        0,
+        0,
+      );
+    },
+
+    renderResult(result, { expanded, isPartial }, theme) {
+      const details = result.details as LibrarianDetails | undefined;
+      if (!details) {
+        const first = result.content[0];
+        return new Text(first?.type === "text" ? first.text : "(no output)", 0, 0);
+      }
+
+      const status = isPartial ? "running" : details.status;
+      const icon =
+        status === "done"
+          ? theme.fg("success", "✓")
+          : status === "error"
+            ? theme.fg("error", "✗")
+            : status === "aborted"
+              ? theme.fg("warning", "◼")
+              : theme.fg("warning", "⏳");
+
+      const cacheLabel =
+        details.cache.mode === "enabled"
+          ? theme.fg("success", "cache:on")
+          : theme.fg("muted", "cache:off");
+      const header = `${icon} ${theme.fg("toolTitle", theme.bold("librarian "))}${theme.fg(
+        "dim",
+        `${details.turns} turns • ${details.toolCalls.length} tools • `,
+      )}${cacheLabel}`;
+
+      const workspaceLine = `${theme.fg("muted", "workspace: ")}${theme.fg("toolOutput", details.workspace)}`;
+      const modelLine = `${theme.fg("muted", "model: ")}${theme.fg("toolOutput", details.model.modelRef)} ${theme.fg(
+        "dim",
+        `(${details.model.thinkingLevel}, ${details.model.autoSelected ? "auto" : "configured"})`,
+      )}`;
+      const cacheLine = `${theme.fg("muted", "cache: ")}${theme.fg("toolOutput", details.cache.root)} ${theme.fg(
+        "dim",
+        `(${details.cache.mode}, ${details.cache.ttlDays}d TTL, cleaned ${details.cache.cleanupDeleted})`,
+      )}`;
+
+      const answer =
+        (result.content[0]?.type === "text"
+          ? result.content[0].text
+          : renderAnswer(details)
+        ).trim() || "(no output)";
+
+      const toolLines = details.toolCalls.slice(expanded ? 0 : -6).map((call) => {
+        const callIcon = call.isError ? theme.fg("error", "✗") : theme.fg("dim", "→");
+        return `${callIcon} ${theme.fg("toolOutput", formatToolCall(call))}`;
+      });
+      if (!expanded && details.toolCalls.length > 6) toolLines.unshift(theme.fg("muted", "…"));
+
+      if (status === "running") {
+        const parts = [header, workspaceLine, modelLine, cacheLine];
+        if (toolLines.length) parts.push("", theme.fg("muted", "Tools:"), ...toolLines);
+        parts.push("", theme.fg("muted", "Searching GitHub…"));
+        return new Text(parts.join("\n"), 0, 0);
+      }
+
+      if (!expanded) {
+        const previewLines = answer.split("\n").slice(0, 18);
+        const parts = [
+          header,
+          workspaceLine,
+          modelLine,
+          cacheLine,
+          "",
+          theme.fg("toolOutput", previewLines.join("\n")),
+        ];
+        if (answer.split("\n").length > previewLines.length)
+          parts.push(theme.fg("muted", "(Ctrl+O to expand)"));
+        if (toolLines.length) parts.push("", theme.fg("muted", "Tools:"), ...toolLines);
+        return new Text(parts.join("\n"), 0, 0);
+      }
+
+      const container = new Container();
+      container.addChild(new Text(header, 0, 0));
+      container.addChild(new Text(workspaceLine, 0, 0));
+      container.addChild(new Text(modelLine, 0, 0));
+      container.addChild(new Text(cacheLine, 0, 0));
+      if (details.cache.cleanupErrors.length) {
+        container.addChild(
+          new Text(
+            theme.fg("warning", `cache cleanup warnings: ${details.cache.cleanupErrors.length}`),
+            0,
+            0,
+          ),
+        );
+      }
+      if (toolLines.length) {
+        container.addChild(new Spacer(1));
+        container.addChild(new Text([theme.fg("muted", "Tools:"), ...toolLines].join("\n"), 0, 0));
+      }
+      container.addChild(new Spacer(1));
+      container.addChild(new Markdown(answer, 0, 0, getMarkdownTheme()));
+      return container;
+    },
+  });
 }