@danypops/pi-lector 0.13.11 → 0.14.0

package/extension/src/apply-patch/rendering.ts

@@ -1,6 +1,7 @@
 import type { EditOutcome } from "@danypops/lector";
 import { renderDiffLines, renderTruncatedList, type TextMeasure } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * The applied result (EditOutcome) only carries a hash transition, not the
@@ -15,7 +16,7 @@ const DEFAULT_VISIBLE_PATCH_LINES = 12;
 
 export function formatApplyPatchCall(args: { path?: unknown; patchText?: unknown }, theme: LectorTheme, measure?: TextMeasure): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	const header = `${theme.fg("toolTitle", theme.bold("apply_patch"))} ${theme.fg("accent", path)}`;
+	const header = `${theme.fg("toolTitle", theme.bold(presentationTitle("apply_patch")))} ${theme.fg("accent", path)}`;
 	if (typeof args.patchText !== "string" || args.patchText.length === 0) return header;
 
 	const styledLines = renderDiffLines(

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

@@ -14,6 +14,7 @@ import type {
 import { keyHint, type ThemeColor } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { colorForKind, formatLocation, type LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * Custom TUI rendering for the code-intelligence tools: go_to_definition,
@@ -41,7 +42,7 @@ function formatPositionalCall(toolName: string, args: { path?: unknown; line?: u
 	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(toolName))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
 function moreLine(theme: LectorTheme): (hidden: number) => string {
@@ -110,7 +111,7 @@ export function formatHoverResult(hover: Hover | undefined, expanded: boolean, t
 
 export function formatDocumentSymbolsCall(args: { path?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	return `${theme.fg("toolTitle", theme.bold("document_symbols"))} ${theme.fg("accent", path)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("document_symbols")))} ${theme.fg("accent", path)}`;
 }
 
 /** Flattens a hierarchical DocumentSymbolEntry[] into (depth, entry) pairs, depth-first, for bounded rendering. */
@@ -149,7 +150,7 @@ export function formatDocumentSymbolsResult(symbols: readonly DocumentSymbolEntr
 
 export function formatDiagnosticsCall(args: { path?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	return `${theme.fg("toolTitle", theme.bold("diagnostics"))} ${theme.fg("accent", path)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("diagnostics")))} ${theme.fg("accent", path)}`;
 }
 
 export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | undefined, expanded: boolean, theme: LectorTheme): string {
@@ -175,7 +176,7 @@ export function formatDiagnosticsResult(diagnostics: readonly Diagnostic[] | und
 
 function formatPathCall(toolName: string, args: { path?: unknown }, theme: LectorTheme, qualifier = ""): string {
 	const path = typeof args.path === "string" ? args.path : "";
-	return `${theme.fg("toolTitle", theme.bold(toolName))}${qualifier ? ` ${theme.fg("muted", qualifier)}` : ""} ${theme.fg("accent", path)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))}${qualifier ? ` ${theme.fg("muted", qualifier)}` : ""} ${theme.fg("accent", path)}`;
 }
 
 export function formatCodeActionPreviewCall(
@@ -249,7 +250,11 @@ export function formatDiagnosticDeltaResult(result: OperationOutputs["workspace.
 }
 
 export function formatTypeHierarchyCall(args: { direction?: unknown; path?: unknown; line?: unknown; character?: unknown }, theme: LectorTheme): string {
-	return `${formatPositionalCall("type_hierarchy", args, theme)} ${theme.fg("muted", typeof args.direction === "string" ? args.direction : "")}`;
+	const direction = typeof args.direction === "string" ? args.direction : undefined;
+	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(presentationTitle("type_hierarchy", direction)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
 export function formatTypeHierarchyResult(
@@ -311,7 +316,7 @@ export function formatCallHierarchyCall(args: { direction?: unknown; path?: unkn
 	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}`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("call_hierarchy", direction)))} ${theme.fg("accent", `${path}:${line}:${character}`)}`;
 }
 
 function formatPrepareCallHierarchyResult(items: readonly CallHierarchyEntry[] | undefined, theme: LectorTheme): string {
@@ -384,7 +389,7 @@ export function formatReachableFromResult(symbols: readonly SymbolNode[] | undef
 export function formatWorkspaceMapCall(args: { path?: unknown; maxEntries?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
 	const maxEntries = typeof args.maxEntries === "number" ? ` (top ${args.maxEntries})` : "";
-	return `${theme.fg("toolTitle", theme.bold("workspace_map"))} ${theme.fg("dim", path)}${theme.fg("muted", maxEntries)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("workspace_map")))} ${theme.fg("dim", path)}${theme.fg("muted", maxEntries)}`;
 }
 
 export function formatWorkspaceMapResult(result: WorkspaceMapResult | undefined, expanded: boolean, theme: LectorTheme): string {

package/extension/src/cross-workspace-search/rendering.ts

@@ -3,14 +3,19 @@ import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { describeFindSymbolSources } from "../find-symbols/rendering.ts";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 import type { CrossWorkspaceOutcome } from "./operations.ts";
 
 const DEFAULT_VISIBLE_PER_WORKSPACE = 10;
 
-export function formatCrossWorkspaceCall(args: { directories?: unknown; query?: unknown }, theme: LectorTheme): string {
+export function formatCrossWorkspaceCall(
+	toolName: "find_symbols_across_projects" | "search_code_across_projects",
+	args: { directories?: unknown; query?: unknown },
+	theme: LectorTheme,
+): string {
 	const directories = Array.isArray(args.directories) ? args.directories.filter((d): d is string => typeof d === "string") : [];
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", `across ${directories.length} project(s)`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle(toolName)))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", `across ${directories.length} project(s)`)}`;
 }
 
 function formatOutcomeHeader(entry: CrossWorkspaceOutcome<unknown>, theme: LectorTheme): string {

package/extension/src/external-search/rendering.ts

@@ -1,27 +1,61 @@
 import type { GithubRepoSearchResult, NpmPackageCandidate, SourcegraphCodeCandidate } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 type ExternalSearchAction = "github_repos" | "npm_packages" | "sourcegraph_code";
 
 export function formatExternalSearchCall(action: ExternalSearchAction, args: { query?: unknown }, theme: LectorTheme): string {
-	const label = theme.fg("toolTitle", theme.bold("external_search"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("external_search", action)));
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", query)}`;
+	return `${label} ${theme.fg("accent", `"${query}"`)}`;
 }
 
-export function formatGithubRepoSearchResult(result: GithubRepoSearchResult | undefined, theme: LectorTheme): string {
+const VISIBLE_CANDIDATES = 8;
+
+function boundedCandidates<T>(candidates: readonly T[], expanded: boolean): { visible: readonly T[]; more: number } {
+	const visible = expanded ? candidates : candidates.slice(0, VISIBLE_CANDIDATES);
+	return { visible, more: candidates.length - visible.length };
+}
+
+export function formatGithubRepoSearchResult(result: GithubRepoSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {
 	if (!result) return theme.fg("dim", "No result.");
-	const count = result.candidates.length;
-	const summary = count === 0 ? theme.fg("dim", "no repositories matched") : theme.fg("success", `${count} repositor${count === 1 ? "y" : "ies"}`);
-	return result.authenticated ? summary : `${summary} ${theme.fg("warning", "(unauthenticated -- lower rate limit)")}`;
+	if (result.candidates.length === 0) return theme.fg("dim", "no repositories matched");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map(
+		(candidate) =>
+			`${theme.fg("accent", `${candidate.host}/${candidate.owner}/${candidate.repo}`)} · ${candidate.stars} stars${candidate.language ? ` · ${candidate.language}` : ""}${candidate.description ? `\n  ${candidate.description}` : ""}`,
+	);
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	if (!result.authenticated) lines.push(theme.fg("warning", "unauthenticated -- lower rate limit"));
+	return lines.join("\n");
 }
 
-export function formatNpmPackageSearchResult(result: { candidates: readonly NpmPackageCandidate[] } | undefined, theme: LectorTheme): string {
-	const count = result?.candidates.length ?? 0;
-	return count === 0 ? theme.fg("dim", "no packages matched") : theme.fg("success", `${count} package${count === 1 ? "" : "s"}`);
+export function formatNpmPackageSearchResult(
+	result: { candidates: readonly NpmPackageCandidate[] } | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.candidates.length === 0) return theme.fg("dim", "no packages matched");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map(
+		(candidate) =>
+			`${theme.fg("accent", `${candidate.name}@${candidate.version}`)} · score ${candidate.score.toFixed(3)}${candidate.description ? `\n  ${candidate.description}` : ""}`,
+	);
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	return lines.join("\n");
 }
 
-export function formatSourcegraphCodeSearchResult(result: { candidates: readonly SourcegraphCodeCandidate[] } | undefined, theme: LectorTheme): string {
-	const count = result?.candidates.length ?? 0;
-	return count === 0 ? theme.fg("dim", "no code matches") : theme.fg("success", `${count} match${count === 1 ? "" : "es"}`);
+export function formatSourcegraphCodeSearchResult(
+	result: { candidates: readonly SourcegraphCodeCandidate[] } | undefined,
+	expanded: boolean,
+	theme: LectorTheme,
+): string {
+	if (!result || result.candidates.length === 0) return theme.fg("dim", "no code matches");
+	const { visible, more } = boundedCandidates(result.candidates, expanded);
+	const lines = visible.map((candidate) => {
+		const matches = candidate.lineMatches.slice(0, expanded ? candidate.lineMatches.length : 3);
+		return `${theme.fg("accent", `${candidate.repository}/${candidate.path}`)}\n${matches.map((match) => `  ${match.line}: ${match.preview}`).join("\n")}`;
+	});
+	if (more > 0) lines.push(theme.fg("muted", `… ${more} more (expand to show)`));
+	return lines.join("\n");
 }

package/extension/src/find-files/rendering.ts

@@ -2,13 +2,14 @@ import type { FindFilesResult } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 const DEFAULT_VISIBLE_PATHS = 40;
 
 export function formatFindFilesCall(args: { directory?: unknown; patterns?: unknown }, theme: LectorTheme): string {
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const patterns = Array.isArray(args.patterns) ? args.patterns.filter((p): p is string => typeof p === "string") : [];
-	return `${theme.fg("toolTitle", theme.bold("find_files"))} ${theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "))} ${theme.fg("dim", directory)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("find_files")))} ${theme.fg("accent", patterns.map((p) => `"${p}"`).join(", "))} ${theme.fg("dim", directory)}`;
 }
 
 export function formatFindFilesResult(result: FindFilesResult | undefined, expanded: boolean, theme: LectorTheme): string {

package/extension/src/find-symbols/rendering.ts

@@ -2,6 +2,7 @@ import type { SymbolSearchResult, WorkspaceSymbol } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import { colorForKind, formatLocation, type LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /**
  * Custom TUI rendering for find_symbols -- the one Lector-backed tool with
@@ -18,7 +19,7 @@ const DEFAULT_VISIBLE_RESULTS = 8;
 
 export function formatFindSymbolsCall(args: { query?: unknown; directory?: unknown }, theme: FindSymbolsTheme): string {
 	const query = typeof args.query === "string" ? args.query : "";
-	let content = `${theme.fg("toolTitle", theme.bold("find_symbols"))} ${theme.fg("accent", `"${query}"`)}`;
+	let content = `${theme.fg("toolTitle", theme.bold(presentationTitle("find_symbols")))} ${theme.fg("accent", `"${query}"`)}`;
 	if (typeof args.directory === "string" && args.directory.length > 0) {
 		content += ` ${theme.fg("muted", `in ${args.directory}`)}`;
 	}

package/extension/src/git/rendering.ts

@@ -3,6 +3,7 @@ import { keyHint } from "@earendil-works/pi-coding-agent";
 import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { renderDiffLines, renderTruncatedList, type TextMeasure } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /** Real ANSI-aware measurement, not Malevich's own ASCII-only default -- every diff line renderDiffLines receives is already theme.fg-styled. */
 const measure: TextMeasure = { visibleWidth, truncateToWidth };
@@ -61,31 +62,32 @@ export function formatGitCall(
 	theme: LectorTheme,
 ): string {
 	const action = typeof args.action === "string" ? args.action : "";
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("git", action)));
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	if (action === "compare-symbol") {
 		const path = typeof args.path === "string" ? args.path : "";
 		const symbol = typeof args.symbol === "string" ? args.symbol : "";
 		const fromRef = typeof args.fromRef === "string" ? args.fromRef : "";
 		const toRef = typeof args.toRef === "string" ? ` -> ${args.toRef}` : "";
-		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} (${symbol}) ${fromRef}${toRef}`;
+		return `${label} ${theme.fg("accent", `${directory}/${path}`)} (${symbol}) ${fromRef}${toRef}`;
 	}
 	if (action === "is-ancestor") {
 		const ancestorRef = typeof args.ancestorRef === "string" ? args.ancestorRef : "";
 		const ref = typeof args.ref === "string" ? args.ref : "";
-		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ancestorRef} -> ${ref}`;
+		return `${label} ${theme.fg("accent", directory)} ${ancestorRef} -> ${ref}`;
 	}
 	if (action === "grep-ref" || action === "grep-history") {
 		const ref = action === "grep-ref" && typeof args.ref === "string" ? `${args.ref} ` : "";
 		const pattern = typeof args.pattern === "string" ? args.pattern : "";
-		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)} ${ref}"${pattern}"`;
+		return `${label} ${theme.fg("accent", directory)} ${ref}"${pattern}"`;
 	}
 	if (action === "show") {
 		const ref = typeof args.ref === "string" ? args.ref : "";
 		const path = typeof args.path === "string" ? args.path : "";
-		return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", `${directory}/${path}`)} @ ${ref}`;
+		return `${label} ${theme.fg("accent", `${directory}/${path}`)} @ ${ref}`;
 	}
 	const ref = typeof args.ref === "string" ? ` ${args.ref}` : "";
-	return `${theme.fg("toolTitle", theme.bold("git"))} ${theme.fg("muted", action)} ${theme.fg("accent", directory)}${ref}`;
+	return `${label} ${theme.fg("accent", directory)}${ref}`;
 }
 
 function formatGitWorktreeAddResult(result: GitWorktreeAddResult | undefined, theme: LectorTheme): string {

package/extension/src/index.ts

@@ -4,7 +4,6 @@ import { resolve } from "node:path";
 import type {
 	CachedRepositoryPage,
 	ContentHash,
-	ContextBundleResult,
 	Diagnostic,
 	DocumentSymbolEntry,
 	EditOutcome,
@@ -121,6 +120,9 @@ import {
 	PACKAGE_SOURCE_LIST_VISIBLE_ROWS,
 	packageSourceListMoreLine,
 } from "./package-source/rendering.ts";
+import { formatSemanticModelContent } from "./presentation/model-content.ts";
+import { withLectorPresentation } from "./presentation/presentation-contract.ts";
+import { presentationTitle } from "./presentation/tool-presentation.ts";
 import { createLectorReadOperations } from "./read/operations.ts";
 import { createReferenceBasedRenameOperations } from "./reference-based-rename/operations.ts";
 import { createRenameOperations } from "./rename/operations.ts";
@@ -189,7 +191,7 @@ export default function (pi: ExtensionAPI) {
 	const customToolNames = new Set<string>();
 	function registerLectorTool<TParams extends TSchema, TDetails = unknown, TState = unknown>(tool: ToolDefinition<TParams, TDetails, TState>): void {
 		customToolNames.add(tool.name);
-		pi.registerTool(tool);
+		pi.registerTool(withLectorPresentation(tool));
 	}
 	pi.on("tool_result", (event) => {
 		if (!customToolNames.has(event.toolName)) return;
@@ -471,7 +473,11 @@ export default function (pi: ExtensionAPI) {
 				return { content: [{ type: "text", text }], details: result };
 			},
 			renderCall(args, theme) {
-				return new Text(theme.fg("toolTitle", `localize ${typeof args.query === "string" ? args.query : "context"}`), 0, 0);
+				return new Text(
+					`${theme.fg("toolTitle", theme.bold(presentationTitle("localize_context")))} ${theme.fg("accent", typeof args.query === "string" ? `"${args.query}"` : "")}`,
+					0,
+					0,
+				);
 			},
 			renderResult(result, { isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Localizing..."), 0, 0);
@@ -482,8 +488,11 @@ export default function (pi: ExtensionAPI) {
 						.join("\n");
 					return new Text(theme.fg("error", errorText || "localize_context failed"), 0, 0);
 				}
-				const details = result.details as ContextBundleResult | undefined;
-				return new Text(details ? `${details.candidates.length} candidates · graph ${details.completeness.graph}` : "Localization complete", 0, 0);
+				const contentText = result.content
+					.filter((block) => block.type === "text")
+					.map((block) => block.text)
+					.join("\n");
+				return new Text(contentText || "Localization complete", 0, 0);
 			},
 		});
 
@@ -1195,7 +1204,7 @@ export default function (pi: ExtensionAPI) {
 				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)}`,
+					`${theme.fg("toolTitle", theme.bold(presentationTitle("reference_based_rename")))} ${theme.fg("accent", fromPath)} ${theme.fg("dim", "->")} ${theme.fg("accent", toPath)}`,
 				);
 				return text;
 			},
@@ -1260,7 +1269,7 @@ export default function (pi: ExtensionAPI) {
 				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)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("rename", action)))} ${theme.fg("accent", path)}`);
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -1441,10 +1450,10 @@ export default function (pi: ExtensionAPI) {
 								? ` ${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)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("symbol_annotations", action)))}${theme.fg("accent", id)}`);
 				return text;
 			},
-			renderResult(result, { isPartial }, theme, context) {
+			renderResult(result, { expanded, isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Working on annotation..."), 0, 0);
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
 				if (context.isError) {
@@ -1457,11 +1466,11 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as SymbolAnnotationToolDetails | undefined;
 				if (details?.annotations) {
-					text.setText(formatAnnotationListSummary(details.annotations, theme));
+					text.setText(expanded ? details.annotations.map(formatAnnotationDetail).join("\n\n") : formatAnnotationListSummary(details.annotations, theme));
 					return text;
 				}
 				if (details?.annotation) {
-					text.setText(formatAnnotationSummary(details.annotation, theme));
+					text.setText(expanded ? formatAnnotationDetail(details.annotation) : formatAnnotationSummary(details.annotation, theme));
 					return text;
 				}
 				if (details?.scrubbed !== undefined) {
@@ -1633,7 +1642,10 @@ export default function (pi: ExtensionAPI) {
 				if (params.action === "job_status") {
 					if (!params.jobId) throw new Error("workspace_cache action=job_status requires jobId");
 					const job = await cacheOperations.jobStatus(params.jobId);
-					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "job_status", job } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "job_status"), job) }],
+						details: { action: "job_status", job },
+					};
 				}
 				if (params.action === "wait") {
 					if (!params.jobId) throw new Error("workspace_cache action=wait requires jobId");
@@ -1655,7 +1667,10 @@ export default function (pi: ExtensionAPI) {
 						);
 					}
 					const job = outcome.kind === "terminal" ? outcome.job : await cacheOperations.jobStatus(params.jobId);
-					return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "wait", job } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "wait"), job) }],
+						details: { action: "wait", job },
+					};
 				}
 				if (!params.directory) throw new Error(`workspace_cache action=${params.action} requires directory`);
 				const directory = resolve(cwd, params.directory);
@@ -1663,10 +1678,16 @@ export default function (pi: ExtensionAPI) {
 				const maxSymbolsPerFile = params.maxSymbolsPerFile ?? 100;
 				if (params.action === "status") {
 					const status = await cacheOperations.status(directory, maxFiles, maxSymbolsPerFile);
-					return { content: [{ type: "text", text: JSON.stringify(status) }], details: { action: "status", status } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "status"), status) }],
+						details: { action: "status", status },
+					};
 				}
 				const job = await cacheOperations.submit(directory, maxFiles, maxSymbolsPerFile, params.waitMs ?? 3_000);
-				return { content: [{ type: "text", text: JSON.stringify(job) }], details: { action: "populate", job } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("workspace_cache", "populate"), job) }],
+					details: { action: "populate", job },
+				};
 			},
 			renderCall(args, theme, context) {
 				const action = args.action === "populate" || args.action === "wait" || args.action === "job_status" ? args.action : "status";
@@ -1764,7 +1785,7 @@ export default function (pi: ExtensionAPI) {
 				if (params.action === "status") {
 					const summary = await gitOperations.status(directory, vehicleCall);
 					const details: GitToolDetails = { action: "status", summary };
-					return { content: [{ type: "text", text: JSON.stringify(summary) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "status"), summary) }], details };
 				}
 				if (params.action === "log") {
 					if (params.maxCount === undefined) throw new Error("git action=log requires maxCount");
@@ -1785,18 +1806,18 @@ export default function (pi: ExtensionAPI) {
 					if (params.maxBytes === undefined) throw new Error("git action=compare-symbol requires maxBytes");
 					const comparison = await gitOperations.compareSymbol(directory, params.path, params.symbol, params.fromRef, params.toRef, params.maxBytes);
 					const details: GitToolDetails = { action: "compare-symbol", comparison };
-					return { content: [{ type: "text", text: JSON.stringify(comparison) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "compare-symbol"), comparison) }], details };
 				}
 				if (params.action === "worktree-add") {
 					if (!params.ref) throw new Error("git action=worktree-add requires ref");
 					const worktreeAdd = await gitOperations.worktreeAdd(directory, params.ref, params.forceRefresh, vehicleCall);
 					const details: GitToolDetails = { action: "worktree-add", worktreeAdd };
-					return { content: [{ type: "text", text: JSON.stringify(worktreeAdd) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "worktree-add"), worktreeAdd) }], details };
 				}
 				if (params.action === "worktree-remove") {
 					const worktreeRemove = await gitOperations.worktreeRemove(directory, vehicleCall);
 					const details: GitToolDetails = { action: "worktree-remove", worktreeRemove };
-					return { content: [{ type: "text", text: JSON.stringify(worktreeRemove) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "worktree-remove"), worktreeRemove) }], details };
 				}
 				if (params.action === "show") {
 					if (!params.ref || !params.path) throw new Error("git action=show requires ref and path");
@@ -1809,7 +1830,7 @@ export default function (pi: ExtensionAPI) {
 					if (params.maxMatches === undefined || params.maxBytes === undefined) throw new Error("git action=grep-ref requires maxMatches and maxBytes");
 					const grep = await gitOperations.grep(directory, params.ref, params.pattern, params.pathspecs, params.maxMatches, params.maxBytes, vehicleCall);
 					const details: GitToolDetails = { action: "grep-ref", grep };
-					return { content: [{ type: "text", text: JSON.stringify(grep) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "grep-ref"), grep) }], details };
 				}
 				if (params.action === "grep-history") {
 					if (!params.pattern) throw new Error("git action=grep-history requires pattern");
@@ -1835,20 +1856,20 @@ export default function (pi: ExtensionAPI) {
 						vehicleCall,
 					);
 					const details: GitToolDetails = { action: "grep-history", historyGrep };
-					return { content: [{ type: "text", text: JSON.stringify(historyGrep) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "grep-history"), historyGrep) }], details };
 				}
 				if (params.action === "ls-ref") {
 					if (!params.ref) throw new Error("git action=ls-ref requires ref");
 					if (params.maxResults === undefined) throw new Error("git action=ls-ref requires maxResults");
 					const listFiles = await gitOperations.listFiles(directory, params.ref, params.pathspecs, params.maxResults, vehicleCall);
 					const details: GitToolDetails = { action: "ls-ref", listFiles };
-					return { content: [{ type: "text", text: JSON.stringify(listFiles) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "ls-ref"), listFiles) }], details };
 				}
 				if (params.action === "is-ancestor") {
 					if (!params.ancestorRef || !params.ref) throw new Error("git action=is-ancestor requires ancestorRef and ref");
 					const result = await gitOperations.isAncestor(directory, params.ancestorRef, params.ref, vehicleCall);
 					const details: GitToolDetails = { action: "is-ancestor", isAncestor: { ancestorRef: params.ancestorRef, ref: params.ref, result } };
-					return { content: [{ type: "text", text: JSON.stringify({ isAncestor: result }) }], details };
+					return { content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("git", "is-ancestor"), { isAncestor: result }) }], details };
 				}
 				throw new Error(`unknown git action: ${String(params.action)}`);
 			},
