@d3ara1n/pi-subagent 1.7.1 → 2.1.0

package/README.md

@@ -2,7 +2,7 @@
 
 Role-based subagent orchestration for [pi](https://github.com/earendil-works/pi).
 
-Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, and mid-run corrections can be queued into a running subagent from the view's input box or via `subagent_steer`.
+Provides a `subagent_delegate` tool that lets the main model offload tasks to specialized pi child processes with configurable model roles, real-time TUI progress, and AI-generated summaries. Runs can be foreground (blocking) or background (asynchronous, collected later via `subagent_wait`/`subagent_check`, cancellable via `subagent_cancel`). A centered live view (`/subagent:view`) shows every run's activity feed as it happens, with a per-run brief page for inputs and stats; mid-run corrections can be queued into a running subagent from the view's steer editor or via `subagent_steer`.
 
 ## Design Philosophy
 
@@ -23,7 +23,7 @@ This means:
 
 1. Main model calls the `subagent_delegate` tool with a role and task description
 2. The extension resolves the role to a model via pi-model-roles
-3. Spawns an isolated pi child process in RPC mode (`--mode rpc`) with the configured model, tools, and system prompt — agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands
+3. Spawns an isolated pi child process in RPC mode (`--mode rpc`) with the configured model, tools, and system prompt — agent events stream back over stdout while stdin carries the initial prompt and mid-run steering commands. Children are headless: interactive extension dialogs (`ctx.ui.select/confirm/input`) are answered automatically with `cancelled` (standard "user declined" semantics), so an extension that asks never hangs the run
 4. **Real-time TUI progress** shows tool calls, turns, and elapsed time as the subagent runs
 5. After completion, an **AI-generated one-line summary** is produced for compact display
 6. Returns the result to the main model with usage statistics (turns, tokens, cost)
@@ -54,18 +54,20 @@ This means:
 
 | Command | Description |
 |---------|-------------|
-| `/subagent:view` | Open the live view: a tabbed overlay showing one run's full activity feed at a time, with an input box to steer the focused run |
+| `/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: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`)
 
-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 — its complete activity feed, tail-capped to the visible area with a `⋮ earlier activity` marker when older entries roll off.
+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 feed itself is a continuous, append-only list: 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. 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.
 
-Below the feed sits a steer input box: type a correction and press Enter to queue it into the focused run (only while it is running). The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` closes the overlay.
+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.
+
+Steer input is modal so keys never conflict with typing: in browse mode `s` opens the editor, `Enter` queues the message into the focused run (only while it is running) and returns to browse, `Esc` cancels and clears. The message appears immediately in the feed as an `↩ steer:` entry and is delivered to the child after its current tool batch, before its next LLM call — the run keeps its progress. `Esc` in browse mode closes the overlay.
 
 ## Dependencies
 
@@ -150,11 +152,18 @@ Override, disable, or add subagent roles via `agentOverrides`. Built-in and cust
 }
 ```
 
-**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`. `tools` is optional — absent means all tools, a list restricts to those exact tool names.
+**Required fields for custom roles:** `role`, `description`, `examples`, `decisionTrigger`, `systemPrompt`.
+
+**Tool policy (optional, pick exactly one):**
+
+- `tools` — exact-name allowlist: absent means all tools, a list restricts to exactly those tool names, an **empty array means zero tools**.
+- `excludeTools` — denylist: everything except the listed tool names (handy for e.g. withholding interactive tools from an otherwise full-access role). Absent or empty means no restriction.
+
+Configuring both on the same role is an error — the role is skipped with an error notification at session start.
 
 **Optional fields:** `subagentRoles` (roles this role can spawn via delegate), `timeout` (per-role active-time timeout in seconds; unset or `0` is unlimited, negative values normalize to `0`), `maxTurns` / `maxCost` (per-role budget overrides; unset uses the top-level `maxTurns` / `maxCost` setting, `0` is unlimited, negative values normalize to `0`), `fallbackRole` (backup pi-model-roles role the whole run is retried on after a provider error; unset means no retry — see [Fallback observability](#fallback-observability)).
 
-Invalid custom roles (missing required fields) are silently skipped with an error notification at session start.
+Invalid custom roles (missing required fields) are skipped with an error notification at session start.
 
 ## Usage (by the main model)
 
@@ -220,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": "1.7.1",
+  "version": "2.1.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}`),
       "",
