@d3ara1n/pi-subagent 3.2.3 → 3.3.0

package/README.md

@@ -4,7 +4,7 @@
 
 Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
 
-Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, with a per-run brief page for inputs and stats; mid-run corrections can be queued into a running subagent from the view's steer editor or via `subagent_steer`.
+Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, with a per-run brief page for inputs and stats; mid-run corrections can be queued into a running subagent from the view's steer editor or via `subagent_steer`.
 
 ## Design Philosophy
 
@@ -55,7 +55,7 @@ Observations on how main models behave with this plugin, one family per subsecti
 
 ## TUI Display
 
-- **During execution**: the task's first line with a ⏳ (or ⏸ queued) indicator, a live stream of thinking blocks and tool calls (latest 5 collapsed, everything expanded), and a usage line (elapsed/budget time, turns, tokens, peak context, cost, model). Delegates using inherited conversation are marked in the tool-call title.
+- **During execution**: the task's first line with a ⏳ (or ⏸ queued) indicator, a live stream of thinking blocks, tool calls, and steering messages (latest 5 collapsed, everything expanded), and a usage line (elapsed/budget time, turns, tokens, peak context, cost, model). Delegates using inherited conversation are marked in the tool-call title.
 - **Collapsed result**: the task's first line, then `✓` + the AI-generated summary (or the first line of the output), then the usage line — no activity replay
 - **Expanded result** (Ctrl+O): reference files, context size, the full task, the complete activity stream, the final output as rendered Markdown, and usage details
 - **Fallback trace**: when a provider error (429, quota, timeout, ...) kills a run and it is retried on the role's `fallbackRole`, a `⚠ fallback: first attempt <model> failed (<reason>)` line appears in both views — also while the retry is running (see [Fallback observability](#fallback-observability))
@@ -73,11 +73,11 @@ Observations on how main models behave with this plugin, one family per subsecti
 
 A centered overlay covering most of the screen. A tab row across the top lists every run (icon · id · role); `Tab` cycles the focused run forward and `Shift+Tab` backward, and the rest of the viewport belongs to it alone — showing one of two pages, toggled with `d`. Runs are ordered newest-first, and the row is windowed around the focused cell — the archive can outgrow the terminal width, but focus never scrolls off-screen.
 
-The **activity page** (default) is the run's live feed: a continuous, append-only list where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent. Background runs stay listed for the whole session — the view doubles as the session's run archive, so a run's activity and brief remain browsable even after the model has collected the result. The centered empty notice (with `Esc close` hinted) appears only when nothing has been delegated yet.
+The **activity page** (default) is the run's live feed: a continuous list with pending input pinned below current activity, where each entry is static text with a state icon, and the only animated thing is the ellipsis on a running entry (`.` → `..` → `...`). Finishing freezes an entry in place — its position never changes, only the icon flips. Streamed assistant text grows in place as the run's last line and settles into plain terminal-colored text at the turn boundary. The feed is scrollable (`↑↓`, `PgUp/PgDn`, `Home`/`End`): the view pins to the end and auto-follows new entries; scrolling up unpins (a `⋮ N earlier` marker appears), and reaching the bottom again re-pins. Both foreground and background runs appear here; a foreground run stays listed while its delegate call blocks the main agent. Background runs stay listed for the whole session — the view doubles as the session's run archive, so a run's activity and brief remain browsable even after the model has collected the result. The centered empty notice (with `Esc close` hinted) appears only when nothing has been delegated yet.
 
 The **brief page** shows the run's inputs and vitals at full width: the task and context verbatim (wrapped; head+tail elided beyond 20k chars), inherited-conversation size and truncation status when enabled (never its text), the reference file list annotated with `✓`/`·` for whether the child's tool calls actually touched each file, usage and time stats, the fallback trace, and a stderr tail on failures.
 
