@oh-my-pi/pi-tui 18.4.3 → 18.4.4

package/src/tools/ast-grep.ts

@@ -12,9 +12,13 @@ import {
 	PREVIEW_LIMITS,
 	toPathList,
 } from "../render/render-utils";
-import { classifyGroupedLines, groupLineIndicesByBlank } from "./grouped-file-output";
+import { classifyGroupedLines, describeGroupedOutput, groupLineIndicesByBlank } from "./grouped-file-output";
+import { getLanguageFromPath } from "../lang-from-path";
+import { code, compact, node, span } from "../native/describe";
+import type { NativeChild } from "../native/node";
+import { errorText, noteText, resultText, toolHead } from "./native-view";
 import type { OutputMeta } from "./output-meta";
-import type { RenderResultOptions, ToolRenderer } from "./renderer";
+import type { NativeToolView, RenderResultOptions, ToolRenderer } from "./renderer";
 
 /** Display metadata returned by ast-grep. */
 export interface AstGrepToolDetails {
@@ -167,5 +171,81 @@ export const astGrepToolRenderer = {
 			},
 		);
 	},
+	describeCall(args: AstGrepRenderArgs): NativeToolView {
+		const meta: string[] = [];
+		const scopePaths = toPathList(args.path ?? args.paths);
+		if (scopePaths.length) meta.push(`in ${scopePaths.join(", ")}`);
+		if (args.skip !== undefined && args.skip > 0) meta.push(`skip:${args.skip}`);
+		return { head: toolHead("AST Grep", span(args.pat ?? "?", "code"), ...meta) };
+	},
+
+	describeResult(
+		result: { content: Array<{ type: string; text?: string }>; details?: AstGrepToolDetails; isError?: boolean },
+		_options: RenderResultOptions,
+		args?: AstGrepRenderArgs,
+	): NativeToolView {
+		const details = result.details;
+		const pattern = span(args?.pat ?? "?", "code");
+		if (result.isError) {
+			return {
+				head: toolHead("AST Grep", pattern),
+				tone: "error",
+				body: [errorText(resultText(result) || "Unknown error")],
+			};
+		}
+		const matchCount = details?.matchCount ?? 0;
+		const filesSearched = details?.filesSearched ?? 0;
+		const limitReached = details?.limitReached ?? false;
+		const parseErrors = details?.parseErrors ?? [];
+		const parseNote =
+			parseErrors.length > 0
+				? node(
+						"section",
+						{
+							head: [span(formatParseErrorsCountLabel(parseErrors, details?.parseErrorsTotal), "warning")],
+							collapsible: true,
+							collapsed: true,
+						},
+						[code(parseErrors.join("\n"))],
+						"parse-errors",
+					)
+				: undefined;
+		if (matchCount === 0) {
+			const meta = ["0 matches"];
+			if (details?.scopePath) meta.push(`in ${details.scopePath}`);
+			if (filesSearched > 0) meta.push(`searched ${filesSearched}`);
+			return {
+				head: toolHead("AST Grep", pattern, ...meta),
+				tone: "warning",
+				body: compact<NativeChild>([
+					noteText("No matches found"),
+					parseErrors.length > 0 &&
+						noteText("Query may be mis-scoped; narrow `path` before concluding absence", "warning"),
+					parseNote,
+				]),
+			};
+		}
+		const meta = [formatCount("match", matchCount), formatCount("file", details?.fileCount ?? 0)];
+		if (details?.scopePath) meta.push(`in ${details.scopePath}`);
+		meta.push(`searched ${filesSearched}`);
+		const head = toolHead("AST Grep", pattern, ...meta);
+		if (limitReached) head.push(span(" limit reached", "warning"));
+		const allLines = (details?.displayContent ?? resultText(result)).split("\n");
+		const kept = groupLineIndicesByBlank(allLines)
+			.filter(indices => {
+				const first = allLines[indices[0]!]!;
+				return !first.startsWith("Result limit reached") && !first.startsWith("Parse issues:");
+			})
+			.flatMap(indices => [...indices.map(index => allLines[index]!), ""]);
+		return {
+			head,
+			body: compact<NativeChild>([
+				...describeGroupedOutput(kept, { lang: getLanguageFromPath }),
+				limitReached && noteText("limit reached; narrow path or increase limit", "warning"),
+				parseNote,
+			]),
+			preview: { lines: COLLAPSED_MATCH_LIMIT },
+		};
+	},
 	mergeCallAndResult: true,
 } satisfies ToolRenderer<AstGrepRenderArgs, AstGrepToolDetails>;

