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

package/extensions/plan/web-client.ts

@@ -25,6 +25,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   var token = typeof data.token === "string" ? data.token : "";
   var annotations = Array.isArray(data.annotations) ? data.annotations.slice() : [];
   var saved = false;
+  var approved = false;
   var closed = false;
   var connected = null;
   var everConnected = false;
@@ -37,6 +38,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   var planEl = document.getElementById("plan");
   var statusEl = document.getElementById("status");
   var stateEl = document.getElementById("review-state");
+  var approveButton = document.getElementById("approve");
   var saveButton = document.getElementById("save");
   var cancelButton = document.getElementById("cancel");
   var outlineList = document.getElementById("outline-list");
@@ -62,9 +64,15 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     if (!stateEl) return;
     var label;
     var tone = "";
-    if (saved) {
+    if (approved) {
+      label = "Approved";
+      tone = "success";
+    } else if (saved) {
       label = "Saved";
       tone = "success";
+    } else if (closed) {
+      // Settled by the user, not by a dropped stream: never flash Offline.
+      label = "Closed";
     } else if (connected === true) {
       label = "Connected";
       tone = "success";
@@ -78,7 +86,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     }
     var count = annotations.length;
     label += " \u00b7 " + count + (count === 1 ? " comment" : " comments");
-    if (dirty && !saved) {
+    if (dirty && !saved && !approved && !closed) {
       label += " \u00b7 unsaved";
       if (!tone) tone = "warn";
     }
@@ -254,9 +262,14 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
       return;
     }
     if (block.kind === "list") {
+      var items = [];
       lines.forEach(function (line) {
         var match = /^(\s*)([-*+]|\d+[.)])\s+(.*)$/.exec(line);
         if (!match) {
+          // A following unmarked line is a CommonMark lazy continuation of the
+          // item above; join it so the paragraph hangs under the item's text.
+          var last = items[items.length - 1];
+          if (last) { if (line.trim()) last.rest += " " + line.trim(); return; }
           var plain = el("p"); renderInline(plain, line); wrap.appendChild(plain); return;
         }
         var row = el("div", "bf-block__li");
@@ -272,9 +285,12 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
           rest = box[2];
         }
         marker.textContent = markerText;
-        var body = el("span"); renderInline(body, rest);
+        var body = el("span");
         row.appendChild(marker); row.appendChild(body); wrap.appendChild(row);
+        items.push({ body: body, rest: rest });
       });
+      // Render each body once, after its continuation lines are collected.
+      items.forEach(function (item) { renderInline(item.body, item.rest); });
       return;
     }
     var paragraph = el("p");
@@ -600,6 +616,7 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   }
 
   function lockActions() {
+    if (approveButton) approveButton.disabled = true;
     if (saveButton) saveButton.disabled = true;
     if (cancelButton) cancelButton.disabled = true;
   }
@@ -618,51 +635,67 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     controls.appendChild(reload);
   }
 