-Steer input is modal so keys never conflict with typing: in browse mode `s` opens the editor, `Enter` queues the message into the focused run (only while it is running) and returns to browse, `Esc` cancels and clears. The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` in browse mode closes the overlay.
+Steer input is modal so keys never conflict with typing: in browse mode `s` opens the editor, `Enter` queues the message into the focused run (only while it is running) and returns to browse, `Esc` cancels and clears. The message appears immediately at the bottom of the feed as an `↩ steer (queued):` entry. When the child consumes the user message, the queued marker disappears in place; the entry remains accent-colored in the history. Delivery happens after the current tool batch, before the next LLM call, without resetting the run's progress. `Esc` in browse mode closes the overlay.
 
 ## Dependencies
 
@@ -240,12 +240,12 @@ Three execution properties, kept separate:
 | Tool | Purpose | Returns to the model |
 |------|---------|---------------------|
 | `subagent_delegate(background: true)` | Start an async run | Just the id (`sub-N`) |
-| `subagent_wait(ids?, timeout?)` | Block until **all** listed runs finish (omit `ids` for all current background runs) | A per-run roll call — one `id (role): state (turns, elapsed, tokens, cost)` line per run, never the output; on timeout, the same roll call (live runs carry usage so far) under a timeout header |
+| `subagent_wait(ids?)` | Block until **all** listed runs end (omit `ids` for all current background runs) | A per-run roll call — one `id (role): state (turns, elapsed, tokens, cost)` line per run; retrieve results with `subagent_check` |
 | `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity, elapsed/budget, and usage so far / the **full output** with a usage footer once finished / failure reason + partial output + usage on failed or cancelled. Idempotent: re-delivers the same terminal snapshot — the run stays in the registry for the whole session |
 | `subagent_steer(id, message)` | Queue a mid-run correction into one running run (typically right after a check revealed it heading down a wrong path) | Confirmation that the steer is queued — delivered after the child's current tool batch, before its next LLM call; the run keeps its progress |
 | `subagent_cancel(id, reason?)` | Kill one live (queued/running) run | Confirmation — the same roll-call line wait uses, plus a pointer to check for the partial output; the run settles as `cancelled` (warning styling, same family as timeout/budget) with the reason in its error message |
 
-Typical flow:
+Example tool calls made by the main model:
 
 ```json
 [
@@ -254,22 +254,28 @@ Typical flow:
 ]
 ```
 
-…continue other work, then:
+The main model continues its own work while these runs execute. Before each model request, the extension refreshes an inbox reminder with the status of runs whose results have not been collected. When the model needs a result from a run that has ended, it retrieves it through `subagent_check`:
 
 ```json
-{ "ids": ["sub-1", "sub-2"] }
+{ "id": "sub-1" }
 ```
 
-(call `subagent_wait`), and finally `subagent_check` each finished id to fetch its result. `subagent_check` accepts one id per call because results can be large.
+If the needed run is still queued or running, the model can wait for it through `subagent_wait`:
+
+```json
+{ "ids": ["sub-1"] }
+```
+
+Once the wait returns, the model retrieves the result through `subagent_check`. The reminder supplies status information, while check provides execution details and results; a separate check is not required before waiting. `subagent_check` accepts one id per call because results can be large; `subagent_wait` can await multiple unfinished runs together.
 
 Semantics worth knowing:
 
