@clanker-code/pi-subagents 0.10.8 → 0.11.1

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,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.11.1] - 2026-06-28
+
+### Fixed
+- **Depth 2+ subagents now appear in the TUI widget** — each child session's `DefaultResourceLoader` previously created its own isolated event bus, so lifecycle events (`subagents:created`, `subagents:started`, `subagents:completed`, `subagents:failed`) from depth 2+ agents never reached the parent's widget listener. A forwarding event bus now wraps the parent bus: the child gets its own isolated local bus, but lifecycle events are forwarded to the parent so the widget renders the full recursive agent tree.
+- **Agent tool description shows next spawn depth instead of agent's own depth** — the `{{currentDepth}}` placeholder and recursive guideline in the Agent tool description now show `extensionDepth + 1` (the depth the *next* spawned agent would be at) instead of `extensionDepth` (the agent's own depth), eliminating the off-by-one confusion where a depth-1 agent displayed "1/4" but spawned agents at depth 2.
+- **Event bus propagation covers all spawn paths** — RPC-spawned agents (`cross-extension-rpc.ts`), scheduled agents (`schedule.ts`), and `spawnAndWait` foreground agents now correctly receive the parent's event bus and recursive depth metadata, so lifecycle events from agents spawned via any path are visible in the parent widget.
+- **Dashboard UI action handlers** — steer, abort, and view-result row actions in the subagents management modal now route to the correct handler functions instead of silently no-opping.
+- **Dashboard UI duplicate module push guard** — the `ui_management` probe no longer pushes duplicate module entries when called multiple times in the same session.
+
+### Added
+- **Dashboard UI model column** — the subagents management modal now shows the model used by each agent (e.g. "opus", "sonnet") in a dedicated column.
+
+## [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/dist/agent-manager.d.ts

@@ -8,6 +8,7 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type ToolActivity } from "./agent-runner.js";
+import type { EventBus } from "./cross-extension-rpc.js";
 import { type AgentInvocation, type AgentRecord, type IsolationMode, type SubagentType, type ThinkingLevel } from "./types.js";
 export type OnAgentComplete = (record: AgentRecord) => void;
 export type OnAgentStart = (record: AgentRecord) => void;
@@ -69,6 +70,8 @@ interface SpawnOptions {
     }) => void;
     /** Called when the session successfully compacts. */
     onCompaction?: (info: CompactionInfo) => void;
