@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/tools/intercom-tool.ts

@@ -5,12 +5,13 @@ import { failureDetails } from "../extension/shared.ts";
 import { Text } from "@earendil-works/pi-tui";
 import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
 import { compactVisibleText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import { createReportBody } from "../ui/report-body.ts";
 import { coachingDisabledHint, expandDetailHint, reconcileAnsweredAsk } from "../extension/shared.ts";
 import {
 	type AsyncRun, AsyncRunTracker, buildPeekDigest,
 	dedupeRunsById, getFullRunOutput, IdleCoalescingNotifier,
-	isAsyncRunStalled, runDisplayName, runDurationLabel,
+	isAsyncRunStalled, observedRunModel, runDisplayName, runDurationLabel,
 } from "../engine/async.ts";
 import type { PollGuard } from "../core/nudge.ts";
 import { fenceUntrusted } from "../core/fence.ts";
@@ -21,11 +22,14 @@ import type { InProcessBus } from "../bus/inproc.ts";
 import type { PersonaController } from "../persona/controller.ts";
 import { emptyUsage } from "../engine/stream.ts";
 import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import type { TerminalResultArchive } from "../results/archive.ts";
+import { pageLiveResult, projectResultPage, resultReceiptHint } from "../results/retrieval.ts";
 
 export interface IntercomToolDeps {
 	get lastCtx(): ExtensionContext | undefined;
 	set lastCtx(value: ExtensionContext | undefined);
 	tracker: AsyncRunTracker;
+	archive(ctx: ExtensionContext): TerminalResultArchive;
 	completionNotifier: IdleCoalescingNotifier<AsyncRun>;
 	intercomNotifier: IdleCoalescingNotifier<PendingAsk>;
 	controller: PersonaController;
@@ -131,6 +135,7 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			[
 				Type.Literal("peek"),
 				Type.Literal("result"),
+				Type.Literal("results"),
 				Type.Literal("steer"),
 				Type.Literal("stop"),
 				Type.Literal("list"),
@@ -141,10 +146,15 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			],
 			{
 				description:
-					"peek = status of async sub-agents · result = retrieve one complete settled result by run id · steer = soft redirect into one by run id (it may ignore it) · stop = request engine cancellation by run id · message = retrieve one drained bus message by message id · list/inbox/reply/send = coaching messages (needs a coaching persona)",
+					"peek = status of async sub-agents · results = bounded archive summaries (cursor/limit) · result = page a settled live result by to:run-id or a saved report by ref:result-UUID · steer = soft redirect into one by run id (it may ignore it) · stop = request engine cancellation by run id · message = retrieve one drained bus message by message id · list/inbox/reply/send = coaching messages (needs a coaching persona)",
 			},
 		),
 		to: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "result/steer/stop/peek: the async run id (e.g. 'run-1'); stop: \"all\" cancels every running run · send: the child handle (from `list`)" })),
+		ref: Type.Optional(Type.String({ maxLength: 43, description: "result: opaque result:<UUID> archive reference; never a run id. Mutually exclusive with to." })),
+		offset: Type.Optional(Type.Integer({ minimum: 0, description: "result: stored-body UTF-16 offset (default 0); use nextOffset, never split a surrogate pair." })),
+		limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 16000, description: "result: 2..16000 UTF-16 units (default 8000). results: 1..50 summaries (default 20)." })),
+		cursor: Type.Optional(Type.Integer({ minimum: 0, description: "results: nextCursor from the prior bounded summary page; omit for the first page." })),
+		collect: Type.Optional(Type.Boolean({ description: "result with live to only: true acknowledges the whole report and suppresses its pending completion. Paging alone does not collect." })),
 		messageId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "message: the drained bus message id shown by `inbox`" })),
 		askId: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_REF_CHARS, description: "reply: the message id of the child's pending question" })),
 		message: Type.Optional(Type.String({ maxLength: MAX_INTERCOM_MESSAGE_CHARS, description: "steer/reply/send: the text to deliver" })),
@@ -154,7 +164,10 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 		label: "Intercom",
 		description: [
 			"Steer, stop and inspect your background sub-agents; a finished run or batch wakes you with a completion follow-up.",
-			"Never `peek` healthy children; use it only for status you need. `result { to: runId }` retrieves one complete settled payload by run id.",
+			"Never `peek` healthy children; use it only for status you need. `result { to: runId }` pages a live settled payload by run id (8000 units default, 16000 maximum).",
+			"`results { cursor?, limit? }` lists saved terminal summaries across this session's branches (20 default, 50 maximum); pass nextCursor for the next page.",
+			"`result { ref: 'result:<UUID>', offset?, limit? }` reads a saved report, including after reload, without collecting, billing, restarting a worker or waking the model. Memory-only references last only for this activation. Run ids route only the current runtime; never guess a historical run by id.",
+			"Use nextOffset for more UTF-16 pages. Only a whole live body returned in one read, or explicit live collect:true, suppresses a pending completion. Archive ref reads reject collect.",
 			"`steer` sends a soft course-correction to one (by run id); in-process async runs can receive it mid-run,",
 			"while child-engine (MCP/worktree) async runs receive it as a brokered follow-up. After remaining tools return, Pi can consume steering; arbitrary active tool work is not promised to stop immediately.",
 			"`message` retrieves a drained bus message by its message id; `list`/`inbox`/`reply`/`send` exchange coaching messages (a child reaches you via `contact_supervisor`)",
@@ -180,8 +193,29 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				if (refusal) return refusal;
 				return { content: [{ type: "text", text: buildPeekDigest(runs, { now: Date.now(), stallMs: d.STALL_FLAG_MS, ...(waiting ? { waitingForSupervisor: waiting } : {}) }) }], details: { action: "peek", ok: true, ...targetSnapshot }, isError: false };
 			}
