@shanepadgett/tau-agent 0.26.0 → 0.28.0

package/extensions/explore/ast/tools/relationships.ts

@@ -0,0 +1,160 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatRelationshipResult } from "../format/relationships.ts";
+import type { ExploreFileGraph } from "../graph/file-graph.ts";
+import { queryRelationships, type RelationshipOp } from "../graph/relationships.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const relationshipParams = Type.Object(
+	{
+		path: Type.String({ description: "Directory scope (repo/package/subtree)" }),
+		targetPath: Type.Optional(Type.String({ description: "Defining file when known" })),
+		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
+		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line to pin one candidate" })),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max sites to return" }),
+	},
+	{ additionalProperties: false },
+);
+
+function createRelationshipTool(
+	op: RelationshipOp,
+	description: string,
+	promptSnippet: string,
+	promptGuidelines: string[],
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return defineTool<typeof relationshipParams, ExploreToolDetails>({
+		name: op,
+		label: op,
+		description,
+		promptSnippet,
+		promptGuidelines,
+		parameters: relationshipParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const graph = graphFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const result = await queryRelationships({
+				engine,
+				graph,
+				scopePath: params.path,
+				op,
+				targetPath: params.targetPath,
+				name: params.name,
+				line: params.line,
+				resultLimit: params.resultLimit,
+				signal: abort,
+			});
+			const text = formatRelationshipResult(result, engine.cwd);
+			const bounded = truncateBoundedHead(text);
+			const siteCount = result.kind === "resolved" ? result.sites.length : 0;
+			return {
+				content: [{ type: "text", text: bounded.content }],
+				details: {
+					declarationCount: siteCount,
+					returnedBytes: Buffer.byteLength(bounded.content),
+					truncated: bounded.truncated,
+				},
+			};
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const name = args.name ?? "?";
+			const scope = stripLeadingAt(args.path ?? "");
+			const pin = args.targetPath !== undefined ? stripLeadingAt(args.targetPath) : "";
+			const targets = pin.length > 0 ? [`${name} @ ${pin}`] : [name];
+			const options = [`[scope=${scope} limit=${args.resultLimit ?? "?"}]`];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, op, targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}
+
+export function createCallersTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return createRelationshipTool(
+		"callers",
+		"Syntactic call sites of a declaration. For types: constructions and implementors.",
+		"Find callers of a symbol",
+		[
+			"Use after selecting a change target when inbound uses affect the plan.",
+			"Disambiguate with targetPath or line when the name is common.",
+			"Treat ambiguous sites as non-actionable until tightened.",
+		],
+		rowState,
+		engineFor,
+		graphFor,
+	);
+}
+
+export function createCalleesTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return createRelationshipTool(
+		"callees",
+		"Direct callees inside a declaration body. For types: ancestor types from heritage.",
+		"Find callees of a symbol",
+		["Direct only — no depth parameter.", "Use to skim outbound dependencies before editing a body."],
+		rowState,
+		engineFor,
+		graphFor,
+	);
+}
+
+export function createReferencesTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return createRelationshipTool(
+		"references",
+		"Direct references: calls, constructions, imports, and heritage mentions of a declaration.",
+		"Find references to a symbol",
+		[
+			"Includes import and re-export-style bindings when classified.",
+			"Not a full IDE rename set — respect certainty labels.",
+		],
+		rowState,
+		engineFor,
+		graphFor,
+	);
+}
+
+export function createImplementationsTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return createRelationshipTool(
+		"implementations",
+		"Syntactic inheritance/implementation sites and conservative same-name overrides.",
+		"Find implementations of a type or method",
+		[
+			"For types: heritage clauses naming the target.",
+			"For methods: same-name methods on types that extend/implement the owner (conservative).",
+		],
+		rowState,
+		engineFor,
+		graphFor,
+	);
+}

package/extensions/explore/ast/tools/render.ts

