@mystilleef/pi-subagent 0.3.1 → 0.5.0

package/README.md

@@ -1,38 +1,81 @@
 # Subagent
 
-This `pi` extension provides a `subagent` tool designed for the
-[SPAE Framework](https://github.com/mystilleef/spae-framework).
+`pi-subagent` adds isolated subagent orchestration to
+[Pi](https://github.com/earendil-works/pi). It provides a `subagent`
+tool and `/run` command for delegating work to specialized agents in
+separate child Pi processes. Designed especially for the `SPAE`
+framework, but doesn't require it.
+
+## Action
+
+Agents in
+[action](https://raw.githubusercontent.com/mystilleef/pi-subagent/main/assets/parallel-agents-demo.mp4).
 
 ## Installation
 
+**Install from `npm`:**
+
 ```sh
 pi install npm:@mystilleef/pi-subagent
 ```
 
+**Try temporarily without installing:**
+
+```sh
+pi -e npm:@mystilleef/pi-subagent
+```
+
 ## Features
 
-- **Asynchronous:** Agents always run in background.
-- **Parallel:** Run more than one agents simultaneously.
-- **Simplicity:** No advanced orchestration workflows.
-- **Bloat-free:** No pre-installed agents.
+- **Asynchronous:** Agents run in the background.
+- **Parallel:** Run many agents simultaneously.
+- **Isolated:** Each delegated task receives a separate context window.
+- **Simple:** No complex orchestration workflow required.
+- **Bloat-free:** No bundled agents.
 
 ## Usage
 
-Invoke an agent with:
+**Run an agent with an optional task:**
 
 ```text
 /run agent [optional task]
 ```
 
-Stop running agents with:
+**Examples:**
+
+```text
+/run spec implement google login screen
+/run plan
+/run inspect
+/run build
+/run verify
+```
+
+**Use natural language to launch agents in parallel:**
+
+```text
+use the work agent to write a poem about linux; use the commit agent to make
+commits; use the query agent to summarize the project.
+```
+
+**Show active and completed jobs:**
+
+```text
+/jobs
+```
+
+**Cancel running `subagents`:**
 
 ```text
 /cancel-subagent
 ```
 
-## Workflow
+## _SPAE_ Workflow
 
-The [SPAE Framework](https://github.com/mystilleef/spae-framework) emphasizes a structured workflow.
+`pi-subagent` supports the
+[`SPAE` Framework](https://github.com/mystilleef/spae-framework), but
+doesn't require it. `SPAE` provides pre-built agents and skills for a
+structured workflow.
 
 | Phase | Agent                     | Purpose                                       |
 | ----- | ------------------------- | --------------------------------------------- |
@@ -42,4 +85,119 @@ The [SPAE Framework](https://github.com/mystilleef/spae-framework) emphasizes a
 | 4     | `/run build`              | Carry out tasks from `PLAN.md`                |
 | 5     | `/run verify`             | Verify implementation against `SPEC.md`       |
 
-Visit the [SPAE Framework](https://github.com/mystilleef/spae-framework) for pre-packaged agents and their associated skills.
+## Agent definitions
+
+This package ships no agents. Define agents as Markdown files with YAML
+`frontmatter` and a Markdown system prompt body.
+
+**Discovery locations:**
+
+- User-global agents: `~/.pi/agents/*.md`
+- Project-local agents: nearest `.pi/agents/*.md`
+
+**Required `frontmatter`:**
+
+```yaml
+name: review
+description: Review code for correctness and maintainability.
+```
+
+**Optional `frontmatter`:**
+
+```yaml
+tools: read, bash, edit
+skills: code-review
+thinking: medium
+```
+
+**Accepted `thinking` values:**
+
+- `off`
+- `minimal`
+- `low`
+- `medium`
+- `high`
+- `xhigh`
+
+## Tool
+
+The extension also registers a `subagent` tool for model-driven
+delegation.
+
+**Inputs:**
+
+- `agent`: agent name.
+- `task`: task prompt for the child agent.
+- `agentScope`: optional lookup scope, one of `user`, `project`, or
+  `both`.
+- `debug`: optional flag that includes full child messages in result
+  details.
+
+## Security
+
+`Subagents` launch child `pi --json` processes. Agents, tools, and
+extensions run with user permissions, so treat agent definitions like
+executable automation.
+
+**Trust guidance:**
+
+- Review project-local agents before running them.
+- Avoid delegating secrets unless the agent and tools need them.
+- Prefer trusted repositories for shared agent definitions.
+- Remember that child agents can call their configured tools.
+
+## Configuration and limits
+
+**Environment variables:**
+
+- `PI_SUBAGENT_DEPTH`: nested subagent depth guard. Nested calls stop at
+  depth `1`.
+- `PI_SUBAGENT_MAX_OUTPUT_BYTES`: max returned output bytes. Default:
+  `50000`.
+- `PI_SUBAGENT_MAX_OUTPUT_LINES`: max returned output lines. Default:
+  `500`.
+
+## Troubleshooting
+
+**Missing agent:**
+
+- Confirm the file lives under `~/.pi/agents/` or the nearest
+  `.pi/agents/`.
+- Confirm `frontmatter` includes `name` and `description`.
+- Confirm `/run` uses the `name` value, not the filename.
+
+**Project-local agent prompt:**
+
+- Pi may request confirmation before loading project-local agents when
+  UI context exists.
+
+**Nested subagent blocked:**
+
+- Nested delegation hits the `PI_SUBAGENT_DEPTH` safety limit.
+- Run the child task directly from the parent session instead.
+
+**Truncated output:**
+
+- Raise `PI_SUBAGENT_MAX_OUTPUT_BYTES` or
+  `PI_SUBAGENT_MAX_OUTPUT_LINES`.
+- Ask the child agent for a shorter summary.
+
+## Development
+
+**Install dependencies:**
+
+```sh
+bun install
+```
+
+**Run full verification:**
+
+```sh
+bun verify
+```
+
+**Check npm package contents:**
+
+```sh
+bun pack:smoke
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mystilleef/pi-subagent",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Pi subagent for the SPAE Framework",
   "author": "Lateef Alabi-Oki <mystilleef@gmail.com>",
   "license": "MIT",
@@ -8,7 +8,13 @@
     "type": "git",
     "url": "git+https://github.com/mystilleef/pi-subagent.git"
   },
+  "bugs": {
+    "url": "https://github.com/mystilleef/pi-subagent/issues"
+  },
+  "homepage": "https://github.com/mystilleef/pi-subagent#readme",
   "keywords": [
+    "pi-package",
+    "pi-extension",
     "pi",
     "agent",
     "subagent",
@@ -23,7 +29,8 @@
   },
   "type": "module",
   "engines": {
-    "bun": ">=1.3.13"
+    "bun": ">=1.3.13",
+    "node": ">=18"
   },
   "files": [
     "src",
@@ -33,26 +40,37 @@
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "video": "https://raw.githubusercontent.com/mystilleef/pi-subagent/main/assets/parallel-agents-demo.mp4"
+  },
+  "publishConfig": {
+    "access": "public"
   },
   "scripts": {
-    "verify": "bun check && bun test",
-    "coverage": "bun check && bun test --coverage",
-    "check": "biome check --fix --unsafe . && tsc --noEmit",
+    "verify": "bun fix && bun check && bun test",
+    "coverage": "bun fix && bun check && bun test --coverage",
+    "check": "biome check . && tsc --noEmit",
+    "fix": "biome check --write --unsafe .",
+    "pack:smoke": "bun scripts/pack-smoke.ts",
     "migrate": "biome migrate --write",
     "release": "sh -c 'npm version \"$1\" -m \"chore(release): %s\" && git push --follow-tags' --"
   },
-  "dependencies": {
-    "@earendil-works/pi-agent-core": "^0.74.0",
-    "@earendil-works/pi-ai": "^0.74.0",
-    "@earendil-works/pi-coding-agent": "^0.74.0",
-    "@earendil-works/pi-tui": "^0.74.0",
-    "typebox": "^1.1.38"
+  "peerDependencies": {
+    "@earendil-works/pi-agent-core": "*",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.15",
+    "@earendil-works/pi-agent-core": "^0.75.4",
+    "@earendil-works/pi-ai": "^0.75.4",
+    "@earendil-works/pi-coding-agent": "^0.75.4",
+    "@earendil-works/pi-tui": "^0.75.4",
     "@types/bun": "^1.3.14",
-    "@types/node": "^25.8.0",
+    "@types/node": "^25.9.1",
+    "typebox": "^1.1.38",
     "typescript": "^6.0.3"
   }
 }

package/src/cancel-command.ts

@@ -15,7 +15,9 @@ export async function cancelSubagentCommandHandler(
       return;
     }
     const options = [
-      ...jobs.map((job) => `${job.agentName} (${job.requestId})`),
+      ...jobs.map(
+        (job) => `${job.agentName} ${job.instanceName} (${job.requestId})`,
+      ),
       "All running subagents",
     ];
     const selection = await ctx.ui.select("Cancel subagent", options);

package/src/index.ts

@@ -7,6 +7,7 @@ import {
   resetAgentDiscoveryCache,
 } from "./agent-cache.js";
 import { cancelSubagentCommandHandler } from "./cancel-command.js";
+import { jobsCommandHandler } from "./jobs-command.js";
 import { renderSubagentProgress } from "./progress.js";
 import { renderSubagentResultMessage } from "./run.js";
 import { runCommandHandler } from "./run-command.js";
@@ -38,6 +39,10 @@ export default function registerSubagentExtension(pi: ExtensionAPI) {
       "Cancel active /run subagents: /cancel-subagent [requestId|all]",
     handler: async (args, ctx) => cancelSubagentCommandHandler(ctx, args),
   });
+  pi.registerCommand("jobs", {
+    description: "List all /run jobs and their statuses: /jobs",
+    handler: async (args, ctx) => jobsCommandHandler(ctx, args),
+  });
   pi.registerTool({
     name: "subagent",
     label: "Subagent",

package/src/instance-name.ts

@@ -0,0 +1,164 @@
+const DEFAULT_ADJECTIVES = [
+  "able",
+  "agile",
+  "alert",
+  "amber",
+  "ample",
+  "apt",
+  "arctic",
+  "avid",
+  "bold",
+  "brave",
+  "bright",
+  "brisk",
+  "calm",
+  "clever",
+  "cosmic",
+  "crisp",
+  "daring",
+  "dawn",
+  "eager",
+  "early",
+  "fair",
+  "fast",
+  "fierce",
+  "fine",
+  "fresh",
+  "gentle",
+  "golden",
+  "grand",
+  "happy",
+  "honest",
+  "jolly",
+  "keen",
+  "kind",
+  "lively",
+  "lucky",
+  "merry",
+  "mighty",
+  "nimble",
+  "noble",
+  "novel",
+  "patient",
+  "proud",
+  "quick",
+  "quiet",
+  "rapid",
+  "ready",
+  "sharp",
+  "smart",
+  "solid",
+  "steady",
+  "swift",
+  "tidy",
+  "vivid",
+  "warm",
+  "wise",
+] as const;
+
+const DEFAULT_NOUNS = [
+  "badger",
+  "beacon",
+  "bison",
+  "brook",
+  "cedar",
+  "comet",
+  "coral",
+  "coyote",
+  "crane",
+  "dolphin",
+  "eagle",
+  "ember",
+  "falcon",
+  "finch",
+  "forest",
+  "fox",
+  "gecko",
+  "glade",
+  "harbor",
+  "hawk",
+  "heron",
+  "island",
+  "jaguar",
+  "koala",
+  "lagoon",
+  "lemur",
+  "lynx",
+  "maple",
+  "meadow",
+  "otter",
+  "panda",
+  "panther",
+  "pelican",
+  "phoenix",
+  "puma",
+  "raven",
+  "reef",
+  "river",
+  "salmon",
+  "sparrow",
+  "summit",
+  "tiger",
+  "valley",
+  "violet",
+  "walrus",
+  "willow",
+  "wolf",
+  "wren",
+  "yak",
+  "zephyr",
+] as const;
+
+const usedInstanceNames = new Set<string>();
+
+let adjectives: readonly string[] = DEFAULT_ADJECTIVES;
+let nouns: readonly string[] = DEFAULT_NOUNS;
+let randomSource: () => number = Math.random;
+
+function normalizeRandomIndex(limit: number): number {
+  const value = randomSource();
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(limit - 1, Math.max(0, Math.floor(value * limit)));
+}
+
+function nameAt(index: number): string {
+  const adjective = adjectives[Math.floor(index / nouns.length)];
+  const noun = nouns[index % nouns.length];
+  return `${adjective}-${noun}`;
+}
+
+export function generateSubagentInstanceName(): string {
+  const capacity = adjectives.length * nouns.length;
+  if (usedInstanceNames.size >= capacity) {
+    throw new Error(
+      "No unused subagent instance names remain for this session.",
+    );
+  }
+  const start = normalizeRandomIndex(capacity);
+  for (let offset = 0; offset < capacity; offset += 1) {
+    const candidate = nameAt((start + offset) % capacity);
+    if (!usedInstanceNames.has(candidate)) {
+      usedInstanceNames.add(candidate);
+      return candidate;
+    }
+  }
+  throw new Error("No unused subagent instance names remain for this session.");
+}
+
+export function resetSubagentInstanceNamesForTest() {
+  usedInstanceNames.clear();
+  adjectives = DEFAULT_ADJECTIVES;
+  nouns = DEFAULT_NOUNS;
+  randomSource = Math.random;
+}
+
+export function configureSubagentInstanceNamesForTest(options: {
+  adjectives?: readonly string[];
+  nouns?: readonly string[];
+  randomSource?: () => number;
+}) {
+  usedInstanceNames.clear();
+  adjectives = options.adjectives ?? DEFAULT_ADJECTIVES;
+  nouns = options.nouns ?? DEFAULT_NOUNS;
+  randomSource = options.randomSource ?? Math.random;
+}

package/src/jobs-command.ts

@@ -0,0 +1,41 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import {
+  getAllProgressStates,
+  type SubagentProgressState,
+} from "./progress-state.js";
+import { listRunJobs } from "./run-registry.js";
+import { renderRunsBoard } from "./ui.js";
+
+export async function jobsCommandHandler(
+  ctx: ExtensionCommandContext,
+  _args: string,
+): Promise<void> {
+  const activeRequestIds = new Set(listRunJobs().map((j) => j.requestId));
+  const active: SubagentProgressState[] = [];
+  const completed: SubagentProgressState[] = [];
+  for (const s of getAllProgressStates()) {
+    if (activeRequestIds.has(s.requestId)) active.push(s);
+    else if (s.status !== "running") completed.push(s);
+  }
+  const all = [...active, ...completed];
+  if (all.length === 0) {
+    ctx.ui.notify("No /run jobs in this session.");
+    return;
+  }
+  const output = await ctx.ui.custom<string>(
+    (_tui, theme, _keybindings, done) => ({
+      invalidate() {},
+      render(width) {
+        const tuiLines = renderRunsBoard(all, theme, width).render(width);
+        const notifyWidth = Math.max(1, width - 2);
+        const notifyLines = renderRunsBoard(all, theme, notifyWidth).render(
+          notifyWidth,
+        );
+        done(notifyLines.join("\n"));
+        return tuiLines;
+      },
+    }),
+  );
+  ctx.ui.notify(output);
+}

package/src/progress-state.ts

@@ -1,3 +1,4 @@
+import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import {
   isStatusOnlyFailure,
   isStatusOnlySuccess,
@@ -9,11 +10,35 @@ import {
 } from "./normalize.js";
 import type { SubagentDetails } from "./types.js";
 
+export type ThemeBg = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+
 export type ProgressStatus = "running" | "success" | "error" | "cancelled";
 
+export const STATUS_COLOR: Record<ProgressStatus, ThemeColor> = {
+  success: "success",
+  error: "error",
+  cancelled: "error",
+  running: "accent",
+};
+
+export const STATUS_ICON: Record<ProgressStatus, string> = {
+  success: "✓",
+  error: "✗",
+  cancelled: "⊘",
+  running: "⟳",
+};
+
+export const STATUS_BG: Record<ProgressStatus, ThemeBg> = {
+  success: "toolSuccessBg",
+  error: "toolErrorBg",
+  cancelled: "toolErrorBg",
+  running: "toolPendingBg",
+};
+
 export interface SubagentProgressState {
   requestId: string;
   agent: string;
+  instanceName?: string;
   taskPreview: string;
   status: ProgressStatus;
   startTime: number;
@@ -34,10 +59,12 @@ export function createProgressState(
   requestId: string,
   agent: string,
   task: string,
+  instanceName = requestId,
 ): void {
   store.set(requestId, {
     requestId,
     agent,
+    instanceName,
     taskPreview: makeTaskPreview(task),
     status: "running",
     startTime: Date.now(),
@@ -50,6 +77,9 @@ export function getProgressState(
 ): SubagentProgressState | undefined {
   return store.get(requestId);
 }
+export function getAllProgressStates(): SubagentProgressState[] {
+  return [...store.values()].sort((a, b) => b.startTime - a.startTime);
+}
 
 export function patchProgressState(
   requestId: string,
@@ -231,3 +261,53 @@ export function isToolCallPart(part: unknown): part is {
     typeof maybe.name === "string"
   );
 }
+
+/**
+ * Format a millisecond duration for compact display.
+ * Renders sub-minute durations as decimal seconds (`45.2s`),
+ * longer durations as minutes and whole seconds (`2m 15s`).
+ */
+export function formatElapsed(ms: number): string {
+  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
+  const mins = Math.floor(ms / 60000);
+  const secs = Math.floor((ms % 60000) / 1000);
+  return `${mins}m ${secs}s`;
+}
+
+/**
+ * Format a raw token count for compact inline display.
+ * Values below 1000 rendered as-is. Larger counts use `k`
+ * or `M` suffixes with one decimal place, stripping trailing `.0`.
+ */
+export function formatTokenCount(count: number): string {
+  if (count < 1000) return String(count);
+  const unit = count >= 1_000_000 ? "M" : "k";
+  const divisor = count >= 1_000_000 ? 1_000_000 : 1000;
+  return `${trimTrailingZero((count / divisor).toFixed(1))}${unit}`;
+}
+
+function trimTrailingZero(value: string): string {
+  return value.endsWith(".0") ? value.slice(0, -2) : value;
+}
+
+export function formatContextPercent(state: SubagentProgressState): string {
+  const d = state.contextWindowTokens;
+  if (!d || d <= 0 || !Number.isFinite(d)) return "--%";
+  const n = state.contextTokens;
+  if (!n || n <= 0 || !Number.isFinite(n)) return "0%";
+  return `${Math.round((n / d) * 100)}%`;
+}
+
+/**
+ * Format the one-line statistics header for a subagent progress display.
+ * Includes tool count, context window usage, and elapsed time.
+ * When the subagent is still running (`durationMs` unset), elapsed is
+ * computed live from `startTime`.
+ *
+ * @returns Single line ending in `\n`, e.g. `"3 tools · 45% ctx · 12.3s\n"`
+ */
+export function formatHeaderStats(state: SubagentProgressState): string {
+  const elapsedMs = state.durationMs ?? Date.now() - state.startTime;
+  const toolLabel = state.toolCount === 1 ? "tool" : "tools";
+  return `${state.toolCount} ${toolLabel} · ${formatContextPercent(state)} ctx · ${formatElapsed(elapsedMs)}\n`;
+}

package/src/progress.ts

@@ -16,36 +16,19 @@
  * @module progress
  */
 
-import type { ThemeColor } from "@earendil-works/pi-coding-agent";
 import type { Component } from "@earendil-works/pi-tui";
-import { Text } from "@earendil-works/pi-tui";
+import { Box, Text } from "@earendil-works/pi-tui";
 import {
+  formatHeaderStats,
   getProgressState,
   type ProgressStatus,
+  STATUS_BG,
+  STATUS_COLOR,
+  STATUS_ICON,
   type SubagentProgressState,
+  type ThemeBg,
 } from "./progress-state.js";
-import type { SubagentTheme, ThemeBg } from "./ui.js";
-
-const STATUS_COLOR: Record<ProgressStatus, ThemeColor> = {
-  success: "success",
-  error: "error",
-  cancelled: "error",
-  running: "accent",
-};
-
-const STATUS_ICON: Record<ProgressStatus, string> = {
-  success: "✓",
-  error: "✗",
-  cancelled: "⊘",
-  running: "⟳",
-};
-
-const STATUS_BG: Record<ProgressStatus, ThemeBg> = {
-  success: "toolSuccessBg",
-  error: "toolErrorBg",
-  cancelled: "toolErrorBg",
-  running: "toolPendingBg",
-};
+import { formatSubagentTitle, type SubagentTheme } from "./ui.js";
 
 export { makeToolPreview } from "./normalize.js";
 export {
@@ -55,64 +38,21 @@ export {
   extractProgressFromDetails,
   failProgressState,
   finalizeProgressState,
+  formatContextPercent,
+  formatElapsed,
+  formatHeaderStats,
+  formatTokenCount,
   getProgressState,
   makeTaskPreview,
   type ProgressStatus,
   patchProgressState,
   resetProgressStore,
+  STATUS_COLOR,
+  STATUS_ICON,
   type SubagentProgressState,
+  type ThemeBg,
 } from "./progress-state.js";
 
-/**
- * Format a millisecond duration for compact display.
- * Renders sub-minute durations as decimal seconds (`45.2s`),
- * longer durations as minutes and whole seconds (`2m 15s`).
- */
-export function formatElapsed(ms: number): string {
-  if (ms < 60000) return `${(ms / 1000).toFixed(1)}s`;
-  const mins = Math.floor(ms / 60000);
-  const secs = Math.floor((ms % 60000) / 1000);
-  return `${mins}m ${secs}s`;
-}
-
-/**
- * Format a raw token count for compact inline display.
- * Values below 1000 rendered as-is. Larger counts use `k`
- * or `M` suffixes with one decimal place, stripping trailing `.0`.
- */
-export function formatTokenCount(count: number): string {
-  if (count < 1000) return String(count);
-  const unit = count >= 1_000_000 ? "M" : "k";
-  const divisor = count >= 1_000_000 ? 1_000_000 : 1000;
-  return `${trimTrailingZero((count / divisor).toFixed(1))}${unit}`;
-}
-
-/**
- * Format the one-line statistics header for a subagent progress display.
- * Includes tool count, context window usage, and elapsed time.
- * When the subagent is still running (`durationMs` unset), elapsed is
- * computed live from `startTime`.
- *
- * @returns Single line ending in `\n`, e.g. `"3 tools · 45% ctx · 12.3s\n"`
- */
-export function formatHeaderStats(state: SubagentProgressState): string {
-  const elapsedMs = state.durationMs ?? Date.now() - state.startTime;
-  const toolLabel = state.toolCount === 1 ? "tool" : "tools";
-  return `${state.toolCount} ${toolLabel} · ${formatContextPercent(state)} ctx · ${formatElapsed(elapsedMs)}\n`;
-}
-
-function formatContextPercent(state: SubagentProgressState): string {
-  const d = state.contextWindowTokens;
-  if (!d || d <= 0 || !Number.isFinite(d)) return "--%";
-  const n = state.contextTokens;
-  if (!n || n <= 0 || !Number.isFinite(n)) return "0%";
-  return `${Math.round((n / d) * 100)}%`;
-}
-
-function trimTrailingZero(value: string): string {
-  return value.endsWith(".0") ? value.slice(0, -2) : value;
-}
-
 /**
  * Create a live-updating TUI progress component from a pi message.
  *
@@ -156,11 +96,7 @@ class DynamicSubagentProgressText implements Component {
   render(width: number): string[] {
     const state = getProgressState(this.requestId);
     if (!state) return [];
-    const text = formatProgressText(this.requestId, this.options, this.theme);
-    const bg = getProgressBackground(state.status);
-    return text
-      ? new Text(text, 1, 1, (line) => this.theme.bg(bg, line)).render(width)
-      : [];
+    return renderProgressBox(state, this.options, this.theme).render(width);
   }
 }
 
@@ -168,44 +104,97 @@ function getProgressBackground(status: ProgressStatus): ThemeBg {
   return STATUS_BG[status];
 }
 
-function formatProgressText(
-  requestId: string,
+function renderProgressBox(
+  state: SubagentProgressState,
   options: { expanded: boolean },
   theme: SubagentTheme,
-): string | undefined {
-  const state = getProgressState(requestId);
-  if (!state) return undefined;
+): Box {
   const status = state.status;
-  const header = `${theme.fg(STATUS_COLOR[status], STATUS_ICON[status])} ${theme.fg("toolTitle", theme.bold(state.agent))} ${theme.fg("dim", `[${status}]`)} ${theme.fg("muted", formatHeaderStats(state))}`;
-  if (status === "running") {
-    const toolLine = state.lastToolPreview
-      ? `\n  ${formatRunningToolPreview(state.lastToolPreview, theme)}`
-      : "";
-    const taskLine = options.expanded
-      ? `\n  ${theme.fg("dim", state.taskPreview)}`
-      : "";
-    return header + toolLine + taskLine;
+  const title = formatSubagentTitle(state.agent, state.instanceName, theme);
+  const header = `${theme.fg(STATUS_COLOR[status], STATUS_ICON[status])} ${title} ${theme.fg("dim", `[${status}]`)} ${theme.fg("muted", formatHeaderStats(state))}`;
+  const box = new Box(1, 1, (line) =>
+    theme.bg(getProgressBackground(status), line),
+  );
+  box.addChild(new Text(header, 0, 0));
+  addProgressBody(box, state, options, theme);
+  return box;
+}
+
+function addProgressBody(
+  box: Box,
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): void {
+  const body = makeProgressBody(state, options, theme);
+  if (body.length === 0) return;
+  for (const line of body) box.addChild(line);
+}
+
+function makeProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  if (state.status === "running")
+    return makeRunningProgressBody(state, options, theme);
+  if (state.status === "error" || state.status === "cancelled") {
+    return makeStoppedProgressBody(state, options, theme);
   }
-  if (status === "error" || status === "cancelled") {
-    const errorLine = state.errorText
-      ? `\n  ${theme.fg("error", state.errorText)}`
-      : "";
-    const taskLine = options.expanded
-      ? `\n  ${theme.fg("dim", state.taskPreview)}`
-      : "";
-    return header + errorLine + taskLine;
+  if (state.status === "success")
+    return makeSuccessProgressBody(state, options, theme);
+  return [];
+}
+
+function makeRunningProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const body: Text[] = [];
+  if (state.lastToolPreview) {
+    body.push(
+      new Text(formatRunningToolPreview(state.lastToolPreview, theme), 2, 0),
+    );
   }
-  if (status === "success") {
-    const output = state.finalOutput?.trim().split("\n")[0] ?? "";
-    if (!options.expanded) {
-      return output ? `${header}\n  ${theme.fg("toolOutput", output)}` : header;
-    }
-    const outputSection = output
-      ? `\n${theme.fg("muted", "─── Output ───")}\n${theme.fg("toolOutput", output)}`
-      : `\n${theme.fg("muted", "(no output)")}`;
-    return `${header}\n  ${theme.fg("dim", state.taskPreview)}${outputSection}`;
+  if (options.expanded)
+    body.push(new Text(theme.fg("dim", state.taskPreview), 2, 0));
+  return body;
+}
+
+function makeStoppedProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const body: Text[] = [];
+  if (state.errorText)
+    body.push(new Text(theme.fg("error", state.errorText), 2, 0));
+  if (options.expanded)
+    body.push(new Text(theme.fg("dim", state.taskPreview), 2, 0));
+  return body;
+}
+
+function makeSuccessProgressBody(
+  state: SubagentProgressState,
+  options: { expanded: boolean },
+  theme: SubagentTheme,
+): Text[] {
+  const output = state.finalOutput?.trim().split("\n")[0] ?? "";
+  if (!options.expanded) {
+    return output ? [new Text(theme.fg("toolOutput", output), 2, 0)] : [];
   }
-  return header;
+  const body = [new Text(theme.fg("dim", state.taskPreview), 2, 0)];
+  body.push(
+    output
+      ? new Text(
+          `${theme.fg("muted", "─── Output ───")}\n${theme.fg("toolOutput", output)}`,
+          0,
+          0,
+        )
+      : new Text(theme.fg("muted", "(no output)"), 0, 0),
+  );
+  return body;
 }
 
 function formatRunningToolPreview(

package/src/run-registry.ts

@@ -1,6 +1,7 @@
 export type RunJob = {
   requestId: string;
   agentName: string;
+  instanceName: string;
   controller: AbortController;
   startedAt: number;
   cancelReason?: string;

package/src/subagent-orchestrator.ts

@@ -11,12 +11,14 @@ import {
   discoverAgents,
   type ThinkingLevel,
 } from "./agents.js";
+import { generateSubagentInstanceName } from "./instance-name.js";
 import { runSingleAgent } from "./process.js";
 import {
   cancelProgressState,
   createProgressState,
   failProgressState,
   finalizeProgressState,
+  getProgressState,
 } from "./progress.js";
 import {
   createSubagentError,
@@ -26,7 +28,12 @@ import {
   patchProgressFromDetails,
   sanitizeDetailsForDisplay,
 } from "./result-details.js";
-import { type RunJob, registerRunJob, removeRunJob } from "./run-registry.js";
+import {
+  listRunJobs,
+  type RunJob,
+  registerRunJob,
+  removeRunJob,
+} from "./run-registry.js";
 import { formatSubagentResultForParent } from "./summary.js";
 import type {
   OnUpdateCallback,
@@ -167,6 +174,16 @@ function sendSubagentResultMessage(
   });
 }
 
+export function emitCompletionAlert(
+  state: ReturnType<typeof getProgressState>,
+): void {
+  if (!state) return;
+  if (state.status === "cancelled") return;
+  const tty = (process.stdout as { isTTY?: boolean }).isTTY;
+  if (!tty) return;
+  process.stdout.write("\x07");
+}
+
 async function runSubagentWorker(
   pi: ExtensionAPI,
   ctx: ExtensionContext,
@@ -252,11 +269,22 @@ async function runSubagentWorker(
   } finally {
     requestProgressRender();
     removeRunJob(requestId);
+    if (listRunJobs().length === 0) {
+      const state = getProgressState(requestId);
+      if (state) {
+        emitCompletionAlert(state);
+      }
+    }
   }
 }
 
 export type StartJobResult =
-  | { kind: "started"; requestId: string; makeDetails: DetailsBuilder }
+  | {
+      kind: "started";
+      requestId: string;
+      instanceName: string;
+      makeDetails: DetailsBuilder;
+    }
   | { kind: "cancelled"; makeDetails: DetailsBuilder }
   | { kind: "not_found"; makeDetails: DetailsBuilder };
 
@@ -266,7 +294,7 @@ export function formatStartJobStatus(
 ): string {
   if (result.kind === "not_found") return `Unknown agent: "${agentName}"`;
   if (result.kind === "cancelled") return "Canceled";
-  return `Subagent ${agentName} started (job: ${result.requestId})`;
+  return `Subagent ${agentName} ${result.instanceName} started (job: ${result.requestId})`;
 }
 
 function needsProjectAgentConfirmation(
@@ -305,6 +333,16 @@ export async function startSubagentJob(
   );
   const requested = agents.find((a) => a.name === params.agent);
   if (!requested) return { kind: "not_found", makeDetails };
+  if (hostSignal?.aborted) return { kind: "cancelled", makeDetails };
+  const task = params.task?.trim() ?? "";
+  if (needsProjectAgentConfirmation(ctx, requested)) {
+    const confirmed = await confirmProjectAgentRun(
+      ctx,
+      requested,
+      discovery.projectAgentsDir,
+    );
+    if (!confirmed) return { kind: "cancelled", makeDetails };
+  }
   if (requested.source === "project") {
     const userAgents = discoverAgents(ctx.cwd, "user");
     const hasUserCollision = userAgents.agents.some(
@@ -319,36 +357,34 @@ export async function startSubagentJob(
       });
     }
   }
-  const task = params.task?.trim() ?? "";
-  if (needsProjectAgentConfirmation(ctx, requested)) {
-    const confirmed = await confirmProjectAgentRun(
-      ctx,
-      requested,
-      discovery.projectAgentsDir,
-    );
-    if (!confirmed) return { kind: "cancelled", makeDetails };
-  }
   const parentModel = ctx.model
     ? { provider: ctx.model.provider, id: ctx.model.id }
     : undefined;
   const parentThinking = pi.getThinkingLevel() as ThinkingLevel;
   const requestId = crypto.randomUUID();
+  const instanceName = generateSubagentInstanceName();
   const controller = new AbortController();
   const job: RunJob = registerRunJob({
     requestId,
     agentName: params.agent,
+    instanceName,
     controller,
     startedAt: Date.now(),
   });
   const mergedSignal = hostSignal
     ? AbortSignal.any([hostSignal, job.controller.signal])
     : job.controller.signal;
-  createProgressState(requestId, params.agent, task);
+  const makeStartedDetails: DetailsBuilder = (results, options) =>
+    makeDetails(
+      results.map((result) => ({ ...result, instanceName })),
+      options,
+    );
+  createProgressState(requestId, params.agent, task, instanceName);
   pi.sendMessage({
     customType: "subagent-progress",
     content: "",
     display: true,
-    details: { requestId },
+    details: { agent: params.agent, instanceName, requestId },
   });
   const requestProgressRender = createProgressRenderRequester(ctx, requestId);
   setImmediate(() => {
@@ -366,12 +402,17 @@ export async function startSubagentJob(
       debug,
       parentModel,
       parentThinking,
-      makeDetails,
+      makeStartedDetails,
       requestId,
       job,
       mergedSignal,
     );
   });
   if (mergedSignal.aborted) return { kind: "cancelled", makeDetails };
-  return { kind: "started", requestId, makeDetails };
+  return {
+    kind: "started",
+    requestId,
+    instanceName,
+    makeDetails: makeStartedDetails,
+  };
 }

package/src/termination.ts

@@ -124,10 +124,13 @@ function sendTreeSignal(
     sendDirectSignal(proc, signal, state, options);
     return;
   }
-  if (options.killProcessTree) {
-    options.killProcessTree(proc, signal, platform);
+  const markTreeKilled = () => {
     state.metadata.target = "tree";
     state.metadata.processTreeKilled = true;
+  };
+  if (options.killProcessTree) {
+    options.killProcessTree(proc, signal, platform);
+    markTreeKilled();
     return;
   }
   if (platform !== "win32") {
@@ -137,8 +140,7 @@ function sendTreeSignal(
       options.killProcessGroup ??
       ((pid, nextSignal) => process.kill(pid, nextSignal))
     )(-pid, signal);
-    state.metadata.target = "tree";
-    state.metadata.processTreeKilled = true;
+    markTreeKilled();
     return;
   }
   if (signal === "SIGKILL") {
@@ -148,8 +150,7 @@ function sendTreeSignal(
       "/t",
       "/f",
     ]);
-    state.metadata.target = "tree";
-    state.metadata.processTreeKilled = true;
+    markTreeKilled();
     return;
   }
   throw new Error("unsupported tree termination platform");

package/src/types.ts

@@ -26,6 +26,7 @@ export interface StreamingProgress {
 
 export interface SingleResult {
   agent: string;
+  instanceName?: string;
   agentSource: "user" | "project" | "unknown";
   task: string;
   exitCode: number;

package/src/ui.ts

@@ -12,13 +12,20 @@ import {
   extractSemanticToolTarget,
   normalizeSummaryValue,
 } from "./normalize.js";
+import {
+  formatContextPercent,
+  formatElapsed,
+  type ProgressStatus,
+  STATUS_BG,
+  STATUS_COLOR,
+  STATUS_ICON,
+  type SubagentProgressState,
+  type ThemeBg,
+} from "./progress-state.js";
 import { hasSubagentFailed } from "./result-details.js";
 import type { SubagentDetails, UsageStats } from "./types.js";
 
-/**
- * Background theme keys for subagent tool status.
- */
-export type ThemeBg = "toolPendingBg" | "toolSuccessBg" | "toolErrorBg";
+export type { ThemeBg };
 
 /**
  * Abstraction for theme-aware text formatting.
@@ -27,8 +34,35 @@ export type SubagentTheme = {
   fg: (color: ThemeColor, text: string) => string;
   bg: (color: ThemeBg, text: string) => string;
   bold: (text: string) => string;
+  italic?: (text: string) => string;
 };
 
+const ANSI_ITALIC_ON = "\x1b[3m";
+const ANSI_ITALIC_OFF = "\x1b[23m";
+const ANSI_STRIKETHROUGH_ON = "\x1b[9m";
+const ANSI_STRIKETHROUGH_OFF = "\x1b[29m";
+const ANSI_UNDERLINE_ON = "\x1b[4m";
+const ANSI_UNDERLINE_OFF = "\x1b[24m";
+
+function italicText(text: string, theme: SubagentTheme): string {
+  return theme.italic
+    ? theme.italic(text)
+    : `${ANSI_ITALIC_ON}${text}${ANSI_ITALIC_OFF}`;
+}
+
+/**
+ * Formats the shared subagent title from agent and optional instance name.
+ */
+export function formatSubagentTitle(
+  agent: string,
+  instanceName: string | undefined,
+  theme: SubagentTheme,
+): string {
+  const agentSegment = theme.fg("toolTitle", theme.bold(agent));
+  if (!instanceName) return agentSegment;
+  return `${agentSegment} ${theme.fg("accent", italicText(instanceName, theme))}`;
+}
+
 /**
  * Formats token counts into human-readable strings (e.g., "1.2k", "1.5M").
  */
@@ -96,7 +130,7 @@ export function formatResultFooter(
     parts.push(`${usage.turns} turn${usage.turns > 1 ? "s" : ""}`);
   if (typeof durationMs === "number") parts.push(formatDuration(durationMs));
   if (usage.cost) parts.push(`$${usage.cost.toFixed(4)}`);
-  return `\n${parts.join(" · ")}`;
+  return parts.join(" · ");
 }
 
 /**
@@ -149,9 +183,10 @@ function makeMarkdownTheme(theme: SubagentTheme): MarkdownTheme {
     hr: fg("mdHr"),
     listBullet: fg("mdListBullet"),
     bold: (text) => theme.bold(text),
-    italic: (text) => `\x1b[3m${text}\x1b[23m`,
-    strikethrough: (text) => `\x1b[9m${text}\x1b[29m`,
-    underline: (text) => `\x1b[4m${text}\x1b[24m`,
+    italic: (text) => `${ANSI_ITALIC_ON}${text}${ANSI_ITALIC_OFF}`,
+    strikethrough: (text) =>
+      `${ANSI_STRIKETHROUGH_ON}${text}${ANSI_STRIKETHROUGH_OFF}`,
+    underline: (text) => `${ANSI_UNDERLINE_ON}${text}${ANSI_UNDERLINE_OFF}`,
   };
 }
 
@@ -199,20 +234,168 @@ export function renderSubagentResult(
     );
   }
   const failed = hasSubagentFailed(r);
+  const cancelled = r.stopReason === "aborted";
+  const resultStatus: ProgressStatus = cancelled
+    ? "cancelled"
+    : failed
+      ? "error"
+      : "success";
   const finalOutput = r.finalOutput ?? getFinalOutput(r.messages ?? []);
-  const bg = failed ? "toolErrorBg" : "toolSuccessBg";
-  const box = new Box(1, 1, (line) => theme.bg(bg, line));
+  const title = formatSubagentTitle(r.agent, r.instanceName, theme);
   const bodyText = stripOutcomeLineForResultUi(bodyOverride ?? finalOutput);
-  if (bodyText) {
-    box.addChild(
+  const usageStr = formatResultFooter(r.usage, r.model, r.durationMs);
+  return renderStatusCard(
+    {
+      status: resultStatus,
+      title,
+      variant: "full",
+      body: bodyText,
+      footer: usageStr,
+    },
+    theme,
+  );
+}
+
+type StatusCardVariant = "full" | "abridged";
+
+type StatusCardOptions = {
+  status: ProgressStatus;
+  title: string;
+  variant: StatusCardVariant;
+  metadata?: string;
+  body?: string;
+  footer?: string;
+};
+
+function renderStatusCard(
+  options: StatusCardOptions,
+  theme: SubagentTheme,
+): Box {
+  const box = new Box(1, 1, (line) =>
+    theme.bg(STATUS_BG[options.status], line),
+  );
+  const icon = theme.fg(
+    STATUS_COLOR[options.status],
+    STATUS_ICON[options.status],
+  );
+  const status = theme.fg("dim", `[${options.status}]`);
+  const metadata = options.metadata
+    ? ` ${theme.fg("muted", options.metadata)}`
+    : "";
+  box.addChild(new Text(`${icon} ${options.title} ${status}${metadata}`, 0, 0));
+  box.addChild(makeStatusCardBody(options, theme));
+  if (options.variant === "full" && options.footer)
+    box.addChild(new Text(theme.fg("dim", options.footer), 0, 0));
+  return box;
+}
+
+function makeStatusCardBody(
+  options: StatusCardOptions,
+  theme: SubagentTheme,
+): Box {
+  const body = new Box(2, options.variant === "full" ? 1 : 0);
+  const bodyText = options.body ?? "";
+  if (bodyText && options.variant === "full") {
+    body.addChild(
       new Markdown(bodyText, 0, 0, makeMarkdownTheme(theme), {
         color: (text) => theme.fg("toolOutput", text),
       }),
     );
+  } else if (bodyText) {
+    body.addChild(new Text(theme.fg("toolOutput", bodyText), 0, 0));
   } else {
-    box.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
+    body.addChild(new Text(theme.fg("muted", "(no output)"), 0, 0));
   }
-  const usageStr = formatResultFooter(r.usage, r.model, r.durationMs);
-  if (usageStr) box.addChild(new Text(theme.fg("dim", usageStr), 0, 0));
+  return body;
+}
+
+const BODY_PREVIEW_MAX = 120;
+
+function selectRunsBoardBody(state: SubagentProgressState): string {
+  return (
+    [state.finalOutput, state.errorText, state.taskPreview].find(
+      (c): c is string => typeof c === "string" && c.trim().length > 0,
+    ) ?? ""
+  );
+}
+
+function renderJobCard(
+  state: SubagentProgressState,
+  theme: SubagentTheme,
+): Box {
+  const title = formatSubagentTitle(state.agent, state.instanceName, theme);
+  const elapsed = formatElapsed(
+    state.durationMs ?? Date.now() - state.startTime,
+  );
+  const ctxPercent = formatContextPercent(state);
+  const toolLabel = state.toolCount === 1 ? "tool" : "tools";
+  const metadata = `${state.toolCount} ${toolLabel} · ${ctxPercent} ctx · ${elapsed}`;
+  const bodyText = selectRunsBoardBody(state);
+  const preview =
+    bodyText.length > BODY_PREVIEW_MAX
+      ? `${bodyText.slice(0, BODY_PREVIEW_MAX - 1)}…`
+      : bodyText;
+  return renderStatusCard(
+    {
+      status: state.status,
+      title,
+      variant: "abridged",
+      metadata,
+      body: preview,
+    },
+    theme,
+  );
+}
+
+/** Sort states by startTime descending (newest first). */
+function sortByStartTimeDesc(
+  a: SubagentProgressState,
+  b: SubagentProgressState,
+): number {
+  return b.startTime - a.startTime;
+}
+
+/** Ordered section definitions: label → status filter for the runs board. */
+const BOARD_SECTIONS: [string, ProgressStatus][] = [
+  ["ACTIVE", "running"],
+  ["FAILED", "error"],
+  ["CANCELLED", "cancelled"],
+  ["SUCCEEDED", "success"],
+];
+
+/**
+ * Renders a unified job board for the `/jobs` command.
+ * Jobs render in status-specific sections, each sorted by `startTime` descending.
+ * Status icons preserve the existing /jobs contract for running and cancelled jobs.
+ */
+export function renderRunsBoard(
+  states: SubagentProgressState[],
+  theme: SubagentTheme,
+  width = 80,
+): Component {
+  if (states.length === 0) {
+    return new Text(theme.fg("muted", "No /run jobs in this session."), 0, 0);
+  }
+  const grouped = new Map<ProgressStatus, SubagentProgressState[]>();
+  for (const s of states) {
+    const bucket = grouped.get(s.status);
+    if (bucket) bucket.push(s);
+    else grouped.set(s.status, [s]);
+  }
+  for (const bucket of grouped.values()) bucket.sort(sortByStartTimeDesc);
+  const box = new Box(0, 0);
+  const addSection = (
+    label: string,
+    sectionStates: SubagentProgressState[],
+  ) => {
+    if (sectionStates.length === 0) return;
+    const sectionHeader = `${label} (${sectionStates.length})`;
+    const ruler = "─".repeat(Math.max(0, width - sectionHeader.length - 1));
+    box.addChild(new Text(theme.fg("dim", `${sectionHeader} ${ruler}`), 0, 0));
+    for (const state of sectionStates)
+      box.addChild(renderJobCard(state, theme));
+  };
+  for (const [label, status] of BOARD_SECTIONS)
+    addSection(label, grouped.get(status) ?? []);
   return box;
 }