+			if (params.action === "results" || (params.action === "result" && params.ref !== undefined)) {
+				const invalid = params.to !== undefined || params.collect !== undefined || (params.action === "results" && (params.ref !== undefined || params.offset !== undefined)) || (params.action === "result" && params.cursor !== undefined);
+				if (invalid) return { content: [{ type: "text", text: "Archive reads accept ref/offset/limit; results accepts cursor/limit. to and collect are live-only." }], details: failureDetails({ action: params.action }), isError: true };
+				const archive = d.archive(ctx);
+				if (params.action === "results") {
+					const page = archive.list({ ...(params.cursor !== undefined ? { cursor: params.cursor } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) });
+					const text = page.ok ? ["Saved terminal reports (not live workers):", ...page.results.map((r) => `${r.ref} · ${sanitizeDisplayLabel(r.label ?? r.agent)} · ${r.status} · ${r.storage}${r.truncated ? " · truncated" : ""}`), ...(page.nextCursor !== undefined ? [`nextCursor: ${page.nextCursor}`] : []), ...(page.warnings.length ? [`Storage warnings: ${page.warnings.join(", ")}`] : [])].join("\n") : page.message;
+					return { content: [{ type: "text", text }], details: { action: "results", ...page }, isError: !page.ok };
+				}
+				const page = archive.read({ ref: params.ref!, ...(params.offset !== undefined ? { offset: params.offset } : {}), ...(params.limit !== undefined ? { limit: params.limit } : {}) });
+				if (!page.ok) {
+					return { content: [{ type: "text", text: page.message }], details: { action: "result", ...page }, isError: true };
+				}
+				// Bounded-page rule: the fenced body is delivered once, in content; details stay
+				// bounded metadata exactly like the live result path (no whole page hidden there).
+				const { body: _pageBody, ...pageMeta } = page;
+				return {
+					content: [{ type: "text", text: `${page.summary.ref} · ${page.summary.status} · ${page.summary.storage}${page.summary.truncated ? " · saved body truncated" : ""}\n${projectResultPage(page, page.summary.error)}` }],
+					details: { action: "result", ...pageMeta }, isError: false,
+				};
+			}
 			if (params.action === "result") {
-				if (!params.to) {
+				if (!params.to || params.cursor !== undefined) {
 					return { content: [{ type: "text", text: "intercom result needs { to: <run id> }." }], details: failureDetails({ action: "result", ok: false }), isError: true };
 				}
 				const run = d.tracker.peek(params.to);
@@ -199,14 +233,17 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				// same result cannot appear again as a follow-up a moment later. Telling the tracker too
 				// makes this retained copy the first thing retention evicts — the supervisor has read it,
 				// so it is the cheapest payload in the map to lose.
-				d.completionNotifier.discard((pending) => pending.id === run.id);
-				d.tracker.markCollected(run.id);
 				const full = getFullRunOutput(run);
-				const body = full === "(no output)" ? full : fenceUntrusted(full);
-				// The cause is engine/child-authored text too. Keep the run id/status as trusted compact
-				// metadata, but put the diagnostic inside the same untrusted fence as the payload.
-				const cause = run.error ? `\nFailure detail:\n${fenceUntrusted(run.error)}` : "";
-				const displayRun = sanitizeDisplayLabel(run.label ?? run.agent);
+				const page = pageLiveResult(full, params.offset, params.limit);
+				if (!page) return { content: [{ type: "text", text: "Invalid result offset/limit; use nextOffset and 2..16000 units." }], details: failureDetails({ action: "result", ...targetSnapshot }), isError: true };
+				if (params.collect === true || (page.offset === 0 && page.endOfStoredBody)) {
+					d.completionNotifier.discard((pending) => pending.id === run.id);
+					d.tracker.markCollected(run.id);
+				}
+				const body = projectResultPage(page, run.error);
+				const receipt = resultReceiptHint(run.resultReceipt);
+				const displayRun = runDisplayName(run);
+				const modelUsed = observedRunModel(run);
 				// The wall time this leg took: an explicit collection is one of the paths a completion reaches
 				// the supervisor through, so it carries the same reading the passive completion report does.
 				const took = runDurationLabel(run);
@@ -216,8 +253,8 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				const billed = d.childUsage.accountMany([{ key: run.id, usage: run.result?.usage ?? emptyUsage() }]);
 				d.publishPersonaCost();
 				return {
-					content: [{ type: "text", text: `${run.id} (${displayRun}) · ${run.status}${took ? ` · ${took}` : ""}${cause}\n${body}${note ? `\n\n${note}` : ""}` }],
-					details: { action: "result", ok: true, status: run.status, ...targetSnapshot },
+					content: [{ type: "text", text: `${run.id} (${displayRun}) · ${run.status}${took ? ` · ${took}` : ""}${modelUsed ? `\nObserved model: ${modelUsed}` : ""}\n${body}${receipt ? `\n${receipt}` : ""}${note ? `\n\n${note}` : ""}` }],
+					details: { action: "result", ok: true, status: run.status, ...targetSnapshot, ...(modelUsed ? { modelUsed } : {}), page: { offset: page.offset, nextOffset: page.nextOffset, endOfStoredBody: page.endOfStoredBody }, ...(run.resultReceipt ? { resultReceipt: { ...run.resultReceipt } } : {}) },
 					isError: false,
 					...toolUsageField(billed),
 				};
@@ -317,7 +354,12 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 			return component;
 		},
 		renderResult(result, { expanded }, theme, context) {
-			const details = (result.details ?? {}) as { action?: string; ok?: boolean; runId?: string; target?: string; message?: string };
+			const details = (result.details ?? {}) as {
+				action?: string; ok?: boolean; runId?: string; target?: string; message?: string;
+				results?: Array<{ truncated?: boolean }>;
+				summary?: { ref?: string; storage?: string; storedChars?: number; truncated?: boolean };
+				nextCursor?: number; nextOffset?: number; warnings?: readonly string[];
+			};
 			const state = context?.state as IntercomRenderState | undefined;
 			const action = details.action ?? context?.args?.action;
 			const savedId = details.runId ?? context?.args?.to;
@@ -353,7 +395,20 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				const showTitle = !state?.callText || !preview;
 				return new Text(`${showTitle ? theme.fg("success", title) : ""}${preview ? `${showTitle ? "\n" : ""}${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}` : ""}`, 0, 0);
 			}
+			// Archive views are listings/diagnostics, never Markdown reports. A successful archive
+			// read carries no runId (live results do) and a summary (its own receipt); the invalid
+			// argument mix and failed reads fall through to the literal failure rendering below.
+			const listing = details.action === "results" && details.ok === true && Array.isArray(details.results) ? details.results : undefined;
+			const archivedPage = details.action === "result" && details.ok === true
+				&& typeof details.summary === "object" && details.summary !== null && details.runId === undefined
+				? details.summary
+				: undefined;
 			if (expanded) {
+				// Archive pages/listings stay literal via the shared renderer — complete sanitized
+				// content, no Markdown re-render of a quote-fenced page or a ref listing.
+				if (!failed && (listing || archivedPage)) {
+					return renderLiteralToolResult(result, { expanded }, theme, context);
+				}
 				// Explicit report/message actions only; missing/running diagnostics and control
 				// receipts remain literal. Older history with no action is not guessed from prose.
 				if (!failed && ["result", "message", "inbox"].includes(action ?? "")) {
@@ -361,6 +416,35 @@ export function registerIntercomTool(pi: ExtensionAPI, d: IntercomToolDeps): voi
 				}
 				return new Text(`${prefix}${theme.fg("toolOutput", full)}`, 0, 0);
 			}
+			if (!failed && listing) {
+				// Purpose line first (count + paging/truncation/storage honesty), then a bounded
+				// listing preview; the payload's own header line is replaced by the purpose line.
+				const truncated = listing.filter((entry) => entry?.truncated === true).length;
+				const flags = [
+					...(details.nextCursor !== undefined ? [`next page: cursor ${details.nextCursor}`] : []),
+					...(truncated > 0 ? [`${truncated} truncated`] : []),
+					...(details.warnings?.length ? [`warnings: ${details.warnings.join(", ")}`] : []),
+				];
+				const purpose = compactInlineText(`results · ${listing.length} retained${flags.length ? ` · ${flags.join(" · ")}` : ""}`, { maxChars: 100 });
+				const preview = compactVisibleText(full.split("\n").slice(1).join("\n"), { maxLines: 3, maxLineChars: 100 });
+				return new Text(`${theme.fg("success", purpose)}\n${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}`, 0, 0);
+			}
+			if (!failed && archivedPage) {
+				// Page position reads against the STORED body (originals may be truncated); honesty
+				// flags surface collapsed so a memory-only or truncated receipt is never mistaken
+				// for a durable whole report without expanding.
+				const end = details.nextOffset ?? archivedPage.storedChars ?? 0;
+				const flags = [
+					...(archivedPage.truncated ? ["truncated"] : []),
+					...(archivedPage.storage === "memory-only" ? ["memory-only"] : []),
+					...(details.warnings?.length ? [`warnings: ${details.warnings.join(", ")}`] : []),
+				];
+				const purpose = compactInlineText(`result · ${archivedPage.ref ?? "?"} · page ${end}/${archivedPage.storedChars ?? "?"}${flags.length ? ` · ${flags.join(" · ")}` : ""}`, { maxChars: 100 });
+				// The payload's receipt header and paging diagnostic line are replaced by the purpose
+				// line; the fence wrapper is dropped by the preview, leaving the page body quoted.
+				const preview = compactVisibleText(full.split("\n").slice(2).join("\n"), { maxLines: 3, maxLineChars: 100 });
+				return new Text(`${theme.fg("success", purpose)}\n${theme.fg("toolOutput", preview.text)}${preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : ""}`, 0, 0);
+			}
 			const preview = compactVisibleText(full, { maxLines: 4, maxLineChars: 100 });
 			const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
 			return new Text(`${prefix}${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);

package/src/tools/models.ts

@@ -3,6 +3,7 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 import { Type } from "typebox";
 import { Text } from "@earendil-works/pi-tui";
 import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 
 export interface ModelsToolDeps {
 	get lastCtx(): ExtensionContext | undefined;
@@ -45,5 +46,19 @@ export function registerModelsTool(pi: ExtensionAPI, d: ModelsToolDeps): void {
 			const query = compactInlineText(args.query ?? "(shortlist)", { maxChars: 96 }) || "(shortlist)";
 			return new Text(`${theme.fg("toolTitle", theme.bold("models "))}${theme.fg("dim", query)}`, 0, 0);
 		},
+		renderResult(result, { expanded }, theme, context) {
+			// The catalog itself is literal data: the shared renderer bounds it collapsed and
+			// shows the complete sanitized listing expanded.
+			if (expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const failed = context?.isError ?? result.isError ?? false;
+			if (failed) return renderLiteralToolResult(result, { expanded: false }, theme, context);
+			const details = (result.details ?? {}) as { total?: number; shown?: number; shortlist?: boolean };
+			const total = typeof details.total === "number" && Number.isFinite(details.total) ? details.total : 0;
+			const shown = typeof details.shown === "number" && Number.isFinite(details.shown) ? details.shown : 0;
+			const summary = shown === 0
+				? "no catalog matches"
+				: `${total} catalog models · showing ${shown}${details.shortlist ? " nearby candidates" : " matches"}`;
+			return new Text(`${theme.fg("toolTitle", theme.bold("models · "))}${theme.fg("accent", compactInlineText(summary, { maxChars: 96 }))}`, 0, 0);
+		},
 	});
 }

package/src/tools/monitor.ts

@@ -4,8 +4,10 @@ import { Type } from "typebox";
 import { Text } from "@earendil-works/pi-tui";
 import type { MonitorManager } from "../core/monitor.ts";
 import { neutralizeMonitorUnicode } from "../core/monitor-output.ts";
+import { formatDuration } from "../core/time.ts";
 import { armWakeAdvice, failureDetails } from "../extension/shared.ts";
 import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import { fenceUntrusted, stripTerminalControls } from "../core/fence.ts";
 import type { MonitorArchive, MonitorLogRecord } from "../monitor/archive.ts";
 
@@ -88,12 +90,29 @@ export function registerMonitorTool(pi: ExtensionAPI, d: MonitorToolDeps): void
 				...(params.maxEvents !== undefined ? { maxEvents: params.maxEvents } : {}),
 			});
 			if (!result.ok) return fail(result.error);
-			return { content: [{ type: "text" as const, text: `Armed ${result.entry.id} (${compactInlineText(result.entry.label, { maxChars: 120 })}); ${params.mode === "exit" ? "wakes when this job exits" : "wakes on relevant stdout lines"}. Deadline ${new Date(result.entry.expiresAtEpochMs).toISOString()}. ${armWakeAdvice(ctx, "watch", "condition", "Keep this session open. Continue independent work, or end your turn; it wakes you by itself, so never sleep, poll, or arm a `timer` to wait for it.")}` }], details: { ok: true, id: result.entry.id, expiresAtEpochMs: result.entry.expiresAtEpochMs } };
+			return { content: [{ type: "text" as const, text: `Armed ${result.entry.id} (${compactInlineText(result.entry.label, { maxChars: 120 })}); ${params.mode === "exit" ? "wakes when this job exits" : "wakes on relevant stdout lines"}. Deadline ${new Date(result.entry.expiresAtEpochMs).toISOString()}. ${armWakeAdvice(ctx, "watch", "condition", "Keep this session open. Continue independent work, or end your turn; it wakes you by itself, so never sleep, poll, or arm a `timer` to wait for it.")}` }], details: { ok: true, id: result.entry.id, expiresAtEpochMs: result.entry.expiresAtEpochMs, label: compactInlineText(result.entry.label, { maxChars: 120 }), mode: params.mode } };
 		},
 		renderCall(args, theme) {
 			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
 			const label = compactInlineText(args.label ?? args.id ?? "", { maxChars: 96 });
 			return new Text(`${theme.fg("toolTitle", theme.bold(`monitor ${action}`))}${label ? ` ${theme.fg("dim", label)}` : ""}`, 0, 0);
 		},
+		renderResult(result, { expanded }, theme, context) {
+			const details = (result.details ?? {}) as { ok?: boolean; label?: string; mode?: string; expiresAtEpochMs?: number };
+			const failed = context?.isError ?? result.isError ?? false;
+			const isArm = !failed && typeof details.label === "string" && (details.mode === "output" || details.mode === "exit");
+			if (!isArm) {
+				// Failures and every list/cancel/result receipt share the one literal renderer:
+				// error heading, bounded sanitized preview, expansion hint.
+				return renderLiteralToolResult(result, { expanded }, theme, context);
+			}
+			if (expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const left = typeof details.expiresAtEpochMs === "number" && Number.isFinite(details.expiresAtEpochMs)
+				? details.expiresAtEpochMs - Date.now()
+				: undefined;
+			const deadline = left === undefined ? "" : left > 0 ? ` · deadline in ${formatDuration(left)}` : " · deadline reached";
+			const summary = compactInlineText(`${details.label} · ${details.mode}${deadline}`, { maxChars: 140 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("armed "))}${theme.fg("accent", summary)}`, 0, 0);
+		},
 	});
 }

