@d3ara1n/pi-subagent 2.1.0 → 3.0.0

package/README.md

@@ -32,7 +32,7 @@ This means:
 
 | Role | Model Role | Timeout | Tools | Can Delegate To | Description |
 |------|-----------|---------|-------|-----------------|-------------|
-| `explorer` | fast | 900s | read, find, grep | — | Fast code exploration (read-only) |
+| `explorer` | fast | 900s | read, find, grep, bash | — | Fast code exploration incl. git history inspection (read-only) |
 | `reviewer` | heavy | 3600s | read, bash, grep, find | — | Deep code review, runs git/tests for evidence (read-only) |
 | `worker` | default | 2400s | all (no whitelist) | explorer, researcher | Implementation — the only role that can modify files; full tool access (web, MCP, everything) |
 | `researcher` | fast | 2400s | web_search, fetch_content, source_check, get_search_content, read, bash, edit, write, delegate | explorer | Web research + GitHub repo analysis; writes artifacts only inside its temp dir |
@@ -56,7 +56,7 @@ This means:
 |---------|-------------|
 | `/subagent:view` | Open the live view: a tabbed overlay with a per-run activity feed and a brief detail page (inputs, files, stats), plus modal steer input for the focused run |
 | `/subagent:doctor` | Diagnose pi invocation, model-role resolution, configuration, and role references |
-| `/subagent:status` | List background runs (active + collected) and their current state |
+| `/subagent:status` | List background runs and their current state |
 | `/subagent:cancel <id\|all> [reason]` | Cancel a live background run (or every live run); the optional reason is recorded with the run |
 
 ### Live view (`/subagent:view`)
@@ -229,15 +229,15 @@ Typical flow:
 
 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 unclaimed runs 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 owns the collection point: `subagent_wait`, then `subagent_check` each run. The inbox reminder (below) lists runs not yet checked 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.
