@clanker-code/pi-subagents 0.10.8 → 0.11.0

package/AGENTS.md

@@ -31,6 +31,8 @@ See the general guide at `~/.llm-general/npm-autopublish-via-ci.md` for other re
 
 ## Keeping Upstream In Sync
 
+**Do NOT pull in upstream changes without consulting Max first.** You may preview the changes and whether there will be any conflicts, and if so estimate how complex it will be to fix — but do not merge, rebase, or cherry-pick without explicit approval.
+
 Periodically run:
 
 ```bash

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.0] - 2026-06-28
+
+### Added
+- **Dashboard UI module integration** — `pi-agent-dashboard` users can now see subagents in the dashboard. Three integration points: a footer-segment decorator showing running/completed agent counts, a `/subagents` management-modal command that opens a table view of all subagent history with row actions (view result, abort, steer), and round-trip event handlers wired through the `ui_management` protocol. Lifecycle events trigger automatic dashboard invalidation.
+- **Compact view for `get_subagent_result`** — when tool output is collapsed in the TUI, `get_subagent_result` now shows first 20 + last 20 lines of the result body with a styled divider (`─────── ⋐ N lines hidden from preview ⋑ ───────`). The full content is still passed through to the LLM. The divider format also applies to the `Agent` tool's collapsed view.
+- **`list_subagents` and `clear_subagents` tools** — agents can inspect retained subagent records with a compact `List Agents` renderer and clear stale completed records with a compact `Clear Agents` renderer. `list_subagents` defaults to active/problem agents plus the two most recent successful completions and reports hidden done counts; `all: true` shows the full retained list. `clear_subagents` defaults to successful completions older than 5 minutes, accepts explicit IDs/prefixes, and refuses to clear running or queued agents.
+
+### Changed
+- **`Agent` defaults omitted `subagent_type` to `general-purpose`** — callers can omit the type for the default general-purpose agent instead of receiving a missing-argument error.
+- **Built-in `Explore` no longer pins Haiku** — the default Explore agent now inherits the parent/session model unless the caller or a custom agent definition supplies a model.
+- **`snipMiddleLines` divider updated** — the collapsed-output divider now uses a styled format with locale-aware line counts instead of plain text.
+
+### Fixed
+- **Nested subagents now appear in the live widget as soon as they are created** — the widget listens to `subagents:created` lifecycle events in addition to started/completed/failed updates, and created events now include record metadata so queued recursive agents do not render as running while waiting.
+- **`get_subagent_result` peek now bounds embedded multiline output by rendered lines** — JSONL transcript entries whose text blocks contain newlines are split before `peek.lines`, `peek.after`, regex filtering, and character truncation are applied, preventing a small requested line count from returning huge multiline tool/file output records.
+- **`get_subagent_result` renderResult uses typed status** — `GetResultDetails.status` is now typed as `AgentRecord['status']` and correctly renders `queued` status with the accent spinner icon.
+
 ## [0.10.8] - 2026-06-23
 
 ### Changed

package/README.md

@@ -32,6 +32,7 @@ Upstream changes are reviewed for cherry-picking when practical; otherwise they
 - **Conversation viewer** — select any agent in `/agents` to open a live-scrolling overlay of its full conversation (auto-follows new content, scroll up to pause). Stop a still-running agent from here by pressing `x` (then `x` again to confirm) — works for background agents too
 - **Custom agent types** — define agents in `.pi/agents/<name>.md` with YAML frontmatter: custom system prompts, model selection, thinking levels, tool restrictions
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
+- **Agent record maintenance** — `list_subagents` gives the LLM a compact retained-agent summary (active, problem, recent done, hidden done count) and `clear_subagents` clears old completed records without touching active agents
 - **Session resume** — pick up where an agent left off, preserving full conversation context
 - **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
 - **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
@@ -43,6 +44,7 @@ Upstream changes are reviewed for cherry-picking when practical; otherwise they
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
 - **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show a bounded preview and transcript path. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`, `compacted`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
