@d3ara1n/pi-subagent 2.0.0 → 2.2.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 |
@@ -63,7 +63,7 @@ This means:
 
 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, and the rest of the viewport belongs to it alone — showing one of two pages, toggled with `d`.
 
-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.
+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. A run leaves the view once its result is in the conversation — when the last one goes, the overlay shows a centered empty notice (with `Esc close` hinted) rather than shrinking away.
 
 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), 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.
 
@@ -229,7 +229,7 @@ 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 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 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": "2.0.0",
+  "version": "2.2.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

@@ -53,6 +53,7 @@ import {
   renderCancelResult,
   renderCheckCall,
   renderCheckResult,
+  renderCompletionNotice,
   renderWaitCall,
   renderWaitResult,
 } from "./render-async.ts";
@@ -145,6 +146,12 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "- Delegate ONLY when a task involves significant work (heavy analysis, multi-step investigation, large-scope changes) AND you only care about the conclusion, not intermediate steps. A good test: the task would clutter your context with 3+ turns of raw tool output.",
       "- DO NOT delegate simple tasks — a single read, a one-line edit, a basic grep, or straightforward changes touching 1-2 files. Just do them yourself; spawning a child process costs more than the task.",
       "",
+      "SELF-CONTAINED DELEGATION (subagents have NO memory of this conversation):",
+      "",
+      "- The child sees exactly three things: task, context, files — nothing else of this chat exists for it. Any requirement, decision, or constraint it must know has to be restated in those channels.",
+      "- Never write phantom references (\"as discussed above\", \"per the requirements\") — the child has never seen that material. Inline the actual content instead.",
+      "- The isolation is deliberate: don't dump your whole conversation either. Pass what the task needs and nothing more, so the child's judgment isn't steered by irrelevant history.",
+      "",
       "AVAILABLE ROLES:",
       ...entries.map(([name, role]) => `  - ${name}: ${role.description}`),
       "",
@@ -280,6 +287,10 @@ export default function subagentExtension(pi: ExtensionAPI) {
     for (const run of liveRuns) run.abort("session shutdown");
   });
 