-- **Read-once collection:** `subagent_check` on a terminal run returns the result and frees it — the output now lives in the conversation history, and only a lightweight tombstone stays in the registry (`/subagent:status` lists it under "Collected"). Re-checking a collected id explains that its result is already in the history.
-- **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 collect: `subagent_check` still returns the partial output once, and `subagent_wait` reports the run as `cancelled (partial output kept)`.
-- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the unclaimed runs (queued, running, and finished-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Runs missing from the list were already collected — so a finished run the model forgot to check keeps surfacing until it does.
+- **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 (partial output kept)`.
+- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the runs not yet checked on the active branch (queued, running, and finished-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. 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_ms` is optional.** Without it, `subagent_wait` blocks until every run finishes; each run is still bounded by its own role timeout.
 - 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 (active + collected) and its current state.
+- 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.
 
 ### Steering a running subagent
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "2.1.0",
+  "version": "3.0.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/index.ts

@@ -17,7 +17,6 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { getModelRolesAPI } from "@d3ara1n/pi-model-roles";
 import type {
-  CollectedRun,
   SubagentConfig,
   SubagentResult,
   SubagentRole,
@@ -28,6 +27,7 @@ import { BUILTIN_ROLES } from "./roles.ts";
 import { getPiInvocation } from "./spawn.ts";
 import {
   AsyncSemaphore,
+  collectDeliveredIds,
   createThrottler,
   describeCurrentActivity,
   formatBudgetNote,
@@ -47,6 +47,7 @@ import { buildInboxReminder, injectReminder } from "./reminder.ts";
 import { renderDelegateCall, renderDelegateResult } from "./render.ts";
 import { createViewPanel } from "./view.ts";
 import {
+  createSteerCallRender,
   renderBackgroundDelegateCall,
   renderBackgroundDelegateResult,
   renderCancelCall,
@@ -54,6 +55,7 @@ import {
   renderCheckCall,
   renderCheckResult,
   renderCompletionNotice,
+  renderSteerResult,
   renderWaitCall,
   renderWaitResult,
 } from "./render-async.ts";
@@ -101,14 +103,15 @@ export default function subagentExtension(pi: ExtensionAPI) {
   refreshAvailableRoles();
 
   // ── Background run registry ────────────────────────────────────
-  // Process-lifetime map of unclaimed background runs (queued, running, and
+  // Process-lifetime map of background runs (queued, running, and
   // finished/failed alike). Foreground delegate runs are NOT registered —
-  // their lifecycle is the tool call itself. subagent_check on a terminal run
-  // collects it: the handle is freed and a lightweight CollectedRun tombstone
-  // takes its place, so ids stay resolvable while memory does not grow with
-  // full results.
+  // their lifecycle is the tool call itself. Runs stay registered for the
+  // whole session: subagent_check is idempotent and re-delivers the terminal
+  // snapshot on every call, so branch navigation or compaction can never
+  // strand a result outside the model's reach. Whether a run still needs
+  // reminding is NOT tracked here — it derives from the session tree (see
+  // collectDeliveredIds + the context handler), the single source of truth.
   const backgroundRuns = new Map<string, RunHandle>();
-  const collectedRuns = new Map<string, CollectedRun>();
   let runCounter = 0;
   let sessionGeneration = 0;
 
@@ -250,7 +253,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     rebuildGuidelines(availableRoles);
   });
 
-  pi.on("context", async (event) => {
+  pi.on("context", async (event, ctx) => {
     // Completion notices are persisted custom messages so the user can see
     // them in the transcript, but they are deliberately UI-only. Keep the
     // model on the reminder/check path instead of duplicating the notice in
@@ -260,10 +263,16 @@ export default function subagentExtension(pi: ExtensionAPI) {
         message.role !== "custom" || message.customType !== BACKGROUND_COMPLETION_MESSAGE_TYPE,
     );
 
-    // The model's inbox: every unclaimed background run, injected at a
-    // cache-stable head position before every provider call. Empty inbox and
-    // no filtered notices → context stays untouched, cache fully stable.
-    const reminder = buildInboxReminder(backgroundRuns.values());
+    // The model's inbox: every background run not yet checked on the active
+    // branch, injected at a cache-stable head position before every provider
+    // call. Delivery state is derived from the session tree (append-only:
+    // branching away drops the check entry, branching back restores it), so
+    // the inbox re-arms itself after tree navigation. Empty inbox and no
+    // filtered notices → context stays untouched, cache fully stable.
+    const reminder = buildInboxReminder(
+      backgroundRuns.values(),
+      collectDeliveredIds(ctx.sessionManager.buildContextEntries()),
+    );
     if (!reminder && messages.length === event.messages.length) return;
     return { messages: reminder ? injectReminder(messages, reminder) : messages };
   });
@@ -386,9 +395,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
         backgroundRuns.set(run.id, run);
         const runGeneration = sessionGeneration;
         void run.promise.then((result) => {
-          // A collected run already has a visible check result. Do not emit a
-          // second notice, and never publish completions from an old session.
-          if (!backgroundRuns.has(run.id) || runGeneration !== sessionGeneration) return;
+          // Never publish completions from an old session. Within a session
+          // every completion emits its UI-only notice card once — check
+          // results never suppress it (they are not LLM-visible either way).
+          if (runGeneration !== sessionGeneration) return;
 
           const outcome = isFailedResult(result)
             ? "failed"
@@ -543,16 +553,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       const unknown = ids.filter((id) => !backgroundRuns.has(id));
       if (unknown.length > 0) {
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
-        const collectedNotes = unknown
-          .filter((id) => collectedRuns.has(id))
-          .map((id) => `${id} was already collected (result is in your history)`);
-        const trulyUnknown = unknown.filter((id) => !collectedRuns.has(id));
-        const parts = [
-          `Unknown subagent id(s): ${trulyUnknown.length > 0 ? trulyUnknown.join(", ") : "(none)"}.`,
-          collectedNotes.length > 0 ? `${collectedNotes.join("; ")}.` : "",
-          `Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
-        ].filter(Boolean);
-        throw new Error(parts.join(" "));
+        throw new Error(
+          `Unknown subagent id(s): ${unknown.join(", ")}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+        );
       }
       const runs = ids.map((id) => backgroundRuns.get(id)!);
       const timeoutMs =
@@ -659,7 +662,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_check",
     label: "Check a background subagent",
     description:
-      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. Checking a terminal run collects it: the output is returned once and the run leaves the background registry. One id per call because results can be large.",
+      "Get an instant snapshot of ONE background subagent run: queued / running (with current activity) / finished (with the full output as the run result) / failed (with reason and partial output). Does not wait — use subagent_wait for that. Idempotent: checking a terminal run again re-delivers the same snapshot, so the result stays reachable even after branch navigation or compaction. One id per call because results can be large.",
     promptSnippet: "Inspect a background subagent run",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -668,12 +671,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. Check the remaining runs or delegate new ones.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
@@ -683,19 +680,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // Freeze live frames so the snapshot's elapsed time stays static.
       const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
 
-      // Read-once collection: a terminal check returns the result AND frees
-      // the run — the output now lives in the conversation history, so the
-      // registry keeps only a lightweight tombstone for id resolution.
-      if (run.state === "finished" || run.state === "failed") {
-        backgroundRuns.delete(run.id);
-        collectedRuns.set(run.id, {
-          id: run.id,
-          role: run.role,
-          task: taskPreview(run.task),
-          state: run.state,
-        });
-      }
-
       return {
         content: [{ type: "text", text: formatCheckText(run.id, run.role, snap) }],
         details: { id: run.id, role: run.role, result: snap },
@@ -710,7 +694,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_steer",
     label: "Steer a running background subagent",
     description:
-      "Queue a mid-run correction into ONE running background subagent — typically right after subagent_check showed it heading down a wrong path. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress (unlike cancel). Only running runs accept steering; queued runs reject it, and terminal runs are collected by check instead. Typical flow: check → steer → check again later.",
+      "Queue a mid-run correction into ONE running background subagent — typically right after subagent_check showed it heading down a wrong path. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress (unlike cancel). Only running runs accept steering; queued runs reject it, and check is the tool for terminal runs. Typical flow: check → steer → check again later.",
     promptSnippet: "Send a mid-run correction to a background subagent",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -723,12 +707,6 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — nothing left to steer. Delegate a new run if a correction is still needed.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
@@ -752,16 +730,19 @@ export default function subagentExtension(pi: ExtensionAPI) {
             text: `Steer queued for ${params.id} (${run.role}) — delivered after its current tool batch. Verify the effect with subagent_check later.`,
           },
         ],
-        details: { id: params.id, role: run.role },
+        details: { id: params.id, role: run.role, message: params.message },
       };
     },
+
+    renderCall: createSteerCallRender((id) => backgroundRuns.get(id)?.role),
+    renderResult: renderSteerResult,
   });
 
   pi.registerTool({
     name: "subagent_cancel",
     label: "Cancel a background subagent",
     description:
-      "Cancel ONE background subagent run (queued or running): the child process is killed and the run settles as cancelled (its own stop reason, same family as timeout — partial output kept), NOT as a plain failure. The reason is recorded with the run: whoever reads the partial output later via subagent_check sees why it was stopped. Cancelling does not collect — check still returns the partial output once. A finished/failed run cannot be cancelled; check it instead.",
+      "Cancel ONE background subagent run (queued or running): the child process is killed and the run settles as cancelled (its own stop reason, same family as timeout — partial output kept), NOT as a plain failure. The reason is recorded with the run: whoever reads the partial output later via subagent_check sees why it was stopped. Cancelling does not remove the run — check still returns the partial output. A finished/failed run cannot be cancelled; check it instead.",
     promptSnippet: "Cancel a background subagent run",
     parameters: Type.Object({
       id: Type.String({ description: "Run id returned by a background delegate call" }),
@@ -776,19 +757,13 @@ export default function subagentExtension(pi: ExtensionAPI) {
     async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
       const run = backgroundRuns.get(params.id);
       if (!run) {
-        const collected = collectedRuns.get(params.id);
-        if (collected) {
-          throw new Error(
-            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. There is nothing left to cancel.`,
-          );
-        }
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         throw new Error(
           `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
         );
       }
 
-      // Terminal runs cannot be cancelled — point at the collector instead.
+      // Terminal runs cannot be cancelled — point at check instead.
       if (run.state === "finished" || run.state === "failed") {
         const what = run.state === "finished" ? "its result" : "the failure reason and partial output";
         const text =
@@ -822,8 +797,8 @@ export default function subagentExtension(pi: ExtensionAPI) {
   pi.registerCommand("subagent:view", {
     description: "Open the live subagent activity view (watch progress, steer runs)",
     handler: async (_args, ctx) => {
-      // Union of every known run: background registry (until collected) plus
-      // live in-flight runs (foreground delegate calls included). Dedupe by id —
+      // Union of every known run: the background registry plus live
+      // in-flight runs (foreground delegate calls included). Dedupe by id —
       // background runs appear in both.
       const runsProvider = () => {
         const seen = new Set<string>();
@@ -942,40 +917,31 @@ export default function subagentExtension(pi: ExtensionAPI) {
   pi.registerCommand("subagent:status", {
     description: "List background subagent runs and their current state",
     handler: async (_args, ctx) => {
-      if (backgroundRuns.size === 0 && collectedRuns.size === 0) {
+      if (backgroundRuns.size === 0) {
         ctx.ui.notify("No background runs.", "info");
         return;
       }
       const lines: string[] = [];
-      if (backgroundRuns.size > 0) {
-        lines.push("Active:");
-        for (const run of backgroundRuns.values()) {
-          // Freeze live frames so elapsed-dependent details don't drift in the listing.
-          const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
-          let icon: string;
-          let detail: string;
-          if (run.state === "failed") {
-            icon = "\u2717";
-            detail = snap.errorMessage || "unknown error";
-          } else if (run.state === "finished") {
-            icon = "\u2713";
-            detail = snap.summary || taskPreview(snap.output) || "(no output)";
-          } else if (run.state === "queued") {
-            icon = "\u23F8";
-            detail = "queued — waiting for a concurrency slot";
-          } else {
-            icon = "\u23F3";
-            detail = `running — ${describeCurrentActivity(snap)}`;
-          }
-          lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
-        }
-      }
-      if (collectedRuns.size > 0) {
-        if (lines.length > 0) lines.push("");
-        lines.push("Collected (result already returned via subagent_check):");
-        for (const c of collectedRuns.values()) {
-          lines.push(`\u2713 ${c.id} (${c.role}): ${c.state} — "${c.task}"`);
+      lines.push("Runs:");
+      for (const run of backgroundRuns.values()) {
+        // Freeze live frames so elapsed-dependent details don't drift in the listing.
+        const snap = run.result ? run.snapshot : freezeFrame(run.snapshot);
+        let icon: string;
+        let detail: string;
+        if (run.state === "failed") {
+          icon = "\u2717";
+          detail = snap.errorMessage || "unknown error";
+        } else if (run.state === "finished") {
+          icon = "\u2713";
+          detail = snap.summary || taskPreview(snap.output) || "(no output)";
+        } else if (run.state === "queued") {
+          icon = "\u23F8";
+          detail = "queued — waiting for a concurrency slot";
+        } else {
+          icon = "\u23F3";
+          detail = `running — ${describeCurrentActivity(snap)}`;
         }
+        lines.push(`${icon} ${run.id} (${run.role}): ${detail}`);
       }
       ctx.ui.notify(lines.join("\n"), "info");
     },
@@ -1018,13 +984,9 @@ export default function subagentExtension(pi: ExtensionAPI) {
       }
 
       if (target !== "all" && !backgroundRuns.has(target)) {
-        const collected = collectedRuns.get(target);
         const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
         ctx.ui.notify(
-          (collected
-            ? `${target} (${collected.role}) was already collected — nothing to cancel.`
-            : `Unknown subagent id: ${target}.`) +
-            ` Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+          `Unknown subagent id: ${target}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
           "error",
         );
         return;

package/src/reminder.test.ts

@@ -5,9 +5,10 @@
  *   node --test packages/pi-subagent/src/reminder.test.ts
  *
  * Coverage: row formatting per state (queued/running/finished/failed/budget),
- * byte-stability between calls (the cache-prefix contract), empty-inbox
- * no-op, and cache-stable head injection (string content, block content,
- * non-user first message, empty transcript).
+ * delivery-derived row removal (terminal rows checked on the active branch
+ * drop out; live rows never do), byte-stability between calls (the
+ * cache-prefix contract), empty-inbox no-op, and cache-stable head injection
+ * (string content, block content, non-user first message, empty transcript).
  */
 
 import { test, describe } from "node:test";
@@ -40,19 +41,22 @@ function entry(partial: Partial<InboxEntry> & Pick<InboxEntry, "id" | "state">):
 
 describe("buildInboxReminder", () => {
   test("empty inbox returns undefined (zero injection)", () => {
-    assert.equal(buildInboxReminder([]), undefined);
+    assert.equal(buildInboxReminder([], new Set()), undefined);
   });
 
   test("queued and running rows carry no time-derived detail", () => {
-    const text = buildInboxReminder([
-      entry({ id: "sub-3", state: "queued", snapshot: frame({ exitCode: -1, queued: true }) }),
-      entry({
-        id: "sub-2",
-        state: "running",
-        // Live frame: startTime present — a naive formatter would derive elapsed from it.
-        snapshot: frame({ exitCode: -1, startTime: Date.now() - 60_000 }),
-      }),
-    ])!;
+    const text = buildInboxReminder(
+      [
+        entry({ id: "sub-3", state: "queued", snapshot: frame({ exitCode: -1, queued: true }) }),
+        entry({
+          id: "sub-2",
+          state: "running",
+          // Live frame: startTime present — a naive formatter would derive elapsed from it.
+          snapshot: frame({ exitCode: -1, startTime: Date.now() - 60_000 }),
+        }),
+      ],
+      new Set(),
+    )!;
     assert.match(text, /\n- sub-3 \(worker\) — queued — "Investigate flaky tests/);
     assert.match(text, /\n- sub-2 \(worker\) — running — "Investigate flaky tests/);
     // No seconds anywhere on live rows — byte-stability contract.
@@ -60,56 +64,68 @@ describe("buildInboxReminder", () => {
   });
 
   test("finished row freezes duration from elapsedMs", () => {
-    const text = buildInboxReminder([
-      entry({
-        id: "sub-1",
-        state: "finished",
-        snapshot: frame({ exitCode: 0, elapsedMs: 192_000 }),
-      }),
-    ])!;
+    const text = buildInboxReminder(
+      [
+        entry({
+          id: "sub-1",
+          state: "finished",
+          snapshot: frame({ exitCode: 0, elapsedMs: 192_000 }),
+        }),
+      ],
+      new Set(),
+    )!;
     assert.match(text, /\n- sub-1 \(worker\) — finished \(ran 3m12s\) — "Investigate flaky tests/);
   });
 
   test("budget-stopped finished row is flagged partial", () => {
-    const text = buildInboxReminder([
-      entry({
-        id: "sub-1",
-        state: "finished",
-        snapshot: frame({ exitCode: 0, elapsedMs: 300_000, stopReason: "budget_exceeded" }),
-      }),
-    ])!;
+    const text = buildInboxReminder(
+      [
+        entry({
+          id: "sub-1",
+          state: "finished",
+          snapshot: frame({ exitCode: 0, elapsedMs: 300_000, stopReason: "budget_exceeded" }),
+        }),
+      ],
+      new Set(),
+    )!;
     assert.match(text, /— finished, partial — budget exceeded \(ran 5m\) —/);
   });
 
   test("failed row carries the error preview, first line only", () => {
-    const text = buildInboxReminder([
-      entry({
-        id: "sub-4",
-        state: "failed",
-        snapshot: frame({
-          exitCode: 1,
-          elapsedMs: 5_000,
-          errorMessage: "provider timeout\nretry hint: check quota",
+    const text = buildInboxReminder(
+      [
+        entry({
+          id: "sub-4",
+          state: "failed",
+          snapshot: frame({
+            exitCode: 1,
+            elapsedMs: 5_000,
+            errorMessage: "provider timeout\nretry hint: check quota",
+          }),
         }),
-      }),
-    ])!;
+      ],
+      new Set(),
+    )!;
     assert.match(text, /— failed — provider timeout \(ran 5s\) —/);
     assert.doesNotMatch(text, /retry hint/);
   });
 
   test("cancelled row carries the cancel label, not failed", () => {
-    const text = buildInboxReminder([
-      entry({
-        id: "sub-5",
-        state: "failed",
-        snapshot: frame({
-          exitCode: 1,
-          stopReason: "cancelled",
-          elapsedMs: 7_000,
-          errorMessage: "user: wrong direction after review",
+    const text = buildInboxReminder(
+      [
+        entry({
+          id: "sub-5",
+          state: "failed",
+          snapshot: frame({
+            exitCode: 1,
+            stopReason: "cancelled",
+            elapsedMs: 7_000,
+            errorMessage: "user: wrong direction after review",
+          }),
         }),
-      }),
-    ])!;
+      ],
+      new Set(),
+    )!;
     assert.match(text, /— cancelled — user: wrong direction after review \(ran 7s\) —/);
   });
 
@@ -118,19 +134,52 @@ describe("buildInboxReminder", () => {
       entry({ id: "sub-1", state: "finished", snapshot: frame({ exitCode: 0, elapsedMs: 42_000 }) }),
       entry({ id: "sub-2", state: "running", snapshot: frame({ exitCode: -1, startTime: 123 }) }),
     ];
-    assert.equal(buildInboxReminder(entries), buildInboxReminder(entries));
+    assert.equal(buildInboxReminder(entries, new Set()), buildInboxReminder(entries, new Set()));
   });
 
   test("long task text is truncated to the shared 70-char preview cap", () => {
     const long = "x".repeat(120);
-    const text = buildInboxReminder([entry({ id: "sub-9", state: "running", task: long })])!;
+    const text = buildInboxReminder([entry({ id: "sub-9", state: "running", task: long })], new Set())!;
     assert.ok(text.includes(`"${"x".repeat(70)}..."`));
   });
 
   test("header explains pull-only collection semantics", () => {
-    const text = buildInboxReminder([entry({ id: "sub-1", state: "running" })])!;
+    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, /already collected\]/);
+    assert.match(text, /already checked on this branch\]/);
+  });
+
+  test("terminal rows in the delivered set drop out of the inbox", () => {
+    const text = buildInboxReminder(
+      [
+        entry({ id: "sub-1", state: "finished", snapshot: frame({ exitCode: 0, elapsedMs: 42_000 }) }),
+        entry({ id: "sub-2", state: "failed", snapshot: frame({ exitCode: 1, elapsedMs: 5_000 }) }),
+      ],
+      new Set(["sub-1"]),
+    )!;
+    assert.doesNotMatch(text, /sub-1/);
+    assert.match(text, /sub-2 \(worker\) — failed/);
+  });
+
+  test("live rows stay listed even when their id is in the delivered set", () => {
+    // A live frame checked mid-run does not count as delivery — the result
+    // was not final yet, so the run keeps nagging until a terminal check.
+    const text = buildInboxReminder(
+      [
+        entry({ id: "sub-1", state: "queued", snapshot: frame({ exitCode: -1, queued: true }) }),
+        entry({ id: "sub-2", state: "running", snapshot: frame({ exitCode: -1, startTime: 99 }) }),
+      ],
+      new Set(["sub-1", "sub-2"]),
+    )!;
+    assert.match(text, /sub-1 \(worker\) — queued/);
+    assert.match(text, /sub-2 \(worker\) — running/);
+  });
+
+  test("all terminal rows delivered returns undefined (zero injection)", () => {
+    const entries = [
+      entry({ id: "sub-1", state: "finished", snapshot: frame({ exitCode: 0, elapsedMs: 42_000 }) }),
+    ];
+    assert.equal(buildInboxReminder(entries, new Set(["sub-1"])), undefined);
   });
 });
 

package/src/reminder.ts

@@ -1,11 +1,13 @@
 /**
- * The model's inbox of unclaimed background subagent runs.
+ * The model's inbox of background subagent runs.
  *
  * Injected into the LLM context before every provider call via the `context`
- * event. The reminder lists every delegated run whose result has not been
- * claimed yet — queued, running, and finished/failed alike — so the model
- * cannot forget about them. `subagent_check` on a terminal run returns the
- * output AND removes the run from this list (read-once collection).
+ * event. The reminder lists every delegated run not yet delivered by a
+ * subagent_check on the active branch — queued, running, and
+ * finished/failed alike — so the model cannot forget about them. Delivery
+ * state is derived from the session tree (see collectDeliveredIds), not
+ * tracked in the registry: branching past a check re-arms the inbox,
+ * branching back silences it, and compaction un-delivers naturally.
  *
  * Cache discipline: the reminder is prepended to the FIRST user message, so
  * it sits at a stable position in the message prefix. Its content must stay
@@ -28,7 +30,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 collected]";
+  "[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]";
 
 /** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
 function formatDuration(totalSec: number): string {
@@ -61,12 +63,16 @@ function inboxStatus(entry: InboxEntry): string {
 
 /**
  * Build the inbox reminder text, or undefined when every delegated run has
- * been collected (nothing to remind about — inject nothing, keep the context
- * untouched and the provider cache fully stable).
+ * already been checked on the active branch (nothing to remind about —
+ * inject nothing, keep the context untouched and the provider cache fully
+ * stable). Queued/running runs are always listed regardless of delivery
+ * state — their result is not final yet, so a past check (of a live frame)
+ * never counts as delivered.
  */
-export function buildInboxReminder(entries: Iterable<InboxEntry>): string | undefined {
+export function buildInboxReminder(entries: Iterable<InboxEntry>, delivered: Set<string>): string | undefined {
   const rows: string[] = [];
   for (const entry of entries) {
+    if (entry.state !== "queued" && entry.state !== "running" && delivered.has(entry.id)) continue;
     rows.push(`- ${entry.id} (${entry.role}) — ${inboxStatus(entry)} — "${taskPreview(entry.task)}"`);
   }
   if (rows.length === 0) return undefined;

package/src/render-async.ts

@@ -33,6 +33,7 @@ import type {
   CheckDetails,
   CompletionNoticeDetails,
   RunViewEntry,
+  SteerDetails,
   SubagentResult,
   WaitDetails,
 } from "./types.ts";
@@ -387,6 +388,54 @@ export const renderCheckResult: RenderResultFn = (result, { expanded }, theme, _
   return collapsedText(checkEntryCollapsedText(details.result, fg));
 };
 
+// ── steer: correction echo (check verifies the effect) ──
+
+/**
+ * Factory: the call line shows the run's role, but args carry only id +
+ * message — the registry lookup is injected. Unknown id (e.g. re-rendering a
+ * persisted session where the registry is empty) degrades to the bare id.
+ */
+export function createSteerCallRender(roleOf: (id: string) => string | undefined): RenderCallFn {
+  return (args, theme) => {
+    const id = (args as any).id || "...";
+    const role = roleOf(id);
+    const label = role ? `${id} (${role})` : id;
+    const text = theme.fg("toolTitle", theme.bold("subagent_steer ")) + theme.fg("accent", label);
+    return new Text(text, 0, 0);
+  };
+}
+
+export const renderSteerResult: RenderResultFn = (result, { expanded }, theme) => {
+  const details = result.details as SteerDetails | undefined;
+  if (!details) return collapsedText(contentText(result));
+
+  const fg = theme.fg.bind(theme) as Fg;
+  const icon = fg("accent", "\u21a9"); // ↩ — same marker as steer entries in the activity stream
+  const message = details.message.trim() || "(empty message)";
+
+  // Body carries the correction only — no id/role prefix; the target lives in
+  // the call line and the delivery hint below.
+  if (!expanded) {
+    const firstLine = message.split("\n")[0];
+    return collapsedText(`${icon} ${fg("text", firstLine)}`);
+  }
+
+  const container = new Container();
+  container.addChild(new Text(`${icon} ${fg("text", message)}`, 0, 0));
+  container.addChild(new Spacer(1));
+  container.addChild(
+    new Text(
+      fg(
+        "dim",
+        `${details.id} (${details.role}) — delivered after the current tool batch, verify with subagent_check later`,
+      ),
+      0,
+      0,
+    ),
+  );
+  return container;
+};
+
 // ── cancel: confirmation-only view (check is the result-fetcher) ──
 
 export const renderCancelCall: RenderCallFn = (args, theme) => {

package/src/roles.ts

@@ -15,13 +15,18 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 900,
     description:
-      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures.",
-    examples: ["Find where auth middleware is implemented", "Map the routing structure"],
-    decisionTrigger: "Task finds or maps code without touch?",
-    tools: ["read", "find", "grep"],
+      "READ-ONLY codebase exploration — locate files, grep symbols, trace imports, explain structures, inspect git history (log/diff/blame).",
+    examples: [
+      "Find where auth middleware is implemented",
+      "Map the routing structure",
+      "Summarize what the uncommitted diff changes, file by file",
+    ],
+    decisionTrigger: "Task finds or maps code (including git history) without touch?",
+    tools: ["read", "find", "grep", "bash"],
     systemPrompt: [
       "Code explorer. READ-ONLY — locate code, understand it, and report findings; never modify anything.",
       "Search to locate → read the files relevant to the task → trace imports, identify types, interfaces, functions.",
+      "Bash for read-only inspection only: git log/show/blame/diff, ls, wc. Never run a command that modifies files or state (sed, tee, echo >, git checkout/commit, installs).",
       "Skip noise: lockfiles, vendored, minified, and generated files.",
       "",
       "Output format:",

package/src/types.ts

@@ -230,15 +230,6 @@ export interface WaitDetails {
   timedOut?: boolean;
 }
 
-/** Lightweight tombstone kept in the registry after a run's result was claimed via subagent_check — /subagent:status history without the full state machine. */
-export interface CollectedRun {
-  id: string;
-  role: string;
-  /** First-line task preview (same 70-char cap as the inbox reminder). */
-  task: string;
-  state: "finished" | "failed";
-}
-
 /** Details for a check tool result — a frozen one-shot snapshot of a single run. */
 export interface CheckDetails {
   id: string;
@@ -253,6 +244,17 @@ export interface CheckDetails {
  */
 export type CancelDetails = CheckDetails;
 
+/**
+ * Details for a steer tool result — the echoed correction. Collapsed shows
+ * icon + first line; expanded shows the full message plus the delivery hint
+ * (check is the result-fetcher for the effect, never this row).
+ */
+export interface SteerDetails {
+  id: string;
+  role: string;
+  message: string;
+}
+
 /**
  * Details for the background-run completion notice (custom message
  * `subagent-completion`). The renderer lays these out as a structured notice

package/src/utils.test.ts

@@ -44,6 +44,7 @@ import {
   completionNoticeLines,
   formatToolCall,
   briefFilesUsed,
+  collectDeliveredIds,
 } from "./utils.ts";
 import type { ActivityEntry, SubagentResult, SubagentRole } from "./types.ts";
 
@@ -853,3 +854,40 @@ describe("briefFilesUsed", () => {
     assert.equal(used.get(F1), false);
   });
 });
+
+describe("collectDeliveredIds", () => {
+  const checkEntry = (id: string) => ({
+    type: "message",
+    message: { role: "toolResult", toolName: "subagent_check", details: { id, role: "worker" } },
+  });
+
+  test("collects ids from subagent_check tool results only", () => {
+    const entries = [
+      { type: "message", message: { role: "user", content: "hi" } },
+      { type: "message", message: { role: "assistant", content: [] } },
+      { type: "message", message: { role: "toolResult", toolName: "read", details: { id: "sub-9" } } },
+      { type: "message", message: { role: "toolResult", toolName: "subagent_wait", details: { entries: [] } } },
+      checkEntry("sub-1"),
+      { type: "message", message: { role: "custom", customType: "subagent-completion" } },
+      { type: "compaction" },
+    ];
+    assert.deepEqual(collectDeliveredIds(entries), new Set(["sub-1"]));
+  });
+
+  test("dedupes repeated checks of the same id", () => {
+    assert.deepEqual(collectDeliveredIds([checkEntry("sub-1"), checkEntry("sub-1")]), new Set(["sub-1"]));
+  });
+
+  test("empty path means nothing delivered (branch rewound past the check)", () => {
+    assert.equal(collectDeliveredIds([]).size, 0);
+  });
+
+  test("ignores malformed details", () => {
+    const entries = [
+      { type: "message", message: { role: "toolResult", toolName: "subagent_check" } },
+      { type: "message", message: { role: "toolResult", toolName: "subagent_check", details: {} } },
+      { type: "message", message: { role: "toolResult", toolName: "subagent_check", details: { id: 42 } } },
+    ];
+    assert.equal(collectDeliveredIds(entries).size, 0);
+  });
+});

package/src/utils.ts

@@ -638,9 +638,9 @@ export function formatCheckText(id: string, role: string, r: SubagentResult): st
 }
 
 /**
- * Cancel confirmation text: short, no output dump — the partial output is
- * check's job to return (read-once collection). Always points at check so
- * the now-failed registry entry (and its inbox-reminder line) gets cleared.
+ * Cancel confirmation text for the /subagent:cancel command: short, no output
+ * dump — the partial output is check's job to return. Always points at check
+ * so the user knows where the partial output lives.
  */
 /**
  * Compact stop summary shared by the cancel tool text and its TUI row:
@@ -657,8 +657,8 @@ export function cancelStopSummary(r: SubagentResult): string {
 
 /**
  * Cancel confirmation text: short, no output dump — the partial output is
- * check's job to return (read-once collection). Always points at check so
- * the now-cancelled registry entry (and its inbox-reminder line) gets cleared.
+ * check's job to return. Always points at check so the model fetches the
+ * partial output it is entitled to.
  */
 export function formatCancelText(id: string, role: string, r: SubagentResult): string {
   const head = `${id} (${role})`;
@@ -819,3 +819,40 @@ export function truncateOutput(t: string): string {
   const tail = t.slice(-(MAX_OUTPUT_CHARS - 30_050));
   return `[Output truncated — ${t.length} chars total]\n\n${head}\n\n... [truncated] ...\n\n${tail}`;
 }
+
+// ── Session-tree delivery derivation ────────────────────────
+
+/**
+ * Minimal structural slice of a session entry — the only fields
+ * collectDeliveredIds reads. The real SessionEntry from
+ * ctx.sessionManager.buildContextEntries() satisfies this shape structurally;
+ * keeping it local preserves this module's zero pi-API-dependency rule and
+ * lets tests build plain fakes.
+ */
+interface SessionEntryLike {
+  type: string;
+  message?: {
+    role?: string;
+    toolName?: string;
+    details?: unknown;
+  };
+}
+
+/**
+ * Derive the set of background-run ids already delivered by subagent_check
+ * on the given session entries. The session tree is the single source of
+ * truth for delivery state: it is append-only and branch navigation rebuilds
+ * the active path, so branching past a check entry un-delivers (the inbox
+ * re-arms) while branching back re-delivers — no mirrored state to sync.
+ */
+export function collectDeliveredIds(entries: Iterable<SessionEntryLike>): Set<string> {
+  const ids = new Set<string>();
+  for (const entry of entries) {
+    if (entry.type !== "message") continue;
+    const message = entry.message;
+    if (!message || message.role !== "toolResult" || message.toolName !== "subagent_check") continue;
+    const id = (message.details as { id?: unknown } | undefined)?.id;
+    if (typeof id === "string" && id) ids.add(id);
+  }
+  return ids;
+}