+    /** Parent's event bus — shared with child sessions so lifecycle events propagate to the parent widget. */
+    eventBus?: EventBus;
 }
 interface ResumeOptions {
     signal?: AbortSignal;
@@ -94,6 +97,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 +110,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 +128,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
@@ -197,6 +218,7 @@ export class AgentManager {
             },
             depth: record.depth,
             parentAgentId: record.parentAgentId,
+            eventBus: options.eventBus,
             onSessionCreated: (session) => {
                 record.session = session;
                 // Flush any steers that arrived before the session was ready
@@ -239,12 +261,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 +290,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 +312,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 +341,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 +371,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 +379,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 +400,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 +408,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 +468,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 +480,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 +511,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

@@ -4,6 +4,7 @@
 import type { Model } from "@earendil-works/pi-ai";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { type AgentSession, type ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import type { EventBus } from "./cross-extension-rpc.js";
 import { type SubagentType, type ThinkingLevel } from "./types.js";
 /**
  * Tool names registered by THIS extension. Single source of truth so the
@@ -15,10 +16,20 @@ 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";
 };
+/**
+ * Create a forwarding event bus for a child session.
+ * The child gets its own local bus for emit/on, but lifecycle events
+ * (subagents:*) are also forwarded to the parent bus so the parent widget
+ * can display depth 2+ agents.
+ */
+export declare function createForwardingEventBus(parentBus: EventBus): EventBus;
 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]`
@@ -128,6 +139,9 @@ export interface RunOptions {
     depth?: number;
     /** Parent subagent id when spawned recursively from another subagent. */
     parentAgentId?: string;
+    /** Parent's event bus — shared with the child session so lifecycle events
+     * (subagents:created, subagents:started, etc.) propagate to the parent widget. */
+    eventBus?: EventBus;
 }
 export interface RunResult {
     responseText: string;

package/dist/agent-runner.js

@@ -4,7 +4,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
-import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { createAgentSession, createEventBus, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getConfig, getMemoryToolNames, getReadOnlyMemoryToolNames, getToolNamesForType } from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
 import { DEFAULT_AGENTS } from "./default-agents.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",
 };
 /**
@@ -38,6 +40,38 @@ const RECURSIVE_TOOL_NAMES = [
     SUBAGENT_TOOL_NAMES.STEER,
 ];
 const EXTENSION_DEPTH_KEY = Symbol.for("pi-subagents:extension-depth");
+/** Lifecycle event names that should propagate from child to parent sessions. */
+const FORWARDABLE_EVENTS = new Set([
+    "subagents:created",
+    "subagents:started",
+    "subagents:completed",
+    "subagents:failed",
+    "subagents:compacted",
+]);
+/**
+ * Create a forwarding event bus for a child session.
+ * The child gets its own local bus for emit/on, but lifecycle events
+ * (subagents:*) are also forwarded to the parent bus so the parent widget
+ * can display depth 2+ agents.
+ */
+export function createForwardingEventBus(parentBus) {
+    // Use the parent's EventBus factory to create a properly isolated local bus
+    const localBus = createEventBus();
+    return {
+        on(event, handler) {
+            // Subscribe to local bus only — child doesn't see parent/sibling events
+            return localBus.on(event, handler);
+        },
+        emit(event, data) {
+            // Always emit on local bus for child's own listeners
+            localBus.emit(event, data);
+            // Forward lifecycle events to parent bus for parent widget visibility
+            if (FORWARDABLE_EVENTS.has(event)) {
+                parentBus.emit(event, data);
+            }
+        },
+    };
+}
 const AUTO_EXPOSE_EXTENSION_NAMES = new Set(["pi-c2c"]);
 let extensionDepthLoadChain = Promise.resolve();
 const packageNameCache = new Map();
@@ -53,7 +87,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 +101,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 +122,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]`
@@ -429,6 +470,10 @@ export async function runAgent(ctx, type, prompt, options) {
                 }),
             };
         };
