@d3ara1n/pi-subagent 1.2.2 → 1.3.1

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`).
+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`).
 
 ## Design Philosophy
 
@@ -55,7 +55,8 @@ This means:
 | Command | Description |
 |---------|-------------|
 | `/subagent:doctor` | Diagnose pi invocation, model-role resolution, configuration, and role references |
-| `/subagent:status` | List background subagent runs and their current state |
+| `/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 |
 
 ## Dependencies
 
@@ -181,13 +182,14 @@ Three execution properties, kept separate:
 
 - **Foreground** (default): the call blocks until the run finishes and returns the final output directly. (Under the hood foreground and background share one async run engine — foreground is simply background-but-blocking.)
 - **Parallel**: multiple `subagent_delegate` calls in one turn run concurrently — foreground and background alike, no special flag.
-- **Background** (`background: true`): non-blocking — `subagent_delegate` returns immediately with a run id. Use it when you have your own work to do (or a discussion with the user to continue) while the run executes; two companion tools collect the outcome:
+- **Background** (`background: true`): non-blocking — `subagent_delegate` returns immediately with a run id. Use it when you have your own work to do (or a discussion with the user to continue) while the run executes; three companion tools manage the outcome:
 
 | Tool | Purpose | Returns to the model |
 |------|---------|---------------------|
 | `subagent_delegate(background: true)` | Start an async run | Just the id (`sub-N`) |
 | `subagent_wait(ids?, timeout_ms?)` | Block until **all** listed runs finish (omit `ids` for all current background runs) | Statuses only, one `id (role): finished/failed` line per run — never results; errors when the timeout hits with runs unfinished |
 | `subagent_check(id)` | One-shot snapshot of a single run | `queued` / `running` + current activity / the **full output** once finished / failure reason + partial output. Checking a terminal run **collects** it: the output is returned once and the run leaves the registry |
+| `subagent_cancel(id, reason?)` | Kill one live (queued/running) run | Confirmation with the partial-output size — the run settles as `cancelled` (warning styling, same family as timeout/budget) with the reason in its error message; the partial output stays in the registry for `subagent_check` to collect |
 
 Typical flow:
 
@@ -211,7 +213,8 @@ 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.
 - **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.
-- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the unclaimed runs (queued, running, and finished-but-unchecked alike), injected at a cache-stable head position. Runs missing from the list were already collected — so a finished run the model forgot to check keeps surfacing until it does.
+- **Cancellation keeps the partial output.** `subagent_cancel(id, reason?)` kills the child (SIGTERM, escalating to SIGKILL) and settles the run as `cancelled` — its own stop reason in the same family as `timeout`/`budget_exceeded` (TUI warning styling ⏹, not the error-red ✗ of real failures) — with whatever it had produced. The `reason` becomes the error message verbatim, so whoever reads the partial output later via `subagent_check` — or the audit history — sees `cancelled — <reason>`; the source is distinguishable too (`user: ...` for `/subagent:cancel`, the model's own words for the tool, `session shutdown` for reaping). Cancelling does not collect: `subagent_check` still returns the partial output once, and `subagent_wait` reports the run as `cancelled (partial output kept)`.
+- **Inbox reminder:** every LLM call carries a `[background subagent runs]` system reminder listing the unclaimed runs (queued, running, and finished-but-unchecked alike, including cancelled ones — shown as `cancelled — <reason>`), injected at a cache-stable head position. Runs missing from the list were already collected — so a finished run the model forgot to check keeps surfacing until it does.
 - **`timeout_ms` is optional.** Without it, `subagent_wait` blocks until every run finishes; each run is still bounded by its own role timeout.
 - Background runs share the global `maxConcurrency` gate — extra runs show up as `queued` in wait/check views.
 - **Top-level only:** nested subagents cannot delegate in the background (a subagent process exits when its task finishes, which would orphan the run).
@@ -222,8 +225,9 @@ Semantics worth knowing:
 Each tool row renders one aspect of the same decomposition the foreground row shows all at once (input · process · result · usage):
 
 - **Background subagent_delegate row = input only.** Collapsed: `▶ sub-1 <task first line>`. Expanded: plus `@file` references, context size, and the full task text. Static — the run progresses invisibly until a subagent_wait/subagent_check row picks it up.
-- **subagent_wait row = process + usage.** One block per watched run: status line (`⏸ queued / ⏳ running` + id + task preview; bare, icon-free once terminal), a live activity stream (collapsed keeps the latest 5 items with a leading ellipsis; expanded shows everything) and a ticking usage bar. Once a run finishes, its process stream is replaced by a **status-only** result line (`✓ finished` / `⏲ budget-exceeded with the reason` / `✗ <reason>`) — the output itself never appears in a subagent_wait row; expanded keeps the full process stream instead. A timed-out wait freezes the view.
+- **subagent_wait row = process + usage.** The input line shows the id list (or `(all)`) plus the timeout ceiling (`≤30s`) when one was given. One block per watched run: status line (`⏸ queued / ⏳ running` + id + task preview; bare, icon-free once terminal), a live activity stream (collapsed keeps the latest 5 items with a leading ellipsis; expanded shows everything) and a ticking usage bar. Once a run finishes, its process stream is replaced by a **status-only** result line (`✓ finished` / `⏲ budget-exceeded with the reason` / `⏱ timed out` / `⏹ cancelled with the reason` / `✗ <reason>`) — the output itself never appears in a subagent_wait row; expanded keeps the full process stream instead. A timed-out wait freezes the view.
 - **subagent_check row = the result view.** Same block shape as subagent_wait's single-run view (no id — there is only one), but the result line shows `✓ <AI summary>` (or the budget/failure reason when the run stopped early) and the expanded view renders the **full output** — subagent_check is where the conclusion lives.
+- **subagent_cancel row = confirmation only.** Collapsed: `⏹ sub-1 (worker): cancelled after 1 turn (~29s)` (or `• sub-1 (worker) already finished — nothing to cancel` for a no-op). Expanded adds the reason and the pointer to `subagent_check` — the partial output **never renders here**; it stays in the registry until a check row fetches it (layer contract: delegate = input, wait = process, cancel = intervention, check = result).
 
 ### Passing context and reference files
 
@@ -269,7 +273,7 @@ When a provider error (429, quota, timeout, ...) kills a run and the whole task
 
 ### Run history
 
-Every **spawned** delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json` — finished, failed, and aborted alike (an aborted run already consumed tokens, so its partial activity and cost stay auditable). Records cover role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Runs that never spawned (cancelled while queued, role/model resolution failures) are not recorded. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
+Every **spawned** delegate run is written (best-effort) to `~/.pi/subagent/history/{sessionId}/{toolCallId}.json` — finished, failed, and aborted alike (an aborted run already consumed tokens, so its partial activity and cost stay auditable). Records cover role, task, usage, activity log, the **full raw output** (even when the main model saw a compressed/truncated version), and the `fallbackFrom` snapshot when the run was retried on the fallback role. Runs that never spawned (cancelled before starting — at the concurrency gate or during model resolution) are not recorded. Useful for auditing what subagents did and how much they cost. Disable with `history.enabled: false`.
 
 ## License
 