@@ -2134,7 +2155,7 @@ export default function (pi: ExtensionAPI) {
 				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)}`);
+				text.setText(`${theme.fg("toolTitle", theme.bold(presentationTitle("mutation_history", action)))} ${theme.fg("accent", path)}`);
 				return text;
 			},
 			renderResult(result, { isPartial }, theme, context) {
@@ -2210,7 +2231,10 @@ export default function (pi: ExtensionAPI) {
 						maxResults: params.maxResults,
 						cursor: params.cursor,
 					});
-					return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "list"), page) }],
+						details: { action: "list", page },
+					};
 				}
 				if (params.action === "remove") {
 					if (!params.name || !params.resolvedVersion) throw new Error("package_source action=remove requires ecosystem, name, and resolvedVersion");
@@ -2220,11 +2244,17 @@ export default function (pi: ExtensionAPI) {
 						params.name,
 						params.resolvedVersion,
 					);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "remove", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "remove"), result) }],
+						details: { action: "remove", result },
+					};
 				}
 				if (params.action === "clean") {
 					const result = await packageSourceOperations.clean(optionalPackageEcosystem(params.ecosystem));
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "clean", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "clean"), result) }],
+						details: { action: "clean", result },
+					};
 				}
 				if (!params.directory || !params.name) throw new Error("package_source action=resolve requires directory and name");
 				const directory = resolve(cwd, params.directory);
@@ -2235,7 +2265,10 @@ export default function (pi: ExtensionAPI) {
 					params.registry ?? null,
 					optionalPackageEcosystem(params.ecosystem),
 				);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "resolve", result } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("package_source", "resolve"), result) }],
+					details: { action: "resolve", result },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
@@ -2332,12 +2365,18 @@ export default function (pi: ExtensionAPI) {
 						params.forceRefresh,
 						vehicleCall,
 					);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "fetch", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "fetch"), result) }],
+						details: { action: "fetch", result },
+					};
 				}
 				if (params.action === "evict") {
 					if (!params.owner || !params.repo) throw new Error("repo_cache action=evict requires owner and repo");
 					const result = await repoCacheEvictOperations.evict(params.host ?? "github.com", params.owner, params.repo, params.ref ?? null, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "evict", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "evict"), result) }],
+						details: { action: "evict", result },
+					};
 				}
 				if (params.maxResults === undefined) throw new Error("repo_cache action=list requires maxResults");
 				const page = await repoCacheListOperations.list(
@@ -2346,7 +2385,10 @@ export default function (pi: ExtensionAPI) {
 					params.cursor,
 					vehicleCall,
 				);
-				return { content: [{ type: "text", text: JSON.stringify(page) }], details: { action: "list", page } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("repo_cache", "list"), page) }],
+					details: { action: "list", page },
+				};
 			},
 			renderCall(args, theme, context) {
 				const action = args.action === "list" || args.action === "evict" ? args.action : "fetch";
@@ -2419,14 +2461,23 @@ export default function (pi: ExtensionAPI) {
 				};
 				if (params.action === "github_repos") {
 					const result = await externalSearchOperations.githubRepos(params.query, maxResults, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "github_repos", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "github_repos"), result) }],
+						details: { action: "github_repos", result },
+					};
 				}
 				if (params.action === "npm_packages") {
 					const result = await externalSearchOperations.npmPackages(params.query, maxResults, vehicleCall);
-					return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "npm_packages", result } };
+					return {
+						content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "npm_packages"), result) }],
+						details: { action: "npm_packages", result },
+					};
 				}
 				const result = await externalSearchOperations.sourcegraphCode(params.query, maxResults, vehicleCall);
-				return { content: [{ type: "text", text: JSON.stringify(result) }], details: { action: "sourcegraph_code", result } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("external_search", "sourcegraph_code"), result) }],
+					details: { action: "sourcegraph_code", result },
+				};
 			},
 			renderCall(args, theme, context) {
 				const action = args.action === "npm_packages" || args.action === "sourcegraph_code" ? args.action : "github_repos";
@@ -2434,7 +2485,7 @@ export default function (pi: ExtensionAPI) {
 				text.setText(formatExternalSearchCall(action, args, theme));
 				return text;
 			},
-			renderResult(result, { isPartial }, theme, context) {
+			renderResult(result, { expanded, isPartial }, theme, context) {
 				if (isPartial) return new Text(theme.fg("warning", "Searching..."), 0, 0);
 				if (context.isError) {
 					const errorText = result.content
@@ -2445,9 +2496,9 @@ export default function (pi: ExtensionAPI) {
 				}
 				const details = result.details as ExternalSearchToolDetails | undefined;
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				if (details?.action === "npm_packages") text.setText(formatNpmPackageSearchResult(details.result, theme));
-				else if (details?.action === "sourcegraph_code") text.setText(formatSourcegraphCodeSearchResult(details.result, theme));
-				else text.setText(formatGithubRepoSearchResult(details?.action === "github_repos" ? details.result : undefined, theme));
+				if (details?.action === "npm_packages") text.setText(formatNpmPackageSearchResult(details.result, expanded, theme));
+				else if (details?.action === "sourcegraph_code") text.setText(formatSourcegraphCodeSearchResult(details.result, expanded, theme));
+				else text.setText(formatGithubRepoSearchResult(details?.action === "github_repos" ? details.result : undefined, expanded, theme));
 				return text;
 			},
 		});
@@ -2470,11 +2521,14 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.findSymbols(params.query, directories, params.timeoutMs, params.maxResults);
-				return { content: [{ type: "text", text: JSON.stringify(results) }], details: { results } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("find_symbols_across_projects"), results) }],
+					details: { results },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args, theme));
+				text.setText(formatCrossWorkspaceCall("find_symbols_across_projects", args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {
@@ -2509,11 +2563,14 @@ export default function (pi: ExtensionAPI) {
 			async execute(_toolCallId, params) {
 				const directories = params.directories.map((directory) => resolve(cwd, directory));
 				const results = await crossWorkspaceSearchOperations.searchText(params.query, directories, params.maxMatches, params.maxBytes, params.timeoutMs);
-				return { content: [{ type: "text", text: JSON.stringify(results) }], details: { results } };
+				return {
+					content: [{ type: "text", text: formatSemanticModelContent(presentationTitle("search_code_across_projects"), results) }],
+					details: { results },
+				};
 			},
 			renderCall(args, theme, context) {
 				const text = context.lastComponent instanceof Text ? context.lastComponent : new Text("", 0, 0);
-				text.setText(formatCrossWorkspaceCall(args, theme));
+				text.setText(formatCrossWorkspaceCall("search_code_across_projects", args, theme));
 				return text;
 			},
 			renderResult(result, { expanded, isPartial }, theme, context) {

package/extension/src/line-edit/rendering.ts

@@ -1,10 +1,11 @@
 import type { LineEditOutcome } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 export function formatLineEditCall(args: { path?: unknown; edits?: unknown }, theme: LectorTheme): string {
 	const path = typeof args.path === "string" ? args.path : "";
 	const count = Array.isArray(args.edits) ? args.edits.length : 0;
-	return `${theme.fg("toolTitle", theme.bold("line_edit"))} ${theme.fg("accent", path)} ${theme.fg("dim", `(${count} edit${count === 1 ? "" : "s"})`)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("line_edit")))} ${theme.fg("accent", path)} ${theme.fg("dim", `(${count} edit${count === 1 ? "" : "s"})`)}`;
 }
 
 export function formatLineEditResult(result: LineEditOutcome | undefined, theme: LectorTheme): string {

package/extension/src/package-source/rendering.ts

@@ -2,6 +2,7 @@ import type { PackageSourceListEntry, PackageSourceOperationResult } from "@dany
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList, type TableColumn } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 const DEFAULT_VISIBLE_CANDIDATES = 5;
 
@@ -14,18 +15,18 @@ export function formatPackageSourceCall(
 	args: { action?: unknown; directory?: unknown; name?: unknown; version?: unknown; ecosystem?: unknown; resolvedVersion?: unknown; text?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("package_source"));
 	const action: PackageSourceAction = args.action === "list" || args.action === "remove" || args.action === "clean" ? args.action : "resolve";
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("package_source", action)));
 	if (action === "list") {
 		const text = typeof args.text === "string" && args.text.length > 0 ? ` ${theme.fg("dim", args.text)}` : "";
-		return `${label} ${theme.fg("accent", "list")}${text}`;
+		return `${label}${text}`;
 	}
 	if (action === "remove" || action === "clean") {
 		const name = typeof args.name === "string" ? args.name : "";
 		const version = typeof args.resolvedVersion === "string" ? `@${args.resolvedVersion}` : "";
 		const ecosystem = typeof args.ecosystem === "string" ? args.ecosystem : "";
 		const identity = name ? `${name}${version}` : ecosystem;
-		return `${label} ${theme.fg("accent", action)}${identity ? ` ${theme.fg("dim", identity)}` : ""}`;
+		return `${label}${identity ? ` ${theme.fg("accent", identity)}` : ""}`;
 	}
 	const name = typeof args.name === "string" ? args.name : "";
 	const version = typeof args.version === "string" ? `@${args.version}` : "";

package/extension/src/presentation/model-content.ts

@@ -0,0 +1,62 @@
+export const DEFAULT_MODEL_CONTENT_BYTES = 32_768;
+const MAX_COLLECTION_ENTRIES = 24;
+const MAX_DEPTH = 4;
+
+function scalarText(value: unknown): string | undefined {
+	if (value === null) return "none";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	return undefined;
+}
+
+function appendSemanticLines(lines: string[], value: unknown, path: string, depth: number): void {
+	const scalar = scalarText(value);
+	if (scalar !== undefined) {
+		lines.push(`${path}: ${scalar}`);
+		return;
+	}
+	if (depth >= MAX_DEPTH) {
+		lines.push(`${path}: [nested value omitted]`);
+		return;
+	}
+	if (Array.isArray(value)) {
+		lines.push(`${path} (${value.length})`);
+		for (const [index, entry] of value.slice(0, MAX_COLLECTION_ENTRIES).entries()) appendSemanticLines(lines, entry, `${path}[${index}]`, depth + 1);
+		if (value.length > MAX_COLLECTION_ENTRIES) lines.push(`${path}: ${value.length - MAX_COLLECTION_ENTRIES} more entries omitted`);
+		return;
+	}
+	if (typeof value === "object" && value !== null) {
+		const entries = Object.entries(value).slice(0, MAX_COLLECTION_ENTRIES);
+		if (entries.length === 0) lines.push(`${path}: none`);
+		for (const [key, entry] of entries) appendSemanticLines(lines, entry, path ? `${path}.${key}` : key, depth + 1);
+		if (Object.keys(value).length > MAX_COLLECTION_ENTRIES) lines.push(`${path || "result"}: additional fields omitted`);
+		return;
+	}
+	lines.push(`${path}: unavailable`);
+}
+
+/** Bounds UTF-8 model-facing text independently from presentation details. */
+export function boundModelContentText(full: string, maxBytes = DEFAULT_MODEL_CONTENT_BYTES): string {
+	if (!Number.isInteger(maxBytes) || maxBytes < 64) throw new Error("model content maxBytes must be an integer of at least 64");
+	if (Buffer.byteLength(full, "utf8") <= maxBytes) return full;
+	const suffix = "\n[model content truncated]";
+	const budget = maxBytes - Buffer.byteLength(suffix, "utf8");
+	let bytes = Buffer.from(full, "utf8").subarray(0, Math.max(0, budget));
+	let prefix = "";
+	while (bytes.length > 0) {
+		try {
+			prefix = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+			break;
+		} catch {
+			bytes = bytes.subarray(0, -1);
+		}
+	}
+	return `${prefix}${suffix}`;
+}
+
+/** Formats an operation outcome as bounded, semantic plain text for model consumption. */
+export function formatSemanticModelContent(title: string, value: unknown, maxBytes = DEFAULT_MODEL_CONTENT_BYTES): string {
+	const lines = [title];
+	appendSemanticLines(lines, value, "", 0);
+	return boundModelContentText(lines.join("\n"), maxBytes);
+}

package/extension/src/presentation/presentation-contract.ts

@@ -0,0 +1,148 @@
+import type { JsonValue } from "@danypops/vehicle-core";
+import type { AgentToolResult, AgentToolUpdateCallback, Theme, ToolDefinition } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import type { TSchema } from "typebox";
+import { boundModelContentText, DEFAULT_MODEL_CONTENT_BYTES } from "./model-content.ts";
+import { type PresentationFamily, presentationFamily } from "./tool-presentation.ts";
+
+export const LECTOR_PRESENTATION_SCHEMA = "pi-lector.presentation/v1";
+export const DEFAULT_LECTOR_PRESENTATION_MAX_BYTES = 128 * 1024;
+
+interface LectorPresentationBase {
+	readonly schema: typeof LECTOR_PRESENTATION_SCHEMA;
+	readonly tool: string;
+	readonly action: string | null;
+	readonly payload: JsonValue;
+}
+
+/** Versioned presentation variants persisted independently from model-facing content. */
+export type LectorToolPresentation = {
+	readonly [Family in PresentationFamily]: LectorPresentationBase & { readonly family: Family };
+}[PresentationFamily];
+
+export type LectorPresentationEnvelope = LectorToolPresentation;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isJsonValue(value: unknown): value is JsonValue {
+	if (value === null || typeof value === "string" || typeof value === "boolean") return true;
+	if (typeof value === "number") return Number.isFinite(value);
+	if (Array.isArray(value)) return value.every(isJsonValue);
+	if (isRecord(value)) return Object.values(value).every(isJsonValue);
+	return false;
+}
+
+function serializedJsonValue(value: unknown): JsonValue {
+	if (value === undefined) return null;
+	let serialized: string;
+	try {
+		serialized = JSON.stringify(value, (_key, candidate: unknown) => {
+			if (typeof candidate === "number" && !Number.isFinite(candidate)) throw new TypeError("non-finite number");
+			if (typeof candidate === "bigint" || typeof candidate === "function" || typeof candidate === "symbol") {
+				throw new TypeError(`unsupported ${typeof candidate}`);
+			}
+			return candidate;
+		});
+	} catch (error) {
+		throw new TypeError(`presentation details must be JSON serializable: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	const parsed: unknown = JSON.parse(serialized);
+	if (!isJsonValue(parsed)) throw new TypeError("presentation details must contain only JSON values");
+	return parsed;
+}
+
+/** Projects one tool's renderer details into the versioned, serializable session boundary. */
+export function projectLectorPresentation(
+	tool: string,
+	details: unknown,
+	maxBytes = DEFAULT_LECTOR_PRESENTATION_MAX_BYTES,
+	actionOverride?: string,
+): LectorPresentationEnvelope {
+	if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) throw new TypeError("presentation maxBytes must be a positive integer");
+	const action = actionOverride ?? (isRecord(details) && typeof details.action === "string" ? details.action : null);
+	const envelope: LectorPresentationEnvelope = {
+		schema: LECTOR_PRESENTATION_SCHEMA,
+		tool,
+		action,
+		family: presentationFamily(tool, action ?? undefined),
+		payload: serializedJsonValue(details),
+	};
+	const bytes = Buffer.byteLength(JSON.stringify(envelope), "utf8");
+	if (bytes > maxBytes) throw new RangeError(`presentation details exceed ${maxBytes} bytes (${bytes} observed)`);
+	return envelope;
+}
+
+/** Validates the shared envelope. Domain renderers retain responsibility for validating their payload variant. */
+export function parseLectorPresentation(details: unknown, expectedTool: string): JsonValue | undefined {
+	if (!isRecord(details)) return undefined;
+	if (details.schema !== LECTOR_PRESENTATION_SCHEMA || details.tool !== expectedTool || !("payload" in details)) return undefined;
+	if (details.action !== null && typeof details.action !== "string") return undefined;
+	if (details.family !== presentationFamily(expectedTool, typeof details.action === "string" ? details.action : undefined)) return undefined;
+	try {
+		return serializedJsonValue(details.payload);
+	} catch {
+		return undefined;
+	}
+}
+
+function fallbackText(result: AgentToolResult<unknown>, theme: Theme): Text {
+	const content = result.content
+		.filter((block): block is Extract<(typeof result.content)[number], { type: "text" }> => block.type === "text")
+		.map((block) => block.text)
+		.join("\n");
+	return new Text(theme.fg("toolOutput", content || "No result."), 0, 0);
+}
+
+export interface LectorPresentationOptions {
+	readonly maxBytes?: number;
+	readonly maxModelContentBytes?: number;
+}
+
+/** Wraps a production tool so persisted renderer details cross one validated, bounded envelope. */
+export function withLectorPresentation<TParams extends TSchema, TDetails, TState>(
+	tool: ToolDefinition<TParams, TDetails, TState>,
+	options: LectorPresentationOptions = {},
+): ToolDefinition<TParams, LectorPresentationEnvelope, TState> {
+	const maxBytes = options.maxBytes ?? DEFAULT_LECTOR_PRESENTATION_MAX_BYTES;
+	const maxModelContentBytes = options.maxModelContentBytes ?? DEFAULT_MODEL_CONTENT_BYTES;
+	return {
+		...tool,
+		async execute(toolCallId, params, signal, onUpdate, context) {
+			const parameterRecord = params as Record<string, unknown>;
+			const action =
+				typeof parameterRecord.action === "string"
+					? parameterRecord.action
+					: typeof parameterRecord.direction === "string"
+						? parameterRecord.direction
+						: undefined;
+			const boundedContent = (content: AgentToolResult<unknown>["content"]): AgentToolResult<unknown>["content"] =>
+				content.map((block) => (block.type === "text" ? { ...block, text: boundModelContentText(block.text, maxModelContentBytes) } : block));
+			const wrappedUpdate: AgentToolUpdateCallback<TDetails> | undefined = onUpdate
+				? (update) =>
+						onUpdate({
+							...update,
+							content: boundedContent(update.content),
+							details: projectLectorPresentation(tool.name, update.details, maxBytes, action),
+						})
+				: undefined;
+			const result = await tool.execute(toolCallId, params, signal, wrappedUpdate, context);
+			return {
+				...result,
+				content: boundedContent(result.content),
+				details: projectLectorPresentation(tool.name, result.details, maxBytes, action),
+			};
+		},
+		renderResult(result, renderOptions, theme, context) {
+			const payload = parseLectorPresentation(result.details, tool.name);
+			if (payload === undefined && !renderOptions.isPartial && !context.isError) return fallbackText(result, theme);
+			if (!tool.renderResult) return fallbackText(result, theme);
+			// The envelope is the runtime validation boundary. Each existing domain renderer narrows
+			// its own payload variant; this is the single shared assertion that reconnects its generic.
+			// eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion
+			const domainDetails = payload as TDetails;
+			return tool.renderResult({ ...result, details: domainDetails }, renderOptions, theme, context);
+		},
+	};
+}

