@d3ara1n/pi-subagent 1.5.1 → 1.7.0

package/README.md

@@ -220,7 +220,7 @@ Typical flow:
 
 Semantics worth knowing:
 
-- **Results are pull-only.** Nothing delivers them to the model — no completion event, no notification, nothing wakes the model up. 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 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.
 - **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)`.

package/package.json

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

@@ -57,6 +57,8 @@ import {
   renderWaitResult,
 } from "./render-async.ts";
 
+const BACKGROUND_COMPLETION_MESSAGE_TYPE = "subagent-completion";
+
 // ── Extension entry ────────────────────────────────────────────────
 
 export default function subagentExtension(pi: ExtensionAPI) {
@@ -107,6 +109,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
   const backgroundRuns = new Map<string, RunHandle>();
   const collectedRuns = new Map<string, CollectedRun>();
   let runCounter = 0;
+  let sessionGeneration = 0;
 
   // ── Live-run reaping ─────────────────────────────────────────
   // Every in-flight run (foreground and background alike), removed once
@@ -159,10 +162,14 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "- Parallel: multiple subagent_delegate calls at the same time run concurrently — foreground and background alike, no special flag.",
       "- Background (background: true): non-blocking — returns an id immediately so you can do your own work while the run executes.",
       "",
+      "RUN HISTORY:",
+      "",
+      "- Every spawned run is audited to ~/.pi/subagent/history/{sessionId}/{toolCallId}.json (toolCallId = the delegate call's id). The file holds the FULL raw output even when you received a compressed/truncated version, plus the task, activity log, and usage.",
+      "",
       "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 — no completion event, no notification, nothing wakes you. Dispatching means owning the collection point: finish your own work, then subagent_check(id) for each result. Use subagent_wait(ids) to block until the run finish.",
+      "- 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 the run finish.",
       "- 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.",
     );
@@ -189,6 +196,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
   rebuildGuidelines(availableRoles);
 
   pi.on("session_start", async (_event, ctx) => {
+    sessionGeneration += 1;
     config = loadSubagentConfig(ctx.cwd);
     concurrencyGate = new AsyncSemaphore(config.maxConcurrency);
 
@@ -220,12 +228,21 @@ export default function subagentExtension(pi: ExtensionAPI) {
   });
 
   pi.on("context", async (event) => {
+    // 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
+    // its context.
+    const messages = event.messages.filter(
+      (message) =>
+        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 →
-    // zero injection (context untouched, cache fully stable).
+    // 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());
-    if (!reminder) return;
-    return { messages: injectReminder(event.messages, reminder) };
+    if (!reminder && messages.length === event.messages.length) return;
+    return { messages: reminder ? injectReminder(messages, reminder) : messages };
   });
 
   pi.on("tool_result", (event) => {
@@ -243,6 +260,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
   // runs are audited to history, gates release. Without this, background
   // children would burn tokens as unwaitable orphans after /reload or /new.
   pi.on("session_shutdown", () => {
+    sessionGeneration += 1;
     for (const run of liveRuns) run.abort("session shutdown");
   });
 
@@ -275,7 +293,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: nothing delivers them to you 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.",
+            "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.",
         }),
       ),
       cwd: Type.Optional(Type.String({ description: "Working directory (defaults to current)" })),
@@ -339,6 +357,34 @@ export default function subagentExtension(pi: ExtensionAPI) {
       // ── Background: return the id immediately; the pipeline keeps running. ──
       if (params.background) {
         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;
+
+          const outcome = isFailedResult(result)
+            ? "failed"
+            : result.stopReason === "cancelled"
+              ? "cancelled"
+              : "finished";
+          const detail =
+            outcome === "failed"
+              ? result.errorMessage || result.stderr
+              : outcome === "cancelled"
+                ? result.errorMessage
+                : result.summary;
+          const detailText = detail?.trim() ? ` — ${taskPreview(detail)}` : "";
+          pi.sendMessage(
+            {
+              customType: BACKGROUND_COMPLETION_MESSAGE_TYPE,
+              content: `Background subagent ${run.id} (${run.role}) ${outcome}: "${taskPreview(run.task)}"${detailText}`,
+              display: true,
+              details: { id: run.id, role: run.role, outcome },
+            },
+            { triggerTurn: false },
+          );
+        });
         return {
           content: [
             { type: "text", text: `Background subagent started — id: ${run.id} (${params.role}).` },

package/src/reminder.test.ts

@@ -129,7 +129,7 @@ describe("buildInboxReminder", () => {
 
   test("header explains pull-only collection semantics", () => {
     const text = buildInboxReminder([entry({ id: "sub-1", state: "running" })])!;
-    assert.match(text, /^\[background subagent runs — results are pull-only/);
+    assert.match(text, /^\[background subagent runs — results are pull-only for the model/);
     assert.match(text, /already collected\]/);
   });
 });

package/src/reminder.ts

@@ -28,7 +28,7 @@ export interface InboxEntry {
 }
 
 const INBOX_HEADER =
-  "[background subagent runs — results are pull-only: nothing notifies 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 collected]";
 
 /** `42s`, `3m12s`, `4m` — whole seconds, no live clocks. */
 function formatDuration(totalSec: number): string {

package/src/utils.test.ts

@@ -41,6 +41,7 @@ import {
   createThrottler,
   terminalResultLine,
   buildDisplayItems,
+  formatToolCall,
 } from "./utils.ts";
 import type { ActivityEntry, SubagentResult, SubagentRole } from "./types.ts";
 
@@ -427,6 +428,28 @@ describe("terminalResultLine", () => {
   test("finishedText replaces the success chain (wait's status-only line)", () => {
     assert.equal(terminalResultLine(baseResult(), id, "finished"), "\u2713 finished");
   });
+  test("error message newlines are flattened to one line", () => {
+    assert.equal(
+      terminalResultLine(baseResult({ exitCode: 1, errorMessage: "boom\n  at frame 2\nat frame 3" }), id),
+      "\u2717 boom at frame 2 at frame 3",
+    );
+  });
+});
+
+// ── formatToolCall: single-line guarantee for TUI rows ──
+describe("formatToolCall newline sanitization", () => {
+  const id = (_color: string, text: string) => text;
+
+  test("multi-line bash command renders as one line", () => {
+    const out = formatToolCall("bash", { command: "echo a\necho b\n  echo c" }, id);
+    assert.ok(!out.includes("\n"));
+    assert.equal(out, "$ echo a echo b echo c");
+  });
+  test("default branch preview flattens embedded newlines", () => {
+    const out = formatToolCall("fetch", { url: "https://x.test/a\n/b" }, id);
+    assert.ok(!out.includes("\n"));
+    assert.ok(out.includes("https://x.test/a /b"));
+  });
 });
 
 // ── createThrottler: burst coalescing for onUpdate ──

package/src/utils.ts

@@ -136,10 +136,30 @@ export function shortenPath(p: string): string {
   return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
 }
 
+/** Flatten embedded newlines (multi-line bash commands, patterns, error
+ *  messages) into single spaces so a row never spans multiple terminal lines.
+ *  Every caller renders the result as ONE TUI row — inline rows join it with
+ *  "\n" separators and the :view overlay wraps each row in a border frame. */
+function oneLine(s: string): string {
+  return s.replace(/\s*\r?\n\s*/g, " ");
+}
+
+/**
+ * One-line tool-call row for TUI display. Newline sanitization happens here
+ * at the single choke point so every tool branch is covered.
+ */
 export function formatToolCall(
   toolName: string,
   args: Record<string, unknown>,
   fg: (color: string, text: string) => string,
+): string {
+  return oneLine(renderToolCall(toolName, args, fg));
+}
+
+function renderToolCall(
+  toolName: string,
+  args: Record<string, unknown>,
+  fg: (color: string, text: string) => string,
 ): string {
   switch (toolName) {
     case "subagent_delegate": {
@@ -306,7 +326,7 @@ function failureResultText(r: {
   const isCancelled = r.stopReason === "cancelled";
   return {
     content:
-      r.errorMessage ||
+      oneLine(r.errorMessage || "") ||
       (isTimeout ? "Timed out" : isBudget ? "Budget exceeded" : isCancelled ? "Cancelled" : "failed"),
     // Timeout/budget/cancel are intentional stops with partial output —
     // warning, not the error red reserved for real failures.