+- **Dashboard UI integration** — `pi-agent-dashboard` users can see subagents in the dashboard: a footer badge shows running/completed counts, the `/subagents` command opens a table view of all subagent history with row actions (view result, abort, steer), and lifecycle events trigger automatic UI refresh. No React or SDK required — uses the dashboard's Extension UI Module System
 - **Cross-extension RPC** — other pi extensions can spawn and stop subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`, `subagents:rpc:stop`). Standardized reply envelopes with protocol versioning. Emits `subagents:ready` on load
 - **Schedule subagents** — pass `schedule` to the `Agent` tool to fire on cron / interval / one-shot. Session-scoped jobs with PID-locked persistence; results land via the same steering-style `subagent-notification` path as manual background completions; manage via `/agents → Scheduled jobs`
 - **Model scope enforcement** — opt-in validation that subagent model choices stay within your pi `enabledModels` allowlist (sourced from `/scoped-models`, with both global and project-local pi settings honored). Caller-supplied out-of-scope → hard error to orchestrator; frontmatter-pinned out-of-scope → warning + runs anyway (frontmatter authoritative). Toggle via `/agents → Settings → Scope models`
@@ -153,7 +155,7 @@ Group completions render each agent as a separate block. The LLM receives struct
 | Type | Tools | Model | Prompt Mode | Description |
 |------|-------|-------|-------------|-------------|
 | `general-purpose` | all 7 | inherit | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions |
-| `Explore` | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace` (standalone) | Fast codebase exploration (read-only) |
+| `Explore` | read, bash, grep, find, ls | inherit | `replace` (standalone) | Fast codebase exploration (read-only) |
 | `Plan` | read, bash, grep, find, ls | inherit | `replace` (standalone) | Software architect for implementation planning (read-only) |
 
 The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does. Explore and Plan use standalone prompts tailored to their read-only roles.
@@ -270,7 +272,7 @@ Launch a sub-agent.
 |-----------|------|----------|-------------|
 | `prompt` | string | yes | The task for the agent |
 | `description` | string | yes | Short 3-5 word summary (shown in UI) |
-| `subagent_type` | string | yes | Agent type (built-in or custom) |
+| `subagent_type` | string | no | Agent type (built-in or custom). Defaults to `general-purpose` |
 | `model` | string | no | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | string | no | Thinking level: off, minimal, low, medium, high, xhigh |
 | `max_turns` | number | no | Max agentic turns. Omit for unlimited (default) |
@@ -301,6 +303,24 @@ Send a steering message to a running agent. The message interrupts after the cur
 | `agent_id` | string | yes | Agent ID to steer |
 | `message` | string | yes | Message to inject into agent conversation |
 
+### `list_subagents`
+
+List retained subagent records with a compact custom renderer. By default it shows queued/running agents, failed/stopped/aborted agents, and the two most recent successful agents that have not been cleaned up yet. It also reports how many successful completed agents are hidden. Pass `all: true` for the full retained list.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `all` | boolean | no | Show every retained subagent instead of the default compact subset |
+
+### `clear_subagents`
+
+Clear retained terminal subagent records with a compact custom renderer. By default it clears successful completed/steered agents older than 5 minutes. You can provide explicit IDs or unique prefixes to clear specific terminal agents. Running and queued agents are never cleared; attempts to clear them are reported as errors.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `agent_ids` | string[] | no | Exact IDs or unique prefixes to clear; ignores the age threshold |
+| `older_than_minutes` | number | no | Default-mode age threshold. Defaults to 5 |
+| `include_errors` | boolean | no | Also clear failed/stopped/aborted terminal records older than the threshold |
+
 ## Commands
 
 | Command | Description |

package/bugs.txt

