@ferris1225/pi-subagents 0.26.2 → 0.28.0

package/README.md

@@ -18,16 +18,21 @@ report their results back to the main agent automatically.
   agent automatically: injected as soon as the current tool call finishes (even
   mid-turn), or starting a new turn when idle. No polling, no "go check" step.
 - **Sub-agent toolbelt** — three companion tools that replace the classic
-  sleep/poll anti-pattern: `subagent_wait` blocks in-tool and returns the result,
-  `subagent_status` inspects active and finished runs, and `subagent_stop` cancels
-  a run (delivering its partial output as an aborted result).
+  sleep/poll anti-pattern: `subagent_wait` looks results up in-turn — **non-blocking
+  by default** (a settled run returns its result immediately, a still-active run
+  tells the model to end its turn and wait for the wake-up message; pass
+  `timeoutMs` to block) — `subagent_status` inspects active and finished runs, and
+  `subagent_stop` cancels a run (delivering its partial output as an aborted result).
 - **Honest completions** — a run that exited cleanly but whose tool calls failed
   (e.g. a broken build) is reported as `completed with N failed tool call(s)`
   with the errors attached, so a rosy final text can never hide a failure.
 - **Parallel fan-out** — independent tasks run at the same time, with a configurable
   concurrency limit.
 - **Live progress** — a TUI widget shows each run's status, current activity, model,
-  token usage (input/output and cache read/write), and elapsed time.
+  token usage (input/output and cache read/write), and elapsed time. Auto-fix chain
+  rounds hang under their triggering review as a tree, and each finished round stays
+  visible with a one-line outcome (what a worker changed, or a re-review's
+  PASS/FAIL and what it found) until the chain resolves.
 - **Per-agent configuration** — enable agents, choose a model and thinking level per
   agent, and tune limits from `/subagents-setup`.
 - **Automatic model fallback** — if an agent's model fails at the provider level before
@@ -52,9 +57,10 @@ Several tools now offer some form of sub-agents. What this extension does differ
 - **Results come back on their own.** The extension turns the child's completion
   into a message that wakes the main agent automatically — delivered even
   mid-turn, right after the current tool call. No polling, no "go check
-  the other window" step, and **no `sleep`**: if the model must keep the turn it
-  calls `subagent_wait` (event-driven, returns the actual result) instead of
-  sleeping or polling.
+  the other window" step, and **no `sleep`** and no waiting: the model ends its
+  turn and the result wakes it. A settled result can be fetched in-turn with
+  `subagent_wait` (a non-blocking lookup by default; `timeoutMs` opts into
+  blocking) instead of sleeping or polling.
 - **Failures are handled, not reported.** Three layers of resilience: a provider-
   level model failure first retries the same model up to five times on a transient
   provider error, then retries once with the main window's model; terminal errors
@@ -64,8 +70,9 @@ Several tools now offer some form of sub-agents. What this extension does differ
   tell you when any of these happened.
 - **A quality gate that closes the loop.** When a reviewer returns `REVIEW_FAIL`,
   the extension dispatches a worker briefed with the concrete findings, then a
-  re-review — up to `maxFixRounds` times — and only then wakes the main agent with
-  the whole chain. The gate runs itself instead of asking you to babysit it.
+  re-review — up to `maxFixRounds` times — and only then wakes the main agent.
+  The gate runs itself instead of asking you to babysit it, and the widget shows
+  every round as it happens instead of a black box.
 - **Honest results.** A sub-agent can end its turn with "still working" while its
   last build actually failed. The completion message surfaces the failed tool
   calls from the run's final attempt (`completed with N failed tool call(s)`) with
@@ -74,7 +81,12 @@ Several tools now offer some form of sub-agents. What this extension does differ
   attempt's tool calls are counted — never stale errors from an abandoned one.)
 - **You can see what it is doing.** The widget shows each run's status, current
   activity (which tool, which file), model, token usage including cache reads and