package/package.json

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

@@ -31,6 +31,7 @@ import {
   createThrottler,
   describeCurrentActivity,
   formatBudgetNote,
+  formatCancelText,
   formatCheckText,
   formatFallbackNote,
   formatTimePart,
@@ -47,6 +48,8 @@ import { renderDelegateCall, renderDelegateResult } from "./render.ts";
 import {
   renderBackgroundDelegateCall,
   renderBackgroundDelegateResult,
+  renderCancelCall,
+  renderCancelResult,
   renderCheckCall,
   renderCheckResult,
   renderWaitCall,
@@ -159,6 +162,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
       "",
       "- 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.",
+      "- 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.",
     );
   }
@@ -439,7 +443,7 @@ export default function subagentExtension(pi: ExtensionAPI) {
     name: "subagent_wait",
     label: "Wait for background subagents",
     description:
-      "Block until one or more background subagents (started via subagent_delegate with background: true) finish. Omit ids to wait for ALL current background runs. Returns ONLY each run's final status — one `id (role): finished/failed` line per run, never the results; fetch them afterwards with subagent_check. If timeout_ms elapses before every run finishes, returns an error listing per-run statuses. Cancelling the wait never cancels the runs.",
+      "Block until one or more background subagents (started via subagent_delegate with background: true) finish. Omit ids to wait for ALL current background runs. Returns ONLY each run's final status — one `id (role): finished/failed` line per run, never the results; fetch them afterwards with subagent_check. If timeout_ms elapses before every run finishes, returns an error listing per-run statuses. Cancelling the wait never cancels the runs — to stop a run, use subagent_cancel(id).",
     promptSnippet: "Wait for background subagents to finish",
     parameters: Type.Object({
       ids: Type.Optional(
@@ -546,14 +550,17 @@ export default function subagentExtension(pi: ExtensionAPI) {
       }
 
       // Status line per run — same `id (role): state` shape check uses, so
-      // the model can map ids to roles from wait output alone. Budget-stopped
-      // runs report "finished" but their output is partial — flag it inline.
+      // the model can map ids to roles from wait output alone. Budget stops
+      // report "finished" but their output is partial; cancelled runs keep
+      // their partial output in the registry for check — flag both inline.
       const perId = () =>
         runs
           .map((r) =>
             r.result?.stopReason === "budget_exceeded"
               ? `${r.id} (${r.role}): ${r.state} (budget exceeded — output is partial)`
-              : `${r.id} (${r.role}): ${r.state}`,
+              : r.result?.stopReason === "cancelled"
+                ? `${r.id} (${r.role}): cancelled (partial output kept)`
+                : `${r.id} (${r.role}): ${r.state}`,
           )
           .join("\n");
       if (timedOut) {
@@ -627,6 +634,68 @@ export default function subagentExtension(pi: ExtensionAPI) {
     renderResult: renderCheckResult,
   });
 
+  pi.registerTool({
+    name: "subagent_cancel",
+    label: "Cancel a background subagent",
+    description:
+      "Cancel ONE background subagent run (queued or running): the child process is killed and the run settles as cancelled (its own stop reason, same family as timeout — partial output kept), NOT as a plain failure. The reason is recorded with the run: whoever reads the partial output later via subagent_check sees why it was stopped. Cancelling does not collect — check still returns the partial output once. A finished/failed run cannot be cancelled; check it instead.",
+    promptSnippet: "Cancel a background subagent run",
+    parameters: Type.Object({
+      id: Type.String({ description: "Run id returned by a background delegate call" }),
+      reason: Type.Optional(
+        Type.String({
+          description:
+            "Why the run is no longer needed (a few words suffice). Recorded with the run — whoever reads the partial output later (via subagent_check or history) sees why it was stopped.",
+        }),
+      ),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+      const run = backgroundRuns.get(params.id);
+      if (!run) {
+        const collected = collectedRuns.get(params.id);
+        if (collected) {
+          throw new Error(
+            `${params.id} (${collected.role}) was already collected — its result is in your conversation history. There is nothing left to cancel.`,
+          );
+        }
+        const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
+        throw new Error(
+          `Unknown subagent id: ${params.id}. Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+        );
+      }
+
+      // Terminal runs cannot be cancelled — point at the collector instead.
+      if (run.state === "finished" || run.state === "failed") {
+        const what = run.state === "finished" ? "its result" : "the failure reason and partial output";
+        const text =
+          `${params.id} (${run.role}) already ${run.state} — nothing to cancel. ` +
+          `subagent_check(${params.id}) returns ${what}.`;
+        return {
+          content: [{ type: "text", text }],
+          details: { id: run.id, role: run.role, result: run.snapshot },
+        };
+      }
+
+      // Abort, then wait for the terminal frame: SIGTERM → child cleanup →
+      // cancelled frame carrying the partial output. Bounded by the kill
+      // escalation grace (SIGKILL after 5s), so this await cannot hang.
+      // The reason becomes the terminal errorMessage verbatim — check and
+      // history readers see it prefixed "cancelled — ...".
+      run.abort(params.reason?.trim() || "no longer needed");
+      const result = await run.promise;
+      return {
+        content: [{ type: "text", text: formatCancelText(run.id, run.role, result) }],
+        details: { id: run.id, role: run.role, result },
+      };
+    },
+
+    // Confirmation-only view — the partial output renders only in a check
+    // row (layer contract: cancel intervenes, check fetches).
+    renderCall: renderCancelCall,
+    renderResult: renderCancelResult,
+  });
+
   pi.registerCommand("subagent:doctor", {
     description: "Diagnose pi-subagent configuration and dependencies",
     handler: async (_args, ctx) => {
@@ -756,4 +825,83 @@ export default function subagentExtension(pi: ExtensionAPI) {
       ctx.ui.notify(lines.join("\n"), "info");
     },
   });
+
+  pi.registerCommand("subagent:cancel", {
+    description: "Cancel a background subagent run: /subagent:cancel <id|all> [reason]",
+    getArgumentCompletions: (prefix) => {
+      const items: Array<{ value: string; label: string; description?: string }> = [];
+      for (const run of backgroundRuns.values()) {
+        if (run.state === "queued" || run.state === "running") {
+          items.push({ value: run.id, label: run.id, description: `${run.role} — ${run.state}` });
+        }
+      }
+      if (items.length > 1) {
+        items.push({ value: "all", label: "all", description: "cancel every live run" });
+      }
+      const filtered = items.filter((i) => i.value.startsWith(prefix));
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      // First token = target (id | all), the rest = free-text reason. Without
+      // a reason the abort reads "cancelled by user"; with one, "cancelled by
+      // user: <reason>" — the agent reading the partial output via check sees
+      // that the user (not the model) stopped the run, and why.
+      const trimmed = args.trim();
+      const spaceIdx = trimmed.indexOf(" ");
+      const target = spaceIdx === -1 ? trimmed : trimmed.slice(0, spaceIdx);
+      const reason = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1).trim();
+
+      if (!target) {
+        const live = [...backgroundRuns.values()]
+          .filter((r) => r.state === "queued" || r.state === "running")
+          .map((r) => `${r.id} (${r.role})`);
+        ctx.ui.notify(
+          `Usage: /subagent:cancel <id|all> [reason]\nLive runs: ${live.length > 0 ? live.join(", ") : "(none)"}`,
+          "info",
+        );
+        return;
+      }
+
+      if (target !== "all" && !backgroundRuns.has(target)) {
+        const collected = collectedRuns.get(target);
+        const active = [...backgroundRuns.values()].map((r) => `${r.id} (${r.role})`);
+        ctx.ui.notify(
+          (collected
+            ? `${target} (${collected.role}) was already collected — nothing to cancel.`
+            : `Unknown subagent id: ${target}.`) +
+            ` Active: ${active.length > 0 ? active.join(", ") : "(none)"}.`,
+          "error",
+        );
+        return;
+      }
+
+      // "all" targets only live runs; a named id that finished meanwhile is
+      // reported as already-terminal instead of cancelled.
+      const targets =
+        target === "all"
+          ? [...backgroundRuns.values()].filter((r) => r.state === "queued" || r.state === "running")
+          : [backgroundRuns.get(target)!];
+      if (targets.length === 0) {
+        ctx.ui.notify("No live background runs to cancel.", "info");
+        return;
+      }
+
+      const abortReason = reason.trim() ? `user: ${reason.trim()}` : "user";
+      const lines: string[] = [];
+      for (const run of targets) {
+        if (run.state === "finished" || run.state === "failed") {
+          lines.push(`\u2022 ${run.id} (${run.role}) already ${run.state} — nothing to cancel`);
+          continue;
+        }
+        run.abort(abortReason);
+        const result = await run.promise;
+        lines.push(
+          result.usage.turns > 0 || result.output
+            ? `\u2717 ${run.id} (${run.role}): cancelled after ${result.usage.turns} turn${result.usage.turns === 1 ? "" : "s"} — partial output kept (subagent_check / history)`
+            : `\u2717 ${run.id} (${run.role}): cancelled (nothing had run yet)`,
+        );
+      }
+      ctx.ui.notify(lines.join("\n"), "info");
+    },
+  });
 }

package/src/reminder.test.ts

@@ -97,6 +97,22 @@ describe("buildInboxReminder", () => {
     assert.doesNotMatch(text, /retry hint/);
   });
 
+  test("cancelled row carries the cancel label, not failed", () => {
+    const text = buildInboxReminder([
+      entry({
+        id: "sub-5",
+        state: "failed",
+        snapshot: frame({
+          exitCode: 1,
+          stopReason: "cancelled",
+          elapsedMs: 7_000,
+          errorMessage: "user: wrong direction after review",
+        }),
+      }),
+    ])!;
+    assert.match(text, /— cancelled — user: wrong direction after review \(ran 7s\) —/);
+  });
+
   test("byte-stable: identical state produces identical text", () => {
     const entries = [
       entry({ id: "sub-1", state: "finished", snapshot: frame({ exitCode: 0, elapsedMs: 42_000 }) }),

package/src/reminder.ts

@@ -44,6 +44,13 @@ function inboxStatus(entry: InboxEntry): string {
   if (entry.state === "running") return "running";
   const secs = elapsedSeconds(entry.snapshot);
   const ran = secs != null ? ` (ran ${formatDuration(secs)})` : "";
+  // Cancels are recorded with their own label — the model reading the inbox
+  // must not mistake a deliberate stop ("we no longer need this") for a
+  // crashed run. Same shape as the failed row, reason and frozen duration.
+  if (entry.snapshot.stopReason === "cancelled") {
+    const reason = taskPreview(entry.snapshot.errorMessage || "no reason recorded");
+    return `cancelled — ${reason}${ran}`;
+  }
   if (entry.state === "failed") {
     const reason = taskPreview(entry.snapshot.errorMessage || entry.snapshot.stderr || "unknown error");
     return `failed — ${reason}${ran}`;

package/src/render-async.ts

@@ -24,6 +24,7 @@ import { getMarkdownTheme, type ToolDefinition } from "@earendil-works/pi-coding
 import { Container, Markdown, Spacer, Text } from "@earendil-works/pi-tui";
 import type {
   BackgroundDelegateDetails,
+  CancelDetails,
   CheckDetails,
   RunViewEntry,
   SubagentResult,
@@ -31,6 +32,7 @@ import type {
 } from "./types.ts";
 import {
   buildDisplayItems,
+  cancelStopSummary,
   clearElapsedTimer,
   collapsedText,
   contentText,
@@ -265,8 +267,15 @@ export const renderBackgroundDelegateResult: RenderResultFn = (result, { expande
 
 export const renderWaitCall: RenderCallFn = (args, theme) => {
   const ids = ((args as any).ids as string[] | undefined) ?? [];
+  const timeoutMs = ((args as any).timeout_ms as number | undefined) ?? 0;
   const label = ids.length > 0 ? ids.join(", ") : "(all)";
-  const text = theme.fg("toolTitle", theme.bold("subagent_wait ")) + theme.fg("accent", label);
+  // Show the wait ceiling up front — the user should know how long this row
+  // can block before it gives up. Omitted timeout = wait until runs finish.
+  const cap = timeoutMs > 0 ? ` \u2264${Math.max(1, Math.round(timeoutMs / 1000))}s` : "";
+  const text =
+    theme.fg("toolTitle", theme.bold("subagent_wait ")) +
+    theme.fg("accent", label) +
+    (cap ? theme.fg("dim", cap) : "");
   return new Text(text, 0, 0);
 };
 
@@ -323,3 +332,50 @@ export const renderCheckResult: RenderResultFn = (result, { expanded }, theme, _
   if (expanded) return checkEntryExpandedContainer(details.result, fg);
   return collapsedText(checkEntryCollapsedText(details.result, fg));
 };
+
+// ── cancel: confirmation-only view (check is the result-fetcher) ──
+
+export const renderCancelCall: RenderCallFn = (args, theme) => {
+  const id = (args as any).id || "...";
+  const text = theme.fg("toolTitle", theme.bold("subagent_cancel ")) + theme.fg("accent", id);
+  return new Text(text, 0, 0);
+};
+
+export const renderCancelResult: RenderResultFn = (result, { expanded }, theme, _context) => {
+  const details = result.details as CancelDetails | undefined;
+  if (!details) return collapsedText(contentText(result));
+
+  const fg = theme.fg.bind(theme) as Fg;
+  const r = details.result;
+  const head = `${details.id} (${details.role})`;
+  // Confirmation only — the partial output stays in the registry and renders
+  // only in a subagent_check row. Cancel never shows it (layer contract:
+  // delegate = input, wait = process, cancel = intervention, check = result).
+  const line =
+    r.stopReason === "cancelled"
+      ? `${fg("warning", "\u23F9")} ${fg("text", `${head}: ${cancelStopSummary(r)}`)}`
+      : `${fg("muted", "\u2022")} ${fg("dim", `${head} already ${deriveRunState(r)} — nothing to cancel`)}`;
+  if (!expanded) return collapsedText(line);
+
+  const container = new Container();
+  container.addChild(new Text(line, 0, 0));
+  container.addChild(new Spacer(1));
+  if (r.stopReason === "cancelled") {
+    container.addChild(new Text(fg("dim", `reason: ${r.errorMessage || "—"}`), 0, 0));
+    container.addChild(
+      new Text(
+        fg(
+          "dim",
+          `partial output (${r.output.length} chars) kept in the registry — subagent_check(${details.id}) returns it once`,
+        ),
+        0,
+        0,
+      ),
+    );
+  } else {
+    container.addChild(
+      new Text(fg("dim", `subagent_check(${details.id}) returns its result`), 0, 0),
+    );
+  }
+  return container;
+};

package/src/run.test.ts

@@ -137,6 +137,9 @@ test("a throwing spawn resolves the promise with a failed result carrying the er
   assert.strictEqual(run.state, "failed");
   assert.ok(run.thrown instanceof Error);
   assert.strictEqual(run.thrown.message, "Subagent was aborted");
+  // Non-abort crashes (spawn failure) keep the plain thrown message — the
+  // cancelled stop reason is reserved for real aborts.
+  assert.strictEqual(result.stopReason, undefined);
   assert.strictEqual(result.errorMessage, "Subagent was aborted");
   // The partial frame survives — the foreground path renders aborts like any
   // failure (task line + activity + result line) instead of a bare error.
@@ -252,7 +255,8 @@ test("abort while queued fails the run and exposes thrown for the foreground pat
 
   assert.strictEqual(run.state, "failed");
   assert.ok(run.thrown instanceof Error);
-  assert.match(result.errorMessage!, /cancelled while queued/);
+  assert.strictEqual(result.stopReason, "cancelled");
+  assert.match(result.errorMessage!, /still queued for a concurrency slot/);
   gate.release();
 });
 
@@ -267,8 +271,8 @@ test("handle.abort() reaps a queued background run (no caller signal)", async ()
 
   assert.strictEqual(run.state, "failed");
   assert.ok(run.thrown instanceof Error);
-  assert.match(result.errorMessage!, /cancelled while queued/);
-  assert.match(result.errorMessage!, /session shutdown/);
+  assert.strictEqual(result.stopReason, "cancelled");
+  assert.strictEqual(result.errorMessage, "still queued for a concurrency slot (session shutdown)");
   gate.release();
 });
 
@@ -289,7 +293,10 @@ test("handle.abort(reason) fails a running run with the reason in the error mess
   const result = await run.promise;
 
   assert.strictEqual(run.state, "failed");
-  assert.match(result.errorMessage!, /Subagent was aborted \(session shutdown\)/);
+  assert.strictEqual(result.stopReason, "cancelled");
+  // The abort reason becomes the errorMessage verbatim — renderers add the
+  // "cancelled" framing, so the message itself must not repeat it.
+  assert.strictEqual(result.errorMessage, "session shutdown");
   assert.ok(run.thrown instanceof Error);
   // The internal controller the spawn honored is the same channel abort() used.
   assert.ok(signals[0].aborted);
@@ -307,7 +314,10 @@ test("a pre-aborted caller signal chains into the run before spawn", async () =>
   const result = await run.promise;
 
   assert.strictEqual(run.state, "failed");
-  assert.strictEqual(result.errorMessage, "Subagent was aborted");
+  // Caller-signal abort (foreground Esc): no explicit reason was given, so
+  // the cancelled frame falls back to the bare "cancelled" message.
+  assert.strictEqual(result.stopReason, "cancelled");
+  assert.strictEqual(result.errorMessage, "cancelled");
   // abort() after settle is a no-op — the terminal state never flips.
   run.abort("session shutdown");
   assert.strictEqual(run.state, "failed");

package/src/run.ts

@@ -190,9 +190,11 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
       await opts.gate.acquire(controller.signal);
     } catch {
       const msg =
-        "cancelled while queued for a concurrency slot" +
-        (abortReason ? ` (${abortReason})` : "");
-      finish({ ...inputFrame(1, false), errorMessage: msg }, new Error(msg));
+        "still queued for a concurrency slot" + (abortReason ? ` (${abortReason})` : "");
+      finish(
+        { ...inputFrame(1, false), stopReason: "cancelled", errorMessage: msg },
+        new Error(msg),
+      );
       return;
     }
 
@@ -364,17 +366,23 @@ export function startSubagentRun(opts: StartRunOptions): RunHandle {
       // Keep whatever the last live frame gathered so aborted/crashed runs
       // still show their partial activity and usage.
       const partial = snapshot;
+      // Aborts settle as their own stop reason ("cancelled", same family as
+      // timeout/budget: intentional stop with partial output) and the abort
+      // reason becomes the error message verbatim — no wrapper needed, every
+      // renderer already prefixes "cancelled". Non-abort crashes (spawn
+      // failure) keep the plain thrown message.
+      const wasCancelled = controller.signal.aborted;
       const terminal: SubagentResult = {
         ...inputFrame(1, false),
         output: partial.output,
         usage: partial.usage,
         model: partial.model,
-        stopReason: partial.stopReason,
+        stopReason: wasCancelled ? "cancelled" : undefined,
         activityLog: partial.activityLog,
         budgetMs: partial.budgetMs,
         elapsedMs: partial.startTime ? Date.now() - partial.startTime : undefined,
-        errorMessage: abortReason
-          ? `Subagent was aborted (${abortReason})`
+        errorMessage: wasCancelled
+          ? abortReason || "cancelled"
           : err?.message || String(err),
       };
       // The run spawned before throwing — audit it like any terminal state.

package/src/spawn.ts

@@ -231,6 +231,33 @@ export async function spawnSubagent(
       "--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"),
+    );
 
     // ── Context channel: independent size gate ──
     // Large context spills to @ctx.md (pi auto-wraps in <file>); small context

package/src/types.ts

@@ -230,3 +230,10 @@ export interface CheckDetails {
   role: string;
   result: SubagentResult;
 }
+
+/**
+ * Details for a cancel tool result — same shape as check: the run's terminal
+ * frame. Renders with the confirmation-only view: the stop summary and the
+ * reason, never the partial output (check is the result-fetcher).
+ */
+export type CancelDetails = CheckDetails;

package/src/utils.test.ts

@@ -35,6 +35,7 @@ import {
   formatFallbackNote,
   formatBudgetNote,
   formatCheckText,
+  formatCancelText,
   formatTimePart,
   freezeFrame,
   createThrottler,
@@ -411,6 +412,15 @@ describe("terminalResultLine", () => {
       "\u23F2 Budget exceeded (50 turns; partial output returned)",
     );
   });
+  test("cancelled maps to the ⏹ warning styling like timeout/budget", () => {
+    assert.equal(
+      terminalResultLine(
+        baseResult({ exitCode: 1, stopReason: "cancelled", errorMessage: "user: wrong direction" }),
+        id,
+      ),
+      "\u23F9 user: wrong direction",
+    );
+  });
   test("success chain: AI summary wins, then output first line, then placeholder", () => {
     assert.equal(terminalResultLine(baseResult({ summary: "did the thing" }), id), "\u2713 did the thing");
     assert.equal(terminalResultLine(baseResult(), id), "\u2713 ok");
@@ -528,6 +538,8 @@ describe("background run helpers", () => {
     assert.equal(deriveRunState(baseResult()), "finished");
     assert.equal(deriveRunState(baseResult({ exitCode: 1 })), "failed");
     assert.equal(deriveRunState(baseResult({ stopReason: "timeout", exitCode: 124 })), "failed");
+    // cancelled stops are failures with partial output (same family as timeout)
+    assert.equal(deriveRunState(baseResult({ stopReason: "cancelled" })), "failed");
     // budget stops are intentional finishes
     assert.equal(deriveRunState(baseResult({ stopReason: "budget_exceeded" })), "finished");
   });
@@ -603,6 +615,47 @@ describe("background run helpers", () => {
     assert.match(formatCheckText("sub-1", "explorer", baseResult()), /^sub-1 \(explorer\): finished\n\nok$/);
   });
 
+  test("formatCheckText renders cancelled with the bare reason and partial output", () => {
+    assert.match(
+      formatCheckText(
+        "sub-1",
+        "explorer",
+        baseResult({ exitCode: 1, stopReason: "cancelled", errorMessage: "user: wrong direction" }),
+      ),
+      /^sub-1 \(explorer\): cancelled — user: wrong direction\n\nPartial output:\nok$/,
+    );
+  });
+
+  test("formatCancelText distinguishes never-started cancels from mid-run cancels", () => {
+    // Never-started cancel (gate/model-resolution phase): terminal frame has
+    // NO elapsedMs — nothing ran. Mirrors the real terminal-frame shape:
+    // startTime never survives (live-frame-only field), duration freezes
+    // into elapsedMs.
+    assert.match(
+      formatCancelText("sub-1", "explorer", baseResult({ exitCode: -1, output: "", usage: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, contextTokens: 0, turns: 0 } })),
+      /^sub-1 \(explorer\): cancelled — never started, no partial output\. subagent_check\(sub-1\) clears the registry entry\.$/,
+    );
+    // Mid-run cancel: real terminal shape — elapsedMs frozen, no startTime.
+    const midRun = baseResult({
+      exitCode: -1,
+      elapsedMs: 45000,
+      output: "partial findings",
+      usage: { input: 1000, output: 200, cacheRead: 0, cacheWrite: 0, cost: 0.1, contextTokens: 0, turns: 3 },
+    });
+    assert.match(
+      formatCancelText("sub-2", "worker", midRun),
+      /^sub-2 \(worker\): cancelled after 3 turns \(~45s\) — partial output \(16 chars\) kept in the registry; subagent_check\(sub-2\) returns it once\.$/,
+    );
+    // Aborted before the first completed turn: "under a turn", not "0 turns".
+    const underATurn = baseResult({
+      exitCode: -1,
+      elapsedMs: 2000,
+      output: "",
+      usage: { input: 1000, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0.05, contextTokens: 0, turns: 0 },
+    });
+    assert.match(formatCancelText("sub-3", "worker", underATurn), /cancelled after under a turn \(~2s\)/);
+  });
+
   test("formatCheckText flags budget-stopped runs as partial on the finished line", () => {
     const r = baseResult({ stopReason: "budget_exceeded", errorMessage: "Budget exceeded (50 turns)" });
     assert.match(

package/src/utils.ts

@@ -288,6 +288,7 @@ export function runIcon(
   if (state === "running") return fg("warning", "\u23F3");
   if (r.stopReason === "timeout") return fg("warning", "\u23F1");
   if (r.stopReason === "budget_exceeded") return fg("warning", "\u23F2");
+  if (r.stopReason === "cancelled") return fg("warning", "\u23F9");
   if (state === "failed") return fg("error", "\u2717");
   return fg("success", "\u2713");
 }
@@ -299,9 +300,14 @@ function failureResultText(r: {
 }): { content: string; col: "warning" | "error" } {
   const isTimeout = r.stopReason === "timeout";
   const isBudget = r.stopReason === "budget_exceeded";
+  const isCancelled = r.stopReason === "cancelled";
   return {
-    content: r.errorMessage || (isTimeout ? "Timed out" : isBudget ? "Budget exceeded" : "failed"),
-    col: isTimeout || isBudget ? "warning" : "error",
+    content:
+      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.
+    col: isTimeout || isBudget || isCancelled ? "warning" : "error",
   };
 }
 
@@ -386,6 +392,7 @@ export function isFailedResult(r: { exitCode: number; stopReason?: string }): bo
     r.exitCode !== 0 ||
     r.stopReason === "error" ||
     r.stopReason === "aborted" ||
+    r.stopReason === "cancelled" ||
     r.stopReason === "timeout"
   );
 }
@@ -509,12 +516,51 @@ export function formatCheckText(id: string, role: string, r: SubagentResult): st
   const head = `${id} (${role})`;
   if (state === "queued") return `${head}: queued — waiting for a concurrency slot.`;
   if (state === "running") return `${head}: running — ${describeCurrentActivity(r)}`;
+  if (r.stopReason === "cancelled") {
+    // errorMessage is the bare abort reason ("user: ..." / "session shutdown")
+    // — the "cancelled" prefix here is the only wrapper it gets.
+    return `${head}: cancelled — ${r.errorMessage || "no reason recorded"}\n\nPartial output:\n${r.output}${formatFallbackNote(r)}`;
+  }
   if (state === "failed") {
     return `${head}: failed — ${r.errorMessage || r.stderr || "unknown error"}\n\nPartial output:\n${r.output}${formatFallbackNote(r)}`;
   }
   return `${head}: finished\n\n${r.output}${formatBudgetNote(r)}${formatFallbackNote(r)}${formatUsageFooter(r)}`;
 }
 
+/**
+ * Cancel confirmation text: short, no output dump — the partial output is
+ * check's job to return (read-once collection). Always points at check so
+ * the now-failed registry entry (and its inbox-reminder line) gets cleared.
+ */
+/**
+ * Compact stop summary shared by the cancel tool text and its TUI row:
+ * `cancelled after 3 turns (~45s)` / `cancelled after under a turn (~2s)` /
+ * `cancelled — never started` (never spawned: no elapsedMs on the frame).
+ */
+export function cancelStopSummary(r: SubagentResult): string {
+  if (r.elapsedMs == null) return "cancelled — never started";
+  const turns = r.usage.turns;
+  const secs = Math.max(1, Math.round(r.elapsedMs / 1000));
+  const turnNote = turns > 0 ? `${turns} turn${turns === 1 ? "" : "s"}` : "under a turn";
+  return `cancelled after ${turnNote} (~${secs}s)`;
+}
+
+/**
+ * Cancel confirmation text: short, no output dump — the partial output is
+ * check's job to return (read-once collection). Always points at check so
+ * the now-cancelled registry entry (and its inbox-reminder line) gets cleared.
+ */
+export function formatCancelText(id: string, role: string, r: SubagentResult): string {
+  const head = `${id} (${role})`;
+  if (r.elapsedMs == null) {
+    return `${head}: cancelled — never started, no partial output. subagent_check(${id}) clears the registry entry.`;
+  }
+  return (
+    `${head}: ${cancelStopSummary(r)} — partial output (${r.output.length} chars) ` +
+    `kept in the registry; subagent_check(${id}) returns it once.`
+  );
+}
+
 /** Freeze a live frame into a static snapshot: stop the elapsed clock and fold the open pause into grace. */
 export function freezeFrame(r: SubagentResult): SubagentResult {
   return {