package/src/tools/read-result.ts

@@ -0,0 +1,52 @@
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
+import { Type } from "typebox";
+import { fenceUntrusted } from "../core/fence.ts";
+import { RESULT_READ_DEFAULT, RESULT_READ_MAX } from "../results/types.ts";
+import { isReadRequest, isReadReplyFor, readFailure, type ReadReply, type ScopedReader } from "../bus/result-reader.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
+
+const Params = Type.Object({
+	ref: Type.String({ minLength: 43, maxLength: 43, description: "Granted opaque result:<UUID> reference, not a file path or run id." }),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: Number.MAX_SAFE_INTEGER, description: "UTF-16 offset; use nextOffset from the previous page." })),
+	limit: Type.Optional(Type.Integer({ minimum: 2, maximum: RESULT_READ_MAX, default: RESULT_READ_DEFAULT, description: "Maximum UTF-16 characters to read." })),
+}, { additionalProperties: false });
+type PageDetails = Omit<Extract<ReadReply, { ok: true }>, "body">;
+
+/** Available only when the parent explicitly grants a scoped reader. No archive browsing,
+ * implicit fallback, polling, messages or model wakes. Fencing happens exactly once here.
+ * Wrapped in `defineTool` so callers that store the definition in a wider-typed variable
+ * (engine registration sites) keep renderer parameter inference. */
+export function makeReadResultTool(reader: Pick<ScopedReader, "read">) {
+	return defineTool<typeof Params, PageDetails>({
+		name: "read_result",
+		label: "Read result",
+		description: "Read one bounded page of a terminal result explicitly granted by your supervisor. Use only a supplied result:<UUID> reference. Follow nextOffset for another page; endOfStoredBody ends the retained report, which may be truncated. No search, paths, live runs or polling.",
+		parameters: Params,
+		async execute(_id, request, signal) {
+			if (signal?.aborted) throw new Error(readFailure("cancelled").message);
+			if (!isReadRequest(request)) throw new Error(readFailure("invalid").message);
+			let result: ReadReply;
+			try { result = await reader.read(request, signal); }
+			catch { throw new Error(readFailure(signal?.aborted ? "cancelled" : "unavailable").message); }
+			if (signal?.aborted) throw new Error(readFailure("cancelled").message);
+			try {
+				if (!isReadReplyFor(result, request)) throw new Error();
+			} catch { throw new Error(readFailure("protocol").message); }
+			if (!result.ok) throw new Error(result.message);
+			const { body, ...details } = result;
+			return { content: [{ type: "text", text: `${JSON.stringify(details)}\n${fenceUntrusted(body)}` }], details };
+		},
+		renderCall(args, theme) {
+			const ref = compactInlineText(args.ref ?? "", { maxChars: 48 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("read_result"))}${ref ? ` ${theme.fg("dim", ref)}` : ""}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme, context) {
+			// The granted page IS literal content: the shared renderer bounds it collapsed with an
+			// expansion hint and shows the complete sanitized receipt (details line + fenced body)
+			// expanded; native context.isError drives the failure heading.
+			return renderLiteralToolResult(result, { expanded }, theme, context);
+		},
+	});
+}