-  writes, and elapsed time — plus soft warnings when a run looks stuck.
+  writes, and elapsed time — plus soft warnings when a run looks stuck. When a
+  chain finishes, the delivered message is one condensed summary (one line per
+  round: verdict + what changed/found, plus aggregate usage) instead of every
+  round's raw output stacked together; the final round's full report is attached
+  only when its detail is actionable (a FAIL verdict or a crash), and any round's
+  full report stays one `subagent_status <id>` call away.
 - **Recursion is structurally impossible.** Children are leaf processes: the
   `subagent` tool is excluded from their toolset. No runaway delegation trees.
 - **Zero runtime dependencies.** It is a plain pi extension — install, configure,
@@ -324,10 +336,13 @@ main agent
 The extension registers three companion tools so the main agent never has to
 `sleep`/poll for a background run:
 
-- `subagent_wait` — blocks inside the tool call (event-driven, wakes on the run's
-  completion) and **returns the actual result in-turn**. Use it only when the current
-  turn must receive the result (sequential dependent steps); otherwise end the turn
-  and the completion message wakes you.
+- `subagent_wait` — looks up a run's result in-turn. It does **not block by
+  default**: a settled run returns its result immediately; a still-active run
+  returns a note telling the model to end its turn (the completion message then
+  wakes it). Pass `timeoutMs` to block inside the tool call (event-driven, wakes
+  on the run's completion) — only when the current turn must receive the result
+  right now (sequential dependent steps). Otherwise end the turn and the
+  completion message wakes you.
 - `subagent_status` — lists active runs (id, agent, model, usage, elapsed, activity)
   and finished results; pass an id to read a finished run's full result.
 - `subagent_stop` — cancels an active run (or `all: true`); the child is terminated
@@ -376,9 +391,11 @@ Start dependent work only after the relevant result has been delivered.
 
 ### Waiting for a result in-turn
 
-When the next step depends on a run's result and the turn must not end, use
-`subagent_wait` instead of sleeping or polling. It blocks inside the tool call
-(event-driven) and returns the actual result:
+Results arrive as messages that wake the main agent automatically, so waiting is
+usually unnecessary: end your turn and the result resumes you. When a result must
+be fetched in-turn, `subagent_wait` is a **non-blocking lookup by default** — a
+settled run returns its result immediately, a still-active run returns a note
+telling the model to end its turn:
 
 ```json
 {
@@ -386,8 +403,10 @@ When the next step depends on a run's result and the turn must not end, use
 }
 ```
 
-Pass `timeoutMs` to bound the wait; on timeout it reports the still-running runs
-and the model re-invokes it or ends the turn (the completion message then wakes it).
+Only when the turn must not end AND the result is needed right now (e.g. the user
+asked for it) pass `timeoutMs` to block; on timeout it reports the still-running
+runs and the model ends the turn (the completion message then wakes it) or
+re-invokes with a longer timeout.
 
 ### Inspecting runs
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "0.26.2",
+  "version": "0.28.0",
   "description": "Focused sub-agent delegation for pi: explore / worker / reviewer agents in isolated context, with proactive dispatch injection and per-agent model selection.",
   "type": "module",
   "license": "MIT",

package/src/fixloop.ts

@@ -12,6 +12,7 @@
  */
 
 import { getResultOutput, isFailedResult, reviewVerdict, type SingleResult } from "./spawn.ts";
+import { extractKeyFragments, formatUsageCompact } from "./monitor.ts";
 import type { SubagentsConfig } from "./config.ts";
 
 /**
@@ -62,6 +63,98 @@ export function buildFixTaskBrief(reviewerResult: SingleResult, round: number, m
 	].join("\n");
 }
 
+/**
+ * One step of an auto-fix chain as delivered: the run id (so the condensed
+ * summary can point at per-run detail via subagent_status), the result, and
+ * the human-readable role within the chain ("initial review", "fix round 1",
+ * "re-review round 2"). runId is undefined for steps that never spawned a run
+ * (e.g. an unknown agent).
+ */
+export interface ChainStep {
+	runId?: number;
+	result: SingleResult;
+	relation: string;
+}
+
+/** Max distinguishing fragments kept in a one-line chain summary. */
+export const CHAIN_SUMMARY_FRAGMENTS_MAX = 3;
+
+/** The most telling fragments (paths, quoted phrases, symbols) of a run's final
+ * output: for a worker these are the paths it changed, for a reviewer the
+ * issues it found. Capped so summaries stay one line. */
+export function chainKeyFragments(result: SingleResult): string[] {
+	return extractKeyFragments(getResultOutput(result)).slice(0, CHAIN_SUMMARY_FRAGMENTS_MAX);
+}
+
+/**
+ * Compact one-line outcome for a finished chain run, shown in the widget so
+ * each round reads as what it did: a reviewer reports its verdict plus the
+ * key fragments of what it found ("fail · src/index.ts · render()"), a worker
+ * the fragments of what it changed. Failed runs and runs with nothing
+ * distinctive get no summary.
+ */
+export function summarizeChainResult(result: SingleResult): string | undefined {
+	if (isFailedResult(result)) return undefined;
+	const verdict = result.agent === "reviewer" ? reviewVerdict(getResultOutput(result)) : undefined;
+	if (verdict === "pass") return "pass";
+	const fragments = chainKeyFragments(result);
+	if (verdict === "fail") return fragments.length > 0 ? `fail · ${fragments.join(" · ")}` : "fail";
+	return fragments.length > 0 ? fragments.join(" · ") : undefined;
+}
+
+/**
+ * Condensed, readable summary of a completed auto-fix chain: one line per step
+ * (run id, role, verdict / what changed) plus aggregate usage. Full per-step
+ * reports stay addressable via `subagent_status <id>`; the caller appends the
+ * final step's full block only when its detail is actionable (FAIL verdict or a
+ * crash), so the delivered message stays short instead of stacking every
+ * round's raw output.
+ */
+export function formatChainSummary(steps: readonly ChainStep[]): string {
+	const rounds = steps.filter((step) => step.relation.startsWith("fix round")).length;
+	const last = steps[steps.length - 1];
+	const stepStatus = (step: ChainStep): string => {
+		const { result } = step;
+		if (result.agent === "reviewer") {
+			const verdict = reviewVerdict(getResultOutput(result));
+			if (verdict) return verdict.toUpperCase();
+		}
+		return isFailedResult(result) ? "failed" : "completed";
+	};
+	const lines = [
+		`## Auto-fix chain: ${Math.max(1, rounds)} round${rounds === 1 ? "" : "s"} — final ${stepStatus(last)}`,
+		"",
+	];
+	for (const step of steps) {
+		const fragments = chainKeyFragments(step.result);
+		const suffix =
+			fragments.length > 0
+				? step.result.agent === "worker"
+					? ` — changed: ${fragments.join(" · ")}`
+					: ` — ${fragments.join(" · ")}`
+				: "";
+		const id = step.runId !== undefined ? `#${step.runId} ` : "";
+		lines.push(`- ${id}${step.result.agent} · ${step.relation} · ${stepStatus(step)}${suffix}`);
+	}
+	const total = steps.reduce(
+		(acc, step) => {
+			acc.input += step.result.usage.input;
+			acc.output += step.result.usage.output;
+			acc.cacheRead += step.result.usage.cacheRead;
+			acc.cacheWrite += step.result.usage.cacheWrite;
+			acc.cost += step.result.usage.cost;
+			acc.turns += step.result.usage.turns;
+			return acc;
+		},
+		{ input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 },
+	);
+	const usage = formatUsageCompact(total);
+	lines.push("", `Totals: ${steps.length} run${steps.length === 1 ? "" : "s"}${usage ? ` · ${usage}` : ""}`);
+	const ids = steps.filter((step) => step.runId !== undefined).map((step) => `#${step.runId}`);
+	lines.push(`Full per-run reports (output, usage, failed tools): subagent_status ${ids.join(" ")}`);
+	return lines.join("\n");
+}
+
 /**
  * The re-review brief handed to the reviewer after a worker fix round. Includes
  * the prior review so the reviewer can verify the fixes without re-discovering

package/src/index.ts

@@ -42,7 +42,7 @@ import {
 	type SubagentLiveEvent,
 	type UsageStats,
 } from "./spawn.ts";
-import { buildFixTaskBrief, buildReReviewBrief, shouldTriggerFixLoop } from "./fixloop.ts";
+import { buildFixTaskBrief, buildReReviewBrief, formatChainSummary, shouldTriggerFixLoop, summarizeChainResult, type ChainStep } from "./fixloop.ts";
 import {
 	activityStateLabel,
 	compactLine,
@@ -310,7 +310,7 @@ export default function (pi: ExtensionAPI): void {
 			"Modes: single ({agent, task}) or parallel ({tasks: [{agent, task}, ...]}).",
 			"It starts agents in the background and immediately returns control to the main window; completion messages automatically wake the main agent to continue.",
 			"Each agent has no memory of this conversation — brief it fully (goal, exact paths, constraints, expected output).",
-			"To get a result in-turn without sleeping, use the subagent_wait tool."
+			"Results arrive as wake-up messages automatically — you do NOT need to wait. If you must get a result in-turn, subagent_wait is a non-blocking lookup by default (pass timeoutMs to block)."
 		].join(" "),
 		promptSnippet:
 			"Start background subagents: explore (read-only search), worker (implement), reviewer (adversarial review); completion automatically resumes the main agent. Simple tasks: use direct tools, not subagents.",
@@ -321,8 +321,8 @@ export default function (pi: ExtensionAPI): void {
 			"Use subagent with agent 'reviewer' for a fresh read-only review before reporting work done or committing.",
 			"subagent launches work in the background and ends the current turn; when a result arrives, the main agent is automatically resumed with it.",
 			"Run independent tasks in parallel by passing a tasks array to subagent; let the automatically resumed main agent start dependent work after results arrive.",
-			"NEVER sleep, poll, or call other tools alongside subagent — it ends the turn immediately. The main agent is auto-resumed when results arrive; manual waiting only blocks the turn and delays delivery. The one exception is subagent_wait (below): only when you must stay in the turn.",
-			"If you must keep the turn for a result, call subagent_wait (blocks in-tool and returns the result) — never bash sleep/timeout to wait for a sub-agent.",
+			"NEVER sleep or poll, and do NOT call subagent_wait to hold the turn — subagent ends the turn immediately and the result arrives as a message that wakes you automatically (even mid-turn). Ending your turn is the default and the only correct way to wait.",
+			"If you must keep the turn for a result, call subagent_wait with an explicit timeoutMs (non-blocking by default) — never bash sleep/timeout to wait for a sub-agent.",
 		],
 		parameters: SubagentParams,
 
@@ -469,9 +469,9 @@ export default function (pi: ExtensionAPI): void {
 				task: string,
 				signal: AbortSignal,
 				meta: RunChainMeta,
-			): Promise<SingleResult> => {
+			): Promise<{ runId?: number; result: SingleResult }> => {
 				const agent = agents.find((candidate) => candidate.name === agentName);
-				if (!agent) return failedStartResult(agentName, task, `Unknown agent: "${agentName}".`);
+				if (!agent) return { result: failedStartResult(agentName, task, `Unknown agent: "${agentName}".`) };
 				const thinkingLevel = config.agentThinkingLevels[agent.name] ?? agent.thinking ?? config.thinkingLevel;
 				const runId = monitor.addRun(agent.name, task, agent.model, thinkingLevel, meta);
 				const onLive = makeLiveHandler(runId);
@@ -490,11 +490,15 @@ export default function (pi: ExtensionAPI): void {
 						},
 						sessionRef,
 					);
-					finishRun(runId, isFailedResult(result) ? "failed" : "done");
+					// Keep the finished round visible in the widget while the chain is
+					// still running, with a one-line summary of what it did; the whole
+					// group is dropped when the chain resolves (see removeChainGroup).
+					monitor.setSummary(runId, summarizeChainResult(result));
+					finishRun(runId, isFailedResult(result) ? "failed" : "done", { retain: true });
 					registerRunResult(runId, result);
-					return result;
+					return { runId, result };
 				} catch (error) {
-					finishRun(runId, "failed");
+					finishRun(runId, "failed", { retain: true });
 					const errorMessage = error instanceof Error ? error.message : String(error);
 					const crashed = {
 						...queuedResult(agent, task, thinkingLevel),
@@ -505,7 +509,7 @@ export default function (pi: ExtensionAPI): void {
 						dispatchFailed: true,
 					};
 					registerRunResult(runId, crashed);
-					return crashed;
+					return { runId, result: crashed };
 				}
 			};
 
@@ -517,73 +521,90 @@ export default function (pi: ExtensionAPI): void {
 			 * The triggering reviewer's run stays visible in the widget (annotated) until
 			 * the chain resolves, so the ↳ rows have an obvious parent.
 			 */
+			/** Drop every widget row belonging to an auto-fix chain; the retained
+			 * parent row is removed separately (it does not carry the groupId). */
+			const removeChainGroup = (groupId: string): void => {
+				for (const run of [...monitor.getRuns()]) {
+					if (run.groupId === groupId) monitor.removeRun(run.id);
+				}
+			};
+
 			const startFixLoop = (initialReviewerResult: SingleResult, parentGroupId: string, parentRunId: number): void => {
 				runControllers.set(parentRunId, backgroundQueue.enqueue(
 					async (signal) => {
-						const chain: SingleResult[] = [initialReviewerResult];
+						const chain: ChainStep[] = [
+							{ runId: parentRunId, result: initialReviewerResult, relation: "initial review" },
+						];
 						let lastReviewer = initialReviewerResult;
 						for (let round = 1; round <= config.maxFixRounds; round++) {
 							if (!sessionActive) break;
 							const fixBrief = buildFixTaskBrief(lastReviewer, round, config.maxFixRounds);
-							const workerResult = await launchInLoop("worker", fixBrief, signal, {
+							const workerStep = await launchInLoop("worker", fixBrief, signal, {
 								groupId: parentGroupId,
 								relationLabel: `fix round ${round}`,
 							});
-							chain.push(workerResult);
-							if (!sessionActive || isFailedResult(workerResult)) break;
+							chain.push({ ...workerStep, relation: `fix round ${round}` });
+							if (!sessionActive || isFailedResult(workerStep.result)) break;
 							const reReviewBrief = buildReReviewBrief(lastReviewer, round);
-							const reviewResult = await launchInLoop("reviewer", reReviewBrief, signal, {
+							const reviewStep = await launchInLoop("reviewer", reReviewBrief, signal, {
 								groupId: parentGroupId,
 								relationLabel: `re-review round ${round}`,
 							});
-							chain.push(reviewResult);
-							lastReviewer = reviewResult;
+							chain.push({ ...reviewStep, relation: `re-review round ${round}` });
+							lastReviewer = reviewStep.result;
 							// A crashed re-review must stop the chain like a crashed worker: its
 							// output (if any) is not a verdict, and feeding it to the next fix
 							// round would brief the worker from garbage.
-							if (!sessionActive || isFailedResult(reviewResult)) break;
-							if (reviewVerdict(getResultOutput(reviewResult)) === "pass") break;
+							if (!sessionActive || isFailedResult(reviewStep.result)) break;
+							if (reviewVerdict(getResultOutput(reviewStep.result)) === "pass") break;
 						}
 						// The chain is done (success, exhaustion, or abort): drop the retained
-						// parent row, then deliver the whole chain as one group. The loop's
-						// outcome always wakes the main agent (a passing chain reports
-						// success, a stuck one needs a human). Register the parent's final
-						// state (the last chain result) before removal so subagent_wait can
-						// resolve it.
-						registerRunResult(parentRunId, chain[chain.length - 1]);
+						// parent row and its retained round rows, then deliver one condensed
+						// summary. Register the parent's final state (the last chain result)
+						// before removal so subagent_wait can resolve it.
+						registerRunResult(parentRunId, chain[chain.length - 1].result);
 						runControllers.delete(parentRunId);
+						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
 						if (!sessionActive) return;
-						const items: CompletionMessageItem[] = chain.map((r) => {
-							// A model-level chain run (worker or re-review whose provider never
-							// produced output) is handed to the main window like any other
-							// sub-agent run: the block carries the takeover note. Dispatch
-							// crashes (dispatchFailed) are excluded by the gate itself.
-							const modelLevel = isFailedResult(r) && isModelLevelFailure(r);
-							return {
-								agent: r.agent,
-								block: modelLevel
-									? `${formatCompletionBlock(r, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(r)}`
-									: formatCompletionBlock(r, config.maxResultLines, ctx.cwd),
+						// One compact message instead of every round's raw output: the summary
+						// lines cover each step (verdict + what changed/found), and the final
+						// step's full report is appended only when its detail is actionable
+						// (a FAIL verdict, a crash, or a model-level failure the main agent
+						// must take over). Everything else stays one `subagent_status #id`
+						// call away.
+						const last = chain[chain.length - 1];
+						let block = formatChainSummary(chain);
+						if (isFailedResult(last.result) && isModelLevelFailure(last.result)) {
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}\n\n${modelLevelTakeoverNote(last.result)}`;
+						} else if (isFailedResult(last.result) || reviewVerdict(getResultOutput(last.result)) === "fail") {
+							block = `${block}\n\n${formatCompletionBlock(last.result, config.maxResultLines, ctx.cwd)}`;
+						}
+						sendCompletionGroup([
+							{
+								agent: `auto-fix chain (${last.result.agent})`,
+								block,
 								triggerTurn: true,
-							};
-						});
-						sendCompletionGroup(items);
+							},
+						]);
 						completionBatcher.flush();
 					},
 					() => {
-						// Cancelled before delivery: clean up the retained parent row (each
-						// in-flight chain run was already finished by its launchInLoop path).
+						// Cancelled before delivery: clean up the retained parent row and
+						// every retained chain row (each in-flight chain run was already
+						// finished by its launchInLoop path).
 						runControllers.delete(parentRunId);
+						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
 					},
 					(error) => {
 						// A crash inside the chain orchestration (failed runs are caught by
 						// launchInLoop and delivered as part of the chain) must not vanish:
-						// drop the retained parent row, notify, and deliver a failed result
+						// drop the retained rows, notify, and deliver a failed result
 						// so the main agent knows the chain never completed.
 						registerRunResult(parentRunId, initialReviewerResult);
 						runControllers.delete(parentRunId);
+						removeChainGroup(parentGroupId);
 						monitor.removeRun(parentRunId);
 						if (!sessionActive) return;
 						const errorMessage = error instanceof Error ? error.message : String(error);
@@ -842,13 +863,13 @@ export default function (pi: ExtensionAPI): void {
 		},
 	});
 
-	// Blocking wait: keeps the turn alive until the targeted run(s) settle, then
-	// returns the actual result(s) to the model in-turn. Without it, a model that
-	// must stay in the turn falls back to bash sleep/poll — blocking the turn and
-	// delaying the very wake-up it is waiting for. Ending the turn and letting the
-	// steer-delivered completion wake it is still the preferred path; this tool is
-	// for when the result is needed NOW (sequential dependent steps).
-	const SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+	// In-turn result lookup. Dispatch already ended the turn and results arrive as
+	// wake-up messages, so the default must NOT block: a settled run returns its
+	// result immediately, a still-active run returns a "still running — end your
+	// turn" note and the model finishes (the completion then wakes it). Blocking
+	// is opt-in via an explicit timeoutMs — a long default would hold the turn
+	// hostage for nothing, since the result arrives on its own either way.
+	const SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS = 0;
 
 	const SubagentWaitParams = Type.Object({
 		id: Type.Optional(
@@ -858,7 +879,7 @@ export default function (pi: ExtensionAPI): void {
 		),
 		timeoutMs: Type.Optional(
 			Type.Number({
-				description: `Give up after this many milliseconds and report the still-running runs (default ${SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS}).`,
+					description: `Block for up to this many milliseconds and report the still-running runs. Default ${SUBAGENT_WAIT_DEFAULT_TIMEOUT_MS}: no blocking — settled runs return their result immediately, active runs return a note telling the model to end its turn.`,
 			}),
 		),
 	});
@@ -867,18 +888,19 @@ export default function (pi: ExtensionAPI): void {
 		name: "subagent_wait",
 		label: "Subagent Wait",
 		description: [
-			"Block the current turn until background sub-agent run(s) finish, then return their results.",
-			"Use ONLY when you must stay in the turn and act on the result immediately (sequential dependent steps).",
-			"Prefer ending your turn after subagent — the result arrives automatically and wakes you.",
+			"Look up background sub-agent run(s) and return their results.",
+			"PREFER NOT CALLING THIS: dispatching already ended your turn and results arrive as a message that wakes you automatically.",
+			"By default it does NOT block: a settled run returns its result immediately; a still-active run returns a 'still running — end your turn' note.",
+			"Pass an explicit timeoutMs ONLY when you must stay in the turn and need the result right now (sequential dependent steps).",
 			"NEVER sleep, poll, or wait with bash to get a sub-agent result: end the turn, or call this tool.",
 			"The same result is also delivered as a completion message that resumes the main agent, so you may see it twice (once here, once as a wake-up) — that is expected, not a duplicate.",
 		].join(" "),
-		promptSnippet: "Wait for a background subagent to finish and get its result in-turn (id: run id from the widget; omit for all).",
+		promptSnippet: "Look up a background subagent result in-turn (id: run id from the widget; omit for all). Non-blocking by default; pass timeoutMs to block.",
 		promptGuidelines: [
-			"Call subagent_wait only when you must keep the turn and need the result now — e.g. the next step depends on it.",
-			"After dispatching via subagent, prefer ending the turn: the completion message wakes you automatically (no waiting).",
+			"Do NOT call subagent_wait to hold the turn: results arrive as wake-up messages automatically. The default call is a non-blocking lookup — settled results return immediately, active runs return a note telling you to end your turn.",
+			"Pass an explicit timeoutMs only when you must keep the turn AND the next step depends on the result right now — e.g. the user asked you to wait for it.",
 			"Never use bash sleep/timeout/polling to wait for a sub-agent — it blocks the turn and delays result delivery.",
-			"If subagent_wait times out, call it again with a longer timeoutMs or end the turn and wait for the wake-up message.",
+			"If subagent_wait times out, end the turn and wait for the wake-up message, or call it again with a longer timeoutMs.",
 		],
 		parameters: SubagentWaitParams,
 
@@ -978,7 +1000,10 @@ export default function (pi: ExtensionAPI): void {
 					timer = setTimeout(
 						() =>
 							finish({
-								note: `wait timed out after ${Math.round(timeoutMs / 1000)}s — run #${runId} is still active; call subagent_wait again or end the turn (the result will wake you when ready)`,
+								note:
+									timeoutMs === 0
+										? `run #${runId} is still active — end your turn: the result will wake you (or call subagent_wait again with an explicit timeoutMs to block)`
+										: `wait timed out after ${Math.round(timeoutMs / 1000)}s — run #${runId} is still active; call subagent_wait again or end the turn (the result will wake you when ready)`,
 							}),
 						Math.max(1, timeoutMs),
 					);
@@ -1307,7 +1332,10 @@ export default function (pi: ExtensionAPI): void {
 								const usage = formatUsageCompact(r.usage);
 								const tools = r.toolCount ? `${r.toolCount} tool${r.toolCount === 1 ? "" : "s"}` : "";
 								const elapsed = formatElapsed(r, now);
-								const metaParts = [model, usage, tools, elapsed].filter(Boolean);
+								// The round outcome summary leads the metadata so a finished chain
+								// row reads as what it did ("fail · src/index.ts · render()",
+								// "pass", "src/index.ts · tests/monitor.test.ts").
+								const metaParts = [r.summary, model, usage, tools, elapsed].filter(Boolean);
 								// Running is conveyed by the icon + elapsed; spell out the label only for
 								// the other states (ready / done / stopped) so they are unambiguous.
 								if (r.status !== "running") metaParts.push(statusLabel(r.status));

package/src/monitor.ts

@@ -64,6 +64,11 @@ export interface RunView {
 	relationLabel?: string;
 	/** Free-form note shown in the widget next to the status label (e.g. "auto-fix chain running"). */
 	annotation?: string;
+	/** One-line outcome summary of a finished chain run, shown in the widget so
+	 * each auto-fix round reads as what it did: a reviewer reports its verdict
+	 * plus key fragments of what it found ("fail · src/index.ts · render()"), a
+	 * worker the fragments of what it changed. Unset for non-chain runs. */
+	summary?: string;
 	/** True when a finished run is intentionally kept in the widget (e.g. an
 	 * auto-fix chain parent whose chain is still running). beginTurn preserves
 	 * retained runs so they are not swept between turns. */
@@ -472,6 +477,14 @@ export class MonitorStore {
 		this.notify();
 	}
 
+	/** Set the run's one-line outcome summary (what a finished chain round did). */
+	setSummary(id: number, text: string | undefined): void {
+		const run = this.find(id);
+		if (!run) return;
+		run.summary = text;
+		this.notify();
+	}
+
 	/** Mark a run as retained (kept in the widget despite being finished). */
 	setRetained(id: number, retained: boolean): void {
 		const run = this.find(id);
@@ -517,6 +530,7 @@ export class MonitorStore {
 		const usage = formatUsageCompact(run.usage);
 		const parts = [run.agent];
 		if (run.relationLabel) parts.push(run.relationLabel);
+		if (run.summary) parts.push(run.summary);
 		if (run.model) parts.push(run.model);
 		if (run.thinking) parts.push(`thinking ${run.thinking}`);
 		if (usage) parts.push(usage);

package/src/prompt.ts

@@ -41,9 +41,13 @@ It immediately ends the current main-agent turn so the user can keep working. Wh
 finishes, its result is sent back as a message that automatically resumes the main agent;
 if the main agent is busy, the result waits as a follow-up.
 
-NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout) to wait for
-a sub-agent — the turn already ended and the main agent is auto-resumed when results arrive.
-Manual waiting blocks the turn, delays result delivery, and wastes the user's time.
+NEVER run sleep, wait, or polling commands (e.g. Start-Sleep, sleep, timeout), and do NOT
+call subagent_wait to hold the turn — dispatching already ended it, and results arrive as
+messages that resume the main agent automatically (even mid-turn). Ending your turn is the
+default and the only correct way to wait; subagent_wait blocks the turn so the user cannot
+give you other work meanwhile. It is non-blocking by default: settled results return
+immediately, active runs return a "still running — end your turn" note. Pass an explicit
+timeoutMs only when you must stay in the turn (e.g. the user asked you to wait).
 
 Available agents:
 ${catalog}