@@ -0,0 +1,57 @@
+# pi-subagents bugs
+
+## 2026-06-24: subagent-spawned reviewer c2c alias registrations route to coordinator
+
+Observed in `/home/xertrov/src/autoplanet-harness` session while coordinating nested pi Agent reviewers.
+
+Symptom:
+- Coordinator received transcript notifications like `Subagent <id> registered as pi-...` for reviewer subagents spawned by an implementer subagent.
+- The spawning implementer subagent did **not** receive those c2c alias registration notifications.
+- This made the coordinator see aliases for subagents it did not directly start, while the parent subagent could not map its Agent handles to c2c aliases.
+
+Concrete example:
+- Coordinator directly started T244/G9 implementer: agent `81a4688f-82ce-40e`, alias `pi-8391d3-ae5887a`.
+- T244 spawned reviewer/rereviewer Agent subagents with IDs:
+  - `436193fa-ef20-4d0`
+  - `97bddbcf-53a8-48c`
+  - `56a58df4-c91c-48a`
+  - `82ae1d14-707d-415`
+- Coordinator received registrations for aliases including `pi-8391d3-a723e9a`, `pi-8391d3-a0a8a00`, `pi-8391d3-ab7ed6f`, `pi-8391d3-ab167dc`.
+- T244 reported: its transcript only showed Agent result handles/output paths/completion summaries; it did not see `Subagent <id> registered as pi-...` messages and could not map reviewer IDs to c2c aliases.
+
+Expected behavior:
+- Alias registration notifications for a subagent spawned by another subagent should be delivered to the spawning subagent's transcript, or at least to both the spawning subagent and coordinator with parent/owner metadata.
+- The notification should include parent/spawner identity so coordinators can distinguish direct children from nested reviewer subagents.
+
+Impact:
+- Coordinator receives noisy/ambiguous registrations for unknown aliases.
+- Spawning subagent cannot c2c-message its own reviewers by alias or report alias ownership accurately.
+- Requires extra coordinator debugging messages to identify ownership.
+
+Suggested fix:
+- Route `Subagent <id> registered as <alias>` to the agent that invoked the Agent tool.
+- Add fields like `parent_agent_id`, `parent_alias`, and maybe `root_coordinator_alias` to registration notifications.
+- If root coordinator must also receive nested registrations, label them explicitly as nested.
+
+Additional observation after filing:
+- Coordinator later received another nested-looking registration: `Subagent 8262e0d6-457e-49c registered as pi-8391d3-ab41e8a`, again without the coordinator directly starting that subagent.
+- Confirmed with T245/G6 implementer `pi-8391d3-a861bf0`: it spawned reviewer Agent IDs `8262e0d6-457e-49c` and `14d29ca7-348e-437`, while coordinator received alias registrations `pi-8391d3-ab41e8a` and `pi-8391d3-aa90cd5`; T245 reported it had not received any c2c alias registration notifications for them.
+- After crash recovery restart, coordinator received another nested-looking registration: `Subagent 4f396572-cab5-42c registered as pi-8391d3-a52ab8a`; likely spawned by a recovery worker/reviewer rather than directly by coordinator.
+- Coordinator also received `Subagent 09dc9e7f-f960-411 registered as pi-8391d3-a219275` during recovery worker activity, again likely nested/reviewer notification routed to coordinator.
+- Coordinator also received `Subagent ee594feb-8fd1-458 registered as pi-8391d3-a8f6d40` while nested reviewer activity was ongoing; likely another nested alias notification routed to coordinator.
+- Coordinator also received `Subagent dd29fe5b-357a-48f registered as pi-8391d3-afd6cfc` during T246 nested rereview activity; likely another nested alias notification routed to coordinator.
+- Coordinator received nested-looking registrations `Subagent 9aa66b38-3ba8-405 registered as pi-8391d3-a6cefa4` and `Subagent d33bb514-be85-4a5 registered as pi-8391d3-ae99126` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent ab7cb925-d76c-489 registered as pi-8391d3-a8c6afd` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent ba23eaaf-a706-459 registered as pi-8391d3-af5d393` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent adf52e5e-862e-4c6 registered as pi-8391d3-aa897ea` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent e6eb1662-8223-458 registered as pi-8391d3-adb2231` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent 565012aa-43b6-407 registered as pi-8391d3-a66be3e` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent 603b211a-9daa-421 registered as pi-8391d3-aa92c43` during active worker review activity.
+- Coordinator received nested-looking registration `Subagent 734f3fa3-958b-4bd registered as pi-8391d3-a028432` during active T248 review activity.
+- Coordinator received nested-looking registration `Subagent 2d565584-fcbc-496 registered as pi-8391d3-ac6e43c` during active T250/T251/T252 review activity.
+- Coordinator received nested-looking registration `Subagent 5e7ee0d1-5112-4b9 registered as pi-8391d3-a7722c2` during active T250/T251/T252 review activity.
+- Coordinator received nested-looking registration `Subagent eae7393b-dfb4-445 registered as pi-8391d3-a2a9d62` during active T250/T251/T252 review activity.
+- Coordinator received nested-looking registration `Subagent 6629a0fe-daef-401 registered as pi-8391d3-ad0b4e5` during active T250 review activity.
+- Coordinator received nested-looking registration `Subagent 49eb5d11-178d-4d2 registered as pi-8391d3-a979978` during active T250 review activity.
+- Coordinator received nested-looking registration `Subagent bf846951-6b2f-4b5 registered as pi-8391d3-aabc2c5` during active T250 rereview activity.
+- Coordinator received nested-looking registration `Subagent 3250e286-4fd4-4a2 registered as pi-8391d3-a78b404` during active T250 rereview activity.