@@ -203,6 +210,22 @@ export default function subagentExtension(pi: ExtensionAPI) {
     refreshAvailableRoles();
     applyAgentOverrides(availableRoles, config.agentOverrides);
 
+    // Tool policy is one-dimensional: `tools` is a closed allowlist,
+    // `excludeTools` an open denylist — carrying both is a contradiction
+    // (intent bug, e.g. "append to the allowlist" written as both fields),
+    // never a combination to resolve. Skip the role loudly; the surviving
+    // role set self-documents via guidelines, and delegate fast-fails on the
+    // missing name.
+    for (const [name, role] of Object.entries(availableRoles)) {
+      if (role.tools !== undefined && role.excludeTools !== undefined) {
+        delete availableRoles[name];
+        ctx.ui.notify(
+          `[pi-subagent] Role "${name}" skipped — "tools" and "excludeTools" are mutually exclusive; configure exactly one.`,
+          "error",
+        );
+      }
+    }
+
     // Validate custom roles (skip built-in roles — they already have all fields)
     // `tools` is optional — absent means the role gets all tools.
     const REQUIRED_FIELDS = [
@@ -264,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",
@@ -276,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({
@@ -368,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

@@ -35,7 +35,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 +44,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 +85,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 +102,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/run.ts

@@ -290,6 +290,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
         cwd: opts.cwd,
         thinking,
         tools: opts.roleDef.tools,
+        excludeTools: opts.roleDef.excludeTools,
         systemPrompt: opts.roleDef.systemPrompt,
         context: opts.context,
         contextFiles: opts.files,
@@ -325,6 +326,7 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
             cwd: opts.cwd,
             thinking: fallback.config.thinking,
             tools: opts.roleDef.tools,
+            excludeTools: opts.roleDef.excludeTools,
             systemPrompt: opts.roleDef.systemPrompt,
             context: opts.context,
             contextFiles: opts.files,

package/src/spawn.test.ts

@@ -9,7 +9,7 @@ import assert from "node:assert/strict";
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
-import { composeInitialMessage } from "./spawn.ts";
+import { buildChildArgs, composeInitialMessage } from "./spawn.ts";
 
 describe("composeInitialMessage", () => {
   test("wraps reference files in <file> blocks ahead of context and task", async () => {
@@ -47,3 +47,60 @@ describe("composeInitialMessage", () => {
     assert.equal(message, "<task>\nt\n</task>");
   });
 });
+
+describe("buildChildArgs", () => {
+  test("base invocation: rpc mode, no session, model, then env+policy prompt blocks", () => {
+    const tmpDir = "/tmp/pi-subagent-x";
+    const args = buildChildArgs("prov/model", {}, tmpDir);
+    assert.deepEqual(args.slice(0, 6), [
+      "--mode",
+      "rpc",
+      "--no-session",
+      "--model",
+      "prov/model",
+      "--append-system-prompt",
+    ]);
+    const joined = args.join(" ");
+    assert.ok(joined.includes(`<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}`));
+    assert.ok(joined.includes("<subagent_policy>"));
+    assert.ok(!joined.includes("--tools"));
+    assert.ok(!joined.includes("--exclude-tools"));
+  });
+
+  test("tools list → exact allowlist flag", () => {
+    const args = buildChildArgs("m", { tools: ["read", "grep"] }, "/t");
+    assert.ok(args.includes("--tools"));
+    assert.equal(args[args.indexOf("--tools") + 1], "read,grep");
+  });
+
+  test("tools: [] → --no-tools (literally zero tools)", () => {
+    const args = buildChildArgs("m", { tools: [] }, "/t");
+    assert.ok(args.includes("--no-tools"));
+    assert.ok(!args.includes("--tools"));
+  });
+
+  test("excludeTools → denylist flag; empty ≡ absent (no flag)", () => {
+    const args = buildChildArgs("m", { excludeTools: ["ask_user"] }, "/t");
+    assert.equal(args[args.indexOf("--exclude-tools") + 1], "ask_user");
+    const empty = buildChildArgs("m", { excludeTools: [] }, "/t");
+    assert.ok(!empty.includes("--exclude-tools"));
+  });
+
+  test("tools wins over excludeTools (both set is rejected upstream; belt only)", () => {
+    const args = buildChildArgs("m", { tools: ["read"], excludeTools: ["bash"] }, "/t");
+    assert.equal(args[args.indexOf("--tools") + 1], "read");
+    assert.ok(!args.includes("--exclude-tools"));
+  });
+
+  test("thinking and role system prompt are wrapped in their blocks", () => {
+    const args = buildChildArgs(
+      "m",
+      { thinking: "high", systemPrompt: "  Be brief.  " },
+      "/t",
+    );
+    assert.equal(args[args.indexOf("--thinking") + 1], "high");
+    const roleIdx = args.findIndex((a) => a.startsWith("<subagent_role>"));
+    assert.ok(roleIdx > 0);
+    assert.equal(args[roleIdx], "<subagent_role>\nBe brief.\n</subagent_role>");
+  });
+});

package/src/spawn.ts

@@ -131,6 +131,91 @@ export function getPiInvocation(args: string[]): { command: string; args: string
   return { command: "pi", args };
 }
 
+/**
+ * Build the pi CLI args for one child run (RPC mode).
+ *
+ * Tool policy mirrors pi's CLI flags in three mutually exclusive states
+ * (tools + excludeTools together is rejected at role resolution):
+ *   - `tools` set      → exact allowlist (`--tools`; empty = `--no-tools`, literally zero tools)
+ *   - `excludeTools` set → denylist (`--exclude-tools`; empty ≡ absent — nothing excluded)
+ *   - neither          → all tools (no flag)
+ *
+ * @internal — exported for testing.
+ */
+export function buildChildArgs(
+  modelRef: string,
+  options: {
+    thinking?: string;
+    tools?: string[];
+    excludeTools?: string[];
+    systemPrompt?: string;
+  },
+  tmpDir: string,
+): string[] {
+  const args: string[] = ["--mode", "rpc", "--no-session", "--model", modelRef];
+
+  if (options.thinking) {
+    args.push("--thinking", options.thinking);
+  }
+
+  if (options.tools) {
+    if (options.tools.length > 0) {
+      args.push("--tools", options.tools.join(","));
+    } else {
+      args.push("--no-tools");
+    }
+  } else if (options.excludeTools && options.excludeTools.length > 0) {
+    args.push("--exclude-tools", options.excludeTools.join(","));
+  }
+
+  // System prompt channel: inline text via --append-system-prompt. pi's
+  // resolvePromptInput treats an existing path as a file to read and any
+  // non-path string as literal text, so structured blocks go directly — no
+  // temp file, zero disk I/O.
+  if (options.systemPrompt?.trim()) {
+    args.push(
+      "--append-system-prompt",
+      `<subagent_role>\n${options.systemPrompt.trim()}\n</subagent_role>`,
+    );
+  }
+  args.push(
+    "--append-system-prompt",
+    `<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}\nAvailable as $PI_SUBAGENT_TMPDIR in bash. Use for git clone and scratch files.\n</subagent_env>`,
+  );
+  // Shared behavioral policy for EVERY subagent run — built-in roles and
+  // agentOverrides customs alike. Role prompts (roles.ts) shape WHAT a role
+  // does; this shapes HOW any subagent behaves when the task exceeds its
+  // actual capabilities: report the gap and stop instead of improvising
+  // workarounds until timeout.
+  args.push(
+    "--append-system-prompt",
+    [
+      "<subagent_policy>",
+      "Before attempting the task, check it against your actual capabilities in this",
+      "session — the tool list here is definitive.",
+      "- 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:",
+      "  ## Cannot complete",
+      "  - Missing: the capability or material that is absent",
+      "  - Needed: what would complete the task",
+      "  - Found: partial findings so far (optional)",
+      "",
+      'An early "cannot complete" report is a successful outcome; grinding on',
+      "impossible workarounds until timeout is the failure.",
+      "</subagent_policy>",
+    ].join("\n"),
+  );
+
+  return args;
+}
+
 /**
  * Compose the initial RPC prompt message: reference files as <file> blocks,
  * then context and task as structured tags — the same shape the child saw in
@@ -177,6 +262,8 @@ export async function spawnSubagent(
     cwd?: string;
     /** Thinking level passed to the child pi process when the role defines one. */
     thinking?: string;
+    /** Extra tools withheld from the child (denylist); ignored when `tools` is set. */
+    excludeTools?: string[];
     tools?: string[];
     systemPrompt?: string;
     /** Extra context delivered as a separate channel from the task. */
@@ -232,64 +319,12 @@ export async function spawnSubagent(
   let tmpDir: string | null = null;
 
   try {
-    // Build CLI args. RPC mode (not json): stdin carries the initial prompt and
-    // mid-run steering commands; stdout streams the same agent events.
-    const args: string[] = ["--mode", "rpc", "--no-session", "--model", modelRef];
-
-    if (options.thinking) {
-      args.push("--thinking", options.thinking);
-    }
-
-    if (options.tools && options.tools.length > 0) {
-      args.push("--tools", options.tools.join(","));
-    }
-
     // Scratch dir handed to the child as PI_SUBAGENT_TMPDIR for its bash work
     // (e.g. git clone). The initial prompt goes over stdin, so there is no
     // argv length limit and no spill-to-tempfile channel anymore.
     tmpDir = await fs.promises.mkdtemp(path.join(os.tmpdir(), "pi-subagent-"));
 
-    // ── System prompt channel: inline text via --append-system-prompt ──
-    // pi's resolvePromptInput treats an existing path as a file to read and any
-    // non-path string as literal text, so we pass structured blocks directly —
-    // no temp file, zero disk I/O. Multiple flags are joined with "\n\n".
-    if (options.systemPrompt?.trim()) {
-      args.push(
-        "--append-system-prompt",
-        `<subagent_role>\n${options.systemPrompt.trim()}\n</subagent_role>`,
-      );
-    }
-    args.push(
-      "--append-system-prompt",
-      `<subagent_env>\nPI_SUBAGENT_TMPDIR=${tmpDir}\nAvailable as $PI_SUBAGENT_TMPDIR in bash. Use for git clone and scratch files.\n</subagent_env>`,
-    );
-    // Shared behavioral policy for EVERY subagent run — built-in roles and
-    // agentOverrides customs alike. Role prompts (roles.ts) shape WHAT a role
-    // does; this shapes HOW any subagent behaves when the task exceeds its
-    // actual capabilities: report the gap and stop instead of improvising
-    // workarounds until timeout.
-    args.push(
-      "--append-system-prompt",
-      [
-        "<subagent_policy>",
-        "Before attempting the task, check it against your actual capabilities in this",
-        "session — the tool list here is definitive.",
-        "- 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.",
-        '- "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:",
-        "  ## Cannot complete",
-        "  - Missing: the capability or material that is absent",
-        "  - Needed: what would complete the task",
-        "  - Found: partial findings so far (optional)",
-        "",
-        'An early "cannot complete" report is a successful outcome; grinding on',
-        "impossible workarounds until timeout is the failure.",
-        "</subagent_policy>",
-      ].join("\n"),
-    );
+    const args = buildChildArgs(modelRef, options, tmpDir);
 
     // ── Initial prompt channel: one RPC prompt command over stdin ──
     // RPC mode rejects @file argv, so reference files are inlined here as
@@ -367,6 +402,20 @@ export async function spawnSubagent(
       // RPC command acknowledgements ("response" lines) carry no agent state.
       if (event.type === "response") return;
 
+      // The child is a headless worker — nobody can answer its dialogs.
+      // RPC-mode ctx.ui.select/confirm/input emit extension_ui_request and
+      // park the child's extension on a promise that has NO default timeout;
+      // without a response the child hangs until the run timeout kills it.
+      // Answer immediately with cancelled:true — the standard "user declined"
+      // semantics (undefined/false) extensions already handle. Fire-and-forget
+      // methods (notify/setStatus/setWidget/setTitle) need no answer.
+      if (event.type === "extension_ui_request" && event.id) {
+        if (event.method === "select" || event.method === "confirm" || event.method === "input") {
+          sendCommand({ type: "extension_ui_response", id: event.id, cancelled: true });
+        }
+        return;
+      }
+
       // RPC mode is a resident server. agent_end only marks one low-level run
       // and may be followed by an automatic retry, compaction, or queued
       // continuation. agent_settled is the authoritative terminal event. We run

package/src/types.ts

@@ -55,10 +55,17 @@ export interface SubagentRole {
   /** System prompt for the subagent */
   systemPrompt: string;
   /**
-   * Tools available to this subagent. Empty or absent = all tools (no restriction).
-   * When set, only the listed tool names are exposed to the child (exact-name allowlist).
+   * Tools available to this subagent — exact-name allowlist mapped to pi's `--tools`.
+   * Absent = all tools (no restriction); empty array = literally zero tools (`--no-tools`).
+   * Mutually exclusive with `excludeTools`.
    */
   tools?: string[];
+  /**
+   * Tools withheld from this subagent — everything else stays available (mapped
+   * to pi's `--exclude-tools`). Absent or empty = no restriction.
+   * Mutually exclusive with `tools`.
+   */
+  excludeTools?: string[];
   /** If this role has `delegate`, restrict which roles it may spawn. undefined = no restriction. */
   subagentRoles?: string[];
   /** Per-role active-time timeout in seconds. `0` or unset means unlimited; negative values are normalized to `0`. */
@@ -245,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;
+}