@iowarp/clio-coder 0.3.1 → 0.3.3

package/src/interactive/renderers/tool-execution.ts

@@ -13,11 +13,16 @@
  */
 
 import { sanitizeCallTargetText } from "../../domains/safety/call-target.js";
+import { formatSize } from "../../engine/truncate.js";
 import { visibleWidth, wrapTextWithAnsi } from "../../engine/tui.js";
+import { classifyResourceRead, toolPresentationPolicy } from "../../tools/presentation.js";
+import type { ApprovalRequestView } from "../permission-overlay.js";
 import { clioTheme, formatCompactMs, GLYPH } from "../theme/index.js";
-import { type DiffRenderInput, renderUnifiedDiff } from "./diff.js";
+import { renderDiffLines } from "./diff.js";
 import { tryRenderJson, tryRenderXml } from "./structured.js";
 
+export { classifyResourceRead };
+
 const theme = clioTheme();
 const dim = (text: string): string => theme.fg("dim", text);
 const red = (text: string): string => theme.fg("error", text);
@@ -34,11 +39,12 @@ const BODY_INDENT_VISIBLE_WIDTH = 2;
 const HEADER_PREFIX_PLAIN = "▸ ";
 const ARG_PREVIEW_LIMIT = 60;
 const WEB_FETCH_ARG_PREVIEW_LIMIT = 140;
-const RESULT_PREVIEW_LIMIT = 4000;
 const FULL_RESULT_PREVIEW_LIMIT = 60_000;
 const FULL_RESULT_ROW_LIMIT = 120;
 const STREAMING_RESULT_ROW_LIMIT = 20;
 const ARGS_BODY_LINE_LIMIT = 24;
+/** Rows of mutation diff a folded edit/write row keeps visible before it defers to the body. */
+const FOLDED_DIFF_ROW_LIMIT = 24;
 const STATUS_OK_GLYPH = GLYPH.ok;
 const STATUS_ERROR_GLYPH = GLYPH.error;
 