+  // The completion notice card — system-notice styling, not the tool-row
+  // family, so it never reads as model behavior.
+  pi.registerMessageRenderer(BACKGROUND_COMPLETION_MESSAGE_TYPE, renderCompletionNotice);
+
   pi.registerTool({
     name: "subagent_delegate",
     label: "Delegate to subagent",
@@ -292,7 +303,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       role: Type.String({ description: "Subagent role to use" }),
       task: Type.String({
         description:
-          "The work to do. Instructions only — background material belongs in `context`, reference file paths in `files`.",
+          "The work to do — self-contained: the subagent cannot see this conversation, so restate any requirement or constraint it needs here or in `context`. Instructions only — background material belongs in `context`, reference file paths in `files`.",
       }),
       context: Type.Optional(
         Type.String({
@@ -384,19 +395,17 @@ export default function subagentExtension(pi: ExtensionAPI) {
             : 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)}` : "";
+          // Pure notification: id + outcome only. The result itself surfaces
+          // through subagent_check (model) or /subagent:status (user) — the
+          // notice never previews it.
           pi.sendMessage(
             {
               customType: BACKGROUND_COMPLETION_MESSAGE_TYPE,
-              content: `Background subagent ${run.id} (${run.role}) ${outcome}: "${taskPreview(run.task)}"${detailText}`,
+              content: `Background subagent ${run.id} (${run.role}) ${outcome}: "${taskPreview(run.task)}"`,
               display: true,
-              details: { id: run.id, role: run.role, outcome },
+              // Structured payload for the notice renderer; the content string
+              // stays as the non-TUI fallback (export, print mode).
+              details: { id: run.id, role: run.role, outcome, task: run.task },
             },
             { triggerTurn: false },
           );

package/src/render-async.ts

@@ -1,6 +1,7 @@
 /**
  * TUI rendering for background delegation: the background delegate input
- * block, the wait live view, and the check snapshot view.
+ * block, the wait live view, the check snapshot view, and the completion
+ * notice card.
  *
  * This module is deliberately independent of ./render.ts (the foreground
  * delegate family): the two presentation shapes evolve separately and share
@@ -20,12 +21,17 @@
  * line takes over the icon — never both.
  */
 
-import { getMarkdownTheme, type ToolDefinition } from "@earendil-works/pi-coding-agent";
-import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
+import {
+  getMarkdownTheme,
+  type MessageRenderer,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Box, Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type {
   BackgroundDelegateDetails,
   CancelDetails,
   CheckDetails,
+  CompletionNoticeDetails,
   RunViewEntry,
   SubagentResult,
   WaitDetails,
@@ -35,6 +41,7 @@ import {
   cancelStopSummary,
   clearElapsedTimer,
   collapsedText,
+  completionNoticeLines,
   contentText,
   deriveRunState,
   ensureElapsedTimer,
@@ -224,6 +231,53 @@ function checkEntryExpandedContainer(r: SubagentResult, fg: Fg): Container {
   return container;
 }
 
+// ── completion notice: system-notice card, not the tool-row family ──
+
+/**
+ * Renderer for the `subagent-completion` custom message — the background-run
+ * completion notice. Same visual language as pi's [compaction] card
+ * (bracket label + purple box) and deliberately unlike the tool rows above:
+ * no tool-title prefix, no status icons, no usage lines. The bracket label
+ * is the "this is a system event, not model behavior" signal.
+ *
+ * Collapsed: header row + bare task preview beneath, each line truncated
+ * to the box interior width with "…" — the header can never fall off the
+ * right edge. Expanded (ctrl+o): the same lines untruncated, wrapped by Text.
+ */
+export const renderCompletionNotice: MessageRenderer<CompletionNoticeDetails> = (
+  message,
+  { expanded },
+  theme,
+) => {
+  const fg = theme.fg.bind(theme) as Fg;
+  const box = new Box(1, 1, (t) => theme.bg("customMessageBg", t));
+
+  const details = message.details;
+  if (!details) {
+    // Sessions persisted before structured details: fall back to the plain
+    // content string that was sent alongside them.
+    const text =
+      typeof message.content === "string"
+        ? message.content
+        : (message.content ?? [])
+            .filter((c) => c.type === "text")
+            .map((c) => c.text)
+            .join("\n");
+    box.addChild(new Text(fg("customMessageText", text), 0, 0));
+    return box;
+  }
+
+  const lines = completionNoticeLines(details, fg, theme.bold.bind(theme));
+  if (expanded) {
+    for (const line of lines) box.addChild(new Text(line, 0, 0));
+  } else {
+    // Per-line width-aware truncation inside the box (Box hands children the
+    // interior width; collapsedText never lets a line wrap).
+    box.addChild(collapsedText(lines.join("\n")));
+  }
+  return box;
+};
+
 // ── Background delegate: static input block ────────────────────
 
 export const renderBackgroundDelegateCall: 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:",
@@ -35,7 +40,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 3600,
     description:
-      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs, run tests for evidence.",
+      "READ-ONLY code review & analysis — audit code, assess architecture, review diffs, run tests for evidence. Reports findings and suggested fixes but never implements them.",
     examples: [
       "Review the error handling in src/api/ for security issues",
       "Audit this PR diff for performance regressions",
@@ -44,6 +49,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     tools: ["read", "bash", "grep", "find"],
     systemPrompt: [
       "Senior code reviewer. READ-ONLY — you must NOT modify any file.",
+      "If the task asks you to fix or implement, do NOT do it: report findings and suggested fixes, and state that implementation is out of scope for this role.",
       "Run only read-only commands (git diff/log/show, test runs). Never use sed, tee, echo >, or any write command.",
       "Provide evidence-backed findings with file:line references.",
       "",
@@ -84,7 +90,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     fallbackRole: "default",
     timeout: 2400,
     description:
-      "the ONLY role with WEB ACCESS — search docs, fetch pages, verify claims, analyze GitHub repos. Can clone repos & delegate to explorer.",
+      "the ONLY role with WEB ACCESS — search docs, fetch pages, verify claims, analyze GitHub repos. Reports verified facts and sources only; decisions and proposals stay with the caller. Can clone repos & delegate to explorer.",
     examples: ["Find the React 19 migration guide", "Check GitHub issue #1234 for context"],
     decisionTrigger: "Task searches web or GitHub?",
     tools: [
@@ -101,6 +107,7 @@ export const BUILTIN_ROLES: Record<string, SubagentRole> = {
     subagentRoles: ["explorer"],
     systemPrompt: [
       "Web researcher. Search with varied angles, prefer official docs over blogs.",
+      "Report verified facts and sources only — do not propose solutions or make design decisions; the caller weighs your findings and decides.",
       "If first results are insufficient, refine queries and search again.",
       "",
       "## Research artifacts",

package/src/spawn.ts

@@ -196,6 +196,9 @@ export function buildChildArgs(
       "- If the task needs a capability you do not have (web access, bash, file",
       "  writes, ...) or material that is not present locally or in the provided",
       "  context/files, it is out of scope for you. Do NOT improvise workarounds.",
+      "- The task may reference material as 'discussed above' or 'the requirements'",
+      "  — you have NO prior conversation; only this prompt exists. If referenced",
+      "  material is not in this prompt, report it as Missing — do not guess it.",
       '- "Cannot complete" means a capability or material gap — not "difficult" or',
       '  "uncertain". If it is merely hard, keep working within your tools.',
       "- When you hit a genuine gap, stop early and return:",

package/src/types.ts

@@ -252,3 +252,19 @@ export interface CheckDetails {
  * reason, never the partial output (check is the result-fetcher).
  */
 export type CancelDetails = CheckDetails;
+
+/**
+ * Details for the background-run completion notice (custom message
+ * `subagent-completion`). The renderer lays these out as a structured notice
+ * card; the message's plain `content` string stays as the non-TUI fallback
+ * (export, print mode) and for sessions persisted before this shape existed
+ * (task absent there).
+ */
+export interface CompletionNoticeDetails {
+  /** Registry id (sub-N). */
+  id: string;
+  role: string;
+  outcome: "finished" | "failed" | "cancelled";
+  /** Full task text; the renderer flattens and truncates it. */
+  task?: string;
+}

package/src/utils.test.ts

@@ -41,6 +41,7 @@ import {
   createThrottler,
   terminalResultLine,
   buildDisplayItems,
+  completionNoticeLines,
   formatToolCall,
   briefFilesUsed,
 } from "./utils.ts";
@@ -437,6 +438,60 @@ describe("terminalResultLine", () => {
   });
 });
 
+// ── completionNoticeLines: background-run completion notice card ──
+describe("completionNoticeLines", () => {
+  // Marker fakes so assertions can see both text and color placement.
+  const fg = (color: string, text: string) => `<${color}>${text}</${color}>`;
+  const bold = (text: string) => `*${text}*`;
+
+  test("header: bracket label + id (role) + plain-text outcome", () => {
+    assert.deepEqual(
+      completionNoticeLines({ id: "sub-3", role: "worker", outcome: "finished" }, fg, bold),
+      [
+        "<customMessageLabel>*[subagent]*</customMessageLabel> " +
+          "<customMessageText>sub-3 (worker)</customMessageText> " +
+          "<customMessageText>finished</customMessageText>",
+      ],
+    );
+  });
+
+  test("failed colors the outcome error-red, cancelled warning-yellow", () => {
+    const failed = completionNoticeLines({ id: "sub-1", role: "x", outcome: "failed" }, fg, bold)[0];
+    assert.ok(failed.includes("<error>failed</error>"));
+    const cancelled = completionNoticeLines(
+      { id: "sub-1", role: "x", outcome: "cancelled" },
+      fg,
+      bold,
+    )[0];
+    assert.ok(cancelled.includes("<warning>cancelled</warning>"));
+  });
+
+  test("task preview on its own line without a prefix, newlines flattened", () => {
+    const lines = completionNoticeLines(
+      {
+        id: "sub-2",
+        role: "explorer",
+        outcome: "finished",
+        task: "Map the routing\nstructure",
+      },
+      fg,
+      bold,
+    );
+    assert.deepEqual(lines[1], "<dim>Map the routing structure</dim>");
+  });
+
+  test("whitespace-only task: header-only notice", () => {
+    assert.deepEqual(
+      completionNoticeLines(
+        { id: "sub-4", role: "worker", outcome: "finished", task: "  " },
+        fg,
+        bold,
+      ).length,
+      1,
+    );
+  });
+});
+
 // ── formatToolCall: single-line guarantee for TUI rows ──
 describe("formatToolCall newline sanitization", () => {
   const id = (_color: string, text: string) => text;

package/src/utils.ts

@@ -9,6 +9,7 @@ import type { Component } from "@earendil-works/pi-tui";
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type {
   ActivityEntry,
+  CompletionNoticeDetails,
   FallbackFrom,
   RunState,
   SubagentDetails,
@@ -336,6 +337,40 @@ export function taskPreview(task: string): string {
   return firstLine.length > 70 ? `${firstLine.slice(0, 70)}...` : firstLine;
 }
 
+/**
+ * Lines of the background-run completion notice. Bracket label + id/role +
+ * outcome on the header line, the bare task preview beneath (dim). Pure
+ * notification: the result itself never appears here — it surfaces through
+ * subagent_check (model) or /subagent:status (user). The renderer truncates
+ * each line to the terminal width independently, so the header never falls
+ * off the right edge.
+ *
+ * Visual family: the [compaction] system-notice card (bracket label, purple
+ * box), deliberately NOT the tool-row family — no tool-title prefix, no
+ * status icons. Signals "system event", not model behavior.
+ */
+export function completionNoticeLines(
+  details: CompletionNoticeDetails,
+  fg: (color: string, text: string) => string,
+  bold: (text: string) => string,
+): string[] {
+  // Intentional stops keep the plain text color; only real failures go red
+  // (cancelled keeps warning yellow, mirroring result-line semantics).
+  const outcomeColor =
+    details.outcome === "failed" ? "error" : details.outcome === "cancelled" ? "warning" : "customMessageText";
+  const header =
+    fg("customMessageLabel", bold("[subagent]")) +
+    ` ${fg("customMessageText", `${details.id} (${details.role})`)} ` +
+    fg(outcomeColor, details.outcome);
+
+  const lines = [header];
+  const task = oneLine(details.task ?? "").trim();
+  if (task) {
+    lines.push(fg("dim", task));
+  }
+  return lines;
+}
+
 /**
  * Width-aware collapsed-view component: renders each line truncated with "…"
  * to the actual viewport width (never wraps), padded full-width like Text(0,0).

package/src/view.ts

@@ -93,6 +93,12 @@ function printableChar(data: string): string | undefined {
   return data.length === 1 && data >= " " && data <= "~" ? data : undefined;
 }
 
+/** Center a string within `width` visible columns (pad-right handles the tail). */
+function centerText(s: string, width: number): string {
+  const pad = Math.max(0, Math.floor((width - visibleWidth(s)) / 2));
+  return " ".repeat(pad) + s;
+}
+
 /** Elide oversized brief text to head + tail around an elision marker. */
 function capBriefText(text: string): string {
   if (text.length <= BRIEF_TEXT_CAP) return text;
@@ -432,11 +438,13 @@ export class SubagentViewPanel implements Component, Focusable {
 
     // ── Tab row: one cell per run; the focused one is highlighted. ──
     if (runs.length > 0) {
+      // Brackets stay on every cell, focused included — the selectedBg +
+      // accent highlight is the indicator, so Tab doesn't shift text.
       const cells = runs.map((r) => {
         const isFocused = r === focused;
         const label = `${runIcon(r.snapshot, fg)} ${r.id} ${r.role}`;
         const styled = isFocused ? th.bg("selectedBg", fg("accent", label)) : fg("dim", label);
-        return isFocused ? styled : `[${styled}]`;
+        return `[${styled}]`;
       });
       lines.push(
         row(
@@ -445,7 +453,27 @@ export class SubagentViewPanel implements Component, Focusable {
         ),
       );
     } else {
-      lines.push(row(fg("muted", "subagents: no runs.")));
+      // Empty registry — every run left the view (a run disappears once its
+      // result is in the conversation). Give the state real presence — a
+      // full-size panel with a centered message and the close hint — and
+      // fold steer mode back to browse so Esc closes immediately.
+      if (this.mode === "steer") {
+        this.editor.setText("");
+        this.mode = "browse";
+      }
+      lines.push(row(""));
+      lines.push(row(fg("muted", centerText("no subagent runs", innerW))));
+      lines.push(
+        row(
+          fg(
+            "dim",
+            centerText("a run leaves the view once its result is in the conversation", innerW),
+          ),
+        ),
+      );
+      lines.push(row(""));
+      lines.push(row(""));
+      lines.push(row(fg("dim", "Esc close")));
     }
 
     // ── Focused run: header line, then the current page. ──