@@ -0,0 +1,121 @@
+import { formatSize, keyHint, type Theme } from "@earendil-works/pi-coding-agent";
+import { Text, truncateToWidth, visibleWidth, type Component } from "@earendil-works/pi-tui";
+import { formatToolRowTitle, type ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+
+export type ExploreToolDetails = {
+	declarationCount: number;
+	returnedBytes: number;
+	truncated: boolean;
+};
+
+/**
+ * TUI title width fallbacks for a list: full join, progressively shorter with `,+N`, then summary.
+ * Callers wrap each variant with path/option chrome as needed.
+ */
+export function shrinkingListVariants(items: readonly string[], summary: string, empty = ""): string[] {
+	if (items.length === 0) return [empty];
+	const variants: string[] = [];
+	for (let shown = items.length; shown >= 1; shown -= 1) {
+		const omitted = items.length - shown;
+		const head = items.slice(0, shown).join(",");
+		variants.push(omitted > 0 ? `${head},+${omitted}` : head);
+	}
+	variants.push(summary);
+	return variants;
+}
+
+/** Compact call row: `tool → target [options]` with left-truncating target variants. */
+export class ExploreCallComponent implements Component {
+	private readonly rowState: ToolRowStateStore;
+	private readonly rowId: string;
+	private readonly tool: string;
+	targetVariants: string[];
+	optionVariants: string[];
+	theme: Theme;
+
+	constructor(
+		rowState: ToolRowStateStore,
+		rowId: string,
+		tool: string,
+		targetVariants: string[],
+		optionVariants: string[],
+		theme: Theme,
+	) {
+		this.rowState = rowState;
+		this.rowId = rowId;
+		this.tool = tool;
+		this.targetVariants = targetVariants;
+		this.optionVariants = optionVariants;
+		this.theme = theme;
+	}
+
+	render(width: number): string[] {
+		if (width <= 0) return [];
+		const prefixWidth = visibleWidth(`${this.tool} → `);
+		const shortestTarget = this.targetVariants.at(-1) ?? "";
+		const minimumTargetWidth = Math.min(12, visibleWidth(shortestTarget));
+		const options =
+			this.optionVariants.find(
+				(candidate) => prefixWidth + minimumTargetWidth + (candidate ? visibleWidth(candidate) + 1 : 0) <= width,
+			) ??
+			this.optionVariants.at(-1) ??
+			"";
+		const optionsWidth = options ? visibleWidth(options) + 1 : 0;
+		const targetWidth = Math.max(1, width - prefixWidth - optionsWidth);
+		const target = this.targetVariants.find((candidate) => visibleWidth(candidate) <= targetWidth) ?? shortestTarget;
+		const displayTarget = truncateLeft(target, targetWidth);
+		const line =
+			formatToolRowTitle(this.rowState, this.rowId, this.tool, this.theme) +
+			this.theme.fg("toolOutput", " → ") +
+			this.theme.fg("accent", displayTarget) +
+			(options ? ` ${this.theme.fg("muted", options)}` : "");
+		return [truncateToWidth(line, width, "")];
+	}
+
+	invalidate(): void {}
+}
+
+function truncateLeft(text: string, width: number): string {
+	if (width <= 0) return "";
+	if (visibleWidth(text) <= width) return text;
+	if (width === 1) return "…";
+	let suffix = "";
+	for (const character of Array.from(text).reverse()) {
+		if (visibleWidth(`…${character}${suffix}`) > width) break;
+		suffix = character + suffix;
+	}
+	return `…${suffix}`;
+}
+
+export function renderExploreResult(
+	result: { content: Array<{ type: string; text?: string }>; details?: ExploreToolDetails },
+	expanded: boolean,
+	theme: Theme,
+	context: { lastComponent?: Component; isError: boolean },
+): Text {
+	const text = (context.lastComponent as Text | undefined) ?? new Text("", 0, 0);
+	if (!expanded && !context.isError) {
+		const count = result.details?.declarationCount ?? 0;
+		const noun = count === 1 ? "declaration" : "declarations";
+		const bytes = result.details === undefined ? "" : `, ${formatSize(result.details.returnedBytes)} returned`;
+		text.setText(
+			theme.fg("muted", `${count} ${noun}${bytes} (`) +
+				keyHint("app.tools.expand", "to expand") +
+				theme.fg("muted", ")"),
+		);
+		return text;
+	}
+	const output = result.content
+		.filter((item): item is { type: string; text: string } => item.type === "text" && typeof item.text === "string")
+		.map((item) => item.text)
+		.join("\n");
+	text.setText(
+		output
+			? output
+					.split("\n")
+					.map((line) => theme.fg("toolOutput", line))
+					.join("\n")
+			: "",
+	);
+	return text;
+}

package/extensions/explore/ast/tools/reverse-deps.ts

@@ -0,0 +1,72 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatDepsResult, formatReverseDepsEmpty } from "../format/deps.ts";
+import type { ExploreFileGraph } from "../graph/file-graph.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, type ExploreToolDetails } from "./render.ts";
+
+const reverseDepsParams = Type.Object(
+	{
+		path: Type.String({ description: "Source file" }),
+		depth: Type.Optional(Type.Integer({ minimum: 1, description: "Traversal depth (default 1)" })),
+		resultLimit: Type.Integer({ minimum: 1, maximum: 100, description: "Max importer entries to return" }),
+	},
+	{ additionalProperties: false },
+);
+
+export function createReverseDepsTool(
+	rowState: ToolRowStateStore,
+	engineFor: (cwd: string) => ExploreEngine,
+	graphFor: (cwd: string) => ExploreFileGraph,
+) {
+	return defineTool<typeof reverseDepsParams, ExploreToolDetails>({
+		name: "reverse_deps",
+		label: "reverse_deps",
+		description:
+			"File-level: who imports this file within the inferred project scope. Depth > 1 walks transitive importers (BFS).",
+		promptSnippet: "List files that import this file",
+		promptGuidelines: [
+			"Use for file-level reverse dependencies, not symbol callers.",
+			"Scope is session cwd when the file is under it, else nearest git root.",
+			"Tighten resultLimit on large packages.",
+		],
+		parameters: reverseDepsParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const graph = graphFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const depth = params.depth ?? 1;
+			const result = await graph.reverseDeps(params.path, depth, params.resultLimit, abort);
+			const text = formatDepsResult(result, engine.cwd, formatReverseDepsEmpty());
+			const bounded = truncateBoundedHead(text);
+			return {
+				content: [{ type: "text", text: bounded.content }],
+				details: {
+					declarationCount: result.hits.length,
+					returnedBytes: Buffer.byteLength(bounded.content),
+					truncated: bounded.truncated,
+				},
+			};
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = [stripLeadingAt(args.path ?? "")];
+			const depth = args.depth ?? 1;
+			const options = [`[depth=${depth} limit=${args.resultLimit ?? "?"}]`];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "reverse_deps", targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}

package/extensions/explore/ast/tools/show.ts

@@ -0,0 +1,116 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { basename } from "node:path";
+import { Type, type Static } from "typebox";
+import { truncateBoundedHead } from "../../../../shared/bounded-text-result.ts";
+import type { ToolRowStateStore } from "../../../../shared/tool-row-state.ts";
+import type { ExploreEngine } from "../engine.ts";
+import { formatShowBatch } from "../format/show.ts";
+import { showTargets, type ShowTargetInput } from "../queries/show.ts";
+import { stripLeadingAt } from "../../traverse.ts";
+import { ExploreCallComponent, renderExploreResult, shrinkingListVariants, type ExploreToolDetails } from "./render.ts";
+
+const showTargetSchema = Type.Object(
+	{
+		path: Type.String({ description: "File containing the declaration" }),
+		name: Type.String({ minLength: 1, description: "Declaration name; may be dotted (Type.method)" }),
+		line: Type.Optional(Type.Integer({ minimum: 1, description: "1-indexed line covered by the declaration range" })),
+	},
+	{ additionalProperties: false },
+);
+
+const showParams = Type.Object(
+	{
+		targets: Type.Array(showTargetSchema, {
+			minItems: 1,
+			description: "One or more path+name targets (optional line to disambiguate)",
+		}),
+		view: StringEnum(["signature", "signatureWithDocs", "declaration", "declarationWithImports"] as const, {
+			description:
+				"signature omits docs and bodies; signatureWithDocs adds attached docs; declaration is exact source; declarationWithImports adds import statements that mention identifiers in the declaration",
+		}),
+		contextLines: Type.Optional(
+			Type.Integer({
+				minimum: 0,
+				description: "Lines of source context before and after each declaration (view=declaration only)",
+			}),
+		),
+	},
+	{ additionalProperties: false },
+);
+
+type ShowParams = Static<typeof showParams>;
+
+function showTargetVariants(targets: readonly ShowTargetInput[]): string[] {
+	if (targets.length === 0) return ["targets"];
+	const fileCount = new Set(targets.map((target) => stripLeadingAt(target.path))).size;
+	if (fileCount === 1) {
+		const first = targets[0];
+		const file = first === undefined ? "file" : basename(stripLeadingAt(first.path));
+		return shrinkingListVariants(
+			targets.map((target) => target.name),
+			`${targets.length} symbols`,
+		).map((part) => `${file}: ${part}`);
+	}
+	return shrinkingListVariants(
+		targets.map((target) => `${target.name}@${basename(stripLeadingAt(target.path))}`),
+		`${targets.length} symbols in ${fileCount} files`,
+	);
+}
+
+function showOptionLabel(params: ShowParams): string {
+	const context =
+		params.contextLines === undefined || params.view !== "declaration" ? "" : ` context=${params.contextLines}`;
+	return `[${params.view}${context}]`;
+}
+
+export function createShowTool(rowState: ToolRowStateStore, engineFor: (cwd: string) => ExploreEngine) {
+	return defineTool<typeof showParams, ExploreToolDetails>({
+		name: "show",
+		label: "show",
+		description:
+			"Return signatures, documented signatures, exact declarations, or declarations with related imports for path+name targets. Ambiguous or missing targets fail the whole batch with candidates — no partial bodies.",
+		promptSnippet: "Retrieve signatures or exact declarations for path+name targets",
+		promptGuidelines: [
+			"Prefer signature when the contract is enough; use signatureWithDocs only when attached docs matter.",
+			"Use declaration for exact implementation source; declarationWithImports when edit context needs imports.",
+			"Disambiguate with path and optional line. Do not guess among candidates.",
+			"If the batch exceeds the model-output budget, request fewer targets — show never truncates bodies.",
+		],
+		parameters: showParams,
+		async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+			const engine = engineFor(ctx.cwd);
+			const abort = signal ?? new AbortController().signal;
+			const batch = await showTargets(engine, params.targets, params.view, params.contextLines, abort);
+			const text = formatShowBatch(batch, engine.cwd);
+			const bounded = truncateBoundedHead(text);
+			if (bounded.truncated) {
+				throw new Error("show result exceeded the model-output budget. Request fewer targets.");
+			}
+			return {
+				content: [{ type: "text", text }],
+				details: {
+					declarationCount: batch.blocks.length,
+					returnedBytes: Buffer.byteLength(text),
+					truncated: false,
+				},
+			};
+		},
+		renderCall(args, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			const targets = showTargetVariants(args.targets ?? []);
+			const options = [showOptionLabel(args)];
+			const component =
+				(context.lastComponent as ExploreCallComponent | undefined) ??
+				new ExploreCallComponent(rowState, context.toolCallId, "show", targets, options, theme);
+			component.targetVariants = targets;
+			component.optionVariants = options;
+			component.theme = theme;
+			return component;
+		},
+		renderResult(result, options, theme, context) {
+			rowState.watch(context.toolCallId, context.invalidate);
+			return renderExploreResult(result, options.expanded, theme, context);
+		},
+	});
+}

package/extensions/explore/guidance.ts

@@ -0,0 +1,52 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { ExploreEngine } from "./ast/engine.ts";
+import { walkPaths } from "./traverse.ts";
+
+const GUIDANCE_SCAN_MAX_ENTRIES = 4096;
+
+export function registerExploreGuidance(pi: ExtensionAPI, engineFor: (cwd: string) => ExploreEngine): void {
+	pi.on("before_agent_start", async (event, ctx) => {
+		try {
+			const engine = engineFor(ctx.cwd);
+			const advertised = engine.registry
+				.registeredLanguages()
+				.filter((language) => language.capabilities.shape)
+				.map((language) => language.id);
+			const advertisedSet = new Set(advertised);
+			const detected = new Set<string>();
+
+			await walkPaths({
+				cwd: engine.cwd,
+				root: ".",
+				filesOnly: true,
+				budgets: { maxFiles: GUIDANCE_SCAN_MAX_ENTRIES },
+				onFile(hit) {
+					const language = engine.registry.adapterForPath(hit.absolutePath)?.id;
+					if (language !== undefined && advertisedSet.has(language)) detected.add(language);
+					return detected.size < advertisedSet.size;
+				},
+			});
+
+			const backed = advertised.filter((language) => detected.has(language));
+			if (backed.length === 0) return undefined;
+
+			const guidance = `## Explore source policy
+Structurally backed languages detected in this workspace: ${backed.map((language) => `\`${language}\``).join(", ")}.
+
+- Use the same workflow for every backed language. Identify the job type before loading deeply: locate, reuse, edit, explain, or debug.
+- Ask the smallest sufficient query and stop when it answers the question.
+- Prefer \`outline\` for unfamiliar trees and known packages. A large full harness \`read\` returns an outline; use ranged \`read\` or \`show\` for bodies.
+- Prefer \`discover\` when reuse is the goal and the path is unknown. Search package/public surfaces first.
+- Bind targets with path + name (+ line when needed). Use \`show\` views cheapest to richest: \`signature\`, \`signatureWithDocs\`, \`declaration\`, \`declarationWithImports\`.
+- Run \`impact\` before a non-trivial symbol change. Use \`context\` to understand one symbol in one bounded pack.
+- After selecting a target, use \`callers\`, \`callees\`, \`references\`, or \`implementations\` for focused relationship questions.
+- Use \`ast_search\` for code shapes and harness \`grep\` for literals. Use harness \`read\` for formatting, comments, gaps, and unsupported files.
+- List and search paths with harness \`ls\`, \`find\`, and \`grep\`. Edit only with harness patch/edit/write tools.
+- Trust structural hits as exact path, line, and source text. Do not ask for scores or engine metadata.`;
+
+			return { systemPrompt: `${event.systemPrompt}\n\n${guidance}` };
+		} catch {
+			return undefined;
+		}
+	});
+}