package/src/tools/timer.ts

@@ -1,9 +1,12 @@
 /** Session timer tool — arm a wall-clock wake. */
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 import { armWakeAdvice, failureDetails } from "../extension/shared.ts";
 import { formatRemaining, type TimerScheduler } from "../core/timer.ts";
-import { parseInstant } from "../core/time.ts";
+import { formatDuration, parseInstant } from "../core/time.ts";
+import { compactInlineText } from "../ui/presentation.ts";
+import { renderLiteralToolResult } from "../ui/literal-tool-result.ts";
 import { readClockSnapshot } from "../extension/clock.ts";
 
 export interface TimerToolDeps {
@@ -97,7 +100,25 @@ export function registerTimerTool(pi: ExtensionAPI, d: TimerToolDeps): void {
 			}
 			const e = r.entry;
 			const text = `Armed ${e.id} (${e.label}) — fires in ${formatRemaining(r.remainingMs ?? e.fireAtEpochMs - e.armedAtEpochMs)} [${new Date(e.fireAtEpochMs).toISOString()}]. ${armWakeAdvice(ctx, "alarm", "time-gated step", "You can end this turn now; keep the session open for the alarm.")}`;
-			return { content: [{ type: "text", text }], details: { action: "arm", id: e.id, fireAtEpochMs: e.fireAtEpochMs, ok: true }, isError: false };
+			return { content: [{ type: "text", text }], details: { action: "arm", id: e.id, fireAtEpochMs: e.fireAtEpochMs, label: compactInlineText(e.label, { maxChars: 120 }), ok: true }, isError: false };
+		},
+		renderCall(args, theme) {
+			const action = compactInlineText(args.action ?? "", { maxChars: 12 });
+			const label = compactInlineText(args.label ?? args.id ?? "", { maxChars: 96 });
+			return new Text(`${theme.fg("toolTitle", theme.bold(`timer ${action}`))}${label ? ` ${theme.fg("dim", label)}` : ""}`, 0, 0);
+		},
+		renderResult(result, { expanded }, theme, context) {
+			const details = (result.details ?? {}) as { action?: string; ok?: boolean; id?: string; label?: string; fireAtEpochMs?: number };
+			const failed = context?.isError ?? result.isError ?? false;
+			const fireAt = typeof details.fireAtEpochMs === "number" ? details.fireAtEpochMs : undefined;
+			const isArm = !failed && details.action === "arm" && details.ok === true && fireAt !== undefined;
+			// Failures and every now/list/cancel receipt share the one literal renderer:
+			// error heading, bounded sanitized preview, expansion hint.
+			if (!isArm || expanded) return renderLiteralToolResult(result, { expanded }, theme, context);
+			const left = fireAt - Date.now();
+			const due = left > 0 ? `fires in ${formatDuration(left)}` : "due now";
+			const summary = compactInlineText(`${details.label ?? details.id ?? "alarm"} · ${due}`, { maxChars: 140 });
+			return new Text(`${theme.fg("toolTitle", theme.bold("armed "))}${theme.fg("accent", summary)}`, 0, 0);
 		},
 	});
 }