package/dist/agent-manager.d.ts

@@ -94,6 +94,10 @@ export declare class AgentManager {
     private queue;
     /** Number of currently running background agents. */
     private runningBackground;
+    /** Background agents by id; foreground agents must not emit background completion callbacks. */
+    private backgroundAgentIds;
+    /** Background terminal callbacks already emitted; prevents abort/settle double delivery. */
+    private completedBackgroundCallbacks;
     constructor(onComplete?: OnAgentComplete, maxConcurrent?: number, onStart?: OnAgentStart, onCompact?: OnAgentCompact);
     /** Update the max concurrent background agents limit. */
     setMaxConcurrent(n: number): void;
@@ -103,6 +107,8 @@ export declare class AgentManager {
      * If the concurrency limit is reached, the agent is queued.
      */
     spawn(pi: ExtensionAPI, ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string;
+    /** Emit background completion once, optionally releasing a running concurrency slot. */
+    private completeBackground;
     /** Actually start an agent (called immediately or from queue drain). */
     private startAgent;
     /** Start queued agents up to the concurrency limit. */
@@ -119,6 +125,8 @@ export declare class AgentManager {
     abort(id: string): boolean;
     /** Dispose a record's session and remove it from the map. */
     private removeRecord;
+    /** Remove selected terminal records. Running and queued records are never removed. */
+    clearRecords(ids: string[]): string[];
     private cleanup;
     /**
      * Remove all completed/stopped/errored records immediately.

package/dist/agent-manager.js

@@ -51,6 +51,10 @@ export class AgentManager {
     queue = [];
     /** Number of currently running background agents. */
     runningBackground = 0;
+    /** Background agents by id; foreground agents must not emit background completion callbacks. */
+    backgroundAgentIds = new Set();
+    /** Background terminal callbacks already emitted; prevents abort/settle double delivery. */
+    completedBackgroundCallbacks = new Set();
     constructor(onComplete, maxConcurrent = DEFAULT_MAX_CONCURRENT, onStart, onCompact) {
         this.onComplete = onComplete;
         this.onStart = onStart;
@@ -103,6 +107,8 @@ export class AgentManager {
             options.onOutputFileCreated?.(record.outputFile, id);
         }
         this.agents.set(id, record);
+        if (options.isBackground)
+            this.backgroundAgentIds.add(id);
         const args = { pi, ctx, type, prompt, options };
         if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
             // Queue it — will be started when a running agent completes
@@ -115,11 +121,26 @@ export class AgentManager {
             this.startAgent(id, record, args);
         }
         catch (err) {
+            this.backgroundAgentIds.delete(id);
             this.agents.delete(id);
             throw err;
         }
         return id;
     }
+    /** Emit background completion once, optionally releasing a running concurrency slot. */
+    completeBackground(record, releaseRunningSlot, drain = true) {
+        if (this.completedBackgroundCallbacks.has(record.id))
+            return;
+        this.completedBackgroundCallbacks.add(record.id);
+        if (releaseRunningSlot)
+            this.runningBackground = Math.max(0, this.runningBackground - 1);
+        try {
+            this.onComplete?.(record);
+        }
+        catch { /* ignore completion side-effect errors */ }
+        if (drain)
+            this.drainQueue();
+    }
     /** Actually start an agent (called immediately or from queue drain). */
     startAgent(id, record, { pi, ctx, type, prompt, options }) {
         // Re-validate a caller-supplied cwd: queued spawns can start minutes after
@@ -239,12 +260,7 @@ export class AgentManager {
                 }
             }
             if (options.isBackground) {
-                this.runningBackground--;
-                try {
-                    this.onComplete?.(record);
-                }
-                catch { /* ignore completion side-effect errors */ }
-                this.drainQueue();
+                this.completeBackground(record, true);
             }
             return responseText;
         })
@@ -273,9 +289,7 @@ export class AgentManager {
                 catch { /* ignore cleanup errors */ }
             }
             if (options.isBackground) {
-                this.runningBackground--;
-                this.onComplete?.(record);
-                this.drainQueue();
+                this.completeBackground(record, true);
             }
             return "";
         });