package/src/tools/autoresearch.ts

@@ -1,7 +1,13 @@
 import { Text } from "../components/text";
 import type { Theme } from "../theme/theme";
 import { replaceTabs, truncateToWidth, shortenPath } from "../render/render-utils";
-import type { ToolRenderer } from "./renderer";
+import type { TspTone } from "@oh-my-pi/pi-wire";
+import { ansi, compact, kv, node, row, span, text } from "../native/describe";
+import type { NativeNode } from "../native/node";
+import { OwnerMemo } from "../native/memo";
+import { plainText } from "../native/spans";
+import { errorView, resultText, toolHead } from "./native-view";
+import type { NativeToolView, ToolRenderer, ToolRenderResult } from "./renderer";
 import type { TruncationResult } from "./streaming-output";
 
 /** Whether a lower or higher metric is better. */
@@ -155,6 +161,35 @@ export interface InitExperimentDetails {
 	baselineCommit: string | null;
 }
 
+/** Tone of an experiment disposition: kept succeeds, discarded warns, the rest fail. */
+function experimentTone(status: ExperimentStatus): TspTone {
+	return status === "keep" ? "success" : status === "discard" ? "warning" : "error";
+}
+
+/** Plain first line of a free-form argument, for single-line heads. */
+function firstLine(value: string | undefined): string {
+	return (
+		plainText(value ?? "")
+			.trim()
+			.split("\n")[0] ?? ""
+	);
+}
+
+/** Result text as a wrapped body, or an error card. */
+function describeTextResult(
+	title: string,
+	result: ToolRenderResult<unknown>,
+	style?: string,
+): NativeToolView | undefined {
+	const output = resultText(result);
+	if (result.isError) return errorView(title, output);
+	const body = plainText(output).trimEnd();
+	return body ? { body: [text(style ? [span(body, style)] : body, { wrap: "word" })] } : undefined;
+}
+
+const logResultMemo = new OwnerMemo<NativeToolView | undefined>();
+const runResultMemo = new OwnerMemo<NativeToolView | undefined>();
+
 function renderInitCall(name: string, theme: Theme): string {
 	return `${theme.fg("toolTitle", theme.bold("init_experiment"))} ${theme.fg("accent", truncateToWidth(replaceTabs(name), 100))}`;
 }
@@ -168,8 +203,42 @@ export const initExperimentToolRenderer = {
 		const text = replaceTabs(result.content.find(part => part.type === "text")?.text ?? "");
 		return new Text(text, 0, 0);
 	},
+	describeCall(args): NativeToolView {
+		return { head: toolHead("init_experiment", span(firstLine(args.name), "accent")) };
+	},
+	describeResult(result): NativeToolView | undefined {
+		return describeTextResult("init_experiment", result);
+	},
 } satisfies ToolRenderer<{ name: string }, InitExperimentDetails>;
 
+/** Native log summary: disposition badge, description, and metric/baseline grid. */
+function describeSummary(details: LogDetails): NativeToolView {
+	const { experiment, state } = details;
+	const tone = experimentTone(experiment.status);
+	const deviations = details.scopeDeviations.length;
+	return {
+		tone,
+		body: compact([
+			row(
+				[
+					node("badge", { text: experiment.status.toUpperCase(), tone }),
+					text([span(plainText(experiment.description), "muted")], { wrap: "word", grow: 1 }),
+				],
+				{ gap: "sm" },
+			),
+			kv([
+				[plainText(state.metricName), [span(formatNum(experiment.metric, state.metricUnit), "accent num")]],
+				[
+					"baseline",
+					state.bestMetric !== null ? [span(formatNum(state.bestMetric, state.metricUnit), "num")] : undefined,
+				],
+				["confidence", state.confidence !== null ? [span(`${state.confidence.toFixed(1)}x`, "num")] : undefined],
+				["deviations", deviations > 0 ? [span(String(deviations), "warning")] : undefined],
+			]),
+		]),
+	};
+}
+
 function renderSummary(details: LogDetails, theme: Theme): string {
 	const { experiment, state } = details;
 	const color = experiment.status === "keep" ? "success" : experiment.status === "discard" ? "warning" : "error";
@@ -205,8 +274,46 @@ export const logExperimentToolRenderer = {
 		}
 		return new Text(renderSummary(details, theme), 0, 0);
 	},
+	describeCall(args): NativeToolView {
+		return {
+			head: toolHead(
+				"log_experiment",
+				args.status ? span(args.status, experimentTone(args.status)) : undefined,
+				span(firstLine(args.description), "muted"),
+			),
+		};
+	},
+	describeResult(result): NativeToolView | undefined {
+		return logResultMemo.get(result, [], () => {
+			const details = result.details;
+			if (result.isError || !details) return describeTextResult("log_experiment", result);
+			return describeSummary(details);
+		});
+	},
 } satisfies ToolRenderer<{ status: ExperimentStatus; description: string }, LogDetails>;
 
+/** Native run status: TIMEOUT/FAIL/PASS badge with duration and primary metric. */
+function describeStatus(details: RunDetails): { tone: TspTone; node: NativeNode } {
+	const duration = `${details.durationSeconds.toFixed(1)}s`;
+	let tone: TspTone = "success";
+	let label = "PASS";
+	let meta = duration;
+	if (details.timedOut) {
+		tone = "error";
+		label = "TIMEOUT";
+	} else if (details.exitCode !== 0) {
+		tone = "error";
+		label = "FAIL";
+		meta = `exit=${details.exitCode} ${duration}`;
+	} else if (details.parsedPrimary !== null) {
+		meta = `${duration} ${plainText(details.metricName)}=${formatNum(details.parsedPrimary, details.metricUnit)}`;
+	}
+	return {
+		tone,
+		node: row([node("badge", { text: label, tone }), text([span(meta, tone)], { truncate: "end" })], { gap: "sm" }),
+	};
+}
+
 function renderStatus(details: RunDetails, theme: Theme): string {
 	if (details.timedOut) {
 		return theme.fg("error", `TIMEOUT ${details.durationSeconds.toFixed(1)}s`);
@@ -263,6 +370,40 @@ export const runExperimentToolRenderer = {
 				: "";
 		return new Text(preview ? `${statusText}\n${theme.fg("dim", preview)}${suffix}` : statusText, 0, 0);
 	},
+	describeCall(): NativeToolView {
+		return { head: toolHead("run_experiment", span(DEFAULT_HARNESS_COMMAND, "muted")) };
+	},
+	describeResult(result): NativeToolView | undefined {
+		return runResultMemo.get(result, [], () => {
+			const details = result.details;
+			if (isProgressDetails(details)) {
+				const output = resultText(result);
+				return {
+					tone: "warning",
+					preview: { lines: 6 },
+					body: compact([
+						node("spinner", { label: [span(`Running ${plainText(details.elapsed)}…`, "warning")] }),
+						output.trim() ? ansi(output, { follow: true }) : undefined,
+					]),
+				};
+			}
+			if (result.isError || !details || !isRunDetails(details)) return describeTextResult("run_experiment", result);
+			const status = describeStatus(details);
+			return {
+				tone: status.tone,
+				preview: { lines: 6 },
+				body: compact([
+					status.node,
+					details.tailOutput.trim() ? ansi(details.tailOutput, { follow: true }) : undefined,
+					details.truncation && details.fullOutputPath
+						? text([span("Full output: ", "warning"), span(shortenPath(details.fullOutputPath), "path")], {
+								truncate: "middle",
+							})
+						: undefined,
+				]),
+			};
+		});
+	},
 } satisfies ToolRenderer<unknown, RunDetails | RunExperimentProgressDetails>;
 
 /** Persisted experiment notes after an update. */
@@ -284,4 +425,11 @@ export const updateNotesToolRenderer = {
 		const text = replaceTabs(result.content.find(part => part.type === "text")?.text ?? "");
 		return new Text(theme.fg("muted", text), 0, 0);
 	},
+	describeCall(args): NativeToolView {
+		const preview = args.append_idea ?? args.body?.slice(0, 100);
+		return { head: toolHead("update_notes", span(firstLine(preview), "muted")) };
+	},
+	describeResult(result): NativeToolView | undefined {
+		return describeTextResult("update_notes", result, "muted");
+	},
 } satisfies ToolRenderer<{ body: string; append_idea?: string }, UpdateNotesDetails>;

package/src/tools/bash.ts

@@ -18,7 +18,16 @@ import {
 	stripRawOutputArtifactNotice,
 	stripTrailingNotice,
 } from "./output-meta";
-import type { RenderResultOptions, ToolRenderer } from "./renderer";
+import type {
+	NativeToolHead,
+	NativeToolView,
+	RenderResultContextOptions,
+	RenderResultOptions,
+	ToolRenderer,
+} from "./renderer";
+import { ansi, compact, keyed } from "../native/describe";
+import type { NativeChild } from "../native/node";
+import { footnoteText, resultText } from "./native-view";
 
 /** Default collapsed shell output preview height. */
 export const BASH_DEFAULT_PREVIEW_LINES = DEFAULT_TERMINAL_PREVIEW_LINES;
@@ -261,6 +270,122 @@ export function formatBashCommandLines(args: BashRenderArgs, uiTheme: Theme): st
 	return highlightedLines.map((line, i) => (i === 0 ? `${prefix}${line}` : line));
 }
 
+/**
+ * Plain (unstyled) command line for native views: `cd <dir> && NAME="…" <command>`,
+ * built from the same decoded display args (incl. streamed `__partialJson` env) as the ANSI path.
+ */
+export function formatBashCommandText(args: BashRenderArgs): string {
+	const displayWorkdir = formatToolWorkingDirectory(args.cwd, getProjectDir());
+	const envAssignments = formatBashEnvAssignments(getBashEnvForDisplay(args));
+	const parts: string[] = [];
+	if (displayWorkdir) parts.push(`cd ${displayWorkdir} &&`);
+	if (envAssignments) parts.push(envAssignments);
+	parts.push(args.command || "…");
+	return parts.join(" ");
+}
+
+/** Bash output with the LLM-facing notices (background, exit, wall time, artifact, truncation) removed. */
+function stripBashNotices(
+	rawOutput: string,
+	details: BashToolDetails | undefined,
+): { text: string; artifactId?: string } {
+	const withoutBackground =
+		details?.async?.state === "running"
+			? stripTrailingNotice(rawOutput, formatBackgroundNotice(details.async.jobId))
+			: rawOutput;
+	const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
+	const withoutExit =
+		details?.exitCode === undefined
+			? strippedOutput
+			: stripTrailingNotice(strippedOutput, formatExitCodeNotice(details.exitCode));
+	const withoutWall =
+		details?.wallTimeMs === undefined
+			? withoutExit
+			: stripTrailingNotice(withoutExit, formatWallTimeNotice(details.wallTimeMs));
+	return stripRawOutputArtifactNotice(withoutWall);
+}
+/** `Wall: 1.20s`, `Timeout: 30s`, … metadata parts shown under bash output. */
+function bashStatsParts(
+	details: BashToolDetails | undefined,
+	contextTimeout: number | undefined,
+	artifactId: string | undefined,
+	isError: boolean,
+): string[] {
+	const timeoutDisabled = details?.timeoutDisabled === true || contextTimeout === 0;
+	const timeoutSeconds = timeoutDisabled ? undefined : (details?.timeoutSeconds ?? contextTimeout);
+	const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
+	const wallTimeMs = details?.wallTimeMs;
+	const statsParts: string[] = [];
+	if (details?.async?.state === "running") {
+		statsParts.push(`Backgrounded: ${details.async.jobId}`);
+	}
+	if (details?.service) {
+		const service = details.service;
+		statsParts.push(`Service: ${service.name}`, `State: ${service.state}`);
+		statsParts.push(`Ready: ${service.ready ? "yes" : service.timedOut ? "timed out" : "no"}`);
+		if (service.pid !== undefined) statsParts.push(`PID: ${service.pid}`);
+	}
+	if (wallTimeMs !== undefined) {
+		statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
+	}
+	if (timeoutDisabled) {
+		statsParts.push("Timeout: disabled");
+	}
+	if (typeof timeoutSeconds === "number") {
+		statsParts.push(
+			requestedTimeoutSeconds !== undefined && requestedTimeoutSeconds !== timeoutSeconds
+				? `Timeout: ${timeoutSeconds}s (requested ${requestedTimeoutSeconds}s clamped)`
+				: `Timeout: ${timeoutSeconds}s`,
+		);
+	}
+	if (artifactId) {
+		statsParts.push(`Artifact: ${artifactId}`);
+	}
+	if (isError && typeof details?.exitCode === "number") {
+		statsParts.push(`Exit: ${details.exitCode}`);
+	}
+	return statsParts;
+}
+
+/**
+ * Native head facts of a shell call: title, the command once (`cd`/env
+ * prefix included), a `background` badge for a backgrounded job, the
+ * `exit N` chip and a `timed out` note only when the deadline hit.
+ */
+function shellToolHead(
+	title: string,
+	command: string,
+	details: BashToolDetails | undefined,
+	settled: boolean,
+): NativeToolHead {
+	const exit = settled && details?.exitCode !== undefined && details.exitCode !== 0 ? details.exitCode : undefined;
+	return {
+		title,
+		target: command,
+		targetKind: "command",
+		lang: "bash",
+		badges:
+			details?.async?.state === "running"
+				? [{ text: "background", title: `Backgrounded as job ${details.async.jobId}` }]
+				: undefined,
+		exit,
+		note: settled && details?.timedOut === true ? "timed out" : undefined,
+	};
+}
+
+/** The quiet final line's facts under shell output: service state and the full-output artifact. */
+function shellFootParts(details: BashToolDetails | undefined, artifactId: string | undefined): string[] {
+	const parts: string[] = [];
+	const service = details?.service;
+	if (service) {
+		parts.push(`Service ${service.name}`, service.state);
+		parts.push(service.ready ? "ready" : service.timedOut ? "ready timed out" : "not ready");
+		if (service.pid !== undefined) parts.push(`PID ${service.pid}`);
+	}
+	if (artifactId) parts.push(`Artifact ${artifactId}`);
+	return parts;
+}
+
 function toBashRenderArgs<TArgs>(args: TArgs | undefined, config: ShellRendererConfig<TArgs>): BashRenderArgs {
 	return {
 		command: config.resolveCommand?.(args),
@@ -378,58 +503,17 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 					) {
 						return cachedSnapshot;
 					}
-					const withoutBackground =
-						details?.async?.state === "running"
-							? stripTrailingNotice(rawOutput, formatBackgroundNotice(details.async.jobId))
-							: rawOutput;
-					const strippedOutput = stripOutputNotice(withoutBackground, details?.meta);
-					const withoutExit =
-						details?.exitCode === undefined
-							? strippedOutput
-							: stripTrailingNotice(strippedOutput, formatExitCodeNotice(details.exitCode));
-					const withoutWall =
-						details?.wallTimeMs === undefined
-							? withoutExit
-							: stripTrailingNotice(withoutExit, formatWallTimeNotice(details.wallTimeMs));
-					const rawOutputArtifact = stripRawOutputArtifactNotice(withoutWall);
+					const rawOutputArtifact = stripBashNotices(rawOutput, details);
 					const output = rawOutputArtifact.text;
 					const displayOutput = output.trimEnd();
 					const showingFullOutput = expanded && renderContext?.isFullOutput === true;
 
-					// Build truncation warning
-					const timeoutDisabled = details?.timeoutDisabled === true || renderContext?.timeout === 0;
-					const timeoutSeconds = timeoutDisabled ? undefined : (details?.timeoutSeconds ?? renderContext?.timeout);
-					const requestedTimeoutSeconds = details?.requestedTimeoutSeconds;
-					const wallTimeMs = details?.wallTimeMs;
-					const statsParts: string[] = [];
-					if (details?.async?.state === "running") {
-						statsParts.push(`Backgrounded: ${details.async.jobId}`);
-					}
-					if (details?.service) {
-						const service = details.service;
-						statsParts.push(`Service: ${service.name}`, `State: ${service.state}`);
-						statsParts.push(`Ready: ${service.ready ? "yes" : service.timedOut ? "timed out" : "no"}`);
-						if (service.pid !== undefined) statsParts.push(`PID: ${service.pid}`);
-					}
-					if (wallTimeMs !== undefined) {
-						statsParts.push(`Wall: ${formatWallTimeSeconds(wallTimeMs)}s`);
-					}
-					if (timeoutDisabled) {
-						statsParts.push("Timeout: disabled");
-					}
-					if (typeof timeoutSeconds === "number") {
-						statsParts.push(
-							requestedTimeoutSeconds !== undefined && requestedTimeoutSeconds !== timeoutSeconds
-								? `Timeout: ${timeoutSeconds}s (requested ${requestedTimeoutSeconds}s clamped)`
-								: `Timeout: ${timeoutSeconds}s`,
-						);
-					}
-					if (rawOutputArtifact.artifactId) {
-						statsParts.push(`Artifact: ${rawOutputArtifact.artifactId}`);
-					}
-					if (isError && typeof details?.exitCode === "number") {
-						statsParts.push(`Exit: ${details.exitCode}`);
-					}
+					const statsParts = bashStatsParts(
+						details,
+						renderContext?.timeout,
+						rawOutputArtifact.artifactId,
+						isError,
+					);
 					const timeoutLine =
 						statsParts.length > 0
 							? uiTheme.fg(
@@ -506,6 +590,53 @@ export function createShellRenderer<TArgs>(config: ShellRendererConfig<TArgs>) {
 				},
 			);
 		},
+		describeCall(args: TArgs, options: RenderResultOptions): NativeToolView {
+			const command = formatBashCommandText(toBashRenderArgs(args, config));
+			// The command shows once, in the head; the body is only the output.
+			return {
+				tool: shellToolHead(config.resolveTitle(args, options), command, undefined, false),
+				preview: { tail: BASH_DEFAULT_PREVIEW_LINES },
+			};
+		},
+
+		describeResult(
+			result: {
+				content: Array<{ type: string; text?: string }>;
+				details?: BashToolDetails;
+				isError?: boolean;
+			},
+			options: RenderResultContextOptions & { renderContext?: BashRenderContext },
+			args?: TArgs,
+		): NativeToolView {
+			const details = result.details;
+			const renderContext = options.renderContext;
+			const isError = result.isError === true;
+			const isPartial = options.isPartial === true;
+			const rawOutput = renderContext?.output ?? resultText(result);
+			const stripped = stripBashNotices(rawOutput, details);
+			const output = stripped.text.trimEnd();
+			const expanded = renderContext?.expanded ?? options.expanded;
+			const showingFullOutput = expanded && renderContext?.isFullOutput === true;
+			const command = formatBashCommandText(toBashRenderArgs(args, config));
+			const previewLines = renderContext?.previewLines ?? BASH_DEFAULT_PREVIEW_LINES;
+			// Wall time is the head timer, the timeout a note only when hit, the exit a head chip:
+			// what is left (service state, artifact, truncation) is one quiet final line.
+			const meta = details?.meta;
+			const body: NativeChild[] = compact([
+				output.trim().length > 0 &&
+					keyed(ansi(output, { follow: isPartial, role: "omp.tool.bash.output" }), "output"),
+				footnoteText(shellFootParts(details, stripped.artifactId), {
+					...meta,
+					truncation: showingFullOutput ? undefined : meta?.truncation,
+				}),
+			]);
+			return {
+				tool: shellToolHead(config.resolveTitle(args, options), command, details, !isPartial),
+				body,
+				tone: !isPartial && isError && details?.timedOut === true ? "warning" : undefined,
+				preview: { tail: previewLines },
+			};
+		},
 		mergeCallAndResult: true,
 		inline: true,
 	} satisfies ToolRenderer<TArgs, BashToolDetails>;

package/src/tools/cfg-render.ts

@@ -16,8 +16,11 @@ import {
 } from "../render/render-utils";
 import { highlightCode, type Theme } from "../theme/theme";
 import { parseCfgUrl } from "./cfg-url";
-import type { RenderResultOptions } from "./renderer";
+import type { NativeToolView, RenderResultOptions } from "./renderer";
 import { card, type CardToolResult, firstText, safe } from "./result-card";
+import { code, compact, span, text } from "../native/describe";
+import { plainText } from "../native/spans";
+import { errorView, toolHead } from "./native-view";
 
 /** Summary of a `cfg://` read, attached to read tool details. */
 export interface CfgReadDetails {
@@ -77,6 +80,68 @@ export function renderCfgRead(
 	}, options);
 }
 
+/** TSP view of `read cfg://…`: path and counts in the head, the listing as YAML. */
+export function describeCfgRead(
+	url: string,
+	result: CardToolResult | undefined,
+	details: CfgReadDetails | undefined,
+): NativeToolView {
+	const description = (details?.path ?? parseCfgUrl(url)?.segments.join(".")) || "all settings";
+	const meta: string[] = [];
+	if (details) {
+		meta.push(details.count === 1 ? "1 setting" : `${details.count} settings`);
+		if (details.modified) meta.push(`${details.modified} modified`);
+	}
+	if (result?.isError) return errorView("Config", firstText(result) || "Settings read failed.", description, ...meta);
+	const head = toolHead("Config", description, ...meta);
+	if (!result) return { head };
+	const listing = plainText(safe(firstText(result).trimEnd()));
+	return {
+		head,
+		body: listing ? [code(listing, { lang: "yaml" })] : undefined,
+		preview: { lines: PREVIEW_LIMITS.COLLAPSED_ITEMS },
+	};
+}
+
+/** TSP view of `write cfg://…[/save]`: scope/outcome in the head, then `previous → value`. */
+export function describeCfgWrite(
+	url: string,
+	content: string | undefined,
+	result: CardToolResult | undefined,
+	details: CfgWriteDetails | undefined,
+): NativeToolView {
+	const target = parseCfgUrl(url);
+	const path = details?.path ?? target?.segments.join(".");
+	const save = details?.save ?? target?.save ?? false;
+	if (result?.isError) return errorView("Config", firstText(result) || "Settings write failed.", path);
+	const head = toolHead("Config", path);
+	head.push(span(" "), span(save ? "persist" : "session", save ? "accent strong" : "muted"));
+	if (details?.outcome === "declined") head.push(span(" "), span("declined", "warning strong"));
+	if (details?.outcome === "unchanged") head.push(span(" "), span("unchanged", "muted"));
+	const next = span(plainText(details?.value ?? content?.trim() ?? "…"), "toolOutput");
+	const change = details
+		? [span(plainText(details.previous), "dim"), span(" → ", "dim"), next]
+		: [span("→ ", "dim"), next];
+	return {
+		head,
+		tone: details?.outcome === "declined" ? "warning" : undefined,
+		body: compact([
+			text(change, { wrap: "word" }),
+			details?.effective !== undefined
+				? text(
+						[
+							span(
+								`still ${plainText(details.effective)}: a higher-precedence layer overrides the saved value`,
+								"warning",
+							),
+						],
+						{ wrap: "word" },
+					)
+				: undefined,
+		]),
+	};
+}
+
 /** Render `write cfg://…[/save]`: the proposed value while pending, then the approved/declined change. */
 export function renderCfgWrite(
 	url: string,