package/extension/src/presentation/tool-presentation.ts

@@ -0,0 +1,170 @@
+export type PresentationFamily =
+	| "source"
+	| "markdown"
+	| "symbols"
+	| "locations"
+	| "diagnostics"
+	| "diff"
+	| "mutation"
+	| "status"
+	| "table"
+	| "tree"
+	| "candidates"
+	| "semantic-text";
+
+interface PresentationPathSpec {
+	readonly title: string;
+	readonly family: PresentationFamily;
+}
+
+interface ToolPresentationSpec extends PresentationPathSpec {
+	readonly actions?: Readonly<Record<string, PresentationPathSpec>>;
+}
+
+export const LECTOR_TOOL_PRESENTATION_SPECS: Readonly<Record<string, ToolPresentationSpec>> = {
+	read: { title: "Read File", family: "source" },
+	write: { title: "Write File", family: "mutation" },
+	edit: { title: "Edit File", family: "diff" },
+	find_symbols: { title: "Find Symbols", family: "symbols" },
+	localize_context: { title: "Localize Context", family: "candidates" },
+	go_to_definition: { title: "Go to Definition", family: "locations" },
+	go_to_implementation: { title: "Go to Implementation", family: "locations" },
+	find_references: { title: "Find References", family: "locations" },
+	hover: { title: "Hover", family: "markdown" },
+	document_symbols: { title: "Document Symbols", family: "tree" },
+	diagnostics: { title: "Diagnostics", family: "diagnostics" },
+	code_action_preview: { title: "Preview Code Actions", family: "candidates" },
+	code_action_apply: { title: "Apply Code Action", family: "mutation" },
+	diagnostic_delta: { title: "Diagnostic Delta", family: "diagnostics" },
+	call_hierarchy: {
+		title: "Call Hierarchy",
+		family: "tree",
+		actions: {
+			prepare: { title: "Prepare Call Hierarchy", family: "symbols" },
+			incoming: { title: "Incoming Calls", family: "tree" },
+			outgoing: { title: "Outgoing Calls", family: "tree" },
+		},
+	},
+	type_hierarchy: {
+		title: "Type Hierarchy",
+		family: "tree",
+		actions: {
+			prepare: { title: "Prepare Type Hierarchy", family: "symbols" },
+			supertypes: { title: "Supertypes", family: "tree" },
+			subtypes: { title: "Subtypes", family: "tree" },
+		},
+	},
+	impact_analysis: { title: "Impact Analysis", family: "tree" },
+	reference_based_rename: { title: "Rename File by References", family: "mutation" },
+	rename: {
+		title: "Rename Symbol",
+		family: "mutation",
+		actions: {
+			prepare: { title: "Prepare Rename", family: "semantic-text" },
+			apply: { title: "Rename Symbol", family: "mutation" },
+		},
+	},
+	symbol_annotations: {
+		title: "Symbol Annotations",
+		family: "semantic-text",
+		actions: {
+			create: { title: "Create Symbol Annotation", family: "mutation" },
+			get: { title: "Show Symbol Annotation", family: "markdown" },
+			list: { title: "List Symbol Annotations", family: "table" },
+			refresh: { title: "Refresh Symbol Annotation", family: "mutation" },
+			scrub: { title: "Scrub Symbol Annotation", family: "mutation" },
+			restore: { title: "Restore Symbol Annotation", family: "mutation" },
+			contain: { title: "Contain Symbol Annotation", family: "mutation" },
+			uncontain: { title: "Uncontain Symbol Annotation", family: "mutation" },
+			tree: { title: "Annotation Tree", family: "tree" },
+		},
+	},
+	reachable_from: { title: "Reachable Symbols", family: "tree" },
+	workspace_map: { title: "Workspace Map", family: "symbols" },
+	workspace_cache: {
+		title: "Workspace Cache",
+		family: "status",
+		actions: {
+			status: { title: "Workspace Cache Status", family: "status" },
+			populate: { title: "Populate Workspace Cache", family: "status" },
+			wait: { title: "Wait for Cache Job", family: "status" },
+			job_status: { title: "Cache Job Status", family: "status" },
+		},
+	},
+	git: {
+		title: "Git",
+		family: "semantic-text",
+		actions: {
+			status: { title: "Git Status", family: "status" },
+			log: { title: "Git Log", family: "table" },
+			diff: { title: "Git Diff", family: "diff" },
+			"compare-symbol": { title: "Compare Symbol", family: "diff" },
+			show: { title: "Show File at Git Ref", family: "source" },
+			"grep-ref": { title: "Search Git Ref", family: "locations" },
+			"grep-history": { title: "Search Git History", family: "locations" },
+			"ls-ref": { title: "List Files at Git Ref", family: "table" },
+			"is-ancestor": { title: "Check Git Ancestry", family: "semantic-text" },
+			"worktree-add": { title: "Create Git Worktree", family: "mutation" },
+			"worktree-remove": { title: "Remove Git Worktree", family: "mutation" },
+		},
+	},
+	search_code: { title: "Search Code", family: "locations" },
+	find_files: { title: "Find Files", family: "table" },
+	line_edit: { title: "Edit Lines", family: "diff" },
+	apply_patch: { title: "Apply Patch", family: "diff" },
+	mutation_history: {
+		title: "Mutation History",
+		family: "table",
+		actions: {
+			list: { title: "Mutation History", family: "table" },
+			revert: { title: "Revert Mutation", family: "mutation" },
+			"revert-transaction": { title: "Revert Transaction", family: "mutation" },
+		},
+	},
+	package_source: {
+		title: "Package Source",
+		family: "semantic-text",
+		actions: {
+			resolve: { title: "Resolve Package Source", family: "semantic-text" },
+			list: { title: "List Package Sources", family: "table" },
+			remove: { title: "Remove Package Source", family: "mutation" },
+			clean: { title: "Clean Package Sources", family: "mutation" },
+		},
+	},
+	repo_cache: {
+		title: "Repository Cache",
+		family: "semantic-text",
+		actions: {
+			fetch: { title: "Fetch Repository", family: "status" },
+			list: { title: "List Repository Cache", family: "table" },
+			evict: { title: "Evict Repository", family: "mutation" },
+		},
+	},
+	external_search: {
+		title: "External Search",
+		family: "candidates",
+		actions: {
+			github_repos: { title: "Search GitHub Repositories", family: "candidates" },
+			npm_packages: { title: "Search npm Packages", family: "candidates" },
+			sourcegraph_code: { title: "Search Public Code", family: "candidates" },
+		},
+	},
+	find_symbols_across_projects: { title: "Find Symbols Across Projects", family: "symbols" },
+	search_code_across_projects: { title: "Search Code Across Projects", family: "locations" },
+};
+
+export function presentationTitle(toolName: string, action?: string): string {
+	const spec = LECTOR_TOOL_PRESENTATION_SPECS[toolName];
+	if (!spec) throw new Error(`no presentation specification for ${toolName}`);
+	return (action ? spec.actions?.[action]?.title : undefined) ?? spec.title;
+}
+
+export function presentationFamily(toolName: string, action?: string): PresentationFamily {
+	const spec = LECTOR_TOOL_PRESENTATION_SPECS[toolName];
+	if (!spec) throw new Error(`no presentation specification for ${toolName}`);
+	return (action ? spec.actions?.[action]?.family : undefined) ?? spec.family;
+}
+
+export function presentationPathCount(): number {
+	return Object.values(LECTOR_TOOL_PRESENTATION_SPECS).reduce((count, spec) => count + (spec.actions ? Object.keys(spec.actions).length : 1), 0);
+}