@@ -54,6 +60,8 @@ export interface ToolExecutionStart {
 	args: unknown;
 	/** Live elapsed time supplied by the panel for running segments. */
 	elapsedMs?: number | undefined;
+	/** Pi may stream a tool call's arguments before execution starts. */
+	phase?: "forming" | "ready" | "running" | undefined;
 }
 
 export interface ToolExecutionFinished {
@@ -73,6 +81,10 @@ export interface ToolExecutionFinished {
 	 * model reading the same transcript, to guess at the rule.
 	 */
 	blockReason?: string | undefined;
+	/** Structured exit status when the caller has one; text parsing is legacy fallback only. */
+	exitCode?: number | string | null | undefined;
+	/** Local `!!` bash output is visible to the operator but excluded from model context. */
+	excludeFromContext?: boolean | undefined;
 }
 
 export interface ToolBodyRenderOptions {
@@ -83,6 +95,8 @@ export interface ToolBodyRenderOptions {
 	 * the complete tool output the model actually received.
 	 */
 	unbounded?: boolean;
+	/** Live rows color mutation diffs; replay and export deliberately use plain text. */
+	diffStyle?: "color" | "plain";
 }
 
 /** Row cap for a tool body: unbounded lifts both the row and char limits. */
@@ -218,10 +232,9 @@ function bashExitCodeFromResult(result: unknown): string | null {
 
 /**
  * Map of known tools to their canonical "primary" arg field. When the arg is
- * a string the header summarises it directly and the args body is suppressed
- * because echoing `{"path": "..."}` next to `tool: read(...)` is duplicate
- * noise. Tools not in this map (or with an unexpected arg shape) fall back
- * to a JSON-dump summary plus the full args body.
+ * a string the header summarises it directly and the expanded argument list
+ * omits only that repeated field. Tools not in this map (or with an unexpected
+ * arg shape) fall back to a JSON summary plus their complete redacted fields.
  */
 const PRIMARY_ARG_FIELD: Record<string, string> = {
 	read: "path",
@@ -244,8 +257,8 @@ const PRIMARY_ARG_FIELD: Record<string, string> = {
 
 /**
  * Returns the captured primary-arg string when the header successfully used a
- * known tool's canonical arg, otherwise null. Drives the args-body suppression
- * so `tool: read(README.md)` does not get followed by `{"path": "README.md"}`.
+ * known tool's canonical arg, otherwise null. The argument renderer uses the
+ * same map to omit that one repeated field below `read(README.md)`.
  */
 function capturedPrimaryArg(toolName: string, args: unknown): string | null {
 	const field = PRIMARY_ARG_FIELD[toolName];
@@ -278,24 +291,6 @@ function summarizeArgs(toolName: string, args: unknown): string {
 	return truncate(jsonStringifySafe(safeArgs), ARG_PREVIEW_LIMIT);
 }
 
-/**
- * Compact resource-read classification. Reads of skill/handbook/agent
- * instruction files and docs pages collapse to one labeled line and never
- * auto-expand; their bodies are reference material, not task output.
- */
-export function classifyResourceRead(toolName: string, args: unknown): string | null {
-	if (toolName !== "read") return null;
-	const path = readStringField(args, "path");
-	if (path === null) return null;
-	const normalized = path.replace(/\\/g, "/");
-	const base = normalized.split("/").pop() ?? "";
-	if (base === "SKILL.md") return "skill";
-	if (base === "CLIO-CODER.md") return "handbook";
-	if (base === "AGENTS.md") return "agents";
-	if (/(^|\/)docs\//.test(normalized)) return "docs";
-	return null;
-}
-
 function detailsOf(result: unknown): Record<string, unknown> | null {
 	if (!isPlainObject(result)) return null;
 	return isPlainObject(result.details) ? result.details : null;
@@ -318,12 +313,6 @@ function stringField(record: Record<string, unknown> | null, key: string): strin
 	return typeof value === "string" && value.length > 0 ? value : null;
 }
 
-function formatBytes(bytes: number): string {
-	if (bytes < 1024) return `${bytes}B`;
-	if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-	return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
 function countSummary(observation: Record<string, unknown>): string | null {
 	const unit = stringField(observation, "unit") ?? "results";
 	const shown = numberField(observation, "shownCount");
@@ -396,9 +385,46 @@ function shownBytesOf(finished: ToolExecutionFinished): number | null {
 	const observation = observationOf(finished);
 	const fromObservation = numberField(observation, "shownBytes");
 	if (fromObservation !== null) return fromObservation;
+	const resultSize = detailsOf(finished.result)?.resultSize;
+	const fromResultSize = isPlainObject(resultSize) ? numberField(resultSize, "shownBytes") : null;
+	if (fromResultSize !== null) return fromResultSize;
 	return numberField(finished.resultSummary ?? null, "bytes");
 }
 
+function totalBytesOf(finished: ToolExecutionFinished): number | null {
+	const observation = observationOf(finished);
+	const fromObservation = numberField(observation, "totalBytes");
+	if (fromObservation !== null) return fromObservation;
+	const resultSize = detailsOf(finished.result)?.resultSize;
+	if (isPlainObject(resultSize)) {
+		const total = numberField(resultSize, "bytes");
+		if (total !== null) return total;
+	}
+	return shownBytesOf(finished);
+}
+
+function resultSizeOf(finished: ToolExecutionFinished): Record<string, unknown> | null {
+	const value = detailsOf(finished.result)?.resultSize;
+	return isPlainObject(value) ? value : null;
+}
+
+function isTruncatedResult(finished: ToolExecutionFinished): boolean {
+	const observation = observationOf(finished);
+	if (observation?.truncated === true) return true;
+	if (resultSizeOf(finished)?.truncated === true) return true;
+	const truncation = detailsOf(finished.result)?.truncation;
+	if (isPlainObject(truncation) && truncation.truncated === true) return true;
+	return finished.resultSummary?.truncated === true;
+}
+
+function structuredExitCode(finished: ToolExecutionFinished): string | null {
+	if (isNonExecutedOutcome(finished.outcome)) return null;
+	if (finished.exitCode !== undefined && finished.exitCode !== null) return String(finished.exitCode);
+	const exitCode = detailsOf(finished.result)?.exitCode;
+	if (typeof exitCode === "number" || typeof exitCode === "string") return String(exitCode);
+	return finished.toolName === "bash" && finished.isError ? bashExitCodeFromResult(finished.result) : null;
+}
+
 /**
  * The dim ledger tail appended to a finished collapsed subline: outcome facts,
  * then byte size (duration rides on the status glyph), then the offload path
@@ -409,15 +435,58 @@ function ledgerTail(finished: ToolExecutionFinished): { facts: string; offload:
 	const parts: string[] = [];
 	const outcome = outcomeSummary(finished);
 	if (outcome !== null) parts.push(outcome);
-	const bytes = isNonExecutedOutcome(finished.outcome) ? null : shownBytesOf(finished);
-	if (bytes !== null && bytes > 0) parts.push(formatBytes(bytes));
-	const offloadPath = offloadPathOf(finished);
+	const executed = !isNonExecutedOutcome(finished.outcome);
+	// A folded bash row is the only view of the call the operator gets by
+	// default, so its settlement facts have to be here rather than only in the
+	// expanded body. A failed row already carries `(exit N)` on the status glyph.
+	if (executed && finished.toolName === "bash" && !finished.isError) {
+		parts.push(`exit ${structuredExitCode(finished) ?? "0"}`);
+	}
+	const bytes = executed ? shownBytesOf(finished) : null;
+	if (bytes !== null && bytes > 0) {
+		const total = totalBytesOf(finished);
+		parts.push(
+			total !== null && total > bytes ? `${formatSize(bytes)} shown / ${formatSize(total)} total` : formatSize(bytes),
+		);
+	}
+	if (executed) {
+		if (isTruncatedResult(finished)) parts.push("truncated");
+		const details = detailsOf(finished.result);
+		if (details?.timedOut === true) parts.push("timed out");
+		if (details?.outputCapped === true) parts.push("output capped");
+	}
+	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	const offloadPath = executed ? offloadPathOf(finished) : null;
 	return {
 		facts: parts.length > 0 ? dim(` · ${parts.join(" · ")}`) : "",
 		offload: offloadPath !== null ? dim(` · full: ${offloadPath}`) : "",
 	};
 }
 
+/** Longest diagnostic excerpt a folded failure row may carry. */
+const FAILURE_EXCERPT_LIMIT = 80;
+
+/**
+ * Last non-empty output line of a failed call, bounded so the folded row stays
+ * diagnostically useful without opening the body. Sanitized to one line: the
+ * source is raw tool output. The tool's presentation policy decides whether
+ * its failures carry one; the renderer never names a tool here.
+ */
+function failureExcerpt(finished: ToolExecutionFinished, width: number): string {
+	if (!finished.isError || !toolPresentationPolicy(finished.toolName, finished.args).failureExcerpt) return "";
+	if (isNonExecutedOutcome(finished.outcome)) return "";
+	const text = unwrapResultEnvelope(finished.result);
+	if (typeof text !== "string") return "";
+	let excerpt: string | undefined;
+	for (const raw of text.split("\n")) {
+		const line = sanitizeCallTargetText(raw).trim();
+		if (line.length > 0) excerpt = line;
+	}
+	if (excerpt === undefined) return "";
+	const limit = Math.min(FAILURE_EXCERPT_LIMIT, Math.max(20, width - 20));
+	return dim(` · ${truncate(excerpt, limit)}`);
+}
+
 /**
  * Marker for a call parked at admission awaiting operator approval. Rendered
  * in place of the elapsed counter so a parked call never reads as executing
@@ -430,24 +499,40 @@ const AWAITING_APPROVAL_TAIL = ` ${yellow(GLYPH.phaseBlocked)}${dim(" awaiting a
  * No elapsed counter (nothing is running) and no status glyph (nothing has
  * finished): the awaiting-approval tail is the segment's whole state.
  */
-export function renderToolAwaitingApproval(call: ToolExecutionStart, width: number): string[] {
+export function renderToolAwaitingApproval(
+	call: ToolExecutionStart,
+	width: number,
+	view?: ApprovalRequestView,
+): string[] {
 	const parts = sublineParts({ toolCallId: call.toolCallId, toolName: call.toolName, args: call.args }, undefined, {});
-	return wrapSublineWithTail(parts.lead, AWAITING_APPROVAL_TAIL, width);
+	const lines = wrapSublineWithTail(parts.lead, AWAITING_APPROVAL_TAIL, width);
+	if (view === undefined) return lines;
+	const axis = view.axis.kind === "net" ? `safety-net rail ${view.axis.ruleId}` : `autonomy level ${view.axis.level}`;
+	const facts = [
+		["action", view.actionClass],
+		["axis", axis],
+		...(view.target !== undefined && view.target.length > 0 ? [["target", view.target]] : []),
+	] as const;
+	for (const [label, value] of facts) {
+		lines.push(...indentAndWrap(`${dim(`${label} ·`)} ${value}`, width, false));
+	}
+	return lines;
 }
 
 /**
- * Header status: `undefined` when the call is still in flight (no glyph),
- * `"ok"` for success (green check), `"error"` for failure (red cross). The
+ * Header status follows Pi's call lifecycle before and during execution, then
+ * becomes `"ok"` or `"error"` at settlement. The
  * glyph hangs off the right of the header line so the tool name + args read
  * left-to-right without extra punctuation.
  */
-type HeaderStatus = "ok" | "error" | undefined;
+type HeaderStatus = "forming" | "ready" | "running" | "ok" | "error" | undefined;
 
 /** Keeps a refusal reason to one scannable clause on the status tail. */
 const BLOCK_REASON_LIMIT = 72;
 
 interface StatusMeta {
 	durationMs?: number | undefined;
+	elapsedMs?: number | undefined;
 	exitCode?: string | null;
 	outcome?: ToolExecutionFinished["outcome"];
 	/** Refusal reason, rendered only alongside a non-executed outcome. */
@@ -456,6 +541,12 @@ interface StatusMeta {
 
 function statusGlyph(status: HeaderStatus, meta: StatusMeta = {}): string {
 	if (status === undefined) return "";
+	if (status === "forming") return ` ${dim(GLYPH.queued)}${dim(" forming call")}`;
+	if (status === "ready") return ` ${dim(GLYPH.queued)}${dim(" ready")}`;
+	if (status === "running") {
+		const elapsed = optionalCompactMs(meta.elapsedMs);
+		return ` ${cyan(GLYPH.running)}${dim(elapsed === null ? " running" : ` running · ${elapsed}`)}`;
+	}
 	const duration = optionalCompactMs(meta.durationMs);
 	const durationSuffix = duration ? dim(` · ${duration}`) : "";
 	if (status === "ok") return ` ${green(STATUS_OK_GLYPH)}${durationSuffix}`;
@@ -470,8 +561,8 @@ function statusGlyph(status: HeaderStatus, meta: StatusMeta = {}): string {
 }
 
 function headerLine(toolName: string, args: unknown, status: HeaderStatus, meta: StatusMeta = {}): string {
-	const summary = summarizeArgs(toolName, args);
-	const head = `${dim(HEADER_PREFIX_PLAIN)}${cyanBold(toolName)}${dim("(")}${cyan(summary)}${dim(")")}`;
+	const body = styleSublineBody(buildSublineBody(toolName, args, status, undefined, meta.outcome));
+	const head = `${dim(HEADER_PREFIX_PLAIN)}${body}`;
 	return `${head}${statusGlyph(status, meta)}`;
 }
 
@@ -485,8 +576,9 @@ function styleSublineBody(body: string): string {
 	return sublineLead(match.groups.lead, match.groups.rest);
 }
 
-function buildUnknownToolBody(toolName: string, args: unknown): string {
-	return `${toolName}(${summarizeArgs(toolName, args)})`;
+function buildGenericToolBody(toolName: string, args: unknown): string {
+	const summary = summarizeArgs(toolName, args);
+	return summary.length > 0 ? `tool action ${summary}` : "tool action";
 }
 
 function buildFieldSublineBody(
@@ -543,6 +635,7 @@ const SUBLINE_BODY_BUILDERS: Readonly<Record<string, (args: unknown) => string |
 	bash: (args) => buildFieldSublineBody(args, "command", "running ", { wrapInBackticks: true }),
 	grep: (args) => buildFieldSublineBody(args, "pattern", "searching for ", { wrapInBackticks: true }),
 	find: (args) => buildFieldSublineBody(args, "pattern", "finding ", { wrapInBackticks: true }),
+	web_fetch: (args) => buildFieldSublineBody(args, "url", "fetching "),
 	git: (args) => buildFieldSublineBody(args, "op", "git "),
 	verify: (args) => buildFieldSublineBody(args, "check", "verifying "),
 	code_nav: (args) => {
@@ -580,7 +673,7 @@ const SUBLINE_BODY_BUILDERS: Readonly<Record<string, (args: unknown) => string |
 /**
  * Per-tool subline templates. Maps a tool name to a function that builds the
  * verb-led subline body without the leading glyph and without the trailing
- * status glyph. Unknown tools fall back to the existing `<name>(<arg>)` form.
+ * status glyph. Unknown tools fall back to a tool-neutral action summary.
  */
 function webFetchMeta(result: unknown): string | null {
 	if (!isPlainObject(result) || !isPlainObject(result.details)) return null;
@@ -597,11 +690,10 @@ function webFetchMeta(result: unknown): string | null {
 
 /**
  * A call the permission gate blocked never executed, so the collapsed row must
- * not claim it did. `ran \`id\` · 667B ✗ blocked` read as a command that ran and
- * produced 667 bytes, while the expanded header for the same node correctly said
- * `bash(id) ✗ blocked`. Blocked rows use that same call-signature form, and the
- * ledger byte count is suppressed because those bytes are the denial text, not
- * output.
+ * not claim it did. Blocked calls keep the ordinary operator-facing action
+ * description but use a neutral noun for commands; the status tail supplies the
+ * blocked outcome. The ledger byte count is suppressed elsewhere because those
+ * bytes are the denial text, not output.
  */
 function isNonExecutedOutcome(outcome: ToolExecutionFinished["outcome"]): boolean {
 	return outcome === "blocked";
@@ -614,20 +706,29 @@ function buildSublineBody(
 	result?: unknown,
 	outcome?: ToolExecutionFinished["outcome"],
 ): string {
-	if (isNonExecutedOutcome(outcome)) return buildUnknownToolBody(toolName, args);
+	if (isNonExecutedOutcome(outcome)) {
+		if (toolName === "bash") {
+			return (
+				buildFieldSublineBody(args, "command", "command ", { wrapInBackticks: true }) ??
+				buildGenericToolBody(toolName, args)
+			);
+		}
+		return SUBLINE_BODY_BUILDERS[toolName]?.(args) ?? buildGenericToolBody(toolName, args);
+	}
 	if (toolName === "web_fetch") {
 		const meta = status === undefined ? null : webFetchMeta(result);
-		return `${buildUnknownToolBody(toolName, args)}${meta ? dim(` · ${meta}`) : ""}`;
+		const body = SUBLINE_BODY_BUILDERS.web_fetch?.(args) ?? buildGenericToolBody(toolName, args);
+		return `${body}${meta ? dim(` · ${meta}`) : ""}`;
 	}
 	if (toolName === "bash") {
-		const lead = status === undefined ? "running " : "ran ";
+		const lead = status === "ok" || status === "error" ? "ran " : "running ";
 		return (
-			buildFieldSublineBody(args, "command", lead, { wrapInBackticks: true }) ?? buildUnknownToolBody(toolName, args)
+			buildFieldSublineBody(args, "command", lead, { wrapInBackticks: true }) ?? buildGenericToolBody(toolName, args)
 		);
 	}
 	const body = SUBLINE_BODY_BUILDERS[toolName]?.(args);
 	if (body !== null && body !== undefined) return body;
-	return buildUnknownToolBody(toolName, args);
+	return buildGenericToolBody(toolName, args);
 }
 
 interface SublineParts {
@@ -660,9 +761,7 @@ function sublineParts(
 			tail: `${statusGlyph(status, meta)}${ledger.offload}`,
 		};
 	}
-	const elapsed = optionalCompactMs("elapsedMs" in call ? call.elapsedMs : undefined);
-	const running = elapsed !== null ? dim(` · ${elapsed}`) : "";
-	return { lead: `${dim(HEADER_PREFIX_PLAIN)}${body}${resource}${running}`, tail: "" };
+	return { lead: `${dim(HEADER_PREFIX_PLAIN)}${body}${resource}`, tail: statusGlyph(status, meta) };
 }
 
 /**
@@ -708,33 +807,69 @@ function indentAndWrap(line: string, width: number, isError: boolean): string[]
 	return out;
 }
 
+function scalarArgValue(value: unknown): string | null {
+	if (typeof value === "string") {
+		const lines = value.split("\n").length;
+		const bytes = Buffer.byteLength(value, "utf8");
+		if (lines > 1 || value.length > 160) return dim(`<${lines} lines · ${formatSize(bytes)} text>`);
+		return green(JSON.stringify(value));
+	}
+	if (typeof value === "number") return cyan(String(value));
+	if (typeof value === "boolean") return yellow(String(value));
+	if (value === null) return dim("null");
+	return null;
+}
+
 /**
- * Render the pretty-printed JSON args body. Splits on `\n` first and then
- * applies a line cap so the cut never lands inside an open string or before
- * a closing brace; the previous codepoint-level `truncate` could leave a
- * malformed JSON snippet that broke copy-paste. Mirrors the line-cap strategy
- * `renderResultBlock` already uses for tool output.
+ * Render secondary arguments as a compact typed field list. The primary path,
+ * command, pattern, or query already lives in the call signature; keeping the
+ * rest means `cwd`, timeout, range, glob, and flags no longer disappear merely
+ * because one field was important enough for the header. Nested values retain
+ * the structured JSON renderer, while large strings become byte/line facts
+ * instead of flooding the transcript.
  */
-function renderArgsBody(args: unknown, width: number, isError: boolean): string[] {
+function renderArgsBody(toolName: string, args: unknown, width: number, isError: boolean): string[] {
 	if (isEmptyArgs(args)) return [];
+	const safeArgs = redactToolArgs(args);
+	if (!isPlainObject(safeArgs)) {
+		const bodyWidth = Math.max(1, width - BODY_INDENT_VISIBLE_WIDTH);
+		const lines = tryRenderJson(safeArgs, bodyWidth, { lineLimit: ARGS_BODY_LINE_LIMIT });
+		return lines?.flatMap((line) => indentAndWrap(line, width, isError)) ?? [];
+	}
+	const primary = PRIMARY_ARG_FIELD[toolName];
+	const entries = Object.entries(safeArgs).filter(([key]) => key !== primary);
+	if (entries.length === 0) return [];
 	const out: string[] = [];
 	const bodyWidth = Math.max(1, width - BODY_INDENT_VISIBLE_WIDTH);
-	const lines = tryRenderJson(redactToolArgs(args), bodyWidth, { lineLimit: ARGS_BODY_LINE_LIMIT });
-	if (!lines) return [];
-	for (const raw of lines) {
-		out.push(...indentAndWrap(raw, width, isError));
+	out.push(...indentAndWrap(`${cyanBold("args")}${dim(` · ${entries.length}`)}`, width, isError));
+	const keyWidth = Math.min(18, Math.max(...entries.map(([key]) => visibleWidth(key))));
+	for (const [key, value] of entries) {
+		const label = `${cyan(key.padEnd(keyWidth))}  `;
+		const scalar = scalarArgValue(value);
+		if (scalar !== null) {
+			out.push(...indentAndWrap(`${label}${scalar}`, width, isError));
+			continue;
+		}
+		out.push(...indentAndWrap(cyan(key), width, isError));
+		const lines = tryRenderJson(value, Math.max(1, bodyWidth - 2), { lineLimit: ARGS_BODY_LINE_LIMIT });
+		for (const line of lines ?? [jsonStringifySafe(value)]) {
+			out.push(...indentAndWrap(`  ${line}`, width, isError));
+			if (out.length >= ARGS_BODY_LINE_LIMIT) break;
+		}
+		if (out.length >= ARGS_BODY_LINE_LIMIT) break;
 	}
+	if (out.length >= ARGS_BODY_LINE_LIMIT) out.push(...indentAndWrap(dim("… more arguments hidden"), width, isError));
 	return out;
 }
 
 /**
  * pi-agent-core wraps tool results in `{ content: [{ type: "text", text }, ...] }`
- * envelopes. Rendering that JSON verbatim hides the actual tool output behind
- * a sea of escaped quotes. When the envelope shape matches, concatenate the
- * text segments and treat the join as the real result; otherwise return the
- * value untouched so callers stringify it normally.
+ * envelopes. Rendering that JSON verbatim hides the actual output and, for a
+ * mixed result, can dump a base64 image into the terminal. Text blocks are
+ * joined, image blocks become compact MIME/size placeholders, and unknown
+ * content blocks are named without serializing their payload.
  */
-export function unwrapResultEnvelope(result: unknown): unknown {
+function unwrapResultEnvelope(result: unknown): unknown {
 	if (typeof result === "string" || result === null || result === undefined) return result;
 	const blocks = Array.isArray(result)
 		? result
@@ -745,16 +880,25 @@ export function unwrapResultEnvelope(result: unknown): unknown {
 	const parts: string[] = [];
 	for (const block of blocks) {
 		if (!isPlainObject(block)) return result;
-		if (block.type !== "text" || typeof block.text !== "string") return result;
-		parts.push(block.text);
+		if (block.type === "text" && typeof block.text === "string") {
+			parts.push(block.text);
+			continue;
+		}
+		if (block.type === "image" && typeof block.data === "string") {
+			const mimeType = typeof block.mimeType === "string" ? block.mimeType : "image/unknown";
+			const padding = block.data.endsWith("==") ? 2 : block.data.endsWith("=") ? 1 : 0;
+			const bytes = Math.max(0, Math.floor((block.data.length * 3) / 4) - padding);
+			parts.push(`[image ${mimeType} · ${formatSize(bytes)}]`);
+			continue;
+		}
+		if (typeof block.type === "string") {
+			parts.push(`[${block.type} content]`);
+			continue;
+		}
+		return result;
 	}
 	if (parts.length === 0) return result;
-	return parts.join("");
-}
-
-export function previewResult(result: unknown): string {
-	if (typeof result === "string") return truncate(result, RESULT_PREVIEW_LIMIT);
-	return truncate(jsonStringifySafe(result), RESULT_PREVIEW_LIMIT);
+	return parts.join("\n");
 }
 
 function isEmptyResult(result: unknown): boolean {
@@ -822,50 +966,14 @@ function highlightBashCommand(command: string): string {
 		.join("");
 }
 
-interface EditDiffArgs {
-	path?: string;
-	old_string: string;
-	new_string: string;
-}
-
-/**
- * Defensive shape check: edit-tool args must carry both `old_string` and
- * `new_string` strings before we can render a diff. `path` is optional; the
- * diff renderer falls back to `"file"` when absent. Anything else falls
- * through to the standard result block so the dispatch is opportunistic and
- * never throws.
- */
-function asEditDiffArgs(args: unknown): EditDiffArgs | null {
-	if (!isPlainObject(args)) return null;
-	const oldString = args.old_string;
-	const newString = args.new_string;
-	if (typeof oldString !== "string" || typeof newString !== "string") return null;
-	const out: EditDiffArgs = { old_string: oldString, new_string: newString };
-	if (typeof args.path === "string") out.path = args.path;
-	return out;
-}
-
-// The `diff` library appends a `` sentinel row when a
-// side of the comparison lacks a trailing newline. It is transcript noise, so
-// the edit diff block drops it. The marker text carries no ANSI, so a substring
-// check against the styled row is reliable and keeps this module free of raw
-// escape literals.
-const NO_NEWLINE_MARKER = "\";
-
-function isNoNewlineMarkerRow(row: string): boolean {
-	return row.includes(NO_NEWLINE_MARKER);
+function resultDiff(result: unknown): string | null {
+	const value = detailsOf(result)?.diff;
+	return typeof value === "string" && value.length > 0 ? value : null;
 }
 
-function renderEditDiffBlock(args: EditDiffArgs, width: number): string[] {
+function renderMutationDiffBlock(diff: string, width: number, color: boolean): string[] {
 	const bodyWidth = Math.max(1, width - BODY_INDENT_VISIBLE_WIDTH);
-	const input: DiffRenderInput = { oldText: args.old_string, newText: args.new_string };
-	if (args.path !== undefined) input.filename = args.path;
-	const out: string[] = [];
-	for (const line of renderUnifiedDiff(input, bodyWidth)) {
-		if (isNoNewlineMarkerRow(line)) continue;
-		out.push(`${RAIL_DIM}${line}`);
-	}
-	return out;
+	return renderDiffLines(diff, bodyWidth, { color }).map((line) => `${RAIL_DIM}${line}`);
 }
 
 interface BashArgs {
@@ -884,6 +992,79 @@ function asBashArgs(args: unknown): BashArgs | null {
 	return { command: redactSecretString(command) };
 }
 
+function resultLineCount(result: unknown): number {
+	const unwrapped = unwrapResultEnvelope(result);
+	if (typeof unwrapped !== "string" || unwrapped.length === 0) return 0;
+	const normalized = unwrapped.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+	const withoutTerminator = normalized.endsWith("\n") ? normalized.slice(0, -1) : normalized;
+	return withoutTerminator.split("\n").length;
+}
+
+function toolUsageFact(result: unknown): string | null {
+	if (!isPlainObject(result) || !isPlainObject(result.usage)) return null;
+	const total = numberField(result.usage, "totalTokens");
+	if (total === null || total <= 0) return null;
+	return `${total} tool token${total === 1 ? "" : "s"}`;
+}
+
+function outputFacts(finished: ToolExecutionFinished): string[] {
+	const parts: string[] = [];
+	if (isNonExecutedOutcome(finished.outcome)) {
+		if (finished.excludeFromContext === true) parts.push("excluded from context");
+		return parts;
+	}
+	const exitCode = structuredExitCode(finished) ?? (finished.toolName === "bash" && !finished.isError ? "0" : null);
+	if (exitCode !== null) parts.push(`exit ${exitCode}`);
+	const observation = observationOf(finished);
+	const count = observation === null ? null : countSummary(observation);
+	if (count !== null) parts.push(count);
+	const lines = resultLineCount(finished.result);
+	if (count === null && lines > 0) parts.push(`${lines} line${lines === 1 ? "" : "s"}`);
+	const shownBytes = shownBytesOf(finished);
+	const totalBytes = totalBytesOf(finished);
+	if (shownBytes !== null && shownBytes > 0) {
+		parts.push(
+			totalBytes !== null && totalBytes > shownBytes
+				? `${formatSize(shownBytes)} shown / ${formatSize(totalBytes)} total`
+				: formatSize(shownBytes),
+		);
+	}
+	if (isTruncatedResult(finished)) parts.push("truncated");
+	const details = detailsOf(finished.result);
+	if (details?.timedOut === true) parts.push("timed out");
+	if (details?.outputCapped === true) parts.push("output capped");
+	const usage = toolUsageFact(finished.result);
+	if (usage !== null) parts.push(usage);
+	if (isPlainObject(finished.result) && Array.isArray(finished.result.addedToolNames)) {
+		const added = finished.result.addedToolNames.filter((name): name is string => typeof name === "string");
+		if (added.length > 0) parts.push(`added ${added.join(", ")}`);
+	}
+	if (isPlainObject(finished.result) && finished.result.terminate === true) parts.push("terminal result");
+	if (finished.excludeFromContext === true) parts.push("excluded from context");
+	return parts;
+}
+
+function renderOutputMeta(
+	finished: ToolExecutionFinished,
+	width: number,
+	isError: boolean,
+	label = "output",
+): string[] {
+	const facts = outputFacts(finished);
+	const suffix = facts.length > 0 ? dim(` · ${facts.join(" · ")}`) : "";
+	return indentAndWrap(`${cyanBold(label)}${suffix}`, width, isError);
+}
+
+function renderOutputFooter(finished: ToolExecutionFinished, width: number, isError: boolean): string[] {
+	const out: string[] = [];
+	const offloadPath = isNonExecutedOutcome(finished.outcome) ? null : offloadPathOf(finished);
+	if (offloadPath !== null) out.push(...indentAndWrap(`${yellow("full output")}  ${offloadPath}`, width, isError));
+	const hint =
+		stringField(resultSizeOf(finished), "followUpHint") ?? stringField(finished.resultSummary ?? null, "followUpHint");
+	if (hint !== null) out.push(...indentAndWrap(`${dim("next")}  ${hint}`, width, isError));
+	return out;
+}
+
 /**
  * Bash subrenderer: emits `$ <cmd>` (full command) on its own line under the
  * rail, then the unwrapped output via the same chain as `renderResultBlock`.
@@ -927,11 +1108,17 @@ function renderResultBlock(
 
 /**
  * Header-only render for a tool call that has not yet finished. Used by the
- * live chat panel between `tool_execution_start` and `tool_execution_end`.
- * No status glyph: the absence of the glyph signals "still running".
+ * live chat panel from streamed argument formation through execution. The
+ * lifecycle tail distinguishes a forming call, a ready call, and a running
+ * call without inventing execution time before Pi starts the tool.
  */
 export function renderToolCallHeader(call: ToolExecutionStart, width: number): string[] {
-	return wrap(headerLine(call.toolName, call.args, undefined), width);
+	return wrap(
+		headerLine(call.toolName, call.args, call.phase ?? "running", {
+			elapsedMs: call.elapsedMs,
+		}),
+		width,
+	);
 }
 
 /** Running-only footer used when an operator pauses live output; execution continues. */
@@ -939,11 +1126,7 @@ export function renderToolRunningStatus(call: ToolExecutionStart, width: number)
 	const elapsed = optionalCompactMs(call.elapsedMs);
 	return [
 		...renderToolCallHeader(call, width),
-		...indentAndWrap(
-			dim(elapsed ? `(running... ${elapsed}; live output hidden)` : "(running; live output hidden)"),
-			width,
-			false,
-		),
+		...indentAndWrap(dim(elapsed ? `live output paused · ${elapsed}` : "live output paused"), width, false),
 	];
 }
 
@@ -952,7 +1135,7 @@ function sublineStatus(call: ToolExecutionStart | ToolExecutionFinished): Header
 	// carries a `result` field, so a `ToolExecutionStart` with a stray
 	// `isError: false` (e.g. from a future event-shape change) cannot trip the
 	// finished path. `result` is the type's load-bearing field.
-	if (!("result" in call)) return undefined;
+	if (!("result" in call)) return call.phase ?? "running";
 	return call.isError ? "error" : "ok";
 }
 
@@ -972,25 +1155,58 @@ function sublineStatus(call: ToolExecutionStart | ToolExecutionFinished): Header
  * imports the keybindings manager directly; the caller resolves the key string
  * and passes it in to keep this module pure.
  */
+export interface ToolSublineRenderOptions {
+	/** Live rows color the folded mutation diff; replay and export request plain rows. */
+	diffStyle?: "color" | "plain";
+	/**
+	 * Whether the folded row carries the extras its tool's presentation asks
+	 * for (today the bounded mutation diff). The bare subline level drops them;
+	 * the failure excerpt is not one of them and always rides the row.
+	 */
+	foldedExtras?: "per-tool" | "none";
+}
+
+/**
+ * The bounded diff a folded mutation row keeps under itself, when the tool's
+ * presentation asks for one and the result carries one. A folded `edit` that
+ * hid its change told the operator nothing they could act on.
+ */
+function foldedDiffRows(finished: ToolExecutionFinished, width: number, opts: ToolSublineRenderOptions): string[] {
+	if (opts.foldedExtras === "none") return [];
+	if (finished.isError || isNonExecutedOutcome(finished.outcome)) return [];
+	if (!toolPresentationPolicy(finished.toolName, finished.args).showDiffWhenFolded) return [];
+	const diff = resultDiff(finished.result);
+	if (diff === null) return [];
+	return truncateRowsMiddle(
+		renderMutationDiffBlock(diff, width, opts.diffStyle !== "plain"),
+		FOLDED_DIFF_ROW_LIMIT,
+		false,
+	);
+}
+
 export function renderToolSubline(
 	call: ToolExecutionStart | ToolExecutionFinished,
 	width: number,
 	expandKey?: string,
+	opts: ToolSublineRenderOptions = {},
 ): string[] {
 	const status = sublineStatus(call);
 	const meta: StatusMeta =
 		"result" in call
 			? {
 					durationMs: call.durationMs,
-					exitCode: call.toolName === "bash" && call.isError ? bashExitCodeFromResult(call.result) : null,
+					exitCode: structuredExitCode(call),
 					outcome: call.outcome,
 					blockReason: call.blockReason,
 				}
-			: {};
+			: { elapsedMs: call.elapsedMs };
 	const parts = sublineParts(call, status, meta);
-	const showHint = status !== undefined && expandKey !== undefined && expandKey.length > 0;
+	const excerpt = "result" in call ? failureExcerpt(call, width) : "";
+	const showHint = "result" in call && expandKey !== undefined && expandKey.length > 0;
 	const tail = showHint ? `${parts.tail}${dim(` (${expandKey})`)}` : parts.tail;
-	return wrapSublineWithTail(parts.lead, tail, width);
+	const lines = wrapSublineWithTail(`${parts.lead}${excerpt}`, tail, width);
+	if ("result" in call) lines.push(...foldedDiffRows(call, width, opts));
+	return lines;
 }
 
 /**
@@ -1008,22 +1224,23 @@ export function renderToolExecution(
 	const status: HeaderStatus = finished.isError ? "error" : "ok";
 	const statusMeta: StatusMeta = {
 		durationMs: finished.durationMs,
-		exitCode: finished.toolName === "bash" && finished.isError ? bashExitCodeFromResult(finished.result) : null,
+		exitCode: structuredExitCode(finished),
 		outcome: finished.outcome,
 		blockReason: finished.blockReason,
 	};
 	const out: string[] = [];
 	out.push(...wrap(headerLine(finished.toolName, finished.args, status, statusMeta), width));
 
-	// Edit-tool dispatch: when the tool succeeded and `args` carries the
-	// expected `{ old_string, new_string }` strings, swap the args body and
-	// result block for a unified diff. The header still renders so the user
-	// sees `▸ edit(<path>)`, and the args body is suppressed because echoing
-	// both strings would just duplicate what the diff already shows.
-	if (finished.toolName === "edit" && finished.isError === false) {
-		const editArgs = asEditDiffArgs(redactToolArgs(finished.args));
-		if (editArgs !== null) {
-			out.push(...renderEditDiffBlock(editArgs, width));
+	// Edit and write tools produce one bounded numbered diff on result.details.
+	// It is the authority because canonical edit args can contain multiple
+	// replacements and fuzzy matching can change the actual base text. Live rows
+	// receive Pi's word-level styling; replay and export request plain rows.
+	if ((finished.toolName === "edit" || finished.toolName === "write") && finished.isError === false) {
+		const diff = resultDiff(finished.result);
+		if (diff !== null) {
+			out.push(...renderOutputMeta(finished, width, false, "change"));
+			out.push(...renderMutationDiffBlock(diff, width, opts.diffStyle !== "plain"));
+			out.push(...renderOutputFooter(finished, width, false));
 			return out;
 		}
 	}
@@ -1035,20 +1252,35 @@ export function renderToolExecution(
 	if (finished.toolName === "bash") {
 		const bashArgs = asBashArgs(redactToolArgs(finished.args));
 		if (bashArgs !== null) {
+			out.push(...renderArgsBody(finished.toolName, finished.args, width, finished.isError));
+			out.push(
+				...renderOutputMeta(
+					finished,
+					width,
+					finished.isError,
+					isNonExecutedOutcome(finished.outcome) ? "decision" : "output",
+				),
+			);
 			out.push(...renderBashResultBlock(bashArgs, finished.result, width, finished.isError, opts));
+			out.push(...renderOutputFooter(finished, width, finished.isError));
 			return out;
 		}
 	}
 
-	// Suppress the args body when the header already encodes the salient arg
-	// (e.g. `▸ read(README.md)` already shows the path; rendering
-	// `{"path": "README.md"}` underneath is duplicate noise). For tools without
-	// a known primary arg the body still renders so users see what the model
-	// actually invoked.
-	if (capturedPrimaryArg(finished.toolName, finished.args) === null) {
-		out.push(...renderArgsBody(finished.args, width, finished.isError));
-	}
+	// The primary argument already lives in the signature. Keep the secondary
+	// fields below it so flags, ranges, working directories, and timeouts remain
+	// inspectable without repeating the primary value.
+	out.push(...renderArgsBody(finished.toolName, finished.args, width, finished.isError));
+	out.push(
+		...renderOutputMeta(
+			finished,
+			width,
+			finished.isError,
+			isNonExecutedOutcome(finished.outcome) ? "decision" : "output",
+		),
+	);
 	out.push(...renderResultBlock(finished.result, finished.isError, width, opts));
+	out.push(...renderOutputFooter(finished, width, finished.isError));
 	return out;
 }
 
@@ -1065,13 +1297,15 @@ export function renderToolResultOnly(
 	const status: HeaderStatus = finished.isError ? "error" : "ok";
 	const statusMeta: StatusMeta = {
 		durationMs: finished.durationMs,
-		exitCode: finished.toolName === "bash" && finished.isError ? bashExitCodeFromResult(finished.result) : null,
+		exitCode: structuredExitCode(finished),
 		outcome: finished.outcome,
 		blockReason: finished.blockReason,
 	};
 	const out: string[] = [];
 	out.push(...wrap(headerLine(finished.toolName, undefined, status, statusMeta), width));
+	out.push(...renderOutputMeta(finished, width, finished.isError));
 	out.push(...renderResultBlock(finished.result, finished.isError, width, opts));
+	out.push(...renderOutputFooter(finished, width, finished.isError));
 	return out;
 }
 
@@ -1079,26 +1313,140 @@ export function renderToolResultOnly(
  * Streaming render for an in-flight tool call whose expanded block should
  * surface the latest partial output. Used by the chat panel between
  * `tool_execution_start` and `tool_execution_end` when the user has expanded
- * the tool segment. The header carries no status glyph (still running), the
- * args body is suppressed when the header captures the primary arg, the
- * partial output renders under the rail capped at `RESULT_LINE_LIMIT` lines,
- * and a dim `(running...)` marker on the trailing line communicates that the
- * block is still being written. An empty `partialOutput` renders
+ * the tool segment. The header carries the running lifecycle tail, secondary
+ * arguments remain visible, and the latest cumulative Pi result renders under
+ * a labeled live-output rail capped at the streaming row limit. An empty result renders
  * `(no output yet)` so the user can distinguish a slow start from a stalled
  * call.
  */
-export function renderToolStreamingExecution(call: ToolExecutionStart, width: number, partialOutput: string): string[] {
+export function renderToolStreamingExecution(
+	call: ToolExecutionStart,
+	width: number,
+	partialResult: unknown,
+): string[] {
 	const out: string[] = [];
-	out.push(...wrap(headerLine(call.toolName, call.args, undefined), width));
-	if (capturedPrimaryArg(call.toolName, call.args) === null) {
-		out.push(...renderArgsBody(call.args, width, false));
-	}
-	if (partialOutput.length === 0) {
+	out.push(...renderToolCallHeader({ ...call, phase: "running" }, width));
+	out.push(...renderArgsBody(call.toolName, call.args, width, false));
+	const partial: ToolExecutionFinished = {
+		toolCallId: call.toolCallId,
+		toolName: call.toolName,
+		args: call.args,
+		result: partialResult,
+		isError: false,
+	};
+	out.push(...renderOutputMeta(partial, width, false, "live output"));
+	const partialOutput = unwrapResultEnvelope(partialResult);
+	if (isEmptyResult(partialOutput)) {
 		out.push(...indentAndWrap(dim("(no output yet)"), width, false));
 	} else {
-		out.push(...renderOutputRows(partialOutput, width, false, STREAMING_RESULT_ROW_LIMIT));
+		if (call.toolName === "bash") {
+			const bashArgs = asBashArgs(redactToolArgs(call.args));
+			if (bashArgs !== null) {
+				const commandLine = `${cyanBold("$")} ${highlightBashCommand(stripShellWrapperForDisplay(bashArgs.command))}`;
+				out.push(...indentAndWrap(commandLine, width, false));
+			}
+		}
+		out.push(
+			...renderOutputRows(resultText(partialOutput, FULL_RESULT_PREVIEW_LIMIT), width, false, STREAMING_RESULT_ROW_LIMIT),
+		);
 	}
-	const elapsed = optionalCompactMs(call.elapsedMs);
-	out.push(...indentAndWrap(dim(elapsed !== null ? `(running... ${elapsed})` : "(running...)"), width, false));
 	return out;
 }
+
+/** Display-only lifecycle for operator-issued `!` and `!!` bash commands. */
+export interface BashTranscriptExecution {
+	command: string;
+	output: string;
+	running: boolean;
+	elapsedMs?: number | undefined;
+	totalBytes?: number | undefined;
+	exitCode?: number | null | undefined;
+	cancelled?: boolean | undefined;
+	truncated?: boolean | undefined;
+	fullOutputPath?: string | undefined;
+	excludeFromContext?: boolean | undefined;
+	error?: string | undefined;
+	/**
+	 * Whether the block draws its one-line row instead of the full body. The
+	 * caller resolves this from the transcript detail policy and the operator's
+	 * override, the same way the panel resolves a model bash call. Omitted means
+	 * folded.
+	 */
+	folded?: boolean | undefined;
+}
+
+/**
+ * Render local bash with the same call, argument, output, and settlement grammar
+ * as model-initiated bash. This is a view projection only; callers keep Clio's
+ * existing immutable `bashExecution` ledger entry.
+ */
+export function renderBashTranscriptExecution(
+	execution: BashTranscriptExecution,
+	width: number,
+	expandKey?: string,
+	bodyOptions: ToolBodyRenderOptions = {},
+): string[] {
+	const shownBytes = Buffer.byteLength(execution.output, "utf8");
+	const totalBytes = execution.totalBytes ?? shownBytes;
+	const args: Record<string, unknown> = { command: execution.command };
+	if (execution.excludeFromContext === true) args.context = "excluded from model context";
+	const details = {
+		resultSize: {
+			bytes: totalBytes,
+			shownBytes,
+			truncated: execution.truncated === true,
+			policy: "tail",
+			...(execution.fullOutputPath !== undefined ? { offloadPath: execution.fullOutputPath } : {}),
+		},
+	};
+	const result = {
+		content: [{ type: "text", text: execution.output }],
+		details,
+	};
+	const folded = execution.folded !== false;
+	if (execution.running) {
+		if (folded) {
+			return renderToolSubline(
+				{
+					toolCallId: "local-bash",
+					toolName: "bash",
+					args,
+					elapsedMs: execution.elapsedMs,
+					phase: "running",
+				},
+				width,
+			);
+		}
+		return renderToolStreamingExecution(
+			{
+				toolCallId: "local-bash",
+				toolName: "bash",
+				args,
+				elapsedMs: execution.elapsedMs,
+				phase: "running",
+			},
+			width,
+			result,
+		);
+	}
+	const message = execution.error?.trim();
+	const output = message
+		? `${execution.output}${execution.output.length > 0 ? "\n\n" : ""}${message}`
+		: execution.output;
+	const finished: ToolExecutionFinished = {
+		toolCallId: "local-bash",
+		toolName: "bash",
+		args,
+		result: { ...result, content: [{ type: "text", text: output }] },
+		isError: execution.cancelled === true || execution.error !== undefined || (execution.exitCode ?? 0) !== 0,
+		exitCode: execution.exitCode,
+		...(execution.cancelled === true ? { outcome: "aborted" as const } : {}),
+		excludeFromContext: execution.excludeFromContext,
+		resultSummary: {
+			bytes: shownBytes,
+			truncated: execution.truncated === true,
+			...(execution.fullOutputPath !== undefined ? { offloadPath: execution.fullOutputPath } : {}),
+		},
+	};
+	return folded ? renderToolSubline(finished, width, expandKey) : renderToolExecution(finished, width, bodyOptions);
+}