package/extensions/explore/index.ts

@@ -1,57 +1,103 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { resolve } from "node:path";
-import { onTauEvent } from "../../shared/events.js";
-import { createToolRowStateStore } from "../../shared/tool-row-state.js";
-import { createAstTools } from "./ast-tools.ts";
-import { AstWorkerClient } from "./ast-worker.ts";
-import { registerAutoread } from "./autoread.ts";
-import { createFindTool } from "./find.ts";
-import { createGrepTool } from "./grep.ts";
-import { createLsTool } from "./ls.ts";
-import { createReadCacheStore } from "./read-cache.ts";
-import { createReadSnapshotStore } from "./read-snapshots.ts";
-import { showReadStats } from "./read-stats.ts";
-import { createExploreReadTool } from "./read.ts";
+import { onTauEvent } from "../../shared/events.ts";
+import { createTemporaryOutputStore } from "../../shared/temporary-output-store.ts";
+import { createToolRowStateStore } from "../../shared/tool-row-state.ts";
+import { createExploreEngine, type ExploreEngine } from "./ast/engine.ts";
+import { createFileGraph, type ExploreFileGraph } from "./ast/graph/file-graph.ts";
+import { registerReadOutlineHook } from "./ast/read/hook.ts";
+import { createAstSearchTool } from "./ast/tools/ast-search.ts";
+import { createContextTool } from "./ast/tools/context.ts";
+import { createDepsTool } from "./ast/tools/deps.ts";
+import { createDiscoverTool } from "./ast/tools/discover.ts";
+import { createImpactTool } from "./ast/tools/impact.ts";
+import { createOutlineTool } from "./ast/tools/outline.ts";
+import {
+	createCalleesTool,
+	createCallersTool,
+	createImplementationsTool,
+	createReferencesTool,
+} from "./ast/tools/relationships.ts";
+import { createReverseDepsTool } from "./ast/tools/reverse-deps.ts";
+import { createShowTool } from "./ast/tools/show.ts";
+import { registerExploreGuidance } from "./guidance.ts";
+import { registerExploreAutoread } from "./read/autoread.ts";
 
 export default function exploreExtension(pi: ExtensionAPI): void {
 	const rowState = createToolRowStateStore(pi, "explore.tool-row-state");
-	const readCache = createReadCacheStore();
-	const readSnapshots = createReadSnapshotStore();
-	const astClient = new AstWorkerClient();
-	const ast = createAstTools(astClient, rowState);
-	registerAutoread(pi, rowState);
-	pi.registerTool(ast.outline);
-	pi.registerTool(ast.symbol);
-	pi.registerTool(createLsTool(rowState));
-	pi.registerTool(createFindTool(rowState));
-	pi.registerTool(createGrepTool(rowState));
-	pi.registerTool(createExploreReadTool(rowState, readCache, readSnapshots));
-	pi.registerCommand("read-stats", {
-		description: "Show estimated read token and cost savings for this session",
-		async handler(_args, ctx) {
-			if (ctx.mode !== "tui") {
-				ctx.ui.notify("Read stats require TUI mode", "error");
-				return;
-			}
-			await showReadStats(ctx);
-		},
-	});
-	pi.on("session_start", () => {
+	const temporaryOutput = createTemporaryOutputStore();
+	let engine: ExploreEngine | undefined;
+	let graph: ExploreFileGraph | undefined;
+
+	const engineFor = (cwd: string): ExploreEngine => {
+		const absoluteCwd = resolve(cwd);
+		if (engine !== undefined && engine.cwd === absoluteCwd) return engine;
+		engine?.shutdown();
+		graph?.clear();
+		engine = createExploreEngine({ cwd: absoluteCwd });
+		graph = createFileGraph(engine);
+		return engine;
+	};
+
+	const graphFor = (cwd: string): ExploreFileGraph => {
+		engineFor(cwd);
+		if (graph === undefined) {
+			throw new Error("Explore file graph failed to initialize");
+		}
+		return graph;
+	};
+
+	pi.registerTool(createOutlineTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createShowTool(rowState, engineFor));
+	pi.registerTool(createDiscoverTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createAstSearchTool(rowState, temporaryOutput, engineFor));
+	pi.registerTool(createDepsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createReverseDepsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createCallersTool(rowState, engineFor, graphFor));
+	pi.registerTool(createCalleesTool(rowState, engineFor, graphFor));
+	pi.registerTool(createReferencesTool(rowState, engineFor, graphFor));
+	pi.registerTool(createImplementationsTool(rowState, engineFor, graphFor));
+	pi.registerTool(createImpactTool(rowState, temporaryOutput, engineFor, graphFor));
+	pi.registerTool(createContextTool(rowState, temporaryOutput, engineFor, graphFor));
+	registerReadOutlineHook(pi, engineFor);
+	registerExploreAutoread(pi, rowState, engineFor);
+	registerExploreGuidance(pi, engineFor);
+
+	pi.on("session_start", async (_event, ctx) => {
+		await temporaryOutput.shutdown();
+		await temporaryOutput.start();
 		rowState.clear();
-		readSnapshots.clear();
-		ast.clear();
+		engine?.shutdown();
+		graph?.clear();
+		engine = createExploreEngine({ cwd: ctx.cwd });
+		graph = createFileGraph(engine);
 	});
+
 	onTauEvent(pi, "explore.ast", "tau:file-mutation.applied", (event) => {
-		const paths = event.changes.flatMap((change) => [
-			resolve(event.cwd, change.path),
-			...(change.move ? [resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)] : []),
-		]);
-		ast.invalidate(paths);
+		if (engine === undefined) return;
+		const paths = event.changes.flatMap((change) => {
+			const main = resolve(event.cwd, change.path);
+			if (change.move === undefined) return [main];
+			return [main, resolve(event.cwd, change.move.from), resolve(event.cwd, change.move.to)];
+		});
+		engine.invalidate(paths);
+		const topologyChanged = event.changes.some(
+			(change) => change.kind === "add" || change.kind === "delete" || change.move !== undefined,
+		);
+		if (topologyChanged) graph?.clear();
+		else graph?.invalidate(paths);
+	});
+
+	pi.on("session_tree", () => {
+		engine?.clear();
+		graph?.clear();
 	});
-	pi.on("session_compact", () => readSnapshots.clear());
-	pi.on("session_tree", () => readSnapshots.clear());
+
 	pi.on("session_shutdown", async () => {
-		ast.clear();
-		await astClient.shutdown();
+		engine?.shutdown();
+		engine = undefined;
+		graph?.clear();
+		graph = undefined;
+		await temporaryOutput.shutdown();
 	});
 }