-  function save() {
-    if (saved) return;
-    setStatus("Saving\u2026");
-    fetch("/api/feedback?token=" + encodeURIComponent(token), {
+  // Save and approve share the same POST shape; only the route, the settled
+  // flag, and the wording differ. Both persist the current annotations.
+  function submit(url, okText, failText, mark) {
+    fetch(url + "?token=" + encodeURIComponent(token), {
       method: "POST",
       headers: { "Content-Type": "application/json" },
       body: JSON.stringify({ annotations: annotations })
     }).then(function (response) {
       if (response.ok) {
-        saved = true;
+        mark();
         dirty = false;
-        setStatus("Saved \u2014 return to Pi to continue.", "saved");
+        setStatus(okText, "saved");
         lockActions();
         updateState();
         return;
       }
       if (response.status === 409) {
         setStatus("The plan changed on disk \u2014 reload to review again.", "error");
+        if (approveButton) approveButton.disabled = true;
         if (saveButton) saveButton.disabled = true;
         offerReload();
         return;
       }
       throw new Error("server returned " + response.status);
     }).catch(function (error) {
-      setStatus("Could not save: " + error.message, "error");
+      setStatus(failText + error.message, "error");
     });
   }
 
+  function save() {
+    if (saved || approved || closed) return;
+    setStatus("Saving\u2026");
+    submit("/api/feedback", "Saved \u2014 return to Pi to continue.", "Could not save: ", function () { saved = true; });
+  }
+
+  function approve() {
+    if (saved || approved || closed) return;
+    setStatus("Approving\u2026");
+    submit("/api/approve", "Approved \u2014 return to Pi to continue.", "Could not approve: ", function () { approved = true; });
+  }
+
   function cancel() {
-    if (saved || closed) return;
+    if (saved || approved || closed) return;
     closed = true;
     lockActions();
     setStatus("Closing\u2026");
+    updateState();
     fetch("/api/cancel?token=" + encodeURIComponent(token), { method: "POST" }).catch(function () {}).then(function () {
-      setStatus("Closed without saving.");
+      setStatus("Closed \u2014 return to Pi.");
+      updateState();
     });
   }
 
+  if (approveButton) approveButton.addEventListener("click", approve);
   if (saveButton) saveButton.addEventListener("click", save);
   if (cancelButton) cancelButton.addEventListener("click", cancel);
 
   // Remember a selection made inside a block so clicking the rail button can
   // still quote it after the button press has collapsed the selection.
   document.addEventListener("mouseup", function (event) {
-    if (!planEl || saved) return;
+    if (!planEl || saved || approved || closed) return;
     var wrap = event.target && event.target.closest ? event.target.closest(".bf-block") : null;
     var quote = wrap && !wrap.querySelector(".bf-composer") ? selectionIn(wrap) : "";
     pendingQuote = wrap && quote ? { wrap: wrap, quote: quote } : null;
@@ -692,7 +725,13 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
   }
 
   document.addEventListener("keydown", function (event) {
-    if (event.key === "Escape") { closeComposer(); toggleKeys(false); return; }
+    if (event.key === "Escape") {
+      // Esc peels one layer at a time: the composer, then the sheet, then the review.
+      if (planEl && planEl.querySelector(".bf-composer")) { closeComposer(); return; }
+      if (keysDialog && !keysDialog.hidden) { toggleKeys(false); return; }
+      cancel();
+      return;
+    }
     if (typing(event.target)) return;
     if (event.metaKey || event.ctrlKey || event.altKey) return;
     if (event.key === "?") { event.preventDefault(); toggleKeys(); return; }
@@ -701,11 +740,12 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     if (event.key === "j") { event.preventDefault(); moveActive(1); return; }
     if (event.key === "k") { event.preventDefault(); moveActive(-1); return; }
     if (event.key === "c") { event.preventDefault(); commentOnActive(); return; }
+    if (event.key === "a" && approveButton) { event.preventDefault(); approve(); return; }
     if (event.key === "s") { event.preventDefault(); save(); return; }
   });
 
   window.addEventListener("beforeunload", function () {
-    if (saved || closed) return;
+    if (saved || approved || closed) return;
     var url = "/api/cancel?token=" + encodeURIComponent(token);
     if (navigator.sendBeacon) navigator.sendBeacon(url);
   });
@@ -718,8 +758,9 @@ export const REVIEW_CLIENT_JS = String.raw`(function () {
     var stream = new EventSource("/events?token=" + encodeURIComponent(token));
     stream.addEventListener("open", function () { connected = true; everConnected = true; updateState(); });
     stream.addEventListener("error", function () {
-      // The server ends the stream on save; keep showing Saved rather than Offline.
-      if (!saved) { connected = false; updateState(); }
+      // The server ends the stream once the review is settled; keep showing the
+      // terminal state rather than Offline.
+      if (!saved && !approved && !closed) { connected = false; updateState(); }
     });
   } catch (error) {
     // The server still sees the POST; the stream is only for close detection.

package/extensions/plan/web-page.ts

@@ -49,6 +49,8 @@ export interface ReviewPageData {
 	outline: ReviewOutlineItem[];
 	/** Highlighted HTML per line, keyed by the code block's 0-based start line. */
 	code: Record<string, string[]>;
+	/** Whether the review may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove: boolean;
 	/** Per-session secret the client echoes on every request. */
 	token: string;
 }
@@ -116,7 +118,7 @@ ${WEB_COMPONENTS_CSS}
 .bf-block__li{display:flex;gap:8px;margin:4px 0;line-height:var(--lh-relaxed)}
 .bf-block__marker{flex:0 0 auto;min-width:1.4em;color:var(--muted)}
 .bf-block__marker--done{color:var(--success)}
-.bf-block code{font-family:var(--font-mono);font-size:.9em;background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-sm);padding:.1em .35em}
+.bf-block code{font-family:var(--font-mono);font-size:.9em;background:var(--surface);border-radius:var(--radius-sm);padding:.1em .35em}
 .bf-block pre.bf-code{margin:11px 0;padding:var(--space-3) 0;overflow:auto;background:var(--surface);border:1px solid var(--border);border-radius:var(--radius-md);font:var(--fs-code)/1.55 var(--font-mono);tab-size:4;flex:none}
 .bf-block pre.bf-code code{background:none;border:0;padding:0;font-size:inherit}
 .bf-block pre.bf-code .bf-code__line{display:block;padding:0 14px;white-space:pre;min-height:1.55em}
@@ -170,20 +172,36 @@ ${WEB_COMPONENTS_CSS}
 @media (hover:none){.bf-block__add{opacity:1}}
 `.trim();
 
+/**
+ * The sidebar's one-line keyboard reminder. It names the keys a reviewer reaches
+ * for first and defers to the shortcut sheet (`?`) for the rest, so the line does
+ * not have to grow every time a binding is added.
+ */
+function reviewHints(canApprove: boolean): string {
+	const approve = canApprove ? `, <kbd class="review-kbd">a</kbd> to approve` : "";
+	return `<p class="review-hints">Press <kbd class="review-kbd">j</kbd>/<kbd class="review-kbd">k</kbd> to move, <kbd class="review-kbd">c</kbd> to comment${approve}, <kbd class="review-kbd">s</kbd> to save, <kbd class="review-kbd">?</kbd> for all shortcuts.</p>`;
+}
+
 /** The keyboard sheet, hidden until the client opens it. */
-const KEYS_DIALOG = `<div class="bf-dialog" id="keys-dialog" hidden>
+function keysDialog(canApprove: boolean): string {
+	const approveRow = canApprove
+		? `<div><dt><kbd class="review-kbd">a</kbd></dt><dd>Approve and run the plan</dd></div>
+`
+		: "";
+	return `<div class="bf-dialog" id="keys-dialog" hidden>
 <div class="bf-dialog__panel" role="dialog" aria-modal="true" aria-labelledby="keys-title">
 <div class="bf-dialog__head"><h2 id="keys-title">Keyboard shortcuts</h2><span class="bf-spacer"></span><button type="button" class="bf-btn" id="keys-close">Close</button></div>
 <dl class="review-keys">
-<div><dt><kbd class="review-kbd">j</kbd> <kbd class="review-kbd">k</kbd></dt><dd>Next and previous block</dd></div>
+${approveRow}<div><dt><kbd class="review-kbd">j</kbd> <kbd class="review-kbd">k</kbd></dt><dd>Next and previous block</dd></div>
 <div><dt><kbd class="review-kbd">c</kbd></dt><dd>Comment on the current block</dd></div>
 <div><dt><kbd class="review-kbd">Enter</kbd></dt><dd>Add the comment you are writing</dd></div>
 <div><dt><kbd class="review-kbd">s</kbd></dt><dd>Save feedback and return to Pi</dd></div>
-<div><dt><kbd class="review-kbd">Esc</kbd></dt><dd>Close the composer or this sheet</dd></div>
+<div><dt><kbd class="review-kbd">Esc</kbd></dt><dd>Close the composer, the sheet, or the review</dd></div>
 <div><dt><kbd class="review-kbd">?</kbd></dt><dd>Toggle this sheet</dd></div>
 </dl>
 </div>
 </div>`;
+}
 
 /**
  * Render the review page for `data`. The markup is a fixed shell; the client
@@ -200,11 +218,18 @@ export function renderReviewPage(data: ReviewPageData): string {
 <div class="bf-panel review-panel">
 ${reviewFacts()}
 <nav class="review-nav" aria-labelledby="outline-title"><p class="review-nav__title" id="outline-title">Sections</p><ul id="outline-list"></ul></nav>
-<p class="review-hints">Press <kbd class="review-kbd">j</kbd>/<kbd class="review-kbd">k</kbd> to move, <kbd class="review-kbd">c</kbd> to comment, <kbd class="review-kbd">s</kbd> to save.</p>
+${reviewHints(data.canApprove)}
 </div>
 </details>
 `
 		: "";
+	// Approve is the decisive action, so it takes the primary button and Save is
+	// demoted; a comment-only review has no approve button and keeps Save primary.
+	const approveButton = data.canApprove
+		? `
+<button type="button" class="bf-btn bf-btn--primary" id="approve">Approve &amp; run</button>`
+		: "";
+	const saveButton = `<button type="button" class="${data.canApprove ? "bf-btn" : "bf-btn bf-btn--primary"}" id="save">Save feedback</button>`;
 	return `<!doctype html>
 <html lang="en">
 <head>
@@ -221,15 +246,15 @@ ${brandLockup("plan review")}
 <span class="bf-status review-status" id="status" role="status" aria-live="polite"></span>
 <div class="review-controls">
 ${themeToggle()}
-<button type="button" class="bf-btn bf-btn--icon" id="shortcuts" aria-label="Keyboard shortcuts" title="Keyboard shortcuts">?</button>
-<button type="button" class="bf-btn bf-btn--primary" id="save">Save feedback</button>
-<button type="button" class="bf-btn" id="cancel">Close</button>
+<button type="button" class="bf-btn bf-btn--icon" id="shortcuts" aria-label="Keyboard shortcuts" title="Keyboard shortcuts">?</button>${approveButton}
+${saveButton}
+<button type="button" class="bf-btn" id="cancel">Back to Pi</button>
 </div>
 </div><div class="review-progress" aria-hidden="true"><span class="review-progress__fill" id="progress-fill"></span></div></header>
 <div class="${bodyClass}">
 ${outlinePanel}<main class="bf-app__main bf-review" id="plan" aria-label="Plan"></main>
 </div>
-${KEYS_DIALOG}
+${keysDialog(data.canApprove)}
 <script type="application/json" id="review-data">${island}</script>
 <script src="/client.js" defer></script>
 </body>

package/extensions/plan/web-router.ts

@@ -12,9 +12,9 @@
  * local page from driving the session.
  */
 
-import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { THEME_JS } from "../../lib/web/index.ts";
 import { coerceAnnotations, type PlanAnnotation } from "./feedback.ts";
+import { REVIEW_CLIENT_JS } from "./web-client.ts";
 import { renderReviewPage, type ReviewPageData } from "./web-page.ts";
 
 /** What a save callback reports back. */
@@ -24,12 +24,16 @@ export type SaveResult = { ok: true } | { ok: false; status: number; message: st
 export interface ReviewContext {
 	/** Per-session secret required on the page, event stream, and API routes. */
 	token: string;
+	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove: boolean;
 	/** Build the page data (recomputed per request from the current plan). */
 	page: () => Promise<ReviewPageData>;
 	/** Persist the annotations and report the outcome. */
 	save: (annotations: PlanAnnotation[]) => Promise<SaveResult>;
 	/** Called after a successful save; the server resolves the session once the response has flushed. */
 	onSaved: (annotations: PlanAnnotation[]) => void;
+	/** Called after a successful approve; the server resolves the session once the response has flushed. */
+	onApprove: (annotations: PlanAnnotation[]) => void;
 	/** Called when the user cancels; the server resolves the session once the response has flushed. */
 	onCancel: () => void;
 }
@@ -80,6 +84,27 @@ function errorResponse(status: number, message: string): ServeResponse {
 	return jsonResponse(status, { error: message });
 }
 
+/**
+ * Parse and validate an `{ annotations }` request body. Returns the annotations,
+ * or an error response to send instead.
+ */
+function parseAnnotations(body: string): PlanAnnotation[] | ServeResponse {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(body);
+	} catch {
+		return errorResponse(400, "The request body must be JSON.");
+	}
+	const annotations = coerceAnnotations((parsed as { annotations?: unknown } | null)?.annotations);
+	if (!annotations) return errorResponse(400, "The annotations are malformed.");
+	return annotations;
+}
+
+/** A parsed body is either the annotations or the error response to send. */
+function isResponse(value: PlanAnnotation[] | ServeResponse): value is ServeResponse {
+	return !Array.isArray(value);
+}
+
 /** Validate method and `Host`; returns an error response to send instead. */
 function checkEnvelope(
 	method: string,
@@ -139,19 +164,25 @@ export async function handleReviewRequest(
 	}
 	if (pathname === "/api/feedback") {
 		if (method.toUpperCase() !== "POST") return errorResponse(405, "Use POST to save feedback.");
-		let parsed: unknown;
-		try {
-			parsed = JSON.parse(body);
-		} catch {
-			return errorResponse(400, "The request body must be JSON.");
-		}
-		const annotations = coerceAnnotations((parsed as { annotations?: unknown } | null)?.annotations);
-		if (!annotations) return errorResponse(400, "The annotations are malformed.");
+		const annotations = parseAnnotations(body);
+		if (isResponse(annotations)) return annotations;
 		const result = await ctx.save(annotations);
 		if (!result.ok) return errorResponse(result.status, result.message);
 		ctx.onSaved(annotations);
 		return jsonResponse(200, { ok: true });
 	}
+	if (pathname === "/api/approve") {
+		if (method.toUpperCase() !== "POST") return errorResponse(405, "Use POST to approve.");
+		// Only the exit_plan_mode flow owns the approval side effects, so a comment-only
+		// review refuses this even if a client posts it directly.
+		if (!ctx.canApprove) return errorResponse(403, "This review cannot be approved from the browser.");
+		const annotations = parseAnnotations(body);
+		if (isResponse(annotations)) return annotations;
+		const result = await ctx.save(annotations);
+		if (!result.ok) return errorResponse(result.status, result.message);
+		ctx.onApprove(annotations);
+		return jsonResponse(200, { ok: true });
+	}
 
 	return errorResponse(404, "That page does not exist.");
 }

package/extensions/plan/web.ts

@@ -24,6 +24,7 @@ import type { ReviewPageData } from "./web-page.ts";
 /** How a browser review ended. */
 export type PlanReviewResult =
 	| { status: "saved"; plan: StoredPlan; annotations: PlanAnnotation[] }
+	| { status: "approved"; plan: StoredPlan; annotations: PlanAnnotation[] }
 	| { status: "cancelled" };
 
 /** A running review the caller awaits and then closes. */
@@ -38,9 +39,17 @@ export interface PlanReviewSession {
 	close(): Promise<void>;
 }
 
+/** Per-session options for {@link PlanWebReview.start}. */
+export interface PlanReviewOptions {
+	/** Abort signal; aborting closes the session as cancelled. */
+	signal?: AbortSignal;
+	/** Whether the browser may approve the plan (only the `exit_plan_mode` flow). */
+	canApprove?: boolean;
+}
+
 /** Starts and tracks review sessions. */
 export interface PlanWebReview {
-	start(cwd: string, plan: StoredPlan, signal?: AbortSignal): Promise<PlanReviewSession | undefined>;
+	start(cwd: string, plan: StoredPlan, options?: PlanReviewOptions): Promise<PlanReviewSession | undefined>;
 	/** Stop every running session (session shutdown). */
 	closeAll(): Promise<void>;
 }
@@ -96,7 +105,13 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 	// review turns (and its saved browser theme with it).
 	const ports = new Map<string, number>();
 
-	const start = async (cwd: string, plan: StoredPlan, signal?: AbortSignal): Promise<PlanReviewSession | undefined> => {
+	const start = async (
+		cwd: string,
+		plan: StoredPlan,
+		options: PlanReviewOptions = {},
+	): Promise<PlanReviewSession | undefined> => {
+		const { signal } = options;
+		const canApprove = options.canApprove === true;
 		const token = (deps.token ?? (() => randomBytes(16).toString("hex")))();
 		let settled = false;
 		let resolveDone!: (result: PlanReviewResult) => void;
@@ -147,6 +162,7 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 				})),
 				code,
 				token,
+				canApprove,
 			};
 		};
 
@@ -166,11 +182,15 @@ export function createPlanWebReview(store: PlanStore, deps: PlanWebReviewDeps =
 
 		const context: ReviewContext = {
 			token,
+			canApprove,
 			page,
 			save,
 			onSaved: (annotations) => {
 				pendingResult = savedPlan ? { status: "saved", plan: savedPlan, annotations } : { status: "cancelled" };
 			},
+			onApprove: (annotations) => {
+				pendingResult = savedPlan ? { status: "approved", plan: savedPlan, annotations } : { status: "cancelled" };
+			},
 			onCancel: () => {
 				pendingResult = { status: "cancelled" };
 			},

package/extensions/question/README.md

@@ -4,12 +4,20 @@ A single model-facing tool, `ask_user_question`, that lets the model ask the
 human one or more structured questions mid-turn and wait for typed answers.
 Modelled on Claude Code's `AskUserQuestion`.
 
+<img src="../../assets/question.png" alt="The ask_user_question dialog: Auth and Scope tabs, a question, four numbered options with descriptions, and the navigation hint" width="100%">
+
 ```
 pi --extension ./extensions/question   # load just this extension
 pi -e .                                # load the whole @gavin-hu/my-pi-agent package
 pi install ./                          # install the package
 ```
 
+## Tool rendering
+
+How the `ask_user_question` call and its result look in the transcript — the call line as a headline and the body indented under it:
+
+<img src="../../assets/tools/ask_user_question.png" alt="The ask_user_question tool's call and result: the call line and an indented body with the question headers, the options, and the answers" width="100%">
+
 ## What it does
 
 The model calls `ask_user_question` with 1–4 questions. Each question offers up
@@ -162,7 +170,11 @@ None in v1 — the tool is either available (a UI exists) or not.
 - **Transcript rendering is driven by `details`.** `renderCall` summarises the
   question count and headers and lists one option line per question;
   `renderResult` renders `✓ Auth: 1. OAuth` per answer, `(wrote)` for custom
-  text, warning-colored `Cancelled`, and dim `No UI` when unavailable.
+  text, warning-colored `Cancelled`, and dim `No UI` when unavailable. The call
+  summary reads the call's *streaming* args, so a field that has not arrived yet
+  — a question `header`, an option `label` — reads as absent instead of
+  throwing; a throwing renderer makes Pi fall back to its own call line, a
+  column to the left of the framed one.
 
 ## Files
 

package/extensions/question/answers.ts

@@ -80,37 +80,44 @@ export function formatAnswerText(result: AskResult): string {
 	return lines.join("\n");
 }
 
-/** Minimal shape needed to summarize a call, before or after normalization. */
+/**
+ * Minimal shape needed to summarize a call, before or after normalization.
+ *
+ * The transcript renderer reads this from a call's *streaming* args, where a
+ * field can be missing or still be a fragment: a partial parse can hand back an
+ * option before its label has arrived. Every field is therefore `unknown`, and
+ * the helpers below read a non-string as absent rather than throw.
+ */
 export interface CallQuestion {
-	header?: string;
-	options?: { label: string }[];
+	header?: unknown;
+	options?: unknown;
+}
+
+/** A partial value read as a single line; anything but a string reads empty. */
+function asLine(value: unknown): string {
+	return typeof value === "string" ? sanitizeLine(value) : "";
 }
 
 /** Display headers with positional defaults (`Q1`, `Q2`, …). */
 export function questionHeaders(questions: CallQuestion[]): string[] {
-	return questions.map((question, i) => sanitizeLine(question?.header?.trim() || `Q${i + 1}`));
+	return questions.map((question, i) => asLine(question?.header) || `Q${i + 1}`);
 }
 
 /** One `Header: a, b, Other` summary per question that offers options. */
 export function optionSummary(questions: CallQuestion[]): string[] {
 	return questions
-		.map((question, i) => ({ question, header: question?.header?.trim() || `Q${i + 1}` }))
-		.filter(({ question }) => (question?.options?.length ?? 0) > 0)
-		.map(({ question, header }) => {
-			const labels = question.options?.map((option) => sanitizeLine(option.label)).join(", ");
-			return `${sanitizeLine(header)}: ${labels}, Other`;
+		.map((question, i) => ({ header: asLine(question?.header) || `Q${i + 1}`, options: question?.options }))
+		.filter(({ options }) => Array.isArray(options) && options.length > 0)
+		.map(({ header, options }) => {
+			// A partial option has no label yet; list the ones that have arrived.
+			const labels = (options as unknown[])
+				.map((option) => (option as { label?: unknown } | undefined)?.label)
+				.filter((label): label is string => typeof label === "string")
+				.map((label) => sanitizeLine(label));
+			return `${header}: ${labels.length > 0 ? `${labels.join(", ")}, Other` : "Other"}`;
 		});
 }
 
-/** One-line summary of the questions, used by the transcript call renderer. */
-export function formatCallText(questions: CallQuestion[]): string {
-	const noun = questions.length === 1 ? "question" : "questions";
-	const lines = [`ask_user_question ${questions.length} ${noun} (${questionHeaders(questions).join(", ")})`];
-	const options = optionSummary(questions);
-	if (options.length > 0) lines.push(`  Options: ${options.join(" · ")}`);
-	return lines.join("\n");
-}
-
 /** Human-readable summary of a selection, used in the Submit tab. */
 export function describeSelection(selection: Selection | undefined): string {
 	if (!selection) return "(unanswered)";

package/extensions/question/tools.ts

@@ -70,16 +70,21 @@ export function registerTools(pi: ExtensionAPI): void {
 		},
 
 		renderCall(args, theme, context) {
-			const raw = (args as Partial<AskUserQuestionArgs>).questions ?? [];
-			const count = raw.length;
+			// The args stream in: `questions` can be absent, and an option can arrive
+			// before its label. Read a partial call as a smaller summary and never
+			// throw — a throwing renderer makes Pi fall back to its own call line.
+			const raw = (args as Partial<AskUserQuestionArgs> | undefined)?.questions;
+			const questions = Array.isArray(raw) ? raw : [];
+			const count = questions.length;
 			const noun = count === 1 ? "question" : "questions";
-			const headers = questionHeaders(raw);
+			const headers = questionHeaders(questions);
 			let text = theme.fg("toolTitle", theme.bold(`${TOOL_NAME} `)) + paint(theme, "meta", `${count} ${noun}`);
 			if (headers.length > 0) text += paint(theme, "faint", ` (${headers.join(", ")})`);
 
-			// One indented line per question that offers options, so a long option list
-			// stays mapped to its question instead of wrapping on a single row.
-			for (const line of optionSummary(raw)) text += `\n${paint(theme, "faint", `  ${line}`)}`;
+			// One line per question that offers options, so a long option list stays
+			// mapped to its question instead of wrapping on a single row. The line
+			// carries no indent of its own; the tool-block frame supplies it.
+			for (const line of optionSummary(questions)) text += `\n${paint(theme, "meta", line)}`;
 
 			const component = reuseText(context?.lastComponent);
 			component.setText(text);

package/extensions/rewind/README.md

@@ -10,6 +10,8 @@ rewind uses Pi's session tree, so the branch you leave is not erased.
 This is the `rewind` extension entrypoint; it is one of two sibling git
 extensions in this package (`worktree` is the other).
 
+<img src="../../assets/rewind.png" alt="The /rewind screen: prompt rows newest first, a diamond marking prompts with a code snapshot, and the focused prompt's snapshot detail" width="100%">
+
 ```
 pi --extension ./extensions/rewind   # load this extension alone
 pi -e .                              # load the whole @gavin-hu/my-pi-agent package

package/extensions/rewind/format.ts

@@ -28,8 +28,13 @@ function truncate(text: string, max = LABEL_WIDTH): string {
 /**
  * A short, single-line summary of a user prompt for storage and display.
  * Takes the first non-empty line, collapses whitespace, and truncates.
+ *
+ * A run started by a custom message (a wake) has no user prompt: `event.prompt`
+ * is typed `string` but is `undefined` there, so a missing prompt is accepted
+ * and yields no summary rather than throwing.
  */
-export function summarizePrompt(text: string): string | undefined {
+export function summarizePrompt(text: string | undefined): string | undefined {
+	if (typeof text !== "string") return undefined;
 	const line = text
 		.split(/\r?\n/)
 		.map((part) => sanitizeLine(part))

package/extensions/rewind/index.ts

@@ -37,7 +37,9 @@ export function registerRewind(pi: ExtensionAPI): void {
 	});
 
 	// A new prompt begins a task: the run resolves its snapshot decision up
-	// front, so the `tool_call` guard can stay synchronous.
+	// front, so the `tool_call` guard can stay synchronous. A run started by a
+	// custom message (a wake) has no user prompt — `event.prompt` is undefined
+	// there despite its type — so `beginRun` accepts a missing prompt.
 	pi.on("before_agent_start", async (event, ctx) => {
 		await run.beginRun(event.prompt, ctx);
 	});

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/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,
 			});