@danypops/pi-lector 0.2.1 → 0.3.0

package/extension/src/code-intelligence-rendering.ts

@@ -4,6 +4,7 @@ import type {
 	DocumentSymbolEntry,
 	Hover,
 	IncomingCall,
+	IntelligenceProvenance,
 	JobSnapshot,
 	OutgoingCall,
 	PopulateSymbolGraphResult,
@@ -159,20 +160,29 @@ function formatCallHierarchyEntry(entry: { kind: string; name: string; location:
 	return `${kind} ${name} -- ${location}`;
 }
 
-export function formatPrepareCallHierarchyCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
-	return formatPositionalCall("prepare_call_hierarchy", args, theme);
+export type CallHierarchyDirection = "prepare" | "incoming" | "outgoing";
+
+// A real discriminated union, not one shape with optional fields -- lets formatCallHierarchyResult
+// narrow `items`/`calls` per branch without an unsafe assertion.
+export type CallHierarchyToolDetails =
+	| { readonly direction: "prepare"; readonly items: readonly CallHierarchyEntry[]; readonly provenance?: IntelligenceProvenance }
+	| { readonly direction: "incoming"; readonly calls: readonly IncomingCall[]; readonly provenance?: IntelligenceProvenance }
+	| { readonly direction: "outgoing"; readonly calls: readonly OutgoingCall[]; readonly provenance?: IntelligenceProvenance };
+
+export function formatCallHierarchyCall(args: { direction?: unknown; path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
+	const direction = typeof args.direction === "string" ? args.direction : "";
+	const path = typeof args.path === "string" ? args.path : "";
+	const line = typeof args.line === "number" ? args.line : "?";
+	const character = typeof args.character === "number" ? args.character : "?";
+	return `${theme.fg("toolTitle", theme.bold("call_hierarchy"))} ${theme.fg("muted", direction)} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
-export function formatPrepareCallHierarchyResult(items: readonly CallHierarchyEntry[] | undefined, theme: LectorTheme): string {
+function formatPrepareCallHierarchyResult(items: readonly CallHierarchyEntry[] | undefined, theme: LectorTheme): string {
 	if (!items || items.length === 0) return theme.fg("dim", "No call-hierarchy root at this position.");
 	return items.map((item) => formatCallHierarchyEntry(item, theme)).join("\n");
 }
 
-export function formatIncomingCallsCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
-	return formatPositionalCall("incoming_calls", args, theme);
-}
-
-export function formatIncomingCallsResult(calls: readonly IncomingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
+function formatIncomingCallsResult(calls: readonly IncomingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!calls || calls.length === 0) return theme.fg("dim", "No incoming calls found.");
 
 	const displayCount = expanded ? calls.length : Math.min(calls.length, DEFAULT_VISIBLE_CALLS);
@@ -184,11 +194,7 @@ export function formatIncomingCallsResult(calls: readonly IncomingCall[] | undef
 	return lines.join("\n");
 }
 
-export function formatOutgoingCallsCall(args: { path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
-	return formatPositionalCall("outgoing_calls", args, theme);
-}
-
-export function formatOutgoingCallsResult(calls: readonly OutgoingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
+function formatOutgoingCallsResult(calls: readonly OutgoingCall[] | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!calls || calls.length === 0) return theme.fg("dim", "No outgoing calls found.");
 
 	const displayCount = expanded ? calls.length : Math.min(calls.length, DEFAULT_VISIBLE_CALLS);
@@ -200,6 +206,13 @@ export function formatOutgoingCallsResult(calls: readonly OutgoingCall[] | undef
 	return lines.join("\n");
 }
 
+export function formatCallHierarchyResult(details: CallHierarchyToolDetails | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	if (details.direction === "prepare") return formatPrepareCallHierarchyResult(details.items, theme);
+	if (details.direction === "incoming") return formatIncomingCallsResult(details.calls, expanded, theme);
+	return formatOutgoingCallsResult(details.calls, expanded, theme);
+}
+
 export function formatPopulateSymbolGraphCall(args: { path?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
 	return `${theme.fg("toolTitle", theme.bold("populate_symbol_graph"))} ${theme.fg("accent", path)}`;

package/extension/src/git-rendering.ts

@@ -6,12 +6,30 @@ const DEFAULT_VISIBLE_FILES = 20;
 const DEFAULT_VISIBLE_COMMITS = 10;
 const DEFAULT_VISIBLE_DIFF_LINES = 60;
 
-export function formatGitStatusCall(args: { directory?: unknown }, theme: LectorTheme): string {
+export type GitAction = "status" | "log" | "diff";
+
+export interface GitToolDetails {
+	readonly action: GitAction;
+	readonly summary?: GitStatusSummary;
+	readonly entries?: readonly GitLogEntry[];
+	readonly result?: GitDiffResult;
+}
+
+export function formatGitCall(args: { action?: unknown; directory?: unknown; ref?: unknown }, theme: LectorTheme): string {
+	const action = typeof args.action === "string" ? args.action : "";
 	const directory = typeof args.directory === "string" ? args.directory : "";
-	return `${theme.fg("toolTitle", theme.bold("git_status"))} ${theme.fg("accent", directory)}`;
+	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
+	return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)}${ref}`;
 }
 
-export function formatGitStatusResult(summary: GitStatusSummary | undefined, expanded: boolean, theme: LectorTheme): string {
+export function formatGitResult(details: GitToolDetails | undefined, expanded: boolean, theme: LectorTheme): string {
+	if (!details) return theme.fg("dim", "No result.");
+	if (details.action === "status") return formatGitStatusResult(details.summary, expanded, theme);
+	if (details.action === "log") return formatGitLogResult(details.entries, expanded, theme);
+	return formatGitDiffResult(details.result, expanded, theme);
+}
+
+function formatGitStatusResult(summary: GitStatusSummary | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!summary) return theme.fg("dim", "No status available.");
 	const branch = summary.current ?? "(detached)";
 	const tracking = summary.tracking ? `, tracking ${summary.tracking} (+${summary.ahead}/-${summary.behind})` : "";
@@ -30,12 +48,7 @@ export function formatGitStatusResult(summary: GitStatusSummary | undefined, exp
 	return lines.join("\n");
 }
 
-export function formatGitLogCall(args: { directory?: unknown; maxCount?: unknown }, theme: LectorTheme): string {
-	const directory = typeof args.directory === "string" ? args.directory : "";
-	return `${theme.fg("toolTitle", theme.bold("git_log"))} ${theme.fg("accent", directory)}`;
-}
-
-export function formatGitLogResult(entries: readonly GitLogEntry[] | undefined, expanded: boolean, theme: LectorTheme): string {
+function formatGitLogResult(entries: readonly GitLogEntry[] | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!entries || entries.length === 0) return theme.fg("dim", "No commits found.");
 	const displayCount = expanded ? entries.length : Math.min(DEFAULT_VISIBLE_COMMITS, entries.length);
 	const lines = entries
@@ -46,13 +59,7 @@ export function formatGitLogResult(entries: readonly GitLogEntry[] | undefined,
 	return lines.join("\n");
 }
 
-export function formatGitDiffCall(args: { directory?: unknown; ref?: unknown }, theme: LectorTheme): string {
-	const directory = typeof args.directory === "string" ? args.directory : "";
-	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
-	return `${theme.fg("toolTitle", theme.bold("git_diff"))} ${theme.fg("accent", directory)}${ref}`;
-}
-
-export function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolean, theme: LectorTheme): string {
+function formatGitDiffResult(result: GitDiffResult | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!result || result.diff.length === 0) return theme.fg("dim", "No differences.");
 	const lines = result.diff.split("\n");
 	const displayCount = expanded ? lines.length : Math.min(DEFAULT_VISIBLE_DIFF_LINES, lines.length);

package/extension/src/index.ts

@@ -1,21 +1,15 @@
 import { resolve } from "node:path";
 import type {
-	CallHierarchyEntry,
 	ContentHash,
 	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
 	FindFilesResult,
-	GitDiffResult,
-	GitLogEntry,
-	GitStatusSummary,
 	Hover,
-	IncomingCall,
 	IntelligenceProvenance,
 	JobSnapshot,
 	LineEdit,
 	LineEditOutcome,
-	OutgoingCall,
 	PackageSourceOperationResult,
 	PopulateSymbolGraphResult,
 	RepoFetchResult,
@@ -27,14 +21,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 +50,8 @@ import {
 	formatGoToImplementationResult,
 	formatHoverCall,
 	formatHoverResult,
-	formatIncomingCallsCall,
-	formatIncomingCallsResult,
-	formatOutgoingCallsCall,
-	formatOutgoingCallsResult,
 	formatPopulateSymbolGraphCall,
 	formatPopulateSymbolGraphResult,
-	formatPrepareCallHierarchyCall,
-	formatPrepareCallHierarchyResult,
 	formatReachableFromCall,
 	formatReachableFromResult,
 	formatWorkspaceMapCall,
@@ -68,7 +65,7 @@ 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 { createLectorLineEditOperations } from "./line-edit-operations.ts";
 import { formatLineEditCall, formatLineEditResult } from "./line-edit-rendering.ts";
 import { nearestGitRoot } from "./nearest-workspace-root.ts";
@@ -221,7 +218,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 +233,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;
@@ -265,7 +262,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 +300,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 +345,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 +385,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 +419,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 +456,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 +476,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 +545,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 +568,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) {
@@ -685,20 +631,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 +666,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 +693,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 +725,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 +747,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 +787,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 +804,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 +829,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 +880,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 +901,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 +982,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 +1028,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 +1093,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 +1140,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) {
@@ -1241,7 +1185,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) {
@@ -1279,7 +1223,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) {
@@ -1317,7 +1261,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 +1300,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) {

package/extension/src/lector-client.ts

@@ -1,8 +1,9 @@
 import { existsSync, statSync } from "node:fs";
-import { dirname, parse } from "node:path";
+import { dirname, extname, parse } from "node:path";
 import { createRetryingClient, type RetryingClient } from "@danypops/daemon-kit/pi-client";
 import {
 	connectLectorClient,
+	descriptorForExtension,
 	type LectorClient,
 	type OperationInputs,
 	type OperationName,
@@ -10,7 +11,7 @@ import {
 	remoteErrorIs,
 	type WorkspaceId,
 } from "@danypops/lector";
-import { nearestGitRoot } from "./nearest-workspace-root.ts";
+import { nearestGitRoot, nearestProjectRoot } from "./nearest-workspace-root.ts";
 
 /**
  * Lazily connects to a running Lector daemon and caches, per project root,
@@ -43,9 +44,8 @@ export interface RetryingLectorClient {
 }
 
 // Kept async even though its own body has no await: every call site across this package does
-// `await lectorClient()`, and dropping async here (just to satisfy require-await) would turn an
-// internal implementation detail into a signature change rippling through every one of them.
-// eslint-disable-next-line @typescript-eslint/require-await
+// `await lectorClient()`, and dropping async here would turn an internal implementation detail
+// into a signature change rippling through every one of them.
 export async function lectorClient(): Promise<RetryingLectorClient> {
 	return {
 		call: (operation, input) => retryingClient.call((client) => client.call(operation, input)),
@@ -107,9 +107,17 @@ export function workspaceForDirectory(directory: string): Promise<ResolvedWorksp
  * whose filesystem-root fallback would point a real server at scanning the
  * whole disk. Falls back to the file's own containing directory instead,
  * same bound as workspaceForDirectory.
+ *
+ * Unlike workspaceForDirectory, prefers the file's own language's root markers
+ * (tsconfig.json, go.mod, Cargo.toml, ...) over the nearest .git when both exist --
+ * a monorepo subproject's own root marker is nearer and wins, so its language server
+ * gets that subproject's rootUri instead of the whole repo's.
  */
 export function workspaceForCodeIntelligencePath(absolutePath: string): Promise<ResolvedWorkspace> {
-	return workspaceForDirectory(dirname(absolutePath));
+	const directory = dirname(absolutePath);
+	const descriptor = descriptorForExtension(extname(absolutePath));
+	const root = descriptor ? (nearestProjectRoot(directory, descriptor.rootMarkers) ?? directory) : (nearestGitRoot(directory) ?? directory);
+	return workspaceForRoot(root);
 }
 
 /**

package/extension/src/nearest-workspace-root.ts

@@ -21,14 +21,30 @@ import { dirname, join, parse } from "node:path";
  * workspace root" error -- discovered live, in a separate session, working
  * against a completely different, unrelated repository.)
  */
-export function nearestGitRoot(startDirectory: string): string | undefined {
+function walkUpForMarkers(startDirectory: string, markers: readonly string[]): string | undefined {
 	let dir = startDirectory;
 	const fsRoot = parse(dir).root;
 	while (dir !== fsRoot) {
-		if (existsSync(join(dir, ".git"))) return dir;
+		if (markers.some((marker) => existsSync(join(dir, marker)))) return dir;
 		const parent = dirname(dir);
 		if (parent === dir) break; // defensive: dirname must be strictly ascending
 		dir = parent;
 	}
-	return existsSync(join(fsRoot, ".git")) ? fsRoot : undefined;
+	return markers.some((marker) => existsSync(join(fsRoot, marker))) ? fsRoot : undefined;
+}
+
+export function nearestGitRoot(startDirectory: string): string | undefined {
+	return walkUpForMarkers(startDirectory, [".git"]);
+}
+
+/**
+ * Same nearest-enclosing-root walk as nearestGitRoot, but also checks a language's own root
+ * markers (tsconfig.json, go.mod, Cargo.toml, ...) at each directory, nearest first -- so a
+ * monorepo subproject with its own root marker resolves to itself, not the outer repo's .git.
+ * Found via @arvoretech/pi-lsp comparison: without this, a file inside a monorepo subproject
+ * misattributes its whole project to the repo root, handing the language server the wrong
+ * rootUri (and, for TypeScript, the wrong tsconfig.json) even though a closer one exists.
+ */
+export function nearestProjectRoot(startDirectory: string, rootMarkers: readonly string[]): string | undefined {
+	return walkUpForMarkers(startDirectory, [...rootMarkers, ".git"]);
 }

package/extension/src/symbol-annotation-operations.ts

@@ -25,7 +25,7 @@ export interface SymbolAnnotationOperations {
 	get(path: string, id: string): Promise<OperationOutputs["workspace.getAnnotation"]>;
 	list(
 		path: string,
-		options?: { subtype?: string; status?: OperationInputs["workspace.listAnnotations"]["status"]; maxResults?: number },
+		options?: { subtype?: string; status?: OperationInputs["workspace.listAnnotations"]["status"]; maxResults?: number; query?: string },
 	): Promise<OperationOutputs["workspace.listAnnotations"]>;
 	refresh(
 		path: string,
@@ -37,6 +37,9 @@ export interface SymbolAnnotationOperations {
 	): Promise<OperationOutputs["workspace.refreshAnnotation"]>;
 	scrub(path: string, id: string): Promise<OperationOutputs["workspace.scrubAnnotation"]>;
 	restore(path: string, id: string): Promise<OperationOutputs["workspace.restoreAnnotation"]>;
+	contain(path: string, parentId: string, childId: string): Promise<OperationOutputs["workspace.containAnnotation"]>;
+	uncontain(path: string, parentId: string, childId: string): Promise<OperationOutputs["workspace.uncontainAnnotation"]>;
+	tree(path: string, rootId: string, maxDepth: number): Promise<OperationOutputs["workspace.annotationTree"]>;
 }
 
 export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperations {
@@ -64,7 +67,13 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 				() => workspaceForCodeIntelligencePath(path),
 				async ({ workspaceId }) => {
 					const client = await lectorClient();
-					return client.call("workspace.listAnnotations", { workspaceId, subtype: options.subtype, status: options.status, maxResults: options.maxResults });
+					return client.call("workspace.listAnnotations", {
+						workspaceId,
+						subtype: options.subtype,
+						status: options.status,
+						maxResults: options.maxResults,
+						query: options.query,
+					});
 				},
 			);
 		},
@@ -95,5 +104,32 @@ export function createLectorSymbolAnnotationOperations(): SymbolAnnotationOperat
 				},
 			);
 		},
+		async contain(path, parentId, childId) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.containAnnotation", { workspaceId, parentId, childId });
+				},
+			);
+		},
+		async uncontain(path, parentId, childId) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.uncontainAnnotation", { workspaceId, parentId, childId });
+				},
+			);
+		},
+		async tree(path, rootId, maxDepth) {
+			return withWorkspace(
+				() => workspaceForCodeIntelligencePath(path),
+				async ({ workspaceId }) => {
+					const client = await lectorClient();
+					return client.call("workspace.annotationTree", { workspaceId, rootId, maxDepth });
+				},
+			);
+		},
 	};
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.2.1",
+	"version": "0.3.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",
@@ -18,8 +18,8 @@
 		"typebox": "*"
 	},
 	"dependencies": {
-		"@danypops/daemon-kit": "^0.4.0",
-		"@danypops/lector": "^0.1.15"
+		"@danypops/daemon-kit": "^0.22.1",
+		"@danypops/lector": "^0.3.0"
 	},
 	"devDependencies": {
 		"@earendil-works/pi-ai": "^0.81.1",