-- **Results are pull-only for the model.** A purple completion notice is shown to the user, but nothing delivers the result to the model or wakes it up. The notice is a pure notification in the same visual family as pi's `[compaction]` card — a `[subagent] id (role) outcome` header with the bare task preview beneath, each line truncated to the terminal width — and deliberately unlike the tool rows, so it never reads as model behavior; the result itself never appears in the notice, only in `subagent_check` (model) or `/subagent:status` (user). The model owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists runs not yet collected by a terminal check on the active branch on every request, but it never pushes results.
+- **Results are pull-only for the model.** A purple completion notice is shown to the user, but nothing delivers the result to the model or wakes it up. The notice is a pure notification in the same visual family as pi's `[compaction]` card — a `[subagent] id (role) outcome` header with the bare task preview beneath, each line truncated to the terminal width — and deliberately unlike the tool rows, so it never reads as model behavior; the result itself never appears in the notice, only in `subagent_check` (model) or `/subagent:status` (user). The model collects results with `subagent_check`, using `subagent_wait` when a run has not ended yet. The inbox reminder (below) lists runs not yet collected by a terminal check on the active branch on every request, but it never pushes results.
 - **Background runs survive turn cancellation** and are unaffected by a cancelled `subagent_wait` — cancelling the wait never cancels the runs; call `subagent_wait` or `subagent_check` again later.
 - **Idempotent check, session-tree delivery state:** `subagent_check` re-delivers the same terminal snapshot on every call — runs stay in the registry for the whole session, so no result can ever be stranded by branch navigation or compaction. Whether a run still needs collecting is not tracked in the registry: it derives from the session tree itself. The session is append-only, so branching back past a check entry drops it from the active path — the inbox reminder re-arms and the model simply checks again (the id still resolves; the run is still there). Branching forward to the original branch restores the check entry and silences the reminder again.
 - **Cancellation keeps the partial output.** `subagent_cancel(id, reason?)` kills the child (SIGTERM, escalating to SIGKILL) and settles the run as `cancelled` — its own stop reason in the same family as `timeout`/`budget_exceeded` (TUI warning styling ⏹, not the error-red ✗ of real failures) — with whatever it had produced. The `reason` becomes the error message verbatim, so whoever reads the partial output later via `subagent_check` — or the audit history — sees `cancelled — <reason>`; the source is distinguishable too (`user: ...` for `/subagent:cancel`, the model's own words for the tool, `session shutdown` for reaping). Cancelling does not remove the run: `subagent_check` still returns the partial output, and `subagent_wait` reports the run as `cancelled` with its usage stats.
 - **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the runs not yet collected by a terminal check on the active branch (queued, running, and finished/failed-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Only checks that returned a terminal snapshot count — a peek at a live frame never silences the inbox, so the steer flow's check → steer → check-later cycle cannot strand an outcome. Runs missing from the list were already checked on this branch — so a finished run the model forgot to check keeps surfacing until it does. Branch navigation keeps this honest: the list derives from the session tree, not registry bookkeeping.
-- **`timeout` (seconds) is optional — omitting it is the normal usage.** `subagent_wait` blocks until every run finishes, with each run bounded by its own role timeout; subagent runs typically take minutes. Set a timeout only when the waiter must resume soon (e.g. to report progress to the user).
+- **Wait has no timeout parameter.** `subagent_wait` blocks until all specified runs end. Each run's own role timeout and budgets still apply; cancelling the wait leaves the runs running.
 - Background runs share the global `maxConcurrency` gate — extra runs show up as `queued` in wait/check views.
 - **Top-level only:** nested subagents cannot delegate in the background (a subagent process exits when its task finishes, which would orphan the run).
 - The run registry lives in the pi process: a `/reload` or restart orphans in-flight background runs (their ids stop resolving). `/subagent:status` lists every registered run and its current state.
@@ -281,16 +287,16 @@ Steering queues a correction into a running subagent without killing it — the
 There are two channels into the same mechanism:
 
 - **The model** calls `subagent_steer(id, message)` — typically right after a `subagent_check` snapshot revealed the run heading down a wrong path (check → steer → check again later).
-- **The user** types into the input box of `/subagent:view`, targeting the focused run. Every accepted steer also appears in the run's activity feed as an `↩ steer:` entry, so whoever watches the view sees what was injected and when.
+- **The user** types into the input box of `/subagent:view`, targeting the focused run. Every accepted steer also appears in the run's activity feed, so whoever watches the view sees what was injected and when.
 
-Queued steers are visible in neither wait nor check results — they shape the run's subsequent behavior, not its transcript.
+Steering messages appear in the delegate, wait, check, and live-view activity streams. Pending entries use `↩ steer (queued):`, stay below current activity, and count toward the same five-item collapsed limit. Consumption removes the queued marker without moving the row; `↩ steer:` remains accent-colored in history. Expanded views retain the full activity history. This is TUI presentation only: wait's model-facing response remains a status roll call.
 
 ### Background TUI display
 
 Each tool row renders one aspect of the same decomposition the foreground row shows all at once (input · process · result · usage):
 
 - **Background subagent_delegate row = input only.** Collapsed: `▶ sub-1 <task first line>`. Expanded: plus `@file` references, context size, inherited-conversation size/truncation metadata when enabled, and the full task text. Static — the run progresses invisibly until a subagent_wait/subagent_check row picks it up.
-- **subagent_wait row = process + usage.** The input line shows the id list (or `(all)`) plus the timeout ceiling (`≤30s`) when one was given. One block per watched run: status line (`⏸ queued / ⏳ running` + id + task preview; bare, icon-free once terminal), a live activity stream (collapsed keeps the latest 5 items with a leading ellipsis; expanded shows everything) and a ticking usage bar. Once a run finishes, its process stream is replaced by a **status-only** result line (`✓ finished` / `⏲ budget-exceeded with the reason` / `⏱ timed out` / `⏹ cancelled with the reason` / `✗ <reason>`) — the output itself never appears in a subagent_wait row; expanded keeps the full process stream instead. A timed-out wait freezes the view.
+- **subagent_wait row = process + usage.** The input line shows the id list (or `(all)`). One block per watched run: status line (`⏸ queued / ⏳ running` + id + task preview; bare, icon-free once terminal), a live activity stream (collapsed keeps the latest 5 items with a leading ellipsis; expanded shows everything) and a ticking usage bar. Once a run finishes, its process stream is replaced by a **status-only** result line (`✓ finished` / `⏲ budget-exceeded with the reason` / `⏱ timed out` / `⏹ cancelled with the reason` / `✗ <reason>`) — the output itself never appears in a subagent_wait row; expanded keeps the full process stream instead.
 - **subagent_check row = the result view.** Same block shape as subagent_wait's single-run view (no id — there is only one), but the result line shows `✓ <AI summary>` (or the budget/failure reason when the run stopped early) and the expanded view renders the **full output** — subagent_check is where the conclusion lives.
 - **subagent_cancel row = confirmation only.** Collapsed: `⏹ sub-1 (worker): cancelled after 1 turn (~29s)` (or `• sub-1 (worker) already finished — nothing to cancel` for a no-op). Expanded adds the reason and the pointer to `subagent_check` — the partial output **never renders here**; it stays in the registry until a check row fetches it (layer contract: delegate = input, wait = process, cancel = intervention, check = result).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "3.2.3",
+  "version": "3.3.0",
   "type": "module",
   "description": "Role-based subagent orchestration for pi — delegates tasks to specialized pi child processes with configurable model roles",
   "main": "src/index.ts",

package/src/activity.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { appendActivity, consumeSteer } from "./activity.ts";
+import { buildDisplayItems, formatDisplayItem, renderDisplayItems } from "./utils.ts";
+import type { ActivityEntry } from "./types.ts";
+
+const plain = (_color: string, text: string) => text;
+
+test("pending entries stay below internal activity and consume in place", () => {
+  const log: ActivityEntry[] = [];
+  const first = appendActivity(log, { kind: "toolCall", id: "a", status: "running" });
+  appendActivity(log, { kind: "steer", id: "s1", status: "queued", text: "correct" });
+  appendActivity(log, { kind: "steer", id: "s2", status: "queued", text: "correct" });
+  const second = appendActivity(log, { kind: "toolCall", id: "b", status: "running" });
+  assert.deepEqual(log.map((e) => e.id), ["a", "b", "s1", "s2"]);
+  assert.equal(log[first].id, "a");
+  assert.equal(log[second].id, "b");
+  const before = log.map((e) => e.id);
+  assert.equal(consumeSteer(log, { role: "assistant", content: "correct" }), false);
+  assert.equal(consumeSteer(log, { role: "user", content: "unrelated" }), false);
+  assert.equal(consumeSteer(log, { role: "user", content: [{ type: "text", text: "correct" }] }), true);
+  assert.deepEqual(log.map((e) => e.id), before);
+  assert.deepEqual(log.slice(-2).map((e) => e.status), ["done", "queued"]);
+  appendActivity(log, { kind: "thinking", id: "next", status: "running" });
+  assert.deepEqual(log.map((e) => e.id), ["a", "b", "s1", "next", "s2"]);
+  assert.equal(consumeSteer(log, { role: "user", content: "correct" }), true);
+  assert.equal(consumeSteer(log, { role: "user", content: "correct" }), false);
+});
+
+test("queued items share the visible limit and consumption changes only the marker", () => {
+  const log: ActivityEntry[] = Array.from({ length: 6 }, (_, i) => ({
+    kind: "toolCall", id: `t${i}`, toolName: `tool${i}`, status: "done",
+  }));
+  appendActivity(log, { kind: "steer", id: "s", status: "queued", text: "first\nsecond" });
+  const before = renderDisplayItems(buildDisplayItems(log), 5, plain);
+  assert.equal(before.split("\n").length, 6); // Five items plus the existing history marker.
+  assert.ok(!before.includes("tool1"));
+  assert.ok(before.endsWith("\u21a9 steer (queued): first second"));
+  consumeSteer(log, { role: "user", content: "first\nsecond" });
+  const after = renderDisplayItems(buildDisplayItems(log), 5, plain);
+  assert.equal(after, before.replace(" (queued)", ""));
+  assert.equal(buildDisplayItems(log).length, 7);
+});
+
+test("queued rendering uses status for every display type and steers retain accent", () => {
+  const color = (name: string, text: string) => `<${name}>${text}</${name}>`;
+  for (const status of ["queued", "done"] as const) {
+    assert.match(formatDisplayItem({ type: "steer", status, text: "input" }, color), /^<accent>/);
+  }
+  assert.equal(formatDisplayItem({ type: "steer", status: "done", text: "queued" }, plain), "\u21a9 steer: queued");
+  assert.match(formatDisplayItem({ type: "thinking", status: "queued" }, plain), /\(queued\)/);
+  assert.match(formatDisplayItem({ type: "toolCall", name: "read", args: {}, status: "queued" }, plain), /\(queued\)/);
+});

package/src/activity.ts

@@ -0,0 +1,23 @@
+import type { ActivityEntry } from "./types.ts";
+
+/** @internal Insert live activity before pending entries, keeping the queue at the tail. */
+export function appendActivity(log: ActivityEntry[], entry: ActivityEntry): number {
+  const queued = entry.status === "queued" ? -1 : log.findIndex((item) => item.status === "queued");
+  const index = queued < 0 ? log.length : queued;
+  log.splice(index, 0, entry);
+  return index;
+}
+
+/** @internal Match the user message actually consumed by the child, one occurrence at a time. */
+export function consumeSteer(log: ActivityEntry[], message: { role?: string; content?: unknown }): boolean {
+  if (message.role !== "user") return false;
+  const text = typeof message.content === "string"
+    ? message.content
+    : Array.isArray(message.content)
+      ? message.content.filter((part) => part.type === "text").map((part) => part.text).join("\n")
+      : undefined;
+  const entry = log.find((item) => item.kind === "steer" && item.status === "queued" && item.text === text);
+  if (!entry) return false;
+  entry.status = "done";
+  return true;
+}

package/src/index.ts

@@ -179,7 +179,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "BACKGROUND DELEGATION:",
       "",
       "- Use it only when you have your own work this turn (including an ongoing discussion with the user) while the run executes; otherwise let the call block and return the result directly.",
-      "- Results are pull-only for the model — a completion notice is shown to the user, but nothing wakes you or delivers the result. Dispatching means owning the collection point: finish your own work, then subagent_check(id) for each result. Use subagent_wait(ids) to block until runs finish.",
+      "- When you need a background run's result, collect it with subagent_check if the run has ended; otherwise use subagent_wait, then check to collect it.",
       "- Cancel a run you no longer need with subagent_cancel(id) — the child stops and its partial output stays in the registry for subagent_check to collect.",
       "- Background delegation works only in the top-level session.",
     );
@@ -304,7 +304,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_delegate",
     label: "Delegate to subagent",
     description:
-      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_wait/subagent_check. Subagents are isolated by default; inheritConversation optionally injects a filtered snapshot of the active parent branch.",
+      "Delegate a task to a specialized subagent. By default the call blocks until the run finishes and returns the final output — intermediate tool output stays out of your context. With background: true it returns an id immediately and you collect the result later with subagent_check. Subagents are isolated by default; inheritConversation optionally injects a filtered snapshot of the active parent branch.",
     promptSnippet: "Delegate tasks to specialized subagents",
     promptGuidelines: guidelines,
 
@@ -335,7 +335,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       background: Type.Optional(
         Type.Boolean({
           description:
-            "Non-blocking: returns an id immediately so you can do your own work (or keep discussing with the user) while the run executes — not for parallelism (several foreground calls in one turn already run concurrently). Results are pull-only for the model: a completion notice is shown to the user, but nothing delivers the result or wakes you; fetch with subagent_wait/subagent_check when your own work is done. If the next thing you'd do is wait for the result, omit this and let the call block.",
+            "Return immediately with a run id instead of waiting for the final output. Results are pull-only: a completion notice is shown to the user, but does not deliver the result to the model or wake it.",
         }),
       ),
       cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
@@ -545,7 +545,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_wait",
     label: "Wait for background subagents",
     description:
-      "Block until one or more background subagents (started via subagent_delegate with background: true) finish. Omit ids to wait for ALL current background runs. Returns a per-run roll call — one `id (role): state (turns, elapsed, tokens, cost)` line per run, never the output; fetch it afterwards with subagent_check. If timeout elapses before every run finishes, returns the same roll call (live runs carry usage so far) under a timeout header. Cancelling the wait never cancels the runs — to stop a run, use subagent_cancel(id).",
+      "Wait until all specified background subagent runs end. Omit ids to wait for all current background runs. Returns status and usage for each run; use subagent_check to retrieve results. Cancelling the wait leaves the runs running.",
     promptSnippet: "Wait for background subagents to finish",
     parameters: Type.Object({
       ids: Type.Optional(
@@ -555,12 +555,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
             "Run ids returned by background delegate calls. Omit to wait for all current background runs.",
         }),
       ),
-      timeout: Type.Optional(
-        Type.Number({
-          description:
-            "Max time to wait in seconds. Subagent runs typically take minutes — omit this and let the wait block until they finish (each run's own role timeout is the ceiling); that is the normal usage. Set it only when you must resume soon, e.g. to report progress to the user.",
-        }),
-      ),
+      // Timeout is hidden from the tool schema; restore with the timeoutMs expression below.
+      // timeout: Type.Optional(
+      //   Type.Number({
+      //     description: "Max time to wait in seconds. Omit to wait until all specified runs end.",
+      //   }),
+      // ),
     }),
 
     async execute(_toolCallId, params, signal, onUpdate, _ctx) {
@@ -578,7 +578,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
         );
       }
       const runs = ids.map((id) => backgroundRuns.get(id)!);