package/src/ui/agent-overlay.ts

@@ -23,7 +23,7 @@ import {
 	wrapTextWithAnsi,
 } from "@earendil-works/pi-tui";
 
-import { type AgentNode, type AgentTree, type FlatRow, deriveWaitingNodeIds, flattenTree, isWakeSource, nodeGlyph, runningAnnotation } from "./agent-tree.ts";
+import { type AgentNode, type AgentTree, type FlatRow, deriveWaitingNodeIds, effortTag, flattenTree, isWakeSource, nodeGlyph, runningAnnotation, thinkingDetailLine } from "./agent-tree.ts";
 import { LiveClock } from "./live-clock.ts";
 import { visibleWindow } from "./model-picker.ts";
 import { compactInlineText, OPEN_SEQUENCE_TAIL, sanitizeTerminalText } from "./presentation.ts";
@@ -77,8 +77,12 @@ export function composeAgentRow(input: AgentRowInput): string {
 
 	const prefixCols = 2 + visibleWidth(indent); // "▸ " or "  ", then the indent
 	const avail = Math.max(0, bodyMax - prefixCols - 2); // 2 = glyph + space
-	const labelMax = Math.max(8, Math.floor(avail * 0.62));
-	const label = safeInline(node.label, labelMax) || "agent";
+	// The compact effort sigla rides the label (` · xh` / ` · xh→h`); its width comes out of the
+	// label budget so the appended field never becomes the part a tight row eats first. The final
+	// clamp below still guarantees the row fits either way.
+	const effort = effortTag(node.thinking, node.thinkingEffective);
+	const labelMax = Math.max(8, Math.floor(avail * 0.62) - visibleWidth(effort));
+	const label = (safeInline(node.label, labelMax) || "agent") + effort;
 	const detailMax = node.detail ? Math.max(0, avail - labelMax - 2) : 0;
 	const detail = detailMax > 0 ? safeInline(node.detail ?? "", detailMax) : "";
 	const detailText = detail ? t.fg("dim", `  ${detail}`) : "";
@@ -383,6 +387,10 @@ export class AgentOverlay extends Container {
 			new Text(`${nodeGlyph(node)} ${t.fg("accent", t.bold(safeInline(node.label) || "agent"))}${live ? t.fg("success", wake ? "  ● armed" : "  ● live") : ""}`, 1, 0),
 		);
 		if (node.detail) this.addChild(new Text(t.fg("dim", safeInline(node.detail)), 1, 0));
+		// The drill-in has room for FULL effort names (the rows stay compact): an observed level
+		// appears only once a terminal result actually reported one.
+		const effortLine = thinkingDetailLine(node.thinking, node.thinkingEffective);
+		if (effortLine) this.addChild(new Text(t.fg("dim", effortLine), 1, 0));
 		this.addChild(new Spacer(1));
 
 		const raw = node.output?.trim()

package/src/ui/agent-tree.ts

@@ -1,5 +1,7 @@
 import { compactTokens } from "../core/format.ts";
+import { effortFullName, effortSigla } from "../core/leg-thinking.ts";
 import { formatDuration } from "../core/time.ts";
+import type { ThinkingLevel } from "../core/types.ts";
 import type { ChildUsage } from "../engine/stream.ts";
 import { compactInlineText } from "./presentation.ts";
 import { formatUsage } from "./usage.ts";
@@ -25,6 +27,13 @@ export interface AgentNode {
 	/** Configured agent definition (operator/reviewer/…), if known. */
 	agent?: string;
 	model?: string;
+	/** Requested per-leg thinking effort, known at launch (the spec-level value the launch row
+	 *  carried). Rendered as the compact sigla right after the model; absent/off render nothing. */
+	thinking?: ThinkingLevel;
+	/** Observed effective Pi effort from the terminal result. Set ONLY from a real
+	 *  AgentResult.thinkingEffective (never invented); when it diverges from `thinking`, the row
+	 *  renders the honest `xh→h` form. */
+	thinkingEffective?: ThinkingLevel;
 	/** A short trailing annotation (usage, current activity), shown after the label. */
 	detail: string | undefined;
 	/** The agent's output buffer, shown when the user drills into the node. */
@@ -88,6 +97,28 @@ export interface RenderOptions {
 	waitingForSupervisor?: ReadonlySet<string>;
 }
 
+/** The frozen compact effort tag for a tree/overlay row: ` · xh` after the model, or ` · xh→h`
+ *  when the terminal result reported a DIFFERENT observed effective level. `off`/absent render
+ *  nothing — absence means off, and an observation is never invented: the divergence form shows
+ *  only when both sides are known and genuinely differ (an observed `off` never leaves a dangling
+ *  `→`). Pure. */
+export function effortTag(requested: ThinkingLevel | undefined, effective?: ThinkingLevel): string {
+	const req = requested !== undefined ? effortSigla(requested) : "";
+	if (!req) return "";
+	const obs = effective !== undefined ? effortSigla(effective) : "";
+	return obs && obs !== req ? ` · ${req}→${obs}` : ` · ${req}`;
+}
+
+/** The F9 drill-in line for a leg's effort — FULL names, the drill-in has the room (the compact
+ *  siglas live only on the rows): `thinking: requested xhigh → observed high`. Same honesty rules
+ *  as {@link effortTag}; the line is omitted entirely when nothing was requested. Pure. */
+export function thinkingDetailLine(requested: ThinkingLevel | undefined, effective?: ThinkingLevel): string {
+	const req = requested !== undefined ? effortFullName(requested) : "";
+	if (!req) return "";
+	const obs = effective !== undefined && effective !== requested ? effortFullName(effective) : "";
+	return obs ? `thinking: requested ${req} → observed ${obs}` : `thinking: requested ${req}`;
+}
+
 /** Whether `detail` is the literal "queued" marker a seeded-but-not-yet-live leg carries — shared
  *  by `runningAnnotation` (suppresses the clock) and `telemetryStatus` (`extension.ts`, reports the
  *  `queued` state). One predicate so the two readings of the marker cannot drift apart. */
@@ -179,7 +210,10 @@ export function renderAgentTree(nodes: AgentNode[], opts: RenderOptions = {}): s
 			const isRoot = parentId === undefined;
 			const isLast = i === kids.length - 1;
 			const branch = isRoot ? "" : isLast ? "└─ " : "├─ ";
-			const label = safeInline(node.label) || safeInline(node.id) || "agent";
+			const base = safeInline(node.label) || safeInline(node.id) || "agent";
+			// The compact effort sigla rides AFTER the label clamp — the existing per-part clipping is
+			// untouched; the appended field is at most ` · xh→h` wide.
+			const label = `${base}${effortTag(node.thinking, node.thinkingEffective)}`;
 			const detailText = node.detail ? safeInline(node.detail) : "";
 			const clock = opts.now !== undefined ? runningAnnotation(node, opts.now, opts.stallMs ?? 0, opts.waitingForSupervisor?.has(node.id) ?? false) : undefined;
 			const tail = [detailText, clock].filter((s): s is string => Boolean(s)).join(" · ");
@@ -267,6 +301,8 @@ export interface AddNodeInput {
 	kind?: AgentNodeKind;
 	agent?: string;
 	model?: string;
+	thinking?: ThinkingLevel;
+	thinkingEffective?: ThinkingLevel;
 	detail?: string;
 	output?: string;
 	startedAt?: number;
@@ -279,6 +315,8 @@ export interface AgentNodePatch {
 	kind?: AgentNodeKind;
 	agent?: string;
 	model?: string;
+	thinking?: ThinkingLevel;
+	thinkingEffective?: ThinkingLevel;
 	detail?: string;
 	output?: string;
 	startedAt?: number;
@@ -293,6 +331,8 @@ function applyPatch(node: AgentNode, patch: AgentNodePatch): void {
 	if (patch.kind !== undefined) node.kind = patch.kind;
 	if (patch.agent !== undefined) node.agent = patch.agent;
 	if (patch.model !== undefined) node.model = patch.model;
+	if (patch.thinking !== undefined) node.thinking = patch.thinking;
+	if (patch.thinkingEffective !== undefined) node.thinkingEffective = patch.thinkingEffective;
 	if (patch.detail !== undefined) node.detail = patch.detail;
 	if (patch.output !== undefined) node.output = patch.output;
 	if (patch.startedAt !== undefined) node.startedAt = patch.startedAt;
@@ -333,6 +373,8 @@ export class AgentTree {
 			...(input.kind !== undefined ? { kind: input.kind } : {}),
 			...(input.agent !== undefined ? { agent: input.agent } : {}),
 			...(input.model !== undefined ? { model: input.model } : {}),
+			...(input.thinking !== undefined ? { thinking: input.thinking } : {}),
+			...(input.thinkingEffective !== undefined ? { thinkingEffective: input.thinkingEffective } : {}),
 			...(input.output !== undefined ? { output: input.output } : {}),
 			...(input.dueAt !== undefined ? { dueAt: input.dueAt } : {}),
 		};

package/src/ui/literal-tool-result.ts

@@ -5,7 +5,7 @@ import { compactVisibleText, sanitizeTerminalText } from "./presentation.ts";
 
 interface LiteralResult {
 	content: readonly { type: string; text?: string }[];
-	/** Legacy direct renderer calls may carry this; the native host passes it in context. */
+	/** Direct internal renderer calls carry this; Pi passes it in the render context. */
 	isError?: boolean;
 }
 

package/src/ui/model-picker.ts

@@ -217,7 +217,7 @@ export class ModelPicker extends Container implements Focusable {
 			return;
 		} else {
 			const before = this.input.getValue();
-			// Input has no per-instance keybindings API (Pi 1.3/1.4). Scope its global
+			// Input has no per-instance keybindings API (Pi 1.4). Scope its global
 			// lookup to this synchronous call and restore it even if handling throws.
 			const global = getKeybindings();
 			try {

package/src/ui/orchestration-launch.ts

@@ -0,0 +1,49 @@
+/** Persisted orchestration launch requests. Rendering never consults live persona or model settings. */
+import { resolveLegThinking } from "../core/leg-thinking.ts";
+import type { ThinkingLevel } from "../core/types.ts";
+import type { ModelParticipant, ModelSource } from "../persona/model-participants.ts";
+import { compactInlineText, sanitizeTerminalText } from "./presentation.ts";
+
+export interface OrchestrationLaunchParticipant {
+	key: string;
+	label: string;
+	agent: string;
+	model?: string;
+	modelSource: ModelSource;
+	thinkingRequested?: ThinkingLevel;
+	setupPending: boolean;
+	param?: string;
+	phase?: string;
+}
+
+export interface OrchestrationLaunchSnapshot {
+	participants: OrchestrationLaunchParticipant[];
+	unavailable?: true;
+}
+
+export function snapshotOrchestrationParticipants(
+	participants: readonly ModelParticipant[],
+	opts: { agentThinking(agent: string): ThinkingLevel | undefined; childThinking: unknown; pendingKeys: ReadonlySet<string> },
+): OrchestrationLaunchSnapshot {
+	return { participants: participants.map((p) => {
+		const agentThinking = opts.agentThinking(p.agent);
+		const thinkingRequested = resolveLegThinking(p, agentThinking ? { thinking: agentThinking } : {}, opts.childThinking);
+		return { key: p.key, label: p.label, agent: p.agent, modelSource: p.source, setupPending: !p.assigned && opts.pendingKeys.has(p.key),
+			...(p.model ? { model: p.model } : {}), ...(thinkingRequested ? { thinkingRequested } : {}), ...(p.param ? { param: p.param } : {}) };
+	}) };
+}
+
+/** Three individually bounded rows collapsed; expansion retains every participant and full model ref. */
+export function orchestrationLaunchLines(snapshot: OrchestrationLaunchSnapshot | undefined, expanded: boolean): string[] {
+	if (!snapshot || snapshot.unavailable) return ["Launch metadata unavailable"];
+	const rows = expanded ? snapshot.participants : snapshot.participants.slice(0, 3);
+	const lines = rows.map((p) => {
+		const clean = (value: string, maxChars: number): string => expanded ? sanitizeTerminalText(value) : compactInlineText(value, { maxChars });
+		const label = clean(`${p.phase ? `${p.phase} / ` : ""}${p.label}${p.param ? ` [${p.param}]` : ""}`, 48);
+		const model = p.model ? clean(p.model, 64) : "unknown";
+		const modelText = p.setupPending ? `model pending (current default ${model}; setup may change)` : `requested model ${model}`;
+		return `  ${label} · ${modelText} · requested effort ${p.thinkingRequested ?? "unknown"}`;
+	});
+	if (!expanded && snapshot.participants.length > rows.length) lines.push(`  +${snapshot.participants.length - rows.length} more · expand for launch details`);
+	return lines;
+}