@d3ara1n/pi-subagent 3.3.0 → 3.3.2

package/README.md

@@ -242,7 +242,7 @@ Three execution properties, kept separate:
 | `subagent_delegate(background: true)` | Start an async run | Just the id (`sub-N`) |
 | `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_steer(id, message)` | Queue a correction or updated requirement into one running run | 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 |
 
 Example tool calls made by the main model:
@@ -260,7 +260,7 @@ The main model continues its own work while these runs execute. Before each mode
 { "id": "sub-1" }
 ```
 
-If the needed run is still queued or running, the model can wait for it through `subagent_wait`:
+If the needed run is still queued or running and no independent work remains, the model waits for it through `subagent_wait` rather than repeatedly polling `subagent_check`:
 
 ```json
 { "ids": ["sub-1"] }
@@ -274,7 +274,7 @@ Semantics worth knowing:
 - **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.
+- **Inbox reminder:** each LLM request with outstanding background runs carries a `[background subagent runs]` reminder at a cache-stable head position. It separates **In progress — no final results available yet** (queued/running) from **Ended — results awaiting collection with subagent_check** (finished/failed, including cancelled ones shown as `cancelled — <reason>`). Empty sections are omitted. Live runs provide status information; only terminal runs are presented as awaiting collection. A check of a live snapshot leaves the run visible, while a terminal check removes it from the reminder on the active branch. Once every result is collected, no reminder is injected. Branch navigation derives delivery from the session tree, not registry bookkeeping.
 - **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).
@@ -282,11 +282,11 @@ Semantics worth knowing:
 
 ### Steering a running subagent
 
-Steering queues a correction into a running subagent without killing it — the middle ground between waiting it out and cancelling. The message is delivered after the child finishes its current tool batch, before its next LLM call, so the run keeps its progress and can change course. It is a suggestion injected between turns, not an interrupt: the child may comply immediately, finish what it was doing first, or ignore poor instructions entirely — to actually stop a run, cancel it.
+Steering queues a correction or updated requirement into a running subagent without killing it. The message is delivered after the child finishes its current tool batch, before its next LLM call, so the run keeps its progress and can change course. It is a suggestion injected between turns, not an interrupt: the child may comply immediately, finish what it was doing first, or ignore poor instructions entirely — to actually stop a run, cancel it.
 
 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 model** calls `subagent_steer(id, message)` when there is a concrete deviation from the delegated task or new information changes its requirements. A running status or repeated checks without a result does not establish a wrong direction or a stall; steering must not ask the child to wrap up or return early merely to avoid waiting.
 - **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.
 
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@d3ara1n/pi-subagent",
-  "version": "3.3.0",
+  "version": "3.3.2",
   "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

@@ -42,11 +42,10 @@ test("queued items share the visible limit and consumption changes only the mark
   assert.equal(buildDisplayItems(log).length, 7);
 });
 