-      const timeoutMs = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1000 : 0;
+      // Keep the timeout machinery available while the tool exposes completion-only waiting.
+      // const timeoutMs = typeof params.timeout === "number" && params.timeout > 0 ? params.timeout * 1000 : 0;
+      const timeoutMs = 0;
 
       // ── Live mirror: forward combined snapshots into this tool row ──
       const entries = () => runs.map((r) => ({ id: r.id, role: r.role, result: r.snapshot }));

package/src/reminder.test.ts

@@ -143,9 +143,9 @@ describe("buildInboxReminder", () => {
     assert.ok(text.includes(`"${"x".repeat(70)}..."`));
   });
 
-  test("header explains pull-only collection semantics", () => {
+  test("header identifies results awaiting collection with check", () => {
     const text = buildInboxReminder([entry({ id: "sub-1", state: "running" })], new Set())!;
-    assert.match(text, /^\[background subagent runs — results are pull-only for the model/);
+    assert.match(text, /^\[background subagent runs — results not yet collected with subagent_check/);
     assert.match(text, /already checked on this branch\]/);
   });
 

package/src/reminder.ts

@@ -31,7 +31,7 @@ export interface InboxEntry {
 }
 
 const INBOX_HEADER =
-  "[background subagent runs — results are pull-only for the model: no completion notice wakes you. subagent_wait, then subagent_check to collect each run; a terminal check removes it from this list; runs missing here were already checked on this branch]";
+  "[background subagent runs — results not yet collected with subagent_check; a terminal check removes a run from this list; runs missing here were already checked on this branch]";
 
 /** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
 function formatDuration(totalSec: number): string {

package/src/render-async.ts

@@ -48,13 +48,11 @@ import {
   ensureElapsedTimer,
   formatFallback,
   formatInheritedConversationInput,
-  formatThinking,
+  formatDisplayItem,
   formatTimePart,
-  formatToolCall,
   formatUsageStats,
   renderDisplayItems,
   runIcon,
-  statusStyle,
   taskPreview,
   terminalResultLine,
 } from "./utils.ts";
@@ -85,12 +83,8 @@ function addActivityRows(container: Container, r: SubagentResult, fg: Fg): void
     return;
   }
   for (const item of activity) {
-    if (item.type === "thinking") {
-      container.addChild(new Text(formatThinking(item.status, fg), 0, 0));
-    } else {
-      const { prefix, color } = statusStyle(item.status, fg);
-      container.addChild(new Text(prefix + formatToolCall(item.name, item.args, color), 0, 0));
-    }
+    const row = formatDisplayItem(item, fg);
+    container.addChild(item.type === "steer" ? collapsedText(row) : new Text(row, 0, 0));
   }
 }
 
@@ -207,6 +201,8 @@ function checkEntryExpandedContainer(r: SubagentResult, fg: Fg): Container {
 
   if (state === "finished" || state === "failed") {
     container.addChild(new Text(terminalResultLine(r, fg), 0, 0));
+    container.addChild(new Spacer(1));
+    addActivityRows(container, r, fg);
     // check is the result-fetcher: the full output lives here.
     container.addChild(new Spacer(1));
     if (r.output.trim()) {

package/src/render.test.ts

@@ -1,9 +1,50 @@
-/** Tests for inherited-conversation TUI observability. */
+/** Tests for delegate and background-run TUI observability. */
 
 import assert from "node:assert/strict";
 import test from "node:test";
-import { renderBackgroundDelegateCall, renderBackgroundDelegateResult } from "./render-async.ts";
-import { renderDelegateCall } from "./render.ts";
+import { renderBackgroundDelegateCall, renderBackgroundDelegateResult, renderWaitResult, renderCheckResult } from "./render-async.ts";
+import { renderDelegateCall, renderDelegateResult } from "./render.ts";
+import type { SubagentResult } from "./types.ts";
+
+test("delegate, wait, and check preserve steer rows through consumption and completion", () => {
+  const run: SubagentResult = {
+    role: "worker", task: "task", exitCode: -1, output: "", stderr: "",
+    usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0, contextTokens: 0 },
+    activityLog: [
+      ...Array.from({ length: 6 }, (_, i) => ({ kind: "toolCall" as const, id: `t${i}`, toolName: `tool${i}`, status: "done" as const })),
+      { kind: "steer", id: "s", status: "queued", text: "correction ".repeat(30) },
+    ],
+  };
+  const renderers = [
+    () => ({ render: renderDelegateResult, details: { results: [run] } }),
+    () => ({ render: renderWaitResult, details: { entries: [{ id: "sub-1", role: "worker", result: run }] } }),
+    () => ({ render: renderCheckResult, details: { id: "sub-1", role: "worker", result: run } }),
+  ];
+  for (const make of renderers) {
+    for (const expanded of [false, true]) {
+      for (const width of [40, 100]) {
+        const { render, details } = make();
+        const draw = () => render({ content: [], details } as any, { expanded, isPartial: true }, theme, { state: {} } as any)
+          .render(width).map((line) => line.trimEnd());
+        run.exitCode = -1;
+        run.activityLog.at(-1)!.status = "queued";
+        const pending = draw();
+        const index = pending.findIndex((line) => line.includes("steer (queued):"));
+        assert.ok(index >= 0);
+        assert.ok(expanded || !pending.join("\n").includes("tool1"));
+        run.activityLog.at(-1)!.status = "done";
+        const consumed = draw();
+        assert.equal(consumed.length, pending.length);
+        assert.ok(consumed[index].includes("steer:"));
+        assert.ok(!consumed[index].includes("(queued)"));
+        if (expanded) {
+          run.exitCode = 0;
+          assert.ok(draw().some((line) => line.includes("steer:")));
+        }
+      }
+    }
+  }
+});
 
 const theme = {
   fg: (_color: string, text: string) => text,

package/src/render.ts

@@ -16,13 +16,11 @@ import {
   ensureElapsedTimer,
   formatFallback,
   formatInheritedConversationInput,
-  formatThinking,
+  formatDisplayItem,
   formatTimePart,
-  formatToolCall,
   formatUsageStats,
   renderDisplayItems,
   runIcon,
-  statusStyle,
   taskPreview,
   terminalResultLine,
 } from "./utils.ts";
@@ -150,14 +148,8 @@ export const renderDelegateResult: RenderResultFn = (result, { expanded }, theme
       container.addChild(new Text(theme.fg("muted", runningLabel), 0, 0));
     } else {
       for (const item of displayItems) {
-        if (item.type === "thinking") {
-          container.addChild(new Text(formatThinking(item.status, fg), 0, 0));
-        } else {
-          const { prefix, color } = statusStyle(item.status, fg);
-          container.addChild(
-            new Text(prefix + formatToolCall(item.name, item.args, color), 0, 0),
-          );
-        }
+        const row = formatDisplayItem(item, fg);
+        container.addChild(item.type === "steer" ? collapsedText(row) : new Text(row, 0, 0));
       }
     }
 

package/src/spawn.ts

@@ -13,6 +13,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
+import { appendActivity, consumeSteer } from "./activity.ts";
 import type { SubagentControl, SubagentMessage, SubagentResult } from "./types.ts";
 
 const PI_CODING_AGENT_PACKAGE = "@earendil-works/pi-coding-agent";
@@ -463,6 +464,10 @@ export async function spawnSubagent(
         }
       }
 
+      if (event.type === "message_start" && event.message && consumeSteer(result.activityLog, event.message)) {
+        emitProgress();
+      }
+
       if (event.type === "message_end" && event.message) {
         const msg = event.message as SubagentMessage;
 
@@ -510,14 +515,14 @@ export async function spawnSubagent(
       // Activity log: track thinking blocks and tool calls in arrival order.
       // Both update in place so the TUI reflects real-time state.
       if (event.type === "tool_execution_start" && event.toolCallId) {
-        toolCallIndex.set(event.toolCallId, result.activityLog.length);
-        result.activityLog.push({
+        const index = appendActivity(result.activityLog, {
           kind: "toolCall",
           id: event.toolCallId,
           status: "running",
           toolName: event.toolName,
           args: event.args ?? {},
         });
+        toolCallIndex.set(event.toolCallId, index);
         // Pause the parent timeout clock while the child delegates — nested
         // subagents get their own full budget instead of racing this clock.
         // Ref-counted: concurrent subagent_delegate calls pause once and resume
@@ -545,7 +550,7 @@ export async function spawnSubagent(
       const aev = event.assistantMessageEvent;
       if (event.type === "message_update" && aev) {
         if (aev.type === "thinking_start") {
-          result.activityLog.push({
+          appendActivity(result.activityLog, {
             kind: "thinking",
             id: `thinking-${thinkingCounter++}`,
             status: "running",
@@ -564,7 +569,7 @@ export async function spawnSubagent(
           }
           emitProgress();
         } else if (aev.type === "text_start") {
-          result.activityLog.push({
+          appendActivity(result.activityLog, {
             kind: "text",
             id: `text-${textCounter++}`,
             status: "running",
@@ -719,12 +724,11 @@ export async function spawnSubagent(
         steer(message: string) {
           if (processExited || terminationRequested) return;
           sendCommand({ type: "steer", message });
-          // Mirror the steer into the activity feed so the :view overlay shows
-          // what was injected and when.
-          result.activityLog.push({
+          // Keep pending input visible until the child emits its user message.
+          appendActivity(result.activityLog, {
             kind: "steer",
             id: `steer-${steerCounter++}`,
-            status: "done",
+            status: "queued",
             text: message,
           });
           emitProgress();

package/src/types.ts

@@ -87,7 +87,7 @@ export interface SubagentRole {
 }
 
 /** Status of an individual tool call within a subagent run. */
-export type ToolStatus = "running" | "done" | "failed";
+export type ToolStatus = "queued" | "running" | "done" | "failed";
 
 /** A single entry in the real-time activity log (thinking block, tool call, streamed assistant text, or a user steer). */
 export interface ActivityEntry {

package/src/utils.ts

@@ -142,7 +142,8 @@ export function formatTimePart(r: {
 
 export type DisplayItem =
   | { type: "toolCall"; name: string; args: Record<string, any>; status?: ToolStatus }
-  | { type: "thinking"; status?: ToolStatus };
+  | { type: "thinking"; status?: ToolStatus }
+  | { type: "steer"; text: string; status?: ToolStatus };
 
 /**
  * Map the real-time activity log into renderable display items (in order).
@@ -151,12 +152,12 @@ export type DisplayItem =
  */
 export function buildDisplayItems(activityLog: ActivityEntry[]): DisplayItem[] {
   return activityLog
-    .filter((a) => a.kind === "thinking" || a.kind === "toolCall")
-    .map((a) =>
-      a.kind === "thinking"
-        ? { type: "thinking", status: a.status }
-        : { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status },
-    );
+    .filter((a) => a.kind !== "text")
+    .map((a): DisplayItem => {
+      if (a.kind === "thinking") return { type: "thinking", status: a.status };
+      if (a.kind === "steer") return { type: "steer", text: a.text ?? "", status: a.status };
+      return { type: "toolCall", name: a.toolName ?? "?", args: a.args ?? {}, status: a.status };
+    });
 }
 
 export function shortenPath(p: string): string {
@@ -280,6 +281,24 @@ export function formatThinking(
   return fg("dim", "\u25C6 thought");
 }
 
+export function formatDisplayItem(
+  item: DisplayItem,
+  fg: (color: string, text: string) => string,
+): string {
+  const queued = item.status === "queued";
+  const marker = queued ? " (queued)" : "";
+  if (item.type === "steer") {
+    return fg("accent", `\u21a9 steer${marker}: ${oneLine(item.text)}`);
+  }
+  if (queued) {
+    const body = item.type === "thinking" ? "thinking" : formatToolCall(item.name, item.args, (_c, text) => text);
+    return fg("accent", `\u23f8 ${body}${marker}`);
+  }
+  if (item.type === "thinking") return formatThinking(item.status, fg);
+  const { prefix, color } = statusStyle(item.status, fg);
+  return prefix + formatToolCall(item.name, item.args, color);
+}
+
 export function renderDisplayItems(
   items: DisplayItem[],
   limit: number | undefined,
@@ -290,12 +309,7 @@ export function renderDisplayItems(
   let text = "";
   if (skipped > 0) text += fg("muted", `... ${skipped} earlier items\n`);
   for (const item of toShow) {
-    if (item.type === "thinking") {
-      text += `${formatThinking(item.status, fg)}\n`;
-    } else {
-      const { prefix, color } = statusStyle(item.status, fg);
-      text += `${prefix}${formatToolCall(item.name, item.args, color)}\n`;
-    }
+    text += `${formatDisplayItem(item, fg)}\n`;
   }
   return text.trimEnd();
 }
@@ -622,7 +636,7 @@ export function describeCurrentActivity(r: { activityLog: ActivityEntry[] }): st
   if (!last) return "waiting for first event";
   if (last.kind === "thinking") return last.status === "running" ? "thinking" : "thought";
   if (last.kind === "text") return last.status === "running" ? "responding" : "responded";
-  if (last.kind === "steer") return "steered — awaiting next turn";
+  if (last.kind === "steer") return last.status === "queued" ? "steer queued — awaiting delivery" : "steer received";
   return formatToolCall(last.toolName ?? "?", last.args ?? {}, (_color, text) => text);
 }
 

package/src/view.ts

@@ -58,6 +58,7 @@ import {
   briefFilesUsed,
   formatFallback,
   formatThinking,
+  formatDisplayItem,
   formatTimePart,
   formatToolCall,
   formatTokens,
@@ -396,8 +397,7 @@ export class SubagentViewPanel implements Component, Focusable {
       return truncateToWidth(indent + formatThinking(e.status, fg), width);
     }
     if (e.kind === "steer") {
-      const firstLine = (e.text ?? "").trimEnd().split("\n")[0] || "";
-      return truncateToWidth(indent + fg("accent", `↩ steer: ${firstLine}`), width);
+      return truncateToWidth(indent + formatDisplayItem({ type: "steer", text: e.text ?? "", status: e.status }, fg), width);
     }
     if (e.kind === "text") {
       const buffer = e.text ?? "";
@@ -539,7 +539,7 @@ export class SubagentViewPanel implements Component, Focusable {
       });
       const header =
         `${fg("accent", th.bold("subagents"))} ` +
-        th.fg("dim", `${runningCount} running · ${runs.length} total · Tab/⇧Tab switch`) +
+        th.fg("dim", `${runningCount} running · ${runs.length} total`) +
         "  ";
       const focusIdx = Math.max(0, runs.findIndex((r) => r === focused));
       const win = windowTabCells(cells, focusIdx, innerW - visibleWidth(header));