@danypops/pi-lector 0.2.2 → 0.4.0

package/extension/src/index.ts

@@ -1,21 +1,17 @@
 import { resolve } from "node:path";
 import type {
-	CallHierarchyEntry,
 	ContentHash,
 	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
 	FindFilesResult,
-	GitDiffResult,
-	GitLogEntry,
-	GitStatusSummary,
 	Hover,
-	IncomingCall,
 	IntelligenceProvenance,
 	JobSnapshot,
 	LineEdit,
 	LineEditOutcome,
-	OutgoingCall,
+	MutationHistoryEntry,
+	OperationOutputs,
 	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
@@ -27,14 +23,23 @@ import type {
 	WorkspaceMapResult,
 	WorkspaceQueryOutcome,
 } from "@danypops/lector";
-import { createEditToolDefinition, createReadToolDefinition, createWriteToolDefinition, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+	type AgentToolResult,
+	createEditToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
+	type ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { createLectorApplyPatchOperations } from "./apply-patch-operations.ts";
 import { formatApplyPatchCall, formatApplyPatchResult } from "./apply-patch-rendering.ts";
 import { createLectorCodeIntelligenceOperations } from "./code-intelligence-operations.ts";
 import {
+	type CallHierarchyToolDetails,
 	describePopulateSymbolGraphJob,
+	formatCallHierarchyCall,
+	formatCallHierarchyResult,
 	formatDiagnosticsCall,
 	formatDiagnosticsResult,
 	formatDocumentSymbolsCall,
@@ -47,14 +52,8 @@ import {
 	formatGoToImplementationResult,
 	formatHoverCall,
 	formatHoverResult,
-	formatIncomingCallsCall,
-	formatIncomingCallsResult,
-	formatOutgoingCallsCall,
-	formatOutgoingCallsResult,
 	formatPopulateSymbolGraphCall,
 	formatPopulateSymbolGraphResult,
-	formatPrepareCallHierarchyCall,
-	formatPrepareCallHierarchyResult,
 	formatReachableFromCall,
 	formatReachableFromResult,
 	formatWorkspaceMapCall,
@@ -68,13 +67,18 @@ import { formatFindFilesCall, formatFindFilesResult } from "./find-files-renderi
 import { createLectorFindSymbolsOperations } from "./find-symbols-operations.ts";
 import { describeFindSymbolSources, formatFindSymbolsCall, formatFindSymbolsResult } from "./find-symbols-rendering.ts";
 import { createLectorGitOperations } from "./git-operations.ts";
-import { formatGitDiffCall, formatGitDiffResult, formatGitLogCall, formatGitLogResult, formatGitStatusCall, formatGitStatusResult } from "./git-rendering.ts";
+import { formatGitCall, formatGitResult, type GitToolDetails } from "./git-rendering.ts";
+import { setNewWorkspaceObserver } from "./lector-client.ts";
 import { createLectorLineEditOperations } from "./line-edit-operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
+import { createMutationHistoryOperations } from "./mutation-history-operations.ts";
 import { nearestGitRoot } from "./nearest-workspace-root.ts";
 import { createLectorPackageSourceOperations } from "./package-source-operations.ts";
 import { formatPackageSourceCall, formatPackageSourceResult } from "./package-source-rendering.ts";
 import { createLectorReadOperations } from "./read-operations.ts";
+import { createReferenceBasedRenameOperations } from "./reference-based-rename-operations.ts";
+import { createRenameOperations } from "./rename-operations.ts";
+import { createRepoCacheListOperations } from "./repo-cache-list-operations.ts";
 import { createLectorRepoFetchOperations } from "./repo-fetch-operations.ts";
 import { formatRepoFetchCall, formatRepoFetchResult } from "./repo-fetch-rendering.ts";
 import { createLectorSearchOperations } from "./search-operations.ts";
@@ -118,63 +122,115 @@ function renderIntelligenceSource(body: string, provenance: IntelligenceProvenan
  */
 export default function (pi: ExtensionAPI) {
 	const cacheOperations = createWorkspaceCacheOperations();
-	let cacheRun = 0;
-	let cacheState: CachePresentationState | undefined;
-	let lastInjectedCacheState: string | undefined;
+	// One generation counter shared by every root's monitor loop, not per-root -- a new session
+	// (or shutdown) invalidates every previous session's in-flight monitor regardless of which
+	// root it tracked, and there is exactly one "current session" at a time.
+	let sessionGeneration = 0;
+	// Every workspace root actually touched so far this session, not just one fixed cwd root --
+	// populated by setNewWorkspaceObserver below, the real "first touch" trigger.
+	const cacheStatesByRoot = new Map<string, CachePresentationState>();
+	// Roots already monitored this session -- guards against starting the SAME root's monitor
+	// twice: session_start's own direct kick-off for the cwd root itself calls
+	// cacheOperations.status(), which registers that root via workspace.registerPath, which fires
+	// setNewWorkspaceObserver for it a moment later -- without this guard that would start a
+	// second, redundant concurrent monitor loop for the exact same root.
+	const monitoringRoots = new Set<string>();
+	let lastInjectedSummary: string | undefined;
+	let uiContext: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1] | undefined;
+
+	function combinedSummary(): string {
+		const states = [...cacheStatesByRoot.values()];
+		if (states.length === 0) return "";
+		const [only] = states;
+		if (states.length === 1 && only) return describeCacheState(only);
+		const counts = new Map<string, number>();
+		for (const state of states) counts.set(state.status, (counts.get(state.status) ?? 0) + 1);
+		return [...counts.entries()].map(([status, count]) => `${count} ${status}`).join(", ");
+	}
+
+	function refreshStatusBar(): void {
+		if (!uiContext) return;
+		const summary = combinedSummary();
+		if (!summary) {
+			uiContext.ui.setStatus("lector-cache", undefined);
+			return;
+		}
+		const states = [...cacheStatesByRoot.values()];
+		const worst = states.some((state) => state.status === "not-cached" || state.status === "caching")
+			? "warning"
+			: states.every((state) => state.status === "cached")
+				? "success"
+				: "accent";
+		uiContext.ui.setStatus("lector-cache", uiContext.ui.theme.fg(worst, `Lector: ${summary}`));
+	}
+
+	/** Starts (or restarts, on a stale generation) monitoring one workspace root's cache lifecycle -- shared by session_start's own cwd root and every later root a tool call first touches. */
+	function startMonitoringRoot(root: string, ctx: Parameters<Parameters<ExtensionAPI["on"]>[1]>[1]): void {
+		if (monitoringRoots.has(root)) return;
+		monitoringRoots.add(root);
+		const thisGeneration = sessionGeneration;
+		void monitorWorkspaceCache(cacheOperations, {
+			directory: root,
+			maxFiles: 500,
+			maxSymbolsPerFile: 100,
+			pollIntervalMs: 1_000,
+			maxPolls: 300,
+			shouldContinue: () => sessionGeneration === thisGeneration,
+			onState: (state) => {
+				if (sessionGeneration !== thisGeneration) return;
+				cacheStatesByRoot.set(root, state);
+				if (state.status === "finished-caching") {
+					if (ctx.hasUI) ctx.ui.notify(`Lector finished caching ${root}`, "info");
+					return;
+				}
+				refreshStatusBar();
+			},
+		}).catch((error: unknown) => {
+			if (sessionGeneration !== thisGeneration) return;
+			const message = error instanceof Error ? error.message : String(error);
+			cacheStatesByRoot.delete(root);
+			refreshStatusBar();
+			if (ctx.hasUI) ctx.ui.notify(`Lector cache failed for ${root}: ${message}`, "error");
+		});
+	}
 
 	pi.on("before_agent_start", () => {
-		if (!cacheState) return;
-		const description = describeCacheState(cacheState);
-		if (description === lastInjectedCacheState) return;
-		lastInjectedCacheState = description;
+		const summary = combinedSummary();
+		if (!summary || summary === lastInjectedSummary) return;
+		lastInjectedSummary = summary;
+		const messages = [...cacheStatesByRoot.entries()]
+			.filter(([, state]) => state.status !== "cached")
+			.map(([root, state]) => `${root}: ${cacheContextMessage(state)}`);
+		if (messages.length === 0) return;
 		return {
 			message: {
 				customType: "lector-cache-status",
-				content: cacheContextMessage(cacheState),
+				content: messages.join("\n"),
 				display: false,
 			},
 		};
 	});
 
 	pi.on("session_shutdown", (_event, ctx) => {
-		cacheRun++;
-		cacheState = undefined;
-		lastInjectedCacheState = undefined;
+		sessionGeneration++;
+		cacheStatesByRoot.clear();
+		monitoringRoots.clear();
+		lastInjectedSummary = undefined;
+		uiContext = undefined;
 		ctx.ui.setStatus("lector-cache", undefined);
 	});
 
 	pi.on("session_start", (_event, ctx) => {
 		const { cwd } = ctx;
+		sessionGeneration++;
+		cacheStatesByRoot.clear();
+		monitoringRoots.clear();
+		lastInjectedSummary = undefined;
+		uiContext = ctx;
+		setNewWorkspaceObserver((root) => startMonitoringRoot(root, ctx));
 		const projectRoot = nearestGitRoot(cwd);
-		const thisRun = ++cacheRun;
-		cacheState = undefined;
-		lastInjectedCacheState = undefined;
-		if (projectRoot) {
-			void monitorWorkspaceCache(cacheOperations, {
-				directory: projectRoot,
-				maxFiles: 500,
-				maxSymbolsPerFile: 100,
-				pollIntervalMs: 1_000,
-				maxPolls: 300,
-				shouldContinue: () => cacheRun === thisRun,
-				onState: (state) => {
-					cacheState = state;
-					if (state.status === "finished-caching") {
-						if (ctx.hasUI) ctx.ui.notify(`Lector finished caching ${projectRoot}`, "info");
-						return;
-					}
-					const color = state.status === "cached" ? "success" : state.status === "caching" ? "accent" : "warning";
-					ctx.ui.setStatus("lector-cache", ctx.ui.theme.fg(color, `Lector: ${describeCacheState(state)}`));
-				},
-			}).catch((error: unknown) => {
-				if (cacheRun !== thisRun) return;
-				const message = error instanceof Error ? error.message : String(error);
-				ctx.ui.setStatus("lector-cache", ctx.ui.theme.fg("error", "Lector: cache error"));
-				if (ctx.hasUI) ctx.ui.notify(`Lector cache failed: ${message}`, "error");
-			});
-		} else {
-			ctx.ui.setStatus("lector-cache", undefined);
-		}
+		if (projectRoot) startMonitoringRoot(projectRoot, ctx);
+		else ctx.ui.setStatus("lector-cache", undefined);
 
 		pi.registerTool(createReadToolDefinition(cwd, { operations: createLectorReadOperations() }));
 		pi.registerTool(createWriteToolDefinition(cwd, { operations: createLectorWriteOperations() }));
@@ -221,7 +277,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatFindSymbolsCall(args as { query?: unknown; directory?: unknown }, theme));
+				text.setText(formatFindSymbolsCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -236,7 +292,7 @@ export default function (pi: ExtensionAPI) {
 					return new Text(theme.fg("error", errorText || "find_symbols failed"), 0, 0);
 				}
 				const details = result.details as SymbolSearchResult | undefined;
-				const query = typeof context.args?.query === "string" ? context.args.query : "";
+				const query = typeof context.args.query === "string" ? context.args.query : "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(formatFindSymbolsResult(details, query, expanded, theme));
 				return text;
@@ -244,6 +300,8 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const codeIntelligenceOperations = createLectorCodeIntelligenceOperations();
+		const referenceBasedRenameOperations = createReferenceBasedRenameOperations();
+		const renameOperations = createRenameOperations();
 		const positionParameters = {
 			path: Type.String({ description: "Absolute or cwd-relative path to the file" }),
 			line: Type.Number({ description: "1-indexed line number" }),
@@ -265,7 +323,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGoToDefinitionCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
+				text.setText(formatGoToDefinitionCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -303,7 +361,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGoToImplementationCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
+				text.setText(formatGoToImplementationCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -348,7 +406,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatFindReferencesCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
+				text.setText(formatFindReferencesCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -388,7 +446,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatHoverCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
+				text.setText(formatHoverCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -422,7 +480,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatDocumentSymbolsCall(args as { path?: unknown }, theme));
+				text.setText(formatDocumentSymbolsCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -459,7 +517,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatDiagnosticsCall(args as { path?: unknown }, theme));
+				text.setText(formatDiagnosticsCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -479,118 +537,67 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		pi.registerTool({
-			name: "prepare_call_hierarchy",
-			label: "Prepare Call Hierarchy",
-			description: "Resolve the symbol at an exact file position to its call-hierarchy root -- the first step before incoming_calls or outgoing_calls.",
-			promptSnippet: "Resolve a position to a call-hierarchy root",
+			name: "call_hierarchy",
+			label: "Call Hierarchy",
+			description:
+				"Resolve the symbol at an exact file position to its call-hierarchy root, or find its real callers/callees, project-wide, in one tool. ACTIONS: prepare (confirm what the position resolves to), incoming (who actually calls it, as distinct from find_references which also finds non-call usages), outgoing (what it itself calls).",
+			promptSnippet: "Resolve a position to a call-hierarchy root, or find its callers/callees",
 			promptGuidelines: [
-				"Use prepare_call_hierarchy to confirm what a position resolves to before asking for its callers or callees; incoming_calls and outgoing_calls also do this internally, so calling it first is optional, not required.",
+				"direction=prepare is optional -- incoming/outgoing already resolve the position internally, so calling prepare first is never required, only useful to confirm what a position resolves to.",
+				"direction=incoming finds real callers, distinct from find_references which also finds non-call usages like type positions or re-exports.",
 			],
-			parameters: Type.Object(positionParameters),
-			async execute(_toolCallId, params) {
+			parameters: Type.Object({
+				direction: Type.String({ description: "prepare | incoming | outgoing" }),
+				...positionParameters,
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<CallHierarchyToolDetails>> {
 				const path = resolve(cwd, params.path);
-				const details = await codeIntelligenceOperations.prepareCallHierarchy(path, params.line, params.character);
-				const text =
-					details.items.length === 0
-						? "No call-hierarchy root at this position."
-						: details.items.map((i) => `${i.kind} ${i.name} -- ${i.location.path}:${i.location.line}:${i.location.character}`).join("\n");
-				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
-			},
-			renderCall(args, theme, context) {
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatPrepareCallHierarchyCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
-				return text;
-			},
-			renderResult(result, { isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Resolving position..."), 0, 0);
-				if (context.isError) {
-					const errorText = result.content
-						.filter((block) => block.type === "text")
-						.map((block) => block.text)
-						.join("\n");
-					return new Text(theme.fg("error", errorText || "prepare_call_hierarchy failed"), 0, 0);
+				if (params.direction === "prepare") {
+					const { items, provenance } = await codeIntelligenceOperations.prepareCallHierarchy(path, params.line, params.character);
+					const text =
+						items.length === 0
+							? "No call-hierarchy root at this position."
+							: items.map((i) => `${i.kind} ${i.name} -- ${i.location.path}:${i.location.line}:${i.location.character}`).join("\n");
+					const details: CallHierarchyToolDetails = { direction: "prepare", items, provenance };
+					return { content: [{ type: "text", text: `${describeIntelligenceSource(provenance)}\n${text}` }], details };
 				}
-				const details = result.details as { items?: readonly CallHierarchyEntry[]; provenance?: IntelligenceProvenance } | undefined;
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(renderIntelligenceSource(formatPrepareCallHierarchyResult(details?.items, theme), details?.provenance, theme));
-				return text;
-			},
-		});
-
-		pi.registerTool({
-			name: "incoming_calls",
-			label: "Incoming Calls",
-			description: "Find every real caller of the function/method at an exact file position, project-wide.",
-			promptSnippet: "Find every caller of a function from an exact position",
-			promptGuidelines: [
-				"Use incoming_calls to see who actually calls a function, as distinct from find_references, which also finds non-call usages like type positions or re-exports.",
-			],
-			parameters: Type.Object(positionParameters),
-			async execute(_toolCallId, params) {
-				const path = resolve(cwd, params.path);
-				const details = await codeIntelligenceOperations.incomingCalls(path, params.line, params.character);
-				const text =
-					details.calls.length === 0
-						? "No incoming calls found."
-						: details.calls
-								.map((c) => `${c.from.kind} ${c.from.name} -- ${c.from.location.path}:${c.from.location.line}:${c.from.location.character}`)
-								.join("\n");
-				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
-			},
-			renderCall(args, theme, context) {
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatIncomingCallsCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
-				return text;
-			},
-			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Searching for callers..."), 0, 0);
-				if (context.isError) {
-					const errorText = result.content
-						.filter((block) => block.type === "text")
-						.map((block) => block.text)
-						.join("\n");
-					return new Text(theme.fg("error", errorText || "incoming_calls failed"), 0, 0);
+				if (params.direction === "incoming") {
+					const { calls, provenance } = await codeIntelligenceOperations.incomingCalls(path, params.line, params.character);
+					const text =
+						calls.length === 0
+							? "No incoming calls found."
+							: calls.map((c) => `${c.from.kind} ${c.from.name} -- ${c.from.location.path}:${c.from.location.line}:${c.from.location.character}`).join("\n");
+					const details: CallHierarchyToolDetails = { direction: "incoming", calls, provenance };
+					return { content: [{ type: "text", text: `${describeIntelligenceSource(provenance)}\n${text}` }], details };
 				}
-				const details = result.details as { calls?: readonly IncomingCall[]; provenance?: IntelligenceProvenance } | undefined;
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(renderIntelligenceSource(formatIncomingCallsResult(details?.calls, expanded, theme), details?.provenance, theme));
-				return text;
-			},
-		});
-
-		pi.registerTool({
-			name: "outgoing_calls",
-			label: "Outgoing Calls",
-			description: "Find every function/method the function at an exact file position itself calls.",
-			promptSnippet: "Find every function a function itself calls",
-			promptGuidelines: ["Use outgoing_calls to see what a function calls internally, e.g. to trace a code path forward without opening every file by hand."],
-			parameters: Type.Object(positionParameters),
-			async execute(_toolCallId, params) {
-				const path = resolve(cwd, params.path);
-				const details = await codeIntelligenceOperations.outgoingCalls(path, params.line, params.character);
-				const text =
-					details.calls.length === 0
-						? "No outgoing calls found."
-						: details.calls.map((c) => `${c.to.kind} ${c.to.name} -- ${c.to.location.path}:${c.to.location.line}:${c.to.location.character}`).join("\n");
-				return { content: [{ type: "text", text: `${describeIntelligenceSource(details.provenance)}\n${text}` }], details };
+				if (params.direction === "outgoing") {
+					const { calls, provenance } = await codeIntelligenceOperations.outgoingCalls(path, params.line, params.character);
+					const text =
+						calls.length === 0
+							? "No outgoing calls found."
+							: calls.map((c) => `${c.to.kind} ${c.to.name} -- ${c.to.location.path}:${c.to.location.line}:${c.to.location.character}`).join("\n");
+					const details: CallHierarchyToolDetails = { direction: "outgoing", calls, provenance };
+					return { content: [{ type: "text", text: `${describeIntelligenceSource(provenance)}\n${text}` }], details };
+				}
+				throw new Error(`unknown call_hierarchy direction: ${String(params.direction)}`);
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatOutgoingCallsCall(args as { path?: unknown; line?: unknown; character?: unknown }, theme));
+				text.setText(formatCallHierarchyCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Searching for callees..."), 0, 0);
+				if (isPartial) return new Text(theme.fg("warning", "Resolving call hierarchy..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
 						.filter((block) => block.type === "text")
 						.map((block) => block.text)
 						.join("\n");
-					return new Text(theme.fg("error", errorText || "outgoing_calls failed"), 0, 0);
+					return new Text(theme.fg("error", errorText || "call_hierarchy failed"), 0, 0);
 				}
-				const details = result.details as { calls?: readonly OutgoingCall[]; provenance?: IntelligenceProvenance } | undefined;
+				const details = result.details as CallHierarchyToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(renderIntelligenceSource(formatOutgoingCallsResult(details?.calls, expanded, theme), details?.provenance, theme));
+				text.setText(renderIntelligenceSource(formatCallHierarchyResult(details, expanded, theme), details?.provenance, theme));
 				return text;
 			},
 		});
@@ -599,7 +606,7 @@ export default function (pi: ExtensionAPI) {
 			name: "populate_symbol_graph",
 			label: "Populate Symbol Graph",
 			description:
-				"Walk a workspace's real call relationships into a persisted graph, so reachable_from can answer multi-hop questions (transitive callers, reachability) without chaining many find_references/outgoing_calls calls by hand. Run this once before reachable_from.",
+				"Walk a workspace's real call relationships into a persisted graph, so reachable_from can answer multi-hop questions (transitive callers, reachability) without chaining many find_references/call_hierarchy calls by hand. Run this once before reachable_from.",
 			promptSnippet: "Populate a workspace's symbol graph for multi-hop queries",
 			promptGuidelines: [
 				"Run populate_symbol_graph once for a workspace before using reachable_from against it; an unpopulated workspace's graph is empty, not an error.",
@@ -622,7 +629,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatPopulateSymbolGraphCall(args as { path?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown }, theme));
+				text.setText(formatPopulateSymbolGraphCall(args, theme));
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -676,6 +683,125 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		pi.registerTool({
+			name: "reference_based_rename",
+			label: "Reference-Based Rename",
+			description:
+				"Move/rename a file and rewrite every static import/export specifier the workspace's own populated symbol graph knows references it -- atomically, rolled back entirely on any failure. Non-LSP: uses find_references + a real parse of import/export declarations, not a language server's own rename. Refuses outright (touches nothing) unless the workspace's symbol graph is fully populated and current for the given bounds -- a partial rename that silently misses a reference is worse than refusing (Sourcegraph's CodeScaleBench finding). Does not follow dynamic import(expr)/require(expr) or any plain string reference to the file -- always check the returned caveats.",
+			promptSnippet: "Move a file and update every import that references it",
+			promptGuidelines: [
+				"Run populate_symbol_graph for this workspace first if cache_status/has_warm_index doesn't already show a fully cached (never partial) graph -- reference_based_rename refuses outright otherwise.",
+				"Always read the returned caveats: this never rewrites a dynamic import(expr)/require(expr) or a plain string reference to the old path, even if one exists.",
+			],
+			parameters: Type.Object({
+				fromPath: Type.String({ description: "Absolute or cwd-relative path to the file to move" }),
+				toPath: Type.String({ description: "Absolute or cwd-relative path for its new location" }),
+				maxFiles: Type.Number({ description: "Maximum number of source files the workspace's symbol graph must have scanned" }),
+				maxSymbolsPerFile: Type.Number({ description: "Maximum number of declarations per file the workspace's symbol graph must have processed" }),
+			}),
+			async execute(_toolCallId, params) {
+				const fromPath = resolve(cwd, params.fromPath);
+				const toPath = resolve(cwd, params.toPath);
+				const outcome = await referenceBasedRenameOperations.rename(fromPath, toPath, params.maxFiles, params.maxSymbolsPerFile);
+				const lines = [
+					`moved to ${outcome.movedTo}`,
+					outcome.filesUpdated.length === 0
+						? "no other files referenced it"
+						: `updated imports in ${outcome.filesUpdated.length} file(s): ${outcome.filesUpdated.join(", ")}`,
+					...outcome.caveats.map((caveat) => `caveat: ${caveat}`),
+				];
+				return { content: [{ type: "text", text: lines.join("\n") }], details: { outcome } };
+			},
+			renderCall(args, theme, context) {
+				const fromPath = typeof args.fromPath === "string" ? args.fromPath : "";
+				const toPath = typeof args.toPath === "string" ? args.toPath : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(
+					`${theme.fg("toolTitle", theme.bold("reference_based_rename"))} ${theme.fg("accent", fromPath)} ${theme.fg("dim", "->")} ${theme.fg("accent", toPath)}`,
+				);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Renaming..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "reference_based_rename failed"), 0, 0);
+				}
+				const details = result.details as { outcome?: { movedTo: string; filesUpdated: readonly string[] } } | undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(
+					details?.outcome
+						? `${theme.fg("success", "moved")} ${theme.fg("accent", details.outcome.movedTo)} ${theme.fg("dim", `(${details.outcome.filesUpdated.length} import(s) updated)`)}`
+						: theme.fg("success", "rename complete"),
+				);
+				return text;
+			},
+		});
+
+		interface RenameToolDetails {
+			prepared?: OperationOutputs["workspace.prepareRename"];
+			applied?: OperationOutputs["workspace.rename"];
+		}
+
+		pi.registerTool({
+			name: "rename",
+			label: "Rename",
+			description:
+				"LSP-driven rename via the negotiated language server's own textDocument/prepareRename and textDocument/rename -- the semantic sibling of reference_based_rename, cross-file and identity-aware (resolves through re-exports/aliasing, not just static import specifiers), but only where the workspace's language server actually implements rename. prepare checks whether the symbol at a position can be renamed at all before committing; apply requests the rename and applies the server's own WorkspaceEdit atomically across every file it touches, rolled back entirely on any failure. Actions: prepare, apply.",
+			promptSnippet: "Rename a symbol everywhere it's used, via the language server",
+			promptGuidelines: [
+				"Call prepare first when unsure a position is renameable -- a null range means nothing to rename there, not an error.",
+				"apply fails outright if the negotiated server never advertised rename support -- reference_based_rename is the non-LSP fallback for that case.",
+			],
+			parameters: Type.Object({
+				action: Type.String({ description: "prepare | apply" }),
+				...positionParameters,
+				newName: Type.Optional(Type.String({ description: "Required for apply" })),
+			}),
+			async execute(_toolCallId, params): Promise<{ content: [{ type: "text"; text: string }]; details: RenameToolDetails }> {
+				const path = resolve(cwd, params.path);
+				if (params.action === "prepare") {
+					const prepared = await renameOperations.prepareRename(path, params.line, params.character);
+					const text = prepared.range
+						? `renameable${prepared.range.placeholder ? `: "${prepared.range.placeholder}"` : ""}`
+						: "nothing renameable at this position";
+					return { content: [{ type: "text", text }], details: { prepared } };
+				}
+				if (params.action === "apply") {
+					if (!params.newName) throw new Error("rename apply requires newName");
+					const applied = await renameOperations.rename(path, params.line, params.character, params.newName);
+					const text = `renamed to "${params.newName}" -- updated ${applied.touchedPaths.length} file(s): ${applied.touchedPaths.join(", ")}`;
+					return { content: [{ type: "text", text }], details: { applied } };
+				}
+				throw new Error(`unknown rename action "${params.action}" -- expected prepare or apply`);
+			},
+			renderCall(args, theme, context) {
+				const action = typeof args.action === "string" ? args.action : "";
+				const path = typeof args.path === "string" ? args.path : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("rename"))} ${theme.fg("dim", action)} ${theme.fg("accent", path)}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Renaming..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "rename failed"), 0, 0);
+				}
+				const text = result.content
+					.filter((block) => block.type === "text")
+					.map((block) => block.text)
+					.join("\n");
+				return new Text(theme.fg("success", text), 0, 0);
+			},
+		});
+
 		const symbolAnnotationOperations = createLectorSymbolAnnotationOperations();
 		function resolveAnchorInputs(anchors: readonly { path: string; line: number; character: number }[]): AnnotationAnchorInput[] {
 			return anchors.map((anchor) => ({ path: resolve(cwd, anchor.path), line: anchor.line, character: anchor.character }));
@@ -685,20 +811,24 @@ export default function (pi: ExtensionAPI) {
 			annotations?: readonly SymbolAnnotation[];
 			scrubbed?: boolean;
 			restored?: boolean;
+			contained?: boolean;
+			uncontained?: boolean;
 		}
 
 		pi.registerTool({
 			name: "symbol_annotations",
 			label: "Symbol Annotations",
 			description:
-				'Agent-authored narrative content anchored to one or more symbols in the workspace\'s persisted graph -- e.g. a "user story dataflow" note spanning every symbol touched end-to-end. Every anchor must resolve to a real, currently-known symbol (run populate_symbol_graph first). get/list live-check staleness against the current graph/workspace on every call and persist a correction before returning, so a returned status never disagrees with reality -- a stale annotation must be refreshed (re-authored and re-anchored) or scrubbed (soft-deleted, restorable) by an explicit decision; Lector never rewrites the narrative itself. Actions: create, get, list, refresh, scrub, restore.',
+				'Agent-authored narrative content anchored to one or more symbols in the workspace\'s persisted graph -- e.g. a "user story dataflow" note spanning every symbol touched end-to-end. Every anchor must resolve to a real, currently-known symbol (run populate_symbol_graph first). get/list/tree live-check staleness against the current graph/workspace on every call and persist a correction before returning, so a returned status never disagrees with reality -- a stale annotation must be refreshed (re-authored and re-anchored) or scrubbed (soft-deleted, restorable) by an explicit decision; Lector never rewrites the narrative itself. contain/uncontain build a reusable, nestable structure on top of plain annotations: a container (e.g. a "data flow") can contain other annotations -- including per-symbol notes shared by more than one container (DRY reuse) or another container one level deeper (nested data flows) -- without duplicating their content. tree reads a whole bounded subtree in one call. Actions: create, get, list, refresh, scrub, restore, contain, uncontain, tree.',
 			promptSnippet: "Attach, read, or invalidate narrative annotations on the symbol graph",
 			promptGuidelines: [
 				"Resolve real anchor positions first (find_symbols/document_symbols/go_to_definition) -- an anchor position must match populate_symbol_graph's own recorded position for that symbol, not just any occurrence of its name.",
 				"A stale annotation's body may no longer describe the code accurately -- read it, decide whether to refresh (re-author) or scrub (remove), never trust it as-is.",
+				"Prefer reusing an existing per-symbol annotation as a shared child of several containers over re-authoring the same explanation in each -- that reuse is the reason contain/uncontain exist.",
+				"contain/uncontain are idempotent (containing an already-contained child, or uncontaining an already-absent relationship, is a no-op, not an error) and reject a cycle up front rather than accepting one.",
 			],
 			parameters: Type.Object({
-				action: Type.String({ description: "create | get | list | refresh | scrub | restore" }),
+				action: Type.String({ description: "create | get | list | refresh | scrub | restore | contain | uncontain | tree" }),
 				path: Type.String({ description: "Absolute or cwd-relative path used to resolve which workspace this annotation belongs to" }),
 				id: Type.Optional(Type.String({ description: "Annotation id -- required for get/refresh/scrub/restore" })),
 				subtype: Type.Optional(Type.String({ description: 'Free-form kind, e.g. "user-story-dataflow" or "comment" -- required for create/refresh' })),
@@ -716,7 +846,14 @@ export default function (pi: ExtensionAPI) {
 				),
 				listStatus: Type.Optional(Type.String({ description: "fresh | stale | scrubbed -- for list; defaults to excluding scrubbed" })),
 				listSubtype: Type.Optional(Type.String({ description: "For list: filter by subtype" })),
+				listQuery: Type.Optional(
+					Type.String({ description: "For list: case-insensitive substring match against title or body -- the near-term free-text search over annotations" }),
+				),
 				maxResults: Type.Optional(Type.Number({ description: "For list: bounds the number of results" })),
+				parentId: Type.Optional(Type.String({ description: "The containing annotation's id -- required for contain/uncontain" })),
+				childId: Type.Optional(Type.String({ description: "The contained annotation's id -- required for contain/uncontain" })),
+				rootId: Type.Optional(Type.String({ description: "The subtree's root annotation id -- required for tree" })),
+				maxDepth: Type.Optional(Type.Number({ description: "Maximum containment hops from rootId to include -- required for tree" })),
 			}),
 			async execute(_toolCallId, params) {
 				const path = resolve(cwd, params.path);
@@ -736,7 +873,12 @@ export default function (pi: ExtensionAPI) {
 					text = annotation ? formatAnnotationDetail(annotation) : `no annotation "${params.id}"`;
 				} else if (params.action === "list") {
 					const status = params.listStatus === "fresh" || params.listStatus === "stale" || params.listStatus === "scrubbed" ? params.listStatus : undefined;
-					const { annotations } = await symbolAnnotationOperations.list(path, { subtype: params.listSubtype, status, maxResults: params.maxResults });
+					const { annotations } = await symbolAnnotationOperations.list(path, {
+						subtype: params.listSubtype,
+						status,
+						maxResults: params.maxResults,
+						query: params.listQuery,
+					});
 					details.annotations = annotations;
 					text = annotations.length === 0 ? "no annotations" : annotations.map(formatAnnotationDetail).join("\n\n");
 				} else if (params.action === "refresh") {
@@ -763,6 +905,21 @@ export default function (pi: ExtensionAPI) {
 					const { restored } = await symbolAnnotationOperations.restore(path, params.id);
 					details.restored = restored;
 					text = restored ? `restored ${params.id}` : `"${params.id}" was not scrubbed or does not exist`;
+				} else if (params.action === "contain") {
+					if (!params.parentId || !params.childId) throw new Error("symbol_annotations contain requires parentId and childId");
+					const { contained } = await symbolAnnotationOperations.contain(path, params.parentId, params.childId);
+					details.contained = contained;
+					text = `"${params.parentId}" now contains "${params.childId}"`;
+				} else if (params.action === "uncontain") {
+					if (!params.parentId || !params.childId) throw new Error("symbol_annotations uncontain requires parentId and childId");
+					const { uncontained } = await symbolAnnotationOperations.uncontain(path, params.parentId, params.childId);
+					details.uncontained = uncontained;
+					text = uncontained ? `"${params.parentId}" no longer contains "${params.childId}"` : `"${params.parentId}" did not contain "${params.childId}"`;
+				} else if (params.action === "tree") {
+					if (!params.rootId || params.maxDepth === undefined) throw new Error("symbol_annotations tree requires rootId and maxDepth");
+					const { annotations } = await symbolAnnotationOperations.tree(path, params.rootId, params.maxDepth);
+					details.annotations = annotations;
+					text = annotations.length === 0 ? `no annotation "${params.rootId}"` : annotations.map(formatAnnotationDetail).join("\n\n");
 				} else {
 					throw new Error(`unknown symbol_annotations action: ${String(params.action)}`);
 				}
@@ -770,7 +927,14 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const action = typeof args.action === "string" ? args.action : "";
-				const id = typeof args.id === "string" ? ` ${args.id}` : "";
+				const id =
+					typeof args.id === "string"
+						? ` ${args.id}`
+						: typeof args.parentId === "string" && typeof args.childId === "string"
+							? ` ${args.parentId} -> ${args.childId}`
+							: typeof args.rootId === "string"
+								? ` ${args.rootId}`
+								: "";
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				text.setText(`${theme.fg("toolTitle", theme.bold("symbol_annotations"))} ${theme.fg("accent", action)}${theme.fg("dim", id)}`);
 				return text;
@@ -803,6 +967,14 @@ export default function (pi: ExtensionAPI) {
 					text.setText(details.restored ? theme.fg("success", "restored") : theme.fg("muted", "not scrubbed or not found"));
 					return text;
 				}
+				if (details?.contained !== undefined) {
+					text.setText(theme.fg("success", "contained"));
+					return text;
+				}
+				if (details?.uncontained !== undefined) {
+					text.setText(details.uncontained ? theme.fg("success", "uncontained") : theme.fg("muted", "was not contained"));
+					return text;
+				}
 				text.setText(theme.fg("muted", "done"));
 				return text;
 			},
@@ -812,10 +984,10 @@ export default function (pi: ExtensionAPI) {
 			name: "reachable_from",
 			label: "Reachable From",
 			description:
-				"Every symbol reachable from an exact file position by following the workspace's persisted call graph up to maxDepth hops -- transitive callers/reachability that would otherwise require chaining many find_references/outgoing_calls calls by hand. Requires populate_symbol_graph to have been run for this workspace first.",
+				"Every symbol reachable from an exact file position by following the workspace's persisted call graph up to maxDepth hops -- transitive callers/reachability that would otherwise require chaining many find_references/call_hierarchy calls by hand. Requires populate_symbol_graph to have been run for this workspace first.",
 			promptSnippet: "Find symbols reachable from a position, up to N hops, via the persisted graph",
 			promptGuidelines: [
-				"Use reachable_from for multi-hop questions (does A eventually call C through B); use outgoing_calls/incoming_calls for a single direct hop live against the language server.",
+				"Use reachable_from for multi-hop questions (does A eventually call C through B); use call_hierarchy (direction=incoming/outgoing) for a single direct hop live against the language server.",
 			],
 			parameters: Type.Object({
 				...positionParameters,
@@ -837,7 +1009,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatReachableFromCall(args as { path?: unknown; line?: unknown; character?: unknown; maxDepth?: unknown }, theme));
+				text.setText(formatReachableFromCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -888,7 +1060,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatWorkspaceMapCall(args as { path?: unknown; maxEntries?: unknown }, theme));
+				text.setText(formatWorkspaceMapCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -909,111 +1081,61 @@ export default function (pi: ExtensionAPI) {
 
 		const gitOperations = createLectorGitOperations();
 		pi.registerTool({
-			name: "git_status",
-			label: "Git Status",
+			name: "git",
+			label: "Git",
 			description:
-				"Working tree status for a real git repository -- modified/staged/untracked/renamed files, plus current branch and ahead/behind tracking. Fails clearly if `directory` is not inside a git repository.",
-			promptSnippet: "Show a repository's working tree status",
+				"Working tree status, recent commit log, and unified diff for a real git repository, in one tool. Fails clearly if `directory` is not inside a git repository. ACTIONS: status (working tree state, ahead/behind tracking), log (recent commits, bounded by maxCount), diff (unified diff against `ref`, defaulting to HEAD, bounded by maxBytes).",
+			promptSnippet: "Show a repository's status, log, or diff",
+			promptGuidelines: [
+				"maxCount is required for action=log; maxBytes is required for action=diff -- every bounded query needs its bound stated explicitly, never defaulted silently.",
+			],
 			parameters: Type.Object({
+				action: Type.String({ description: "status | log | diff" }),
 				directory: Type.String({ description: "Directory inside the repository to check, absolute or relative to the current working directory" }),
+				maxCount: Type.Optional(Type.Number({ description: "Maximum number of commits to return, most recent first -- required for action=log" })),
+				ref: Type.Optional(Type.String({ description: "Ref to diff against; defaults to HEAD -- only used for action=diff" })),
+				maxBytes: Type.Optional(Type.Number({ description: "Maximum diff size in bytes before truncating -- required for action=diff" })),
 			}),
 			async execute(_toolCallId, params) {
 				const directory = resolve(cwd, params.directory);
-				const summary = await gitOperations.status(directory);
-				return { content: [{ type: "text", text: JSON.stringify(summary) }], details: { summary } };
-			},
-			renderCall(args, theme, context) {
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitStatusCall(args as { directory?: unknown }, theme));
-				return text;
-			},
-			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Checking status..."), 0, 0);
-				if (context.isError) {
-					const errorText = result.content
-						.filter((block) => block.type === "text")
-						.map((block) => block.text)
-						.join("\n");
-					return new Text(theme.fg("error", errorText || "git_status failed"), 0, 0);
+				if (params.action === "status") {
+					const summary = await gitOperations.status(directory);
+					const details: GitToolDetails = { action: "status", summary };
+					return { content: [{ type: "text", text: JSON.stringify(summary) }], details };
 				}
-				const details = result.details as { summary?: GitStatusSummary } | undefined;
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitStatusResult(details?.summary, expanded, theme));
-				return text;
-			},
-		});
-
-		pi.registerTool({
-			name: "git_log",
-			label: "Git Log",
-			description:
-				"Recent commits for a real git repository, most recent first, bounded to maxCount. Fails clearly if `directory` is not inside a git repository.",
-			promptSnippet: "List a repository's recent commits",
-			parameters: Type.Object({
-				directory: Type.String({ description: "Directory inside the repository to check, absolute or relative to the current working directory" }),
-				maxCount: Type.Number({ description: "Maximum number of commits to return, most recent first" }),
-			}),
-			async execute(_toolCallId, params) {
-				const directory = resolve(cwd, params.directory);
-				const entries = await gitOperations.log(directory, params.maxCount);
-				const text =
-					entries.length === 0 ? "No commits found." : entries.map((e) => `${e.sha.slice(0, 8)} ${e.authoredAt} ${e.authorName} -- ${e.message}`).join("\n");
-				return { content: [{ type: "text", text }], details: { entries } };
-			},
-			renderCall(args, theme, context) {
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitLogCall(args as { directory?: unknown; maxCount?: unknown }, theme));
-				return text;
-			},
-			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Reading log..."), 0, 0);
-				if (context.isError) {
-					const errorText = result.content
-						.filter((block) => block.type === "text")
-						.map((block) => block.text)
-						.join("\n");
-					return new Text(theme.fg("error", errorText || "git_log failed"), 0, 0);
+				if (params.action === "log") {
+					if (params.maxCount === undefined) throw new Error("git action=log requires maxCount");
+					const entries = await gitOperations.log(directory, params.maxCount);
+					const text =
+						entries.length === 0 ? "No commits found." : entries.map((e) => `${e.sha.slice(0, 8)} ${e.authoredAt} ${e.authorName} -- ${e.message}`).join("\n");
+					const details: GitToolDetails = { action: "log", entries };
+					return { content: [{ type: "text", text }], details };
 				}
-				const details = result.details as { entries?: readonly GitLogEntry[] } | undefined;
-				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitLogResult(details?.entries, expanded, theme));
-				return text;
-			},
-		});
-
-		pi.registerTool({
-			name: "git_diff",
-			label: "Git Diff",
-			description:
-				"Unified diff of the working tree against `ref` (defaults to HEAD) for a real git repository, bounded to maxBytes. Fails clearly if `directory` is not inside a git repository.",
-			promptSnippet: "Show a repository's working tree diff",
-			parameters: Type.Object({
-				directory: Type.String({ description: "Directory inside the repository to check, absolute or relative to the current working directory" }),
-				ref: Type.Optional(Type.String({ description: "Ref to diff against; defaults to HEAD" })),
-				maxBytes: Type.Number({ description: "Maximum diff size in bytes before truncating" }),
-			}),
-			async execute(_toolCallId, params) {
-				const directory = resolve(cwd, params.directory);
-				const result = await gitOperations.diff(directory, params.ref, params.maxBytes);
-				return { content: [{ type: "text", text: result.diff.length === 0 ? "No differences." : result.diff }], details: { result } };
+				if (params.action === "diff") {
+					if (params.maxBytes === undefined) throw new Error("git action=diff requires maxBytes");
+					const result = await gitOperations.diff(directory, params.ref, params.maxBytes);
+					const details: GitToolDetails = { action: "diff", result };
+					return { content: [{ type: "text", text: result.diff.length === 0 ? "No differences." : result.diff }], details };
+				}
+				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitDiffCall(args as { directory?: unknown; ref?: unknown }, theme));
+				text.setText(formatGitCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
-				if (isPartial) return new Text(theme.fg("warning", "Computing diff..."), 0, 0);
+				if (isPartial) return new Text(theme.fg("warning", "Running git..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
 						.filter((block) => block.type === "text")
 						.map((block) => block.text)
 						.join("\n");
-					return new Text(theme.fg("error", errorText || "git_diff failed"), 0, 0);
+					return new Text(theme.fg("error", errorText || "git failed"), 0, 0);
 				}
-				const details = result.details as { result?: GitDiffResult } | undefined;
+				const details = result.details as GitToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatGitDiffResult(details?.result, expanded, theme));
+				text.setText(formatGitResult(details, expanded, theme));
 				return text;
 			},
 		});
@@ -1040,7 +1162,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatSearchCall(args as { directory?: unknown; query?: unknown }, theme));
+				text.setText(formatSearchCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -1086,7 +1208,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatFindFilesCall(args as { directory?: unknown; patterns?: unknown }, theme));
+				text.setText(formatFindFilesCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -1151,12 +1273,13 @@ export default function (pi: ExtensionAPI) {
 				// The Pi tool schema can only express plain strings for hash fields (TypeBox has no
 				// concept of Lector's branded LineHash) -- the daemon's own domain validation is the
 				// real runtime check regardless of what TypeScript sees at this call site.
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
 				const result = await lineEditOperations.lineEdit(absolutePath, params.edits as unknown as LineEdit[]);
 				return { content: [{ type: "text", text: `${result.path}: ${result.previousHash} -> ${result.newHash}` }], details: { result } };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatLineEditCall(args as { path?: unknown; edits?: unknown }, theme));
+				text.setText(formatLineEditCall(args, theme));
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -1197,12 +1320,13 @@ export default function (pi: ExtensionAPI) {
 				const absolutePath = resolve(cwd, params.path);
 				// TypeBox has no concept of Lector's branded ContentHash -- the daemon's own domain
 				// validation is the real runtime check regardless of what TypeScript sees here.
+				// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
 				const result = await applyPatchOperations.applyPatch(absolutePath, params.expectedHash as ContentHash, params.patchText);
 				return { content: [{ type: "text", text: `${result.path}: ${result.previousHash ?? "(new)"} -> ${result.newHash}` }], details: { result } };
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatApplyPatchCall(args as { path?: unknown }, theme));
+				text.setText(formatApplyPatchCall(args, theme));
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -1221,6 +1345,67 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		type MutationHistoryToolDetails =
+			| { readonly action: "list"; readonly entries: readonly MutationHistoryEntry[] }
+			| { readonly action: "revert"; readonly reverted: { readonly path: string; readonly newHash: string | null } };
+
+		const mutationHistoryOperations = createMutationHistoryOperations();
+		pi.registerTool({
+			name: "mutation_history",
+			label: "Mutation History",
+			description:
+				"List or revert a file's recorded edit history. Every successful edit/line_edit/apply_patch is recorded (newest first, bounded, not durable across a daemon restart). Reverting restores the file to its exact content immediately before that entry's own mutation, guarded the same way every Lector write is -- refuses if the file changed since, rather than silently clobbering a newer change. A revert is itself a real, further-revertible mutation -- reverting a revert works.",
+			promptSnippet: "List or revert a file's recorded edit history",
+			promptGuidelines: [
+				"list first to find the entry id you want, then revert -- an id from a different file's history, or one already evicted by the bounded history, fails closed rather than guessing.",
+			],
+			parameters: Type.Object({
+				action: Type.Union([Type.Literal("list"), Type.Literal("revert")]),
+				path: Type.String({ description: "Absolute or workspace-relative path to the file" }),
+				maxResults: Type.Optional(Type.Number({ description: "Required for action=list -- maximum entries to return, newest first" })),
+				entryId: Type.Optional(Type.String({ description: "Required for action=revert -- an id returned by a prior action=list" })),
+			}),
+			async execute(_toolCallId, params): Promise<AgentToolResult<MutationHistoryToolDetails>> {
+				const absolutePath = resolve(cwd, params.path);
+				if (params.action === "list") {
+					if (params.maxResults === undefined) throw new Error("mutation_history action=list requires maxResults");
+					const entries = await mutationHistoryOperations.list(absolutePath, params.maxResults);
+					const text =
+						entries.length === 0
+							? "no recorded mutation history for this path"
+							: entries.map((entry) => `${entry.id}  ${new Date(entry.timestamp).toISOString()}  ${entry.operation}`).join("\n");
+					return { content: [{ type: "text", text }], details: { action: "list", entries } };
+				}
+				if (params.entryId === undefined) throw new Error("mutation_history action=revert requires entryId");
+				const reverted = await mutationHistoryOperations.revert(absolutePath, params.entryId);
+				return {
+					content: [{ type: "text", text: `${reverted.path} reverted -> ${reverted.newHash ?? "(deleted)"}` }],
+					details: { action: "revert", reverted },
+				};
+			},
+			renderCall(args, theme, context) {
+				const action = typeof args.action === "string" ? args.action : "";
+				const path = typeof args.path === "string" ? args.path : "";
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("mutation_history"))} ${theme.fg("accent", action)} ${theme.fg("dim", path)}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Working on mutation history..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "mutation_history failed"), 0, 0);
+				}
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				const textBlock = result.content.find((block) => block.type === "text");
+				text.setText(theme.fg("success", textBlock && "text" in textBlock ? textBlock.text : "done"));
+				return text;
+			},
+		});
+
 		const packageSourceOperations = createLectorPackageSourceOperations();
 		pi.registerTool({
 			name: "package_source",
@@ -1241,7 +1426,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatPackageSourceCall(args as { directory?: unknown; name?: unknown; version?: unknown }, theme));
+				text.setText(formatPackageSourceCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -1261,6 +1446,7 @@ export default function (pi: ExtensionAPI) {
 		});
 
 		const repoFetchOperations = createLectorRepoFetchOperations();
+		const repoCacheListOperations = createRepoCacheListOperations();
 		pi.registerTool({
 			name: "repo_fetch",
 			label: "Repo Fetch",
@@ -1279,7 +1465,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatRepoFetchCall(args as { owner?: unknown; repo?: unknown; ref?: unknown; host?: unknown }, theme));
+				text.setText(formatRepoFetchCall(args, theme));
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -1298,6 +1484,53 @@ export default function (pi: ExtensionAPI) {
 			},
 		});
 
+		pi.registerTool({
+			name: "repo_cache_list",
+			label: "Repo Cache List",
+			description:
+				"Lists and queries repo_fetch's own on-disk cache -- no network call, no cache mutation. Filter by any combination of host/owner/repo/ref (exact match) and text (case-insensitive substring across host/owner/repo/refs). Each entry reports whether it's currently a registered workspace (usable directly by other tools) or just present on disk. Bounded and paginated via cursor.",
+			promptSnippet: "List or search previously-fetched external repositories",
+			parameters: Type.Object({
+				text: Type.Optional(Type.String({ description: "Case-insensitive substring match across host/owner/repo/refs" })),
+				host: Type.Optional(Type.String({ description: "Exact host match, e.g. github.com" })),
+				owner: Type.Optional(Type.String()),
+				repo: Type.Optional(Type.String()),
+				ref: Type.Optional(Type.String({ description: "Matches either the requested or the resolved ref" })),
+				maxResults: Type.Number({ description: "Maximum entries to return in this page" }),
+				cursor: Type.Optional(Type.String({ description: "Opaque cursor from a prior call's nextCursor, to fetch the next page" })),
+			}),
+			async execute(_toolCallId, params) {
+				const page = await repoCacheListOperations.list(
+					{ text: params.text, host: params.host, owner: params.owner, repo: params.repo, ref: params.ref },
+					params.maxResults,
+					params.cursor,
+				);
+				return { content: [{ type: "text", text: JSON.stringify(page) }], details: { page } };
+			},
+			renderCall(_args, theme, context) {
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				text.setText(`${theme.fg("toolTitle", theme.bold("repo_cache_list"))}`);
+				return text;
+			},
+			renderResult(result, { isPartial }, theme, context) {
+				if (isPartial) return new Text(theme.fg("warning", "Listing cached repositories..."), 0, 0);
+				if (context.isError) {
+					const errorText = result.content
+						.filter((block) => block.type === "text")
+						.map((block) => block.text)
+						.join("\n");
+					return new Text(theme.fg("error", errorText || "repo_cache_list failed"), 0, 0);
+				}
+				const details = result.details as
+					| { page?: { entries: readonly { host: string; owner: string; repo: string }[]; nextCursor: string | null } }
+					| undefined;
+				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
+				const count = details?.page?.entries.length ?? 0;
+				text.setText(count === 0 ? theme.fg("dim", "no cached repositories") : theme.fg("success", `${count} cached repositor${count === 1 ? "y" : "ies"}`));
+				return text;
+			},
+		});
+
 		const crossWorkspaceSearchOperations = createLectorCrossWorkspaceSearchOperations();
 		pi.registerTool({
 			name: "find_symbols_across_projects",
@@ -1317,7 +1550,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args as { directories?: unknown; query?: unknown }, theme));
+				text.setText(formatCrossWorkspaceCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -1356,7 +1589,7 @@ export default function (pi: ExtensionAPI) {
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args as { directories?: unknown; query?: unknown }, theme));
+				text.setText(formatCrossWorkspaceCall(args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {