@gavin-hu/my-pi-agent 0.8.1 → 0.10.0

package/extensions/rewind/rewind-tui.ts

@@ -9,26 +9,15 @@
  */
 
 import type { Theme } from "@earendil-works/pi-coding-agent";
-import {
-	Key,
-	matchesKey,
-	truncateToWidth,
-	type Component,
-	type TuiMouseEvent,
-	type TuiMouseEventResult,
-} from "@earendil-works/pi-tui";
-import {
-	fitRows,
-	formatRange,
-	isCloseKey,
-	ListCursor,
-	navigateList,
-	scrollList,
-	selectionMarker,
-} from "../../lib/list-cursor.ts";
-import { screenHeader, screenHint, type ViewportRowsSource } from "../../lib/tui.ts";
-import { SEPARATORS } from "../../lib/ui.ts";
-import { formatRewindDetail, formatRewindRow } from "./format.ts";
+import { Key, matchesKey, type Component, type TuiMouseEvent, type TuiMouseEventResult } from "@earendil-works/pi-tui";
+import { fitRows, formatRange, isCloseKey, ListCursor, navigateList, scrollList } from "../../lib/tui/cursor.ts";
+import { dockListFrame, screenHint, type ViewportRowsSource } from "../../lib/tui/chrome.ts";
+import { clip } from "../../lib/tui/columns.ts";
+import { SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { emptyState, listRow } from "../../lib/tui/rows.ts";
+import { titleRule } from "../../lib/tui/rules.ts";
+import { paint } from "../../lib/tui/tokens.ts";
+import { formatRewindDetail, formatRewindParts } from "./format.ts";
 import type { RewindPoint } from "./timeline.ts";
 
 export interface RewindListOptions {
@@ -43,7 +32,7 @@ export interface RewindListOptions {
 /** Rows the screen shows when the terminal height is unknown. */
 const SCREEN_DEFAULT_ITEMS = 12;
 /** Header, summary, blanks, and footer rows around the list (excluding the optional range/detail rows). */
-const SCREEN_CHROME_ROWS = 7;
+const SCREEN_CHROME_ROWS = 6;
 
 /** Selectable, scrollable timeline of prompts opened by `/rewind`. */
 export class RewindListComponent implements Component {
@@ -83,53 +72,68 @@ export class RewindListComponent implements Component {
 
 	invalidate(): void {}
 
-	// Kept off `dockListFrame`: `/rewind` leads with a blank after the header and
-	// has no blank before the hint, so the shared frame would change its output.
-	// Its blank-line convention is deliberately local.
+	// The shared dock frame, like every other list screen.
 	render(width: number): string[] {
 		const w = Math.max(1, width);
-		const lines: string[] = [screenHeader(this.theme, w, "Rewind"), ""];
+		const header = titleRule(this.theme, w, "Rewind");
 
 		if (this.points.length === 0) {
-			lines.push(truncateToWidth(`  ${this.theme.fg("dim", "No prompts on this branch yet.")}`, w));
-		} else {
-			const count = `${this.points.length} prompt${this.points.length === 1 ? "" : "s"}`;
-			lines.push(truncateToWidth(`  ${this.theme.fg("muted", `${count}${SEPARATORS.item}newest first`)}`, w));
-			lines.push("");
-			const cursor = this.cursor;
-			const focused = this.points[cursor.selected];
-			const detail = focused ? formatRewindDetail(Boolean(focused.snapshot), focused.snapshot?.id) : "";
-			cursor.visible = fitRows(
-				this.options.viewportRows,
-				this.points.length,
-				SCREEN_CHROME_ROWS + (detail ? 1 : 0),
-				SCREEN_DEFAULT_ITEMS,
-			);
-
-			const { start, end } = cursor.window(this.points.length);
-			for (let i = start; i < end; i++) {
-				const selected = i === cursor.selected;
-				const row = formatRewindRow(
-					this.points[i].summary,
-					Boolean(this.points[i].snapshot),
-					this.points[i].timestamp,
-					Date.now(),
-					Math.max(1, w - 2),
-				);
-				const body = selected ? this.theme.fg("accent", row) : this.theme.fg("muted", row);
-				lines.push(truncateToWidth(selectionMarker(this.theme, selected) + body, w));
-			}
-			if (cursor.clipped(this.points.length)) {
-				lines.push(formatRange(this.theme, w, { start, end, total: this.points.length }));
-			}
-			lines.push("");
-			if (detail) lines.push(truncateToWidth(`  ${this.theme.fg("muted", detail)}`, w));
+			return dockListFrame({
+				header,
+				body: emptyState(this.theme, w, { label: "No prompts on this branch yet." }),
+				hint: this.hint(w),
+			});
 		}
 
-		lines.push(
-			screenHint(this.theme, w, ["Esc close", { text: "Enter choose", color: "accent" }, "↑/↓ or k/j select"]),
+		const count = `${this.points.length} prompt${this.points.length === 1 ? "" : "s"}`;
+		const cursor = this.cursor;
+		const focused = this.points[cursor.selected];
+		const detail = focused ? formatRewindDetail(Boolean(focused.snapshot), focused.snapshot?.id) : "";
+		cursor.visible = fitRows(
+			this.options.viewportRows,
+			this.points.length,
+			SCREEN_CHROME_ROWS + (detail ? 1 : 0),
+			SCREEN_DEFAULT_ITEMS,
 		);
-		lines.push("");
-		return lines;
+
+		const { start, end } = cursor.window(this.points.length);
+		const body: string[] = [];
+		for (let i = start; i < end; i++) {
+			const selected = i === cursor.selected;
+			const parts = formatRewindParts(
+				this.points[i].summary,
+				Boolean(this.points[i].snapshot),
+				this.points[i].timestamp,
+				Date.now(),
+			);
+			const tone = selected ? "accent" : "meta";
+			body.push(
+				listRow(this.theme, w, {
+					selected,
+					glyph: parts.glyph,
+					glyphRole: tone,
+					label: parts.label,
+					labelRole: tone,
+					trailing: parts.trailing,
+					trailingRole: tone,
+				}),
+			);
+		}
+
+		return dockListFrame({
+			header,
+			summary: clip(`  ${paint(this.theme, "meta", `${count}${SEPARATORS.item}newest first`)}`, w),
+			body,
+			range: cursor.clipped(this.points.length)
+				? formatRange(this.theme, w, { start, end, total: this.points.length })
+				: undefined,
+			detail: detail ? [clip(`  ${paint(this.theme, "meta", detail)}`, w)] : undefined,
+			hint: this.hint(w),
+		});
+	}
+
+	/** The key-hint row, with the primary action in the accent role. */
+	private hint(width: number): string {
+		return screenHint(this.theme, width, ["Esc close", { text: "Enter choose", color: "accent" }, "↑/↓ or k/j select"]);
 	}
 }

package/extensions/rewind/snapshot-run.ts

@@ -54,7 +54,7 @@ export function createSnapshotRun(pi: ExtensionAPI, runtime: RewindRuntime): Sna
 		runAutoSnapshots = false;
 	};
 
-	const beginRun = async (prompt: string, ctx: ExtensionContext): Promise<void> => {
+	const beginRun = async (prompt: string | undefined, ctx: ExtensionContext): Promise<void> => {
 		reset();
 		pendingPrompt = summarizePrompt(prompt);
 		try {

package/extensions/rewind/status.ts

@@ -8,7 +8,8 @@
  */
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { GLYPHS, STATUS_KEYS } from "../../lib/ui.ts";
+import { GLYPHS, STATUS_KEYS } from "../../lib/tui/glyphs.ts";
+import { paint } from "../../lib/tui/tokens.ts";
 import type { RewindConfig } from "./config.ts";
 import { userMessagesFromBranch } from "./timeline.ts";
 
@@ -45,7 +46,7 @@ export function createStatusChip(deps: StatusChipDeps): StatusChip {
 			const label = `${STATUS_GLYPH} ${count}`;
 			let themed = label;
 			try {
-				themed = ctx.ui.theme.fg("accent", label);
+				themed = paint(ctx.ui.theme, "accent", label);
 			} catch {
 				// No initialized theme in a headless run.
 			}

package/extensions/subagent/README.md

@@ -10,6 +10,12 @@ pi -e .                                 # load the whole @gavin-hu/my-pi-agent p
 pi install ./                           # install the package
 ```
 
+## Tool rendering
+
+How the `subagent` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/subagent.png" alt="The subagent tool's call and result: the call line and an indented body with the two tasks, each agent's section rule, its summary, and the usage total" width="100%">
+
 ## What it does
 
 - **Isolated context.** Each subagent is a separate `pi` process with its own

package/extensions/subagent/index.ts

@@ -168,7 +168,7 @@ export default function subagent(pi: ExtensionAPI, deps: SubagentDeps = {}): voi
 		},
 
 		renderCall(args, theme, context) {
-			return renderSubagentCall(args as SubagentArgs, theme, {
+			return renderSubagentCall(args, theme, {
 				cwd: context.cwd,
 				lastComponent: context.lastComponent,
 			});

package/extensions/subagent/render.ts

@@ -12,10 +12,13 @@
 
 import { getMarkdownTheme, type Theme } from "@earendil-works/pi-coding-agent";
 import type { AgentToolResult } from "@earendil-works/pi-agent-core";
-import { Container, Markdown, Spacer, Text, type Component } from "@earendil-works/pi-tui";
+import { Container, Markdown, Spacer, Text, visibleWidth, type Component } from "@earendil-works/pi-tui";
 import { sanitizeLine, shortenPath, stripControlChars } from "../../lib/format.ts";
-import { reuseText, toolDetails } from "../../lib/tui.ts";
-import { expandHint, GLYPHS } from "../../lib/ui.ts";
+import { reuseText, toolDetails } from "../../lib/tui/chrome.ts";
+import { expandHint, GLYPHS, SEPARATORS } from "../../lib/tui/glyphs.ts";
+import { centeredRule } from "../../lib/tui/rules.ts";
+import { BODY_INDENT } from "../../lib/tui/indent.ts";
+import { paint, type TuiRole } from "../../lib/tui/tokens.ts";
 import { aggregateUsage, clip, formatToolCall, formatUsageStats } from "./format.ts";
 import { COLLAPSED_ERROR_MAX, COLLAPSED_ITEM_COUNT, COLLAPSED_TEXT_LINES, type SubagentArgs } from "./schema.ts";
 import { getFinalOutput, isFailedResult } from "./stream.ts";
@@ -24,6 +27,11 @@ import type { SingleResult, SubagentDetails } from "./types.ts";
 type DisplayItem = { type: "text"; text: string } | { type: "toolCall"; name: string; args: Record<string, unknown> };
 type ResultStatus = "running" | "aborted" | "failed" | "success";
 
+/** Columns a section rule adds around its label: a space and three dashes each side. */
+const SECTION_RULE_PAD = 8;
+/** A section rule keeps the `meta` colour the hand-rolled `─── label ───` used. */
+const SECTION_RULE_STYLE = { pad: 1, fillRole: "meta", labelRole: "meta" } as const;
+
 /** Text and tool-call parts of every assistant message, in order. */
 function getDisplayItems(messages: SingleResult["messages"]): DisplayItem[] {
 	const items: DisplayItem[] = [];
@@ -45,12 +53,12 @@ function hasExpandableContent(items: DisplayItem[]): boolean {
 	);
 }
 
-/** Colours per status; the running glyph is time-based, so it is not a value here. */
-const STATUS_COLOR: Record<ResultStatus, "warning" | "error" | "success"> = {
-	running: "warning",
-	aborted: "warning",
-	failed: "error",
-	success: "success",
+/** Design roles per status; the running glyph is time-based, so it is not a value here. */
+const STATUS_ROLE: Record<ResultStatus, TuiRole> = {
+	running: "warn",
+	aborted: "warn",
+	failed: "bad",
+	success: "ok",
 };
 
 /** Static glyphs for terminal states, from the shared narrow-glyph vocabulary. */
@@ -77,12 +85,12 @@ function resultStatus(result: SingleResult, isPartial = false): ResultStatus {
 }
 
 function statusIcon(status: ResultStatus, theme: Theme, now: number): string {
-	return theme.fg(STATUS_COLOR[status], statusGlyph(status, now));
+	return paint(theme, STATUS_ROLE[status], statusGlyph(status, now));
 }
 
-/** The color the status uses, so the `[stopReason]` bracket matches its icon. */
-function statusColor(status: ResultStatus): "warning" | "error" | "success" {
-	return STATUS_COLOR[status];
+/** The role the status uses, so the `[stopReason]` bracket matches its icon. */
+function statusRole(status: ResultStatus): TuiRole {
+	return STATUS_ROLE[status];
 }
 
 /** The message a failed/aborted result should show, falling back to stderr. */
@@ -99,7 +107,7 @@ function renderError(result: SingleResult, status: ResultStatus, theme: Theme, m
 	const detail = errorDetail(result, status, max);
 	if (!detail) return undefined;
 	const label = status === "aborted" ? "Aborted" : "Error";
-	return theme.fg(status === "aborted" ? "warning" : "error", `${label}: ${detail}`);
+	return paint(theme, status === "aborted" ? "warn" : "bad", `${label}: ${detail}`);
 }
 
 /** Whether the collapsed error/stderr text is truncated, so expanding shows more. */
@@ -114,7 +122,7 @@ function hasClippedError(result: SingleResult, status: ResultStatus): boolean {
 function collapsedBody(result: SingleResult, status: ResultStatus, items: DisplayItem[], theme: Theme): string {
 	const error = renderError(result, status, theme, COLLAPSED_ERROR_MAX);
 	if (error) return error;
-	if (items.length === 0) return theme.fg("muted", status === "running" ? "(running…)" : "(no output)");
+	if (items.length === 0) return paint(theme, "meta", status === "running" ? "(running…)" : "(no output)");
 	return renderDisplayItems(items, theme, COLLAPSED_ITEM_COUNT);
 }
 
@@ -164,11 +172,11 @@ function durationSuffix(result: SingleResult, status: ResultStatus, now: number)
 function statusSuffix(result: SingleResult, status: ResultStatus, theme: Theme, now: number): string {
 	let suffix = "";
 	const duration = durationSuffix(result, status, now);
-	if (duration) suffix += theme.fg("dim", duration);
+	if (duration) suffix += paint(theme, "faint", duration);
 	const showReason = status === "failed" || status === "aborted";
 	const stop = showReason && result.stopReason && result.stopReason !== "end" ? result.stopReason : undefined;
 	const reason = stop ?? (status === "failed" ? `exit ${result.exitCode}` : undefined);
-	if (reason) suffix += ` ${theme.fg(statusColor(status), `[${reason}]`)}`;
+	if (reason) suffix += ` ${paint(theme, statusRole(status), `[${reason}]`)}`;
 	return suffix;
 }
 
@@ -180,20 +188,21 @@ function resultHeader(
 	stepPrefix: string,
 	now: number,
 ): string {
-	let header = `${statusIcon(status, theme, now)} ${theme.fg("toolTitle", theme.bold(sanitizeLine(result.agent)))}`;
+	let header = `${statusIcon(status, theme, now)} ${paint(theme, "accent", theme.bold(sanitizeLine(result.agent)))}`;
 	if (result.agentSource && result.agentSource !== "builtin" && result.agentSource !== "unknown") {
-		header += theme.fg("dim", ` [${sanitizeLine(result.agentSource)}]`);
+		header += paint(theme, "faint", ` [${sanitizeLine(result.agentSource)}]`);
 	}
-	if (result.step) header = `${theme.fg("muted", `${stepPrefix} ${result.step} `)}` + header;
+	if (result.step) header = `${paint(theme, "meta", `${stepPrefix} ${result.step} `)}` + header;
 	return header + statusSuffix(result, status, theme, now);
 }
 
-/** Prefix each line of intermediate assistant text with a muted gutter. */
-function quoteLines(text: string, theme: Theme): string {
+/** Prefix each line of intermediate assistant text with the block's body indent. */
+function indentBody(text: string, theme: Theme): string {
+	const indent = " ".repeat(BODY_INDENT);
 	return stripControlChars(text)
 		.trim()
 		.split("\n")
-		.map((line) => theme.fg("muted", "│ ") + theme.fg("toolOutput", line))
+		.map((line) => indent + theme.fg("toolOutput", line))
 		.join("\n");
 }
 
@@ -201,14 +210,14 @@ function renderDisplayItems(items: DisplayItem[], theme: Theme, limit?: number,
 	const shown = limit ? items.slice(-limit) : items;
 	const skipped = limit && items.length > limit ? items.length - limit : 0;
 	const lines: string[] = [];
-	if (skipped > 0) lines.push(theme.fg("muted", `… ${skipped} earlier items`));
+	if (skipped > 0) lines.push(paint(theme, "meta", `… ${skipped} earlier items`));
 	for (const item of shown) {
 		if (item.type === "text") {
 			const safe = stripControlChars(item.text);
 			const text = preview ? safe.split("\n").slice(0, COLLAPSED_TEXT_LINES).join("\n") : safe;
 			lines.push(theme.fg("toolOutput", text));
 		} else {
-			lines.push(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme, preview));
+			lines.push(paint(theme, "meta", "→ ") + formatToolCall(item.name, item.args, theme, preview));
 		}
 	}
 	return lines.join("\n");
@@ -226,45 +235,72 @@ export interface SubagentCallContext {
 	lastComponent?: Component;
 }
 
+/**
+ * The call's arguments as Pi hands them to `renderCall`. While the model streams
+ * a call, a field can still be missing, or arrive with a type the schema will
+ * later reject, so the call line reads every one defensively and never throws: a
+ * throwing renderer makes Pi fall back to its own generic call line.
+ */
+export type StreamedSubagentArgs = Partial<Record<keyof SubagentArgs, unknown>>;
+
+/** One field of a partially-streamed element, or undefined when it has not arrived. */
+function streamedText(element: unknown, key: "agent" | "task" | "cwd"): string | undefined {
+	if (typeof element !== "object" || element === null) return undefined;
+	const value = (element as Record<string, unknown>)[key];
+	return typeof value === "string" ? value : undefined;
+}
+
 /** Preview the requested mode and its agents, reusing the slot's `Text`. */
-export function renderSubagentCall(args: SubagentArgs, theme: Theme, context?: SubagentCallContext): Component {
+export function renderSubagentCall(
+	args: StreamedSubagentArgs | undefined,
+	theme: Theme,
+	context?: SubagentCallContext,
+): Component {
 	const text = reuseText(context?.lastComponent);
-	text.setText(callText(args, theme, context));
+	text.setText(callText(args ?? {}, theme, context));
 	return text;
 }
 
-/** The call-line string for the requested mode. */
-function callText(args: SubagentArgs, theme: Theme, context?: { cwd?: string }): string {
-	const title = theme.fg("toolTitle", theme.bold("subagent ")) + (args.readOnly ? theme.fg("dim", "read-only ") : "");
-	const cwdNote = (cwd?: string) => {
-		if (!cwd || cwd === context?.cwd) return "";
-		return theme.fg("dim", `  in ${shortenPath(cwd)}`);
+/**
+ * The call-line string for the requested mode. Continuation lines carry no
+ * indent of their own: the tool-block frame headlines the first line and
+ * indents the rest by `BODY_INDENT`.
+ */
+function callText(args: StreamedSubagentArgs, theme: Theme, context?: { cwd?: string }): string {
+	const title =
+		theme.fg("toolTitle", theme.bold("subagent ")) + (args.readOnly ? paint(theme, "faint", "read-only ") : "");
+	const cwdNote = (cwd?: unknown) => {
+		if (typeof cwd !== "string" || !cwd || cwd === context?.cwd) return "";
+		return paint(theme, "faint", `  in ${shortenPath(cwd)}`);
 	};
-
-	if (args.chain && args.chain.length > 0) {
-		let text = title + theme.fg("accent", `chain · ${args.chain.length} step${args.chain.length > 1 ? "s" : ""}`);
-		for (let i = 0; i < Math.min(args.chain.length, 3); i++) {
-			const step = args.chain[i];
-			const clean = sanitizeLine(step.task.replace(/\{previous\}/g, ""));
-			text += `\n  ${theme.fg("muted", `${i + 1}.`)} ${theme.fg("accent", sanitizeLine(step.agent))}${theme.fg("dim", ` ${clip(clean, 40)}`)}${cwdNote(step.cwd)}`;
+	const chain = Array.isArray(args.chain) ? args.chain : [];
+	if (chain.length > 0) {
+		let text =
+			title + paint(theme, "label", `chain${SEPARATORS.item}${chain.length} step${chain.length > 1 ? "s" : ""}`);
+		for (let i = 0; i < Math.min(chain.length, 3); i++) {
+			const step = chain[i];
+			const task = (streamedText(step, "task") ?? "…").replace(/\{previous\}/g, "");
+			text += `\n${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "label", sanitizeLine(streamedText(step, "agent") || "…"))}${paint(theme, "meta", ` ${clip(sanitizeLine(task), 40)}`)}${cwdNote(streamedText(step, "cwd"))}`;
 		}
-		if (args.chain.length > 3) text += `\n  ${theme.fg("muted", `… +${args.chain.length - 3} more`)}`;
+		if (chain.length > 3) text += `\n${paint(theme, "meta", `… +${chain.length - 3} more`)}`;
 		return text;
 	}
 
-	if (args.tasks && args.tasks.length > 0) {
-		let text = title + theme.fg("accent", `parallel · ${args.tasks.length} task${args.tasks.length > 1 ? "s" : ""}`);
-		for (let i = 0; i < Math.min(args.tasks.length, 3); i++) {
-			const task = args.tasks[i];
-			text += `\n  ${theme.fg("muted", `${i + 1}.`)} ${theme.fg("accent", sanitizeLine(task.agent))}${theme.fg("dim", ` ${clip(sanitizeLine(task.task), 40)}`)}${cwdNote(task.cwd)}`;
+	const tasks = Array.isArray(args.tasks) ? args.tasks : [];
+	if (tasks.length > 0) {
+		let text =
+			title + paint(theme, "label", `parallel${SEPARATORS.item}${tasks.length} task${tasks.length > 1 ? "s" : ""}`);
+		for (let i = 0; i < Math.min(tasks.length, 3); i++) {
+			const task = tasks[i];
+			text += `\n${paint(theme, "meta", `${i + 1}.`)} ${paint(theme, "label", sanitizeLine(streamedText(task, "agent") || "…"))}${paint(theme, "meta", ` ${clip(sanitizeLine(streamedText(task, "task") ?? "…"), 40)}`)}${cwdNote(streamedText(task, "cwd"))}`;
 		}
-		if (args.tasks.length > 3) text += `\n  ${theme.fg("muted", `… +${args.tasks.length - 3} more`)}`;
+		if (tasks.length > 3) text += `\n${paint(theme, "meta", `… +${tasks.length - 3} more`)}`;
 		return text;
 	}
 
-	const agentName = sanitizeLine(args.agent || "…");
-	let text = title + theme.fg("accent", agentName) + cwdNote(args.cwd);
-	text += `\n  ${theme.fg("dim", clip(sanitizeLine(args.task ?? "…"), 60))}`;
+	const agentName = sanitizeLine(streamedText(args, "agent") || "…");
+	let text = title + paint(theme, "label", agentName) + cwdNote(streamedText(args, "cwd"));
+	text += `\n${paint(theme, "meta", clip(sanitizeLine(streamedText(args, "task") ?? "…"), 60))}`;
 	return text;
 }
 
@@ -283,8 +319,10 @@ function addExpandedResult(
 	if (error) container.addChild(new Text(error, 0, 0));
 
 	container.addChild(new Spacer(1));
-	container.addChild(new Text(theme.fg("muted", "─── Task ───"), 0, 0));
-	container.addChild(new Text(theme.fg("dim", stripControlChars(result.taskTemplate ?? result.task)), 0, 0));
+	container.addChild(
+		new Text(centeredRule(theme, visibleWidth("Task") + SECTION_RULE_PAD, "Task", SECTION_RULE_STYLE), 0, 0),
+	);
+	container.addChild(new Text(paint(theme, "faint", stripControlChars(result.taskTemplate ?? result.task)), 0, 0));
 
 	const displayItems = getDisplayItems(result.messages);
 	const lastItem = displayItems[displayItems.length - 1];
@@ -294,14 +332,18 @@ function addExpandedResult(
 	// order and do not surface a stale earlier message as the answer.
 	const trailingOutput = lastItem?.type === "text" && lastItem.text === finalOutput ? lastItem.text : "";
 	container.addChild(new Spacer(1));
-	container.addChild(new Text(theme.fg("muted", "─── Output ───"), 0, 0));
+	container.addChild(
+		new Text(centeredRule(theme, visibleWidth("Output") + SECTION_RULE_PAD, "Output", SECTION_RULE_STYLE), 0, 0),
+	);
 	let renderedOutput = false;
 	for (const item of displayItems) {
 		if (item.type === "toolCall") {
-			container.addChild(new Text(theme.fg("muted", "→ ") + formatToolCall(item.name, item.args, theme, false), 0, 0));
+			container.addChild(
+				new Text(paint(theme, "meta", "→ ") + formatToolCall(item.name, item.args, theme, false), 0, 0),
+			);
 			renderedOutput = true;
 		} else if (item.text.trim() && item.text !== trailingOutput) {
-			container.addChild(new Text(quoteLines(item.text, theme), 0, 0));
+			container.addChild(new Text(indentBody(item.text, theme), 0, 0));
 			renderedOutput = true;
 		}
 	}
@@ -311,13 +353,13 @@ function addExpandedResult(
 		renderedOutput = true;
 	}
 	if (!renderedOutput) {
-		container.addChild(new Text(theme.fg("muted", status === "running" ? "(running…)" : "(no output)"), 0, 0));
+		container.addChild(new Text(paint(theme, "meta", status === "running" ? "(running…)" : "(no output)"), 0, 0));
 	}
 
 	const usage = usageLine(result);
 	if (usage) {
 		container.addChild(new Spacer(1));
-		container.addChild(new Text(theme.fg("dim", usage), 0, 0));
+		container.addChild(new Text(paint(theme, "faint", usage), 0, 0));
 	}
 }
 
@@ -333,7 +375,7 @@ function collapsedSingleText(result: SingleResult, theme: Theme, isPartial: bool
 	text += `\n\n${collapsedBody(result, status, displayItems, theme)}`;
 	if (isExpandable(result, status, displayItems)) text += `\n${expandHint(theme)}`;
 	const usage = usageLine(result);
-	if (usage) text += `\n${theme.fg("dim", usage)}`;
+	if (usage) text += `\n${paint(theme, "faint", usage)}`;
 	return text;
 }
 
@@ -375,11 +417,11 @@ function multiHeader(details: SubagentDetails, theme: Theme, now: number): strin
 	const bad = failed + aborted;
 	const icon =
 		running > 0
-			? theme.fg("warning", statusGlyph("running", now))
+			? paint(theme, "warn", statusGlyph("running", now))
 			: bad > 0
-				? theme.fg(bad === total ? "error" : "warning", bad === total ? GLYPHS.jobsFailure : GLYPHS.half)
-				: theme.fg("success", GLYPHS.check);
-	return `${icon} ${theme.fg("toolTitle", theme.bold(`${details.mode} · `))}${theme.fg("accent", status)}`;
+				? paint(theme, bad === total ? "bad" : "warn", bad === total ? GLYPHS.jobsFailure : GLYPHS.half)
+				: paint(theme, "ok", GLYPHS.check);
+	return `${icon} ${theme.fg("toolTitle", theme.bold(`${details.mode} · `))}${paint(theme, "accent", status)}`;
 }
 
 function collapsedMultiText(details: SubagentDetails, theme: Theme, now: number): string {
@@ -394,14 +436,14 @@ function collapsedMultiText(details: SubagentDetails, theme: Theme, now: number)
 		const displayItems = getDisplayItems(result.messages);
 		if (isExpandable(result, status, displayItems)) hasHidden = true;
 		const taskText = result.taskTemplate ?? result.task;
-		const taskNote = taskText ? theme.fg("dim", ` ${clip(sanitizeLine(taskText), 50)}`) : "";
-		text += `\n\n${theme.fg("muted", "─── ")}${theme.fg("accent", resultLabel(result, i))}${taskNote} ${statusIcon(status, theme, now)}`;
+		const taskNote = taskText ? paint(theme, "faint", ` ${clip(sanitizeLine(taskText), 50)}`) : "";
+		text += `\n\n${paint(theme, "meta", "─── ")}${paint(theme, "accent", resultLabel(result, i))}${taskNote} ${statusIcon(status, theme, now)}`;
 		text += statusSuffix(result, status, theme, now);
 		text += `\n${collapsedBody(result, status, displayItems, theme)}`;
 	}
 	if (running === 0) {
 		const usage = totalUsageLine(results);
-		if (usage) text += `\n\n${theme.fg("dim", `Total: ${usage}`)}`;
+		if (usage) text += `\n\n${paint(theme, "faint", `Total: ${usage}`)}`;
 	}
 	if (running > 0 || hasHidden) text += `\n${expandHint(theme)}`;
 	return text;
@@ -421,7 +463,7 @@ function fillExpandedMulti(container: Container, details: SubagentDetails, theme
 		const usage = totalUsageLine(details.results);
 		if (usage) {
 			container.addChild(new Spacer(1));
-			container.addChild(new Text(theme.fg("dim", `Total: ${usage}`), 0, 0));
+			container.addChild(new Text(paint(theme, "faint", `Total: ${usage}`), 0, 0));
 		}
 	}
 }

package/extensions/todo/README.md

@@ -8,12 +8,20 @@ about to end after mutating work without a todo update, the extension injects
 one short reminder and forces a continuation, so the list does not silently
 drift behind the work.
 
+<img src="../../assets/todo.png" alt="The /todos screen: a Todos title rule, a 3/7 completed summary, and the list with check, spinner, and circle glyphs" width="100%">
+
 ```
 pi --extension ./extensions/todo    # load just this extension
 pi -e .                             # load the whole @gavin-hu/my-pi-agent package
 pi install ./                       # install the package
 ```
 
+## Tool rendering
+
+How the `todo` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/todo.png" alt="The todo tool's result: the call line and an indented body with the progress line and the task rows below it, each led by a check, spinner, or circle glyph" width="100%">
+
 ## What it does
 
 - Registers one model-callable tool, `todo`, that **replaces** the task list.
@@ -49,22 +57,20 @@ Todos · 1/3 · Writing the tests
 `/todos` is the expanded view and keeps the model's list order (use it to see
 the plan as written).
 
-In the transcript, the call line pairs progress with the active item
-(`todo → 1/4 · Writing tests`), and the result keeps the shared
-`✓` / `◒` / `◌` rail used by the goal result, separated from the call line by a
-blank line. Collapsed, it leads with active work; expanded, it keeps the
-submitted order:
+In the transcript, the call line carries progress only (`todo → 1/4`); the
+result keeps the `✓` / `◒` / `◌` rows, directly under the call line. The item
+text lives on the rows, so the call line never repeats it. Collapsed, it leads
+with active work; expanded, it keeps the submitted order:
 
 ```
-todo → 1/4 · Writing tests
-
+todo → 1/4
   ◒ Writing tests
   ◌ Ship it
   ◌ Write docs
   ✓ Write schema
 ```
 
-Progress lives on the call line, so the rail has no footer; the persistent
+Progress lives on the call line, so the rows have no footer; the persistent
 widget and `/todos` still show the count. A capped collapsed rail ends with
 `… N more` and the `app.tools.expand` hint.
 
@@ -204,10 +210,11 @@ depends on config.
   widget is a single line (`currentTodo` picks the `in_progress` item, else the
   first pending); `/todos` keeps the submitted order, and the transcript result
   orders by status via `compareByActivity` so active work is never hidden. The
-  transcript result draws the same indented glyph rail as the goal result
-  (`BODY_INDENT` / `GLYPH_GAP` from [`lib/ui.ts`](../../lib/ui.ts)), wrapping
-  long items with continuation rows aligned under the text. Progress lives on
-  the call line, so the rail carries no footer.
+  transcript result draws the glyph rows at the block's body indent (the frame
+  supplies `BODY_INDENT`; `GLYPH_GAP` comes from
+  [`lib/tui/glyphs.ts`](../../lib/tui/glyphs.ts)), wrapping long items with
+  continuation rows aligned under the text. Progress lives on the call line, so
+  the rows carry no footer.
 - **The transcript reuses its components.** `renderCall` reuses the slot's
   `Text`, and `renderResult` reuses the `TodoResult` view via
   `context.lastComponent`, updating each in place instead of allocating on every
@@ -223,7 +230,7 @@ depends on config.
 | `state.ts` | Branch reconstruction and status queries (pure). |
 | `nudge.ts` | Lag detection: mutating-tool classification, due check, reminder text (pure). |
 | `format.ts` | Model-facing and transcript text (pure). |
-| `tui.ts` | Widget and scrollable `/todos` components. |
+| `tui.ts` | Widget and scrollable `/todos` components, drawn from the `lib/tui/` kit (`titleRule`, `dockListFrame`, `listRow`, `emptyState`). |
 | `config.ts` | Widget config load/validation (the `todo` section of `bytefly.json`). |
 | `runtime.ts` | Session-scoped state, lag tracking, and widget synchronization. |
 | `tools.ts` | `todo` tool registration and rendering. |