@@ -297,7 +311,7 @@ export class AgentManager {
                 record.status = "error";
                 record.error = err instanceof Error ? err.message : String(err);
                 record.completedAt = Date.now();
-                this.onComplete?.(record);
+                this.completeBackground(record, false, false);
             }
         }
     }
@@ -326,6 +340,8 @@ export class AgentManager {
         record.error = undefined;
         record.resultConsumed = false;
         record.abortController = new AbortController();
+        this.backgroundAgentIds.add(id);
+        this.completedBackgroundCallbacks.delete(id);
         this.runningBackground++;
         this.onStart?.(record);
         const onParentAbort = () => this.abort(id);
@@ -354,12 +370,7 @@ export class AgentManager {
             record.result = responseText;
             record.completedAt = Date.now();
             detach();
-            this.runningBackground--;
-            try {
-                this.onComplete?.(record);
-            }
-            catch { /* ignore completion side-effect errors */ }
-            this.drainQueue();
+            this.completeBackground(record, true);
             return responseText;
         }).catch((err) => {
             if (record.status !== "stopped")
@@ -367,12 +378,7 @@ export class AgentManager {
             record.error = err instanceof Error ? err.message : String(err);
             record.completedAt = Date.now();
             detach();
-            this.runningBackground--;
-            try {
-                this.onComplete?.(record);
-            }
-            catch { /* ignore completion side-effect errors */ }
-            this.drainQueue();
+            this.completeBackground(record, true);
             return "";
         });
         record.promise = promise;
@@ -393,6 +399,7 @@ export class AgentManager {
             this.queue = this.queue.filter(q => q.id !== id);
             record.status = "stopped";
             record.completedAt = Date.now();
+            this.completeBackground(record, false);
             return true;
         }
         if (record.status !== "running")
@@ -400,14 +407,32 @@ export class AgentManager {
         record.abortController?.abort();
         record.status = "stopped";
         record.completedAt = Date.now();
+        if (this.backgroundAgentIds.has(id))
+            this.completeBackground(record, true);
         return true;
     }
     /** Dispose a record's session and remove it from the map. */
     removeRecord(id, record) {
         record.session?.dispose?.();
         record.session = undefined;
+        this.backgroundAgentIds.delete(id);
+        this.completedBackgroundCallbacks.delete(id);
         this.agents.delete(id);
     }
+    /** Remove selected terminal records. Running and queued records are never removed. */
+    clearRecords(ids) {
+        const removed = [];
+        for (const id of ids) {
+            const record = this.agents.get(id);
+            if (!record)
+                continue;
+            if (record.status === "running" || record.status === "queued")
+                continue;
+            this.removeRecord(id, record);
+            removed.push(id);
+        }
+        return removed;
+    }
     cleanup() {
         const cutoff = Date.now() - 10 * 60_000;
         for (const [id, record] of this.agents) {
@@ -442,6 +467,8 @@ export class AgentManager {
             if (record) {
                 record.status = "stopped";
                 record.completedAt = Date.now();
+                if (this.backgroundAgentIds.has(record.id))
+                    this.completedBackgroundCallbacks.add(record.id);
                 count++;
             }
         }
@@ -452,9 +479,12 @@ export class AgentManager {
                 record.abortController?.abort();
                 record.status = "stopped";
                 record.completedAt = Date.now();
+                if (this.backgroundAgentIds.has(record.id))
+                    this.completedBackgroundCallbacks.add(record.id);
                 count++;
             }
         }
+        this.runningBackground = 0;
         return count;
     }
     /** Wait for all running and queued agents to complete (including queued ones). */
@@ -480,6 +510,8 @@ export class AgentManager {
             record.session?.dispose();
         }
         this.agents.clear();
+        this.backgroundAgentIds.clear();
+        this.completedBackgroundCallbacks.clear();
         // Prune any orphaned git worktrees (crash recovery)
         try {
             pruneWorktrees(process.cwd());

package/dist/agent-runner.d.ts

@@ -15,10 +15,13 @@ export declare const SUBAGENT_TOOL_NAMES: {
     readonly AGENT: "Agent";
     readonly GET_RESULT: "get_subagent_result";
     readonly STEER: "steer_subagent";
+    readonly LIST_SUBAGENTS: "list_subagents";
+    readonly CLEAR_SUBAGENTS: "clear_subagents";
     readonly LIST_MODELS: "list_models";
 };
 export declare function getCurrentExtensionDepth(): number;
 export declare function getCurrentExtensionAgentId(): string | undefined;
+export declare function getCurrentExtensionParentAgentId(): string | undefined;
 /**
  * Canonical name of an extension for `extensions: [...]` allowlist matching.
  * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`

package/dist/agent-runner.js

@@ -23,6 +23,8 @@ export const SUBAGENT_TOOL_NAMES = {
     AGENT: "Agent",
     GET_RESULT: "get_subagent_result",
     STEER: "steer_subagent",
+    LIST_SUBAGENTS: "list_subagents",
+    CLEAR_SUBAGENTS: "clear_subagents",
     LIST_MODELS: "list_models",
 };
 /**
@@ -53,7 +55,11 @@ function getLoadingExtensionAgentId() {
     const value = globalThis[EXTENSION_DEPTH_KEY];
     return value && typeof value.agentId === "string" ? value.agentId : undefined;
 }
-async function withLoadingExtensionDepth(depth, agentId, fn) {
+function getLoadingExtensionParentAgentId() {
+    const value = globalThis[EXTENSION_DEPTH_KEY];
+    return value && typeof value.parentAgentId === "string" ? value.parentAgentId : undefined;
+}
+async function withLoadingExtensionDepth(depth, agentId, parentAgentId, fn) {
     const previous = extensionDepthLoadChain;
     let release;
     extensionDepthLoadChain = new Promise((resolve) => {
@@ -63,7 +69,7 @@ async function withLoadingExtensionDepth(depth, agentId, fn) {
     try {
         const g = globalThis;
         const prev = g[EXTENSION_DEPTH_KEY];
-        g[EXTENSION_DEPTH_KEY] = { depth, agentId };
+        g[EXTENSION_DEPTH_KEY] = { depth, agentId, parentAgentId };
         try {
             return await fn();
         }
@@ -84,6 +90,9 @@ export function getCurrentExtensionDepth() {
 export function getCurrentExtensionAgentId() {
     return getLoadingExtensionAgentId();
 }
+export function getCurrentExtensionParentAgentId() {
+    return getLoadingExtensionParentAgentId();
+}
 /**
  * Canonical name of an extension for `extensions: [...]` allowlist matching.
  * Lowercased — extension names match case-insensitively so `extensions: [Mcp]`
@@ -442,7 +451,7 @@ export async function runAgent(ctx, type, prompt, options) {
         systemPromptOverride: () => systemPrompt,
         appendSystemPromptOverride: () => [],
     });
-    await withLoadingExtensionDepth(depth, options.agentId, () => loader.reload());
+    await withLoadingExtensionDepth(depth, options.agentId, options.parentAgentId, () => loader.reload());
     // Plain entries in `tools:` are expected to be built-in names (extension tools
     // go through `ext:`), so an unknown name there is unambiguously a typo. Previously
     // this produced a silently broken agent (#75) — pi-mono accepted the bogus name

package/dist/dashboard-ui.d.ts

@@ -0,0 +1,15 @@
+/**
+ * dashboard-ui.ts — Register dashboard UI modules for subagent visibility.
+ *
+ * Provides three integration points with pi-agent-dashboard:
+ * 1. Footer-segment decorator showing running/completed agent counts
+ * 2. Management-modal module with a table view of all subagent history
+ * 3. Round-trip event handlers for data fetch, abort, and steer actions
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { AgentManager } from "./agent-manager.js";
+/**
+ * Register all dashboard UI integration points.
+ * Call once during extension setup when pi.events is available.
+ */
+export declare function registerDashboardModules(pi: ExtensionAPI, manager: AgentManager): void;

package/dist/dashboard-ui.js

@@ -0,0 +1,206 @@
+/**
+ * dashboard-ui.ts — Register dashboard UI modules for subagent visibility.
+ *
+ * Provides three integration points with pi-agent-dashboard:
+ * 1. Footer-segment decorator showing running/completed agent counts
+ * 2. Management-modal module with a table view of all subagent history
+ * 3. Round-trip event handlers for data fetch, abort, and steer actions
+ */
+import { formatMs, getDisplayName } from "./ui/agent-widget.js";
+import { getLifetimeTotal } from "./usage.js";
+const NAMESPACE = "subagents";
+const MODULE_ID = "subagents-overview";
+const DATA_EVENT = "subagents:rows";
+const INVALIDATE_DEBOUNCE_MS = 500;
+/**
+ * Build a row for the management-modal table from an AgentRecord.
+ */
+function buildAgentRow(record) {
+    const durationMs = record.completedAt
+        ? record.completedAt - record.startedAt
+        : Date.now() - record.startedAt;
+    const totalTokens = getLifetimeTotal(record.lifetimeUsage);
+    return {
+        id: record.id,
+        type: getDisplayName(record.type),
+        description: record.description ?? "",
+        status: record.status,
+        toolUses: record.toolUses ?? 0,
+        tokens: totalTokens > 0 ? formatTokenCount(totalTokens) : "—",
+        duration: formatMs(durationMs),
+        outputFile: record.outputFile ?? "",
+        startedAt: record.startedAt,
+    };
+}
+function formatTokenCount(n) {
+    if (n >= 1_000_000)
+        return `${(n / 1_000_000).toFixed(1)}M`;
+    if (n >= 1_000)
+        return `${(n / 1_000).toFixed(1)}k`;
+    return String(n);
+}
+/**
+ * Register all dashboard UI integration points.
+ * Call once during extension setup when pi.events is available.
+ */
+export function registerDashboardModules(pi, manager) {
+    if (!pi.events)
+        return;
+    let invalidateTimer;
+    function scheduleInvalidate() {
+        if (invalidateTimer)
+            return;
+        invalidateTimer = setTimeout(() => {
+            invalidateTimer = undefined;
+            pi.events.emit("ui:invalidate", {});
+        }, INVALIDATE_DEBOUNCE_MS);
+    }
+    // ── 1. Module Discovery (ui:list-modules) ──────────────────────────
+    pi.events.on("ui:list-modules", ((probe) => {
+        const agents = manager.listAgents();
+        const running = agents.filter(a => a.status === "running").length;
+        const completed = agents.filter(a => a.status === "completed").length;
+        const total = agents.length;
+        // Footer-segment: running/completed counts
+        const parts = [];
+        if (running > 0)
+            parts.push(`● ${running} running`);
+        if (completed > 0)
+            parts.push(`✓ ${completed} done`);
+        if (total === 0)
+            parts.push("No agents");
+        probe.modules.push({
+            kind: "footer-segment",
+            namespace: NAMESPACE,
+            id: "agent-counts",
+            payload: {
+                text: parts.join(" · "),
+                tooltip: `${total} total agents (${running} running, ${completed} completed)`,
+                icon: "mdiRobot",
+            },
+        });
+        // Management-modal: subagent overview table
+        probe.modules.push({
+            kind: "management-modal",
+            id: MODULE_ID,
+            command: "/subagents",
+            title: "Subagents",
+            description: "View and manage background subagents",
+            icon: "mdiRobotOutline",
+            category: "subagents",
+            view: {
+                kind: "table",
+                dataEvent: DATA_EVENT,
+                rowKey: "id",
+                fields: [
+                    { key: "id", label: "ID", kind: "text", width: 120 },
+                    { key: "type", label: "Type", kind: "text", width: 100 },
+                    { key: "description", label: "Description", kind: "text" },
+                    { key: "status", label: "Status", kind: "text", width: 90 },
+                    { key: "toolUses", label: "Tools", kind: "number", width: 60 },
+                    { key: "tokens", label: "Tokens", kind: "text", width: 80 },
+                    { key: "duration", label: "Duration", kind: "text", width: 80 },
+                ],
+                rowActions: [
+                    {
+                        id: "view-result",
+                        label: "View Result",
+                        icon: "mdiEye",
+                        variant: "primary",
+                        event: "subagents:ui:view-result",
+                    },
+                    {
+                        id: "abort",
+                        label: "Abort",
+                        icon: "mdiStop",
+                        variant: "danger",
+                        event: "subagents:ui:abort",
+                        confirm: "Abort this running agent?",
+                    },
+                    {
+                        id: "steer",
+                        label: "Steer",
+                        icon: "mdiMessageArrowRight",
+                        variant: "secondary",
+                        event: "subagents:ui:steer",
+                    },
+                ],
+                emptyState: "No subagents have been spawned in this session.",
+                actions: [
+                    {
+                        id: "refresh",
+                        label: "Refresh",
+                        icon: "mdiRefresh",
+                        variant: "secondary",
+                        event: "subagents:ui:refresh",
+                    },
+                ],
+            },
+        });
+    }));
+    // ── 2. Data Fetch Handler ──────────────────────────────────────────
+    pi.events.on(DATA_EVENT, ((data) => {
+        const agents = manager.listAgents();
+        data.items = agents.map(buildAgentRow);
+    }));
+    // ── 3. Action Handlers ─────────────────────────────────────────────
+    // Refresh: just invalidate to re-probe + re-fetch
+    pi.events.on("subagents:ui:refresh", (() => {
+        scheduleInvalidate();
+    }));
+    // View Result: emit the result as a toast so the dashboard shows it
+    pi.events.on("subagents:ui:view-result", ((data) => {
+        const agentId = data.params?.id ?? data.id;
+        const record = manager.getRecord(agentId);
+        if (!record) {
+            pi.events.emit("ui:invalidate", { id: MODULE_ID });
+            return;
+        }
+        const resultText = record.result?.trim() || "No output yet.";
+        const preview = resultText.length > 2000
+            ? resultText.slice(0, 2000) + "\n…(truncated)"
+            : resultText;
+        pi.events.emit("ui:invalidate", { id: MODULE_ID });
+        // Return result as items so it shows in a detail view
+        data.items = [{
+                id: record.id,
+                type: getDisplayName(record.type),
+                description: record.description,
+                status: record.status,
+                result: preview,
+                outputFile: record.outputFile ?? "",
+            }];
+    }));
+    // Abort: signal the agent to stop
+    pi.events.on("subagents:ui:abort", ((data) => {
+        const agentId = data.params?.id ?? data.id;
+        const record = manager.getRecord(agentId);
+        if (record?.session) {
+            // Use the session's abort mechanism
+            try {
+                record.session.dispose?.();
+            }
+            catch {
+                // Ignore disposal errors
+            }
+        }
+        scheduleInvalidate();
+    }));
+    // Steer: for now just invalidate — full steer requires a prompt input
+    // which the management-modal form view could support in the future
+    pi.events.on("subagents:ui:steer", ((_data) => {
+        // TODO: Could open a form view for entering the steer message
+        scheduleInvalidate();
+    }));
+    // ── 4. Invalidate on agent lifecycle events ────────────────────────
+    const lifecycleEvents = [
+        "subagents:created",
+        "subagents:started",
+        "subagents:completed",
+        "subagents:failed",
+        "subagents:compacted",
+    ];
+    for (const event of lifecycleEvents) {
+        pi.events.on(event, (() => scheduleInvalidate()));
+    }
+}