-test("queued rendering uses status for every display type and steers retain accent", () => {
+test("queued rendering uses status for every display type and steer color follows delivery status", () => {
   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.match(formatDisplayItem({ type: "steer", status: "queued", text: "input" }, color), /^<accent>/);
+  assert.match(formatDisplayItem({ type: "steer", status: "done", text: "input" }, color), /^<dim>/);
   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/index.ts

@@ -179,7 +179,8 @@ 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.",
-      "- 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.",
+      "- While a background run is queued or running, continue independent work. When its result is needed and no independent work remains, use subagent_wait, then subagent_check to collect it; if it has already ended, collect it directly. Do not use repeated subagent_check calls as a substitute for waiting.",
+      "- Use subagent_steer for a concrete deviation from the delegated task or new information that changes its requirements. A running status or several checks without a result is not evidence of a wrong direction or a stall. Do not ask the child to wrap up or return early merely to avoid waiting.",
       "- 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.",
     );
@@ -707,13 +708,13 @@ 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 check is the tool for terminal runs. Typical flow: check → steer → check again later.",
+      "Queue a correction or updated requirement into ONE running background subagent. The message is delivered after the child finishes its current tool batch, before its next LLM call; the run keeps its progress. Only running runs accept steering; queued and terminal runs reject it.",
     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" }),
       message: Type.String({
         description:
-          "The correction. Concise and imperative — it lands mid-run, between the child's turns.",
+          "The concrete correction or updated requirement for the child to follow.",
       }),
     }),
 
@@ -740,7 +741,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
         content: [
           {
             type: "text",
-            text: `Steer queued for ${params.id} (${run.role}) — delivered after its current tool batch. Verify the effect with subagent_check later.`,
+            text: `Steer queued for ${params.id} (${run.role}) — delivered after its current tool batch.`,
           },
         ],
         details: { id: params.id, role: run.role, message: params.message },

package/src/reminder.test.ts

@@ -143,10 +143,53 @@ describe("buildInboxReminder", () => {
     assert.ok(text.includes(`"${"x".repeat(70)}..."`));
   });
 
-  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 not yet collected with subagent_check/);
-    assert.match(text, /already checked on this branch\]/);
+  test("live-only reminders report progress without requesting collection", () => {
+    const text = buildInboxReminder([
+      entry({ id: "sub-1", state: "running" }),
+      entry({ id: "sub-2", state: "queued" }),
+    ], new Set())!;
+    assert.match(text, /^\[background subagent runs\]/);
+    assert.match(text, /In progress — no final results available yet:/);
+    assert.doesNotMatch(text, /awaiting collection|subagent_check|Ended/);
+  });
+
+  test("mixed reminders separate live runs from every terminal outcome", () => {
+    const text = buildInboxReminder([
+      entry({ id: "sub-1", state: "finished" }),
+      entry({ id: "sub-2", state: "running" }),
+      entry({ id: "sub-3", state: "failed", snapshot: frame({ exitCode: 1 }) }),
+      entry({ id: "sub-4", state: "queued" }),
+      entry({ id: "sub-5", state: "failed", snapshot: frame({ exitCode: 1, stopReason: "cancelled" }) }),
+    ], new Set())!;
+    const sections = text.split("\n\n");
+    assert.equal(sections.length, 3);
+    assert.match(sections[1], /^In progress/);
+    assert.deepEqual([...sections[1].matchAll(/- (sub-\d+)/g)].map((match) => match[1]), ["sub-2", "sub-4"]);
+    assert.match(sections[2], /^Ended — results awaiting collection with subagent_check/);
+    assert.deepEqual([...sections[2].matchAll(/- (sub-\d+)/g)].map((match) => match[1]), ["sub-1", "sub-3", "sub-5"]);
+  });
+
+  test("completion makes a live run collectible until its terminal result is delivered", () => {
+    const run = entry({ id: "sub-1", state: "running" });
+    const running = buildInboxReminder([run], new Set())!;
+    assert.doesNotMatch(running, /awaiting collection/);
+
+    run.state = "finished";
+    run.snapshot = frame({ elapsedMs: 42_000 });
+    const finished = buildInboxReminder([run], new Set())!;
+    assert.match(finished, /Ended — results awaiting collection with subagent_check/);
+    assert.match(finished, /sub-1 \(worker\) — finished \(ran 42s\)/);
+    assert.doesNotMatch(finished, /In progress/);
+    assert.equal(buildInboxReminder([run], new Set([run.id])), undefined);
+  });
+
+  test("collecting terminal results leaves live runs without a collection section", () => {
+    const text = buildInboxReminder([
+      entry({ id: "sub-1", state: "finished" }),
+      entry({ id: "sub-2", state: "running" }),
+    ], new Set(["sub-1"]))!;
+    assert.match(text, /sub-2 \(worker\) — running/);
+    assert.doesNotMatch(text, /sub-1|awaiting collection|subagent_check|Ended/);
   });
 
   test("terminal rows in the delivered set drop out of the inbox", () => {
@@ -163,7 +206,7 @@ describe("buildInboxReminder", () => {
 
   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.
+    // was not final yet, so the run remains visible as progress information.
     const text = buildInboxReminder(
       [
         entry({ id: "sub-1", state: "queued", snapshot: frame({ exitCode: -1, queued: true }) }),

package/src/reminder.ts

@@ -2,10 +2,10 @@
  * 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 not yet delivered by a
- * subagent_check of a terminal snapshot 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
+ * event. The reminder separates queued/running work from terminal results
+ * awaiting collection by subagent_check on the active branch. Live runs
+ * stay visible as status information without implying a result is ready.
+ * 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.
@@ -30,8 +30,9 @@ export interface InboxEntry {
   snapshot: SubagentResult;
 }
 
-const INBOX_HEADER =
-  "[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]";
+const INBOX_HEADER = "[background subagent runs]";
+const LIVE_HEADER = "In progress — no final results available yet:";
+const TERMINAL_HEADER = "Ended — results awaiting collection with subagent_check; a terminal check removes a run from this section:";
 
 /** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
 function formatDuration(totalSec: number): string {
@@ -71,13 +72,19 @@ function inboxStatus(entry: InboxEntry): string {
  * live-frame checks), so a past peek at a running run never silences it.
  */
 export function buildInboxReminder(entries: Iterable<InboxEntry>, delivered: Set<string>): string | undefined {
-  const rows: string[] = [];
+  const liveRows: string[] = [];
+  const terminalRows: string[] = [];
   for (const entry of entries) {
-    if (entry.state !== "queued" && entry.state !== "running" && delivered.has(entry.id)) continue;
+    const live = entry.state === "queued" || entry.state === "running";
+    if (!live && delivered.has(entry.id)) continue;
+    const rows = live ? liveRows : terminalRows;
     rows.push(`- ${entry.id} (${entry.role}) — ${inboxStatus(entry)} — "${taskPreview(entry.task)}"`);
   }
-  if (rows.length === 0) return undefined;
-  return `${INBOX_HEADER}\n${rows.join("\n")}`;
+  if (liveRows.length === 0 && terminalRows.length === 0) return undefined;
+  const sections = [INBOX_HEADER];
+  if (liveRows.length > 0) sections.push(`${LIVE_HEADER}\n${liveRows.join("\n")}`);
+  if (terminalRows.length > 0) sections.push(`${TERMINAL_HEADER}\n${terminalRows.join("\n")}`);
+  return sections.join("\n\n");
 }
 
 /** Message array type of the `context` event (AgentMessage[]). */

package/src/utils.ts

@@ -288,7 +288,10 @@ export function formatDisplayItem(
   const queued = item.status === "queued";
   const marker = queued ? " (queued)" : "";
   if (item.type === "steer") {
-    return fg("accent", `\u21a9 steer${marker}: ${oneLine(item.text)}`);
+    // Color follows delivery status like every other entry (queued = accent,
+    // consumed = dim); the ↩ glyph alone carries the external-origin marker.
+    const steerColor = queued ? "accent" : "dim";
+    return fg(steerColor, `\u21a9 steer${marker}: ${oneLine(item.text)}`);
   }
   if (queued) {
     const body = item.type === "thinking" ? "thinking" : formatToolCall(item.name, item.args, (_c, text) => text);