package/extension/src/repo-cache/rendering.ts

@@ -2,6 +2,7 @@ import type { CachedRepositoryEntry, CachedRepositoryPage, RepoFetchResult } fro
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import type { TableColumn } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 /** Table has no row-count bound of its own; a cache can grow arbitrarily large even though repo_cache's own `maxResults` bounds any one page, so the display itself still needs a cap independent of that. */
 export const REPO_CACHE_VISIBLE_ROWS = 20;
@@ -17,16 +18,16 @@ export function formatRepoCacheCall(
 	args: { owner?: unknown; repo?: unknown; ref?: unknown; host?: unknown; text?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("repo_cache"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("repo_cache", action)));
 	if (action === "list") {
 		const filter = typeof args.text === "string" && args.text.length > 0 ? args.text : typeof args.repo === "string" ? args.repo : "";
-		return `${label} ${theme.fg("accent", "list")}${filter ? ` ${theme.fg("dim", filter)}` : ""}`;
+		return `${label}${filter ? ` ${theme.fg("accent", filter)}` : ""}`;
 	}
 	const host = typeof args.host === "string" && args.host.length > 0 ? args.host : "github.com";
 	const owner = typeof args.owner === "string" ? args.owner : "";
 	const repo = typeof args.repo === "string" ? args.repo : "";
 	const ref = typeof args.ref === "string" ? `@${args.ref}` : "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", `${host}/${owner}/${repo}${ref}`)}`;
+	return `${label} ${theme.fg("accent", `${host}/${owner}/${repo}${ref}`)}`;
 }
 
 export function formatRepoFetchResult(result: (RepoFetchResult & { workspaceId: string }) | undefined, theme: LectorTheme): string {

package/extension/src/search/rendering.ts

@@ -2,13 +2,14 @@ import type { TextSearchResult } from "@danypops/lector";
 import { keyHint } from "@earendil-works/pi-coding-agent";
 import { renderTruncatedList } from "malevich-tui-components";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 const DEFAULT_VISIBLE_MATCHES = 20;
 
 export function formatSearchCall(args: { directory?: unknown; query?: unknown }, theme: LectorTheme): string {
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const query = typeof args.query === "string" ? args.query : "";
-	return `${theme.fg("toolTitle", theme.bold("search_code"))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", directory)}`;
+	return `${theme.fg("toolTitle", theme.bold(presentationTitle("search_code")))} ${theme.fg("accent", `"${query}"`)} ${theme.fg("dim", directory)}`;
 }
 
 export function formatSearchResult(result: TextSearchResult | undefined, expanded: boolean, theme: LectorTheme): string {

package/extension/src/workspace-cache/rendering.ts

@@ -1,5 +1,6 @@
 import type { CacheResultCounts, JobSnapshot, PopulateSymbolGraphResult, WorkspaceCacheStatus } from "@danypops/lector";
 import type { LectorTheme } from "../lector-tui-theme.ts";
+import { presentationTitle } from "../presentation/tool-presentation.ts";
 
 type WorkspaceCacheAction = "status" | "populate" | "wait" | "job_status";
 
@@ -8,10 +9,10 @@ export function formatWorkspaceCacheCall(
 	args: { directory?: unknown; maxFiles?: unknown; maxSymbolsPerFile?: unknown; jobId?: unknown },
 	theme: LectorTheme,
 ): string {
-	const label = theme.fg("toolTitle", theme.bold("workspace_cache"));
+	const label = theme.fg("toolTitle", theme.bold(presentationTitle("workspace_cache", action)));
 	if (action === "job_status" || action === "wait") {
 		const jobId = typeof args.jobId === "string" ? args.jobId : "";
-		return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", jobId)}`;
+		return `${label} ${theme.fg("accent", jobId)}`;
 	}
 	const directory = typeof args.directory === "string" ? args.directory : "";
 	const maxFiles = typeof args.maxFiles === "number" ? String(args.maxFiles) : "default";
@@ -20,7 +21,7 @@ export function formatWorkspaceCacheCall(
 		action === "populate" && (typeof args.maxFiles === "number" || typeof args.maxSymbolsPerFile === "number")
 			? theme.fg("dim", ` (maxFiles=${maxFiles}, maxSymbolsPerFile=${maxSymbolsPerFile})`)
 			: "";
-	return `${label} ${theme.fg("accent", action)} ${theme.fg("dim", directory)}${bounds}`;
+	return `${label} ${theme.fg("accent", directory)}${bounds}`;
 }
 
 function formatResultCounts(result: CacheResultCounts): string {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@danypops/pi-lector",
-	"version": "0.13.11",
+	"version": "0.14.0",
 	"description": "Pi host adapter for Lector: overrides read/write/edit with a daemon-backed, hash-guarded filesystem",
 	"license": "MIT",
 	"type": "module",