+    // Create a forwarding event bus so the child session's lifecycle events
+    // (subagents:created, subagents:started, etc.) propagate to the parent's
+    // event bus — making depth 2+ agents visible in the parent widget.
+    const childEventBus = options.eventBus ? createForwardingEventBus(options.eventBus) : undefined;
     const loader = new DefaultResourceLoader({
         cwd: configCwd,
         agentDir,
@@ -441,8 +486,9 @@ export async function runAgent(ctx, type, prompt, options) {
         noContextFiles: true,
         systemPromptOverride: () => systemPrompt,
         appendSystemPromptOverride: () => [],
+        eventBus: childEventBus,
     });
-    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/agent-tool-description.d.ts

@@ -2,7 +2,13 @@ import type { ToolDescriptionMode } from "./settings.js";
 export declare function getModelLabelFromConfig(model: string): string;
 export interface AgentToolDescriptionOptions {
     mode: ToolDescriptionMode;
-    extensionDepth: number;
+    /**
+     * Depth at which the NEXT spawned subagent will run.
+     * This is `extensionDepth + 1` — the agent's own depth plus one.
+     * Displayed as "Current recursive depth" in the tool description so the
+     * LLM sees the depth of the agent it is about to create, not its own depth.
+     */
+    nextSubagentDepth: number;
     schedulingEnabled: boolean;
 }
 export declare function buildScheduleGuideline(schedulingEnabled: boolean): string;

package/dist/agent-tool-description.js

@@ -39,7 +39,7 @@ export function buildScheduleGuideline(schedulingEnabled) {
 }
 export function buildAgentToolDescription(options) {
     const scheduleGuideline = buildScheduleGuideline(options.schedulingEnabled);
-    const recursiveGuideline = `Recursive agents are allowed through depth ${MAX_RECURSIVE_DEPTH}. Current recursive depth: ${options.extensionDepth}/${MAX_RECURSIVE_DEPTH}.`;
+    const recursiveGuideline = `Recursive agents are allowed through depth ${MAX_RECURSIVE_DEPTH}. Current recursive depth: ${options.nextSubagentDepth}/${MAX_RECURSIVE_DEPTH}.`;
     const compactAgentToolDescription = `Launch an autonomous agent for complex, multi-step tasks. Agent types:
 ${buildCompactTypeListText()}
 
@@ -49,7 +49,7 @@ Notes:
 - description: 3-5 words (shown in UI). Prompts must be self-contained — the agent has not seen this conversation.
 - Parallel work: one message, multiple Agent calls; they all run in the background. You are notified when agents finish — never poll or sleep.
 - Background by default: when you have useful independent work, launch it and continue. Doing nothing while an agent runs is worse than letting background work proceed.
-- Recursive agents: current depth ${options.extensionDepth}/${MAX_RECURSIVE_DEPTH}; you may spawn subagents until depth ${MAX_RECURSIVE_DEPTH}.
+- Recursive agents: current depth ${options.nextSubagentDepth}/${MAX_RECURSIVE_DEPTH}; you may spawn subagents until depth ${MAX_RECURSIVE_DEPTH}.
 - The result is not shown to the user — summarize it for them. Verify an agent's claimed code changes before reporting work done.
 - resume continues a previous agent by ID; steer_subagent messages a running one.
 - list_models enumerates the model registry the \`model:\` param accepts — call it before picking a model explicitly.
@@ -105,7 +105,7 @@ Terse command-style prompts produce shallow, generic work.
             compactTypeList: buildCompactTypeListText,
             agentDir: getAgentDir,
             scheduleGuideline: () => scheduleGuideline,
-            currentDepth: () => String(options.extensionDepth),
+            currentDepth: () => String(options.nextSubagentDepth),
             maxDepth: () => String(MAX_RECURSIVE_DEPTH),
             recursiveGuideline: () => recursiveGuideline,
         };

package/dist/cross-extension-rpc.d.ts

@@ -33,6 +33,10 @@ export interface RpcDeps {
     pi: unknown;
     getCtx: () => unknown | undefined;
     manager: SpawnCapable;
+    /** Default recursive depth for RPC-spawned subagents in this session. */
+    depth?: number;
+    /** Parent subagent id for RPC-spawned subagents in this session. */
+    parentAgentId?: string;
 }
 export interface RpcHandle {
     unsubPing: () => void;

package/dist/cross-extension-rpc.js

@@ -66,7 +66,17 @@ export function registerRpcHandlers(deps) {
             }
             normalizedOptions = { ...normalizedOptions, model: resolved };
         }
-        return { id: manager.spawn(pi, ctx, type, prompt, normalizedOptions) };
+        const spawnOptions = {
+            ...normalizedOptions,
+            eventBus: events,
+            depth: normalizedOptions.depth ?? deps.depth,
+            parentAgentId: normalizedOptions.parentAgentId ?? deps.parentAgentId,
+        };
+        if (spawnOptions.depth === undefined)
+            delete spawnOptions.depth;
+        if (spawnOptions.parentAgentId === undefined)
+            delete spawnOptions.parentAgentId;
+        return { id: manager.spawn(pi, ctx, type, prompt, spawnOptions) };
     });
     const unsubStop = handleRpc(events, "subagents:rpc:stop", ({ agentId }) => {
         if (!manager.abort(agentId))

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;