@saccolabs/pi-claude-cli 0.4.12 → 0.4.14

package/README.md

@@ -48,6 +48,12 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - Native tool execution: the CLI runs its own tools; guards are injected as Claude Code PreToolUse hooks via `PI_CLAUDE_CLI_SETTINGS`
 - Reports account rate-limit state (window, reset, overage) to the front-end
   on the `claude-rate-limit` status key — never mixed into turn content
+- Surfaces sub-agent fan-outs: one marker when a `Task` agent starts and one
+  when it reports, plus live per-agent progress on the `claude-subagents`
+  status key — so a fan-out is no longer a blank pane
+- Background sub-agents get to finish: a `result` while agents are still
+  running ends a cycle, not the turn, so their reports reach the model
+  instead of dying with the subprocess
 - Configurable thinking effort across the full ladder (low to max), mapped 1:1 for every model: the level the host asks for is the level the CLI gets
 - Cross-platform subprocess management (Windows, macOS, Linux)
 - Inactivity timeout and process registry for cleanup

package/index.ts

@@ -17,6 +17,7 @@ import {
 import { getCustomToolDefs, writeMcpConfig } from "./src/mcp-config.js";
 import { rewriteOverflowMessage } from "./src/overflow.js";
 import { buildRateLimitPayload, rateLimitIdentity } from "./src/rate-limit.js";
+import type { TaskTrackerState } from "./src/types.js";
 
 // Kill all active Claude subprocesses on process exit to prevent orphans
 process.on("exit", killAllProcesses);
@@ -58,6 +59,41 @@ function publishRateLimit(info: Record<string, unknown>): void {
   }
 }
 
+/**
+ * Live sub-agent state, on its own status key.
+ *
+ * Same reasoning as the rate-limit channel: this is state ABOUT the turn, not
+ * content OF it. `task_progress` fires once per sub-agent tool call (roughly
+ * 700 times in the incident that motivated #23), so folding it into the
+ * transcript would bury the turn and cost context on every later replay. The
+ * durable half — one marker when a sub-agent starts, one when it finishes —
+ * goes in the turn instead, and needs no host change to render.
+ */
+const SUBAGENTS_STATUS_KEY = "claude-subagents";
+/** Last payload pushed, so an unchanged snapshot does not rewrite the status. */
+let lastSubagentsJson: string | undefined;
+
+function publishTaskProgress(state: TaskTrackerState): void {
+  const setStatus = uiContext?.ui?.setStatus;
+  if (typeof setStatus !== "function") return;
+  const json = JSON.stringify(state);
+  if (json === lastSubagentsJson) return;
+  lastSubagentsJson = json;
+  try {
+    // An empty snapshot means the episode is over: CLEAR the key rather than
+    // pushing `{"tasks":[],...}`. A host reads a present status as live
+    // state, so an empty one left standing is a strip that still claims
+    // agents when there are none.
+    setStatus.call(
+      uiContext!.ui,
+      SUBAGENTS_STATUS_KEY,
+      state.tasks.length === 0 ? undefined : json,
+    );
+  } catch {
+    /* never break a turn over a status push */
+  }
+}
+
 let mcpConfigPath: string | undefined;
 let mcpConfigResolved = false;
 
@@ -130,6 +166,7 @@ export default function (pi: ExtensionAPI) {
     pi.on("session_start", async (_event: unknown, ctx: unknown) => {
       uiContext = ctx as typeof uiContext;
       lastRateLimitJson = undefined;
+      lastSubagentsJson = undefined;
       const allTools = pi.getAllTools();
       if (Array.isArray(allTools)) {
         pi.setActiveTools(allTools.map((t: any) => t.name));
@@ -146,6 +183,7 @@ export default function (pi: ExtensionAPI) {
         ...options,
         mcpConfigPath: configPath,
         onRateLimit: publishRateLimit,
+        onTaskProgress: publishTaskProgress,
       });
     };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saccolabs/pi-claude-cli",
-  "version": "0.4.12",
+  "version": "0.4.14",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/event-bridge.ts

@@ -56,6 +56,13 @@ export interface EventBridge {
    * otherwise be invisible — each becomes a one-line marker text block.
    */
   handleAssistantEnvelope(envelope: ClaudeAssistantEnvelope): void;
+  /**
+   * Append a pre-built marker text block. Used for sub-agent lifecycle, whose
+   * events arrive as top-level `system` envelopes rather than content blocks
+   * (`src/task-tracker.ts`). The bridge stays the only writer of
+   * `output.content`.
+   */
+  appendMarker(text: string): void;
   /**
    * The final `result` envelope: authoritative cumulative usage for the
    * whole episode, plus a safety net that appends the final answer text if
@@ -649,6 +656,7 @@ export function createEventBridge(
   return {
     handleEvent,
     handleAssistantEnvelope,
+    appendMarker: appendTextBlock,
     applyResult,
     getOutput: () => output,
   };

package/src/process-manager.ts

@@ -58,6 +58,16 @@ export function spawnClaude(
     modelId,
     "--permission-prompt-tool",
     "stdio",
+    // `AskUserQuestion` renders a picker in the CLI's own TUI, and `-p` has
+    // no TUI. The call therefore cannot be answered by anyone: it returns
+    // "The user did not answer the questions." after a full round trip, and
+    // the model reads that as a person who declined and falls back to asking
+    // in prose. Captured 2026-08-28 on claude-sonnet-5, which then wrote
+    // "happy to discuss in plain text instead". Take the tool away so the
+    // model asks in prose the first time — the host's UI shows prose, and
+    // the user can answer it.
+    "--disallowedTools",
+    "AskUserQuestion",
   ];
 
   // Hermetic mode: keep the user's Claude Code environment out of pi turns.

package/src/provider.ts

@@ -40,6 +40,8 @@ import {
 } from "./process-manager.js";
 import { parseLine } from "./stream-parser.js";
 import { createEventBridge } from "./event-bridge.js";
+import { createTaskTracker, isTaskSubtype } from "./task-tracker.js";
+import type { TaskTrackerState } from "./types.js";
 import { handleControlRequest } from "./control-handler.js";
 import { mapThinkingEffort } from "./thinking-config.js";
 import { isHandoffClaudeTool } from "./tool-mapping.js";
@@ -60,12 +62,61 @@ const INACTIVITY_TIMEOUT_MS =
     ? Number(process.env.PI_CLAUDE_CLI_TIMEOUT_MS)
     : 300_000;
 
+/**
+ * BACKGROUND SUB-AGENTS REPORT BACK, AND THIS IS WHY THEY DIDN'T.
+ *
+ * The CLI answers a background `Agent` call in milliseconds with "Async agent
+ * launched successfully… you will be notified when it completes", and the
+ * model — correctly, per its own tool contract — ends its turn to wait. The
+ * CLI then emits `result` for that turn WHILE the agents keep running.
+ * Killing on that first result is what made every fan-out a dead end: the
+ * agents died mid-tool-call, their reports were never written, and the turn
+ * closed on "Now waiting on the three investigation agents".
+ *
+ * The loop the host was assumed to owe the CLI turned out to be the CLI's
+ * own. Captured 2026-08-28 on claude 2.1.231, holding the process open past
+ * `result`: the sub-agent finished at +25s, `task_notification` carried its
+ * report, the CLI re-invoked the model unprompted, and it answered with the
+ * findings and emitted a SECOND `result`. Nothing was written to stdin to
+ * make that happen.
+ *
+ * So the fix is to stop killing: while `pendingAgents()` is non-zero, a
+ * `result` is a cycle boundary, not the end of the episode. Two bounds keep a
+ * runaway fan-out from holding a turn open forever — the inactivity timer
+ * (which `task_progress` keeps resetting for as long as agents do real work)
+ * and the wall clock below.
+ *
+ * `applyResult` is safe to call per cycle: the CLI's `modelUsage` is
+ * cumulative for the session, verified across a two-result episode
+ * (cache-read 68,718 → 161,295), so the last one wins rather than summing.
+ */
+const WAIT_FOR_AGENTS = process.env.PI_CLAUDE_CLI_NO_AGENT_WAIT !== "1";
+
+/** Hard ceiling on holding a turn open for sub-agents. */
+const AGENT_WAIT_TIMEOUT_MS =
+  Number(process.env.PI_CLAUDE_CLI_AGENT_WAIT_MS) > 0
+    ? Number(process.env.PI_CLAUDE_CLI_AGENT_WAIT_MS)
+    : 900_000;
+
+/**
+ * Backstop on continuation cycles. Each completing agent costs one, and an
+ * agent may launch more; this only exists so a pathological loop cannot spin
+ * without end.
+ */
+const MAX_AGENT_CONTINUATIONS = 32;
+
 /** Extended stream options: pi's SimpleStreamOptions plus optional cwd and mcpConfigPath */
 type StreamViaCLiOptions = SimpleStreamOptions & {
   cwd?: string;
   mcpConfigPath?: string;
   /** Called with account rate-limit state as the CLI reports it. */
   onRateLimit?: (info: Record<string, unknown>) => void;
+  /**
+   * Called with live sub-agent state as the CLI reports it. Ephemeral: this is
+   * progress, not transcript, and must never be folded into turn content. The
+   * durable half (start/finish) rides in the turn as markers instead.
+   */
+  onTaskProgress?: (state: TaskTrackerState) => void;
 };
 
 /**
@@ -193,6 +244,9 @@ export function streamViaCli(
 
       // Create event bridge (before endStreamWithError so bridge is in scope)
       const bridge = createEventBridge(stream, model);
+      // Per-attempt: a resume-miss retry replays the episode, and its
+      // sub-agents must not be counted twice.
+      const taskTracker = createTaskTracker();
 
       // Guard against double stream.end() and double error events.
       // First error path wins; subsequent ones are no-ops.
@@ -229,9 +283,41 @@ export function streamViaCli(
       // Inactivity timeout: kill subprocess if no stdout for INACTIVITY_TIMEOUT_MS
       let inactivityTimer: ReturnType<typeof setTimeout> | undefined;
 
+      // Sub-agent wait state (see WAIT_FOR_AGENTS): how many `result`
+      // envelopes have been treated as cycle boundaries, and the wall-clock
+      // backstop that stops waiting no matter what the agents are doing.
+      let agentContinuations = 0;
+      let agentWaitTimer: ReturnType<typeof setTimeout> | undefined;
+      let agentWaitExpired = false;
+      let waitingForAgents = false;
+
+      /**
+       * End the episode on what it already has: kill the CLI and close the
+       * reader without pushing an error.
+       *
+       * Only correct once a `result` has been seen. Before that, silence means
+       * a wedged CLI and the turn has nothing — which is what the inactivity
+       * timeout's error is for.
+       */
+      function endTurnOnPartialWork() {
+        agentWaitExpired = true;
+        clearTimeout(inactivityTimer);
+        clearTimeout(agentWaitTimer);
+        cleanupProcess(proc!);
+        rl.close();
+      }
+
       function resetInactivityTimer() {
         if (inactivityTimer !== undefined) clearTimeout(inactivityTimer);
         inactivityTimer = setTimeout(() => {
+          // Waiting on sub-agents is the one state where silence is not a
+          // failed turn: the model already spoke and the result already
+          // landed. An agent that dies without notifying must not convert
+          // that into an error and throw the content away.
+          if (waitingForAgents) {
+            endTurnOnPartialWork();
+            return;
+          }
           forceKillProcess(proc!);
           endStreamWithError(
             `Claude CLI subprocess timed out: no output for ${INACTIVITY_TIMEOUT_MS / 1000} seconds`,
@@ -278,6 +364,7 @@ export function streamViaCli(
       // Handle subprocess close -- surface crashes with stderr and exit code
       proc.on("close", (code: number | null, _signal: string | null) => {
         clearTimeout(inactivityTimer);
+        clearTimeout(agentWaitTimer);
         if (broken) return; // resume-miss retry owns the stream
         if (code !== 0 && code !== null) {
           const stderr = getStderr();
@@ -352,6 +439,23 @@ export function streamViaCli(
               /* a status push must never break a turn */
             }
           }
+        } else if (
+          msg.type === "system" &&
+          isTaskSubtype((msg as any).subtype)
+        ) {
+          // Sub-agent lifecycle. The agents' own envelopes carry
+          // parent_tool_use_id and stay internal to the CLI, but these arrive
+          // at top level even for deeply nested agents — the one channel that
+          // makes a fan-out visible at all (#23).
+          if (!selfInterrupted) {
+            const marker = taskTracker.apply(msg as any);
+            if (marker) bridge.appendMarker(marker);
+            try {
+              options?.onTaskProgress?.(taskTracker.snapshot());
+            } catch {
+              /* a status push must never break a turn */
+            }
+          }
         } else if (msg.type === "assistant") {
           // Complete-block envelopes: marker text for the CLI's own tool
           // executions (built-ins, WebSearch, user MCP, …), which in observer
@@ -396,8 +500,39 @@ export function streamViaCli(
             // handoff toolCall) is already accumulated; usage still applies.
             bridge.applyResult(r);
           }
+
+          // Sub-agents still working: this result ends a CYCLE, not the
+          // episode. Leave the CLI alive and keep reading — it re-invokes the
+          // model itself once they report, and emits another result. See
+          // WAIT_FOR_AGENTS for the capture this is built on.
+          if (
+            WAIT_FOR_AGENTS &&
+            !isError &&
+            !selfInterrupted &&
+            !aborted &&
+            !agentWaitExpired &&
+            agentContinuations < MAX_AGENT_CONTINUATIONS &&
+            taskTracker.pendingAgents() > 0
+          ) {
+            agentContinuations++;
+            waitingForAgents = true;
+            if (agentWaitTimer === undefined) {
+              agentWaitTimer = setTimeout(() => {
+                // Give up waiting, but let the turn end on its own content:
+                // the launch markers and whatever the model already said are
+                // real, and an error here would throw them away.
+                endTurnOnPartialWork();
+              }, AGENT_WAIT_TIMEOUT_MS);
+              // A pending wait must never hold the host process open.
+              agentWaitTimer.unref?.();
+            }
+            resetInactivityTimer();
+            return;
+          }
+
           // For success, handoff and error alike: clean up the subprocess
           clearTimeout(inactivityTimer);
+          clearTimeout(agentWaitTimer);
           cleanupProcess(proc!);
           rl.close();
         }
@@ -467,6 +602,16 @@ export function streamViaCli(
       stream.end();
     } finally {
       cleanupSystemPromptFile();
+      // The sub-agent channel is state ABOUT a turn, so it must not outlive
+      // one. Left standing, the last snapshot pins whatever the agents were
+      // doing when the episode ended — a host then shows "running" for
+      // agents that finished, or for agents that died, until the next turn
+      // happens to publish something else.
+      try {
+        options?.onTaskProgress?.({ tasks: [], active: 0, completed: 0 });
+      } catch {
+        /* a status push must never break a turn */
+      }
     }
   })();
 

package/src/task-tracker.ts

@@ -0,0 +1,284 @@
+/**
+ * Sub-agent (Task) visibility.
+ *
+ * The CLI runs sub-agents inside its own process. Their stream envelopes carry
+ * `parent_tool_use_id` and are deliberately not forwarded — they are the CLI's
+ * internal loop, and forwarding hundreds of nested tool calls would bury the
+ * turn. But dropping them left a host with nothing at all: a single
+ * `[Claude Code · Task {…}]` marker and then silence for as long as the
+ * fan-out ran. One pidex turn sat blank for eight minutes behind 14 nested
+ * agents and was killed as hung (issue #23).
+ *
+ * The CLI already publishes a purpose-built feed for exactly this, and the
+ * provider was not reading it. `system` envelopes with a `task_*` subtype
+ * arrive at TOP level (`parent_tool_use_id` is null) even for agents nested
+ * several deep, verified on claude 2.1.231 at spawn depth 2. They are low
+ * volume and carry description, sub-agent type, tool count, tokens and
+ * duration.
+ *
+ * Two channels, split by durability:
+ *
+ * - **Lifecycle goes in the turn** as marker text. `task_started` and the
+ *   terminal `task_notification` are durable facts about what the turn did,
+ *   and belong in the transcript beside the CLI's other tool markers. Two
+ *   lines per sub-agent, so a 14-agent fan-out costs 28.
+ * - **Progress goes out of band**, like `rate_limit_event` before it.
+ *   `task_progress` fires once per sub-agent tool call — ~700 times in the
+ *   incident above — which is live state, not transcript. It must never be
+ *   folded into turn content.
+ *
+ * What this deliberately does NOT do: build a tree. No task envelope names its
+ * parent task, so a nested agent is indistinguishable from a top-level one
+ * here. The list is flat, and honestly so.
+ *
+ * TWO THINGS THIS CHANNEL IS NOT. Both were shipped as sub-agents once, and
+ * both put rows in pidex that named work no agent ever did:
+ *
+ * - **Not every task is an agent.** `task_started` carries `task_type`, and
+ *   the CLI auto-backgrounds a slow `Bash` into a `local_bash` task with the
+ *   tool's own `description`. Captured 2026-08-28 on claude 2.1.231: a
+ *   sub-agent's internal `find` surfaced as `[Claude Code · Task
+ *   {"status":"started","description":"Search for local source checkout of
+ *   pi-claude-cli"}]` — a fourth "agent" in a three-agent fan-out. Only
+ *   `local_agent` and `remote_agent` are sub-agents.
+ * - **Not every notification belongs to this episode.** `task_notification`
+ *   carries no `description` and no `task_type` — only `task_id`. A task
+ *   started in an EARLIER turn notifies in a later one, and a tracker that
+ *   invents a placeholder from the id emits `{"status":"stopped",
+ *   "description":"a8de7d982d824b56a"}`. An id this tracker never saw start
+ *   is not this episode's business, so it is dropped.
+ */
+
+import type {
+  ClaudeTaskEvent,
+  TaskSnapshot,
+  TaskTrackerState,
+} from "./types.js";
+
+/**
+ * Marker argument previews are truncated to keep one row on one line.
+ *
+ * Raised from 120 when `task_id` joined the payload: at 120 the id pushed
+ * `subagent_type` off the end, so a fan-out stopped saying WHICH kind of
+ * agent it launched — the one fact the row exists to carry.
+ */
+export const ARGS_PREVIEW_LIMIT = 200;
+
+/**
+ * Per-field cap on the description, applied BEFORE the whole-payload cap.
+ *
+ * Ordering fields human-first is not enough on its own: one long description
+ * eats the entire preview and takes `subagent_type` and `task_id` with it,
+ * which is how a 300-character task name could cost a host the identity it
+ * needs to collapse the row. Clip the one unbounded field instead, so the
+ * small structural ones always survive.
+ */
+export const DESCRIPTION_PREVIEW_LIMIT = 120;
+
+function clipDescription(value: string): string {
+  return value.length > DESCRIPTION_PREVIEW_LIMIT
+    ? `${value.slice(0, DESCRIPTION_PREVIEW_LIMIT)}…`
+    : value;
+}
+
+/**
+ * `task_type` values that mean "a sub-agent". Everything else the CLI tracks
+ * as a task — `local_bash`, `local_shell`, `local_workflow`, `main_session` —
+ * is plumbing this channel must not report as an agent.
+ *
+ * An event with NO `task_type` is treated as an agent: older CLIs omit the
+ * field, and going silent on them would be a worse regression than the stray
+ * row this filter exists to remove.
+ */
+const AGENT_TASK_TYPES = new Set(["local_agent", "remote_agent"]);
+
+export function isAgentTaskType(taskType: unknown): boolean {
+  return taskType === undefined || taskType === null
+    ? true
+    : typeof taskType === "string" && AGENT_TASK_TYPES.has(taskType);
+}
+
+/**
+ * Build a `[Claude Code · Task …]` marker.
+ *
+ * WIRE CONTRACT — the same shape `event-bridge.ts` emits for CLI-side tool
+ * executions, and front-ends parse it with
+ * `/^\[Claude Code · ([^\s\]]+)(?:\s+([\s\S]*))?\]$/`. The tool name must stay
+ * space-free; everything else rides in the argument JSON, which is truncated
+ * here and must never be parsed as JSON by a consumer.
+ */
+function taskMarker(args: Record<string, unknown>): string {
+  let preview = "";
+  try {
+    const json = JSON.stringify(args);
+    preview =
+      json === "{}"
+        ? ""
+        : ` ${json.slice(0, ARGS_PREVIEW_LIMIT)}${json.length > ARGS_PREVIEW_LIMIT ? "…" : ""}`;
+  } catch {
+    /* unserializable — the marker still names the tool */
+  }
+  return `[Claude Code · Task${preview}]`;
+}
+
+export interface TaskTracker {
+  /**
+   * Fold one `task_*` envelope in. Returns a marker string when the event is a
+   * durable lifecycle transition (start, finish) and nothing when it is live
+   * progress. Unknown subtypes and events without a `task_id` are ignored.
+   */
+  apply(event: ClaudeTaskEvent): string | undefined;
+  /** Current state of every sub-agent seen this episode. */
+  snapshot(): TaskTrackerState;
+  /**
+   * Sub-agents that started this episode and have not reported yet.
+   *
+   * The provider waits on this before it tears the CLI down: the CLI emits
+   * its turn `result` the moment the model stops talking, which for a
+   * background fan-out is long before the agents finish.
+   */
+  pendingAgents(): number;
+}
+
+export function createTaskTracker(): TaskTracker {
+  /** Insertion-ordered, so the snapshot reads in launch order. */
+  const tasks = new Map<string, TaskSnapshot>();
+
+  /**
+   * Patch a task this tracker already knows. Returns undefined for an id it
+   * never saw start — a task from an earlier episode, or one filtered out as
+   * not-an-agent. Inventing a placeholder here is what named rows after raw
+   * task ids; see the header.
+   */
+  function patch(
+    id: string,
+    changes: Partial<TaskSnapshot>,
+  ): TaskSnapshot | undefined {
+    const existing = tasks.get(id);
+    if (!existing) return undefined;
+    Object.assign(existing, changes);
+    return existing;
+  }
+
+  return {
+    apply(event: ClaudeTaskEvent): string | undefined {
+      const id = event.task_id;
+      if (!id) return undefined;
+
+      switch (event.subtype) {
+        case "task_started": {
+          // Plumbing, not a sub-agent: an auto-backgrounded Bash arrives here
+          // wearing the tool's own description. See the header.
+          if (!isAgentTaskType(event.task_type)) return undefined;
+          const task: TaskSnapshot = {
+            taskId: id,
+            description: event.description ?? id,
+            subagentType: event.subagent_type,
+            taskType: event.task_type,
+            toolUseId: event.tool_use_id,
+            status: "running",
+          };
+          tasks.set(id, task);
+          // `skip_transcript` suppresses the ROW, never the tracking: a
+          // hidden sub-agent still holds the turn open, and the provider
+          // reads `pendingAgents()` to decide when the turn may end.
+          if (event.skip_transcript === true) return undefined;
+          return taskMarker({
+            status: "started",
+            description: clipDescription(task.description),
+            subagent_type: task.subagentType,
+            task_id: task.taskId,
+          });
+        }
+
+        case "task_progress": {
+          patch(id, {
+            // `description` on a progress event is the CURRENT step ("Running
+            // …"), not the task's own description. Keep them apart: the task
+            // name was set at start and must not be overwritten by a step.
+            currentStep: event.description,
+            subagentType: event.subagent_type ?? tasks.get(id)?.subagentType,
+            lastToolName: event.last_tool_name,
+            toolUses: event.usage?.tool_uses,
+            totalTokens: event.usage?.total_tokens,
+            durationMs: event.usage?.duration_ms,
+          });
+          return undefined;
+        }
+
+        case "task_updated": {
+          const status = event.patch?.status;
+          if (status) patch(id, { status });
+          return undefined;
+        }
+
+        case "task_notification": {
+          const task = patch(id, {
+            status: event.status ?? "completed",
+            outputFile: event.output_file,
+            summary: event.summary,
+            toolUses: event.usage?.tool_uses ?? tasks.get(id)?.toolUses,
+            totalTokens:
+              event.usage?.total_tokens ?? tasks.get(id)?.totalTokens,
+            durationMs: event.usage?.duration_ms ?? tasks.get(id)?.durationMs,
+            currentStep: undefined,
+          });
+          // Not ours: a task from an earlier episode, or one filtered out at
+          // start. A notification carries no description, so the only row
+          // this could produce would be named after a raw task id.
+          if (!task) return undefined;
+          // The sub-agent's full report reaches the model as the Task tool's
+          // own result. Repeating it here would duplicate kilobytes into the
+          // transcript, so the marker carries the shape of the work, not its
+          // output.
+          return taskMarker({
+            status: task.status,
+            description: clipDescription(task.description),
+            task_id: task.taskId,
+            tool_uses: task.toolUses,
+            total_tokens: task.totalTokens,
+            duration_ms: task.durationMs,
+          });
+        }
+
+        default:
+          return undefined;
+      }
+    },
+
+    snapshot(): TaskTrackerState {
+      const list = [...tasks.values()].map((t) => ({ ...t }));
+      return {
+        tasks: list,
+        active: list.filter((t) => t.status === "running").length,
+        completed: list.filter((t) => t.status !== "running").length,
+      };
+    },
+
+    pendingAgents(): number {
+      let pending = 0;
+      for (const task of tasks.values()) {
+        if (task.status === "running") pending++;
+      }
+      return pending;
+    },
+  };
+}
+
+/** The `system` subtypes this module handles. */
+const TASK_SUBTYPES = new Set([
+  "task_started",
+  "task_progress",
+  "task_updated",
+  "task_notification",
+]);
+
+/**
+ * Whether a `system` envelope's subtype is sub-agent lifecycle.
+ *
+ * `system` also carries init/status/summary envelopes that have nothing to do
+ * with sub-agents, so the provider narrows before handing anything over.
+ */
+export function isTaskSubtype(subtype: unknown): boolean {
+  return typeof subtype === "string" && TASK_SUBTYPES.has(subtype);
+}

package/src/types.ts

@@ -106,6 +106,87 @@ export interface ClaudeSystemMessage {
   tools?: unknown[];
 }
 
+/**
+ * Sub-agent lifecycle, emitted by the CLI as `system` envelopes.
+ *
+ * These arrive at TOP level — `parent_tool_use_id` is null — even for agents
+ * nested several deep, verified on claude 2.1.231 at spawn depth 2. That is
+ * what makes them usable: the sub-agents' own `assistant` envelopes are
+ * tagged with `parent_tool_use_id` and stay internal to the CLI, but their
+ * lifecycle is published here in the open.
+ *
+ * `description` means two different things by subtype. On `task_started` it
+ * names the task; on `task_progress` it is the step running right now
+ * ("Running …"). `src/task-tracker.ts` keeps them apart.
+ */
+export interface ClaudeTaskEvent {
+  type: "system";
+  subtype:
+    | "task_started"
+    | "task_progress"
+    | "task_updated"
+    | "task_notification"
+    | string;
+  task_id?: string;
+  tool_use_id?: string;
+  description?: string;
+  subagent_type?: string;
+  task_type?: string;
+  /** Terminal status on `task_notification`. */
+  status?: string;
+  /** Where the CLI wrote the sub-agent's full report. */
+  output_file?: string;
+  /** Partial state change on `task_updated`. */
+  patch?: { status?: string; end_time?: number };
+  last_tool_name?: string;
+  /**
+   * The CLI's own "do not put this in a transcript" hint. Set on tasks it
+   * considers plumbing; honoured for markers, not for tracking, because a
+   * hidden sub-agent still holds the turn open.
+   */
+  skip_transcript?: boolean;
+  /** The sub-agent's report, on `task_notification`. Live state, not content. */
+  summary?: string;
+  usage?: {
+    total_tokens?: number;
+    tool_uses?: number;
+    duration_ms?: number;
+  };
+}
+
+/** One sub-agent's state, as the host sees it. */
+export interface TaskSnapshot {
+  taskId: string;
+  /** Names the task. Set at `task_started`, never overwritten by a step. */
+  description: string;
+  subagentType?: string;
+  /**
+   * The CLI's task kind — `local_agent` / `remote_agent` for a sub-agent.
+   * Undefined on a CLI too old to send it, which is read as "agent" so the
+   * tracker keeps working rather than going silent.
+   */
+  taskType?: string;
+  /** The `Agent` tool call that launched this task; the join key a host needs. */
+  toolUseId?: string;
+  status: string;
+  /** The step running right now, cleared when the task ends. */
+  currentStep?: string;
+  lastToolName?: string;
+  toolUses?: number;
+  totalTokens?: number;
+  durationMs?: number;
+  outputFile?: string;
+  /** The sub-agent's own report, once it finishes. */
+  summary?: string;
+}
+
+/** Every sub-agent seen this episode, in launch order. */
+export interface TaskTrackerState {
+  tasks: TaskSnapshot[];
+  active: number;
+  completed: number;
+}
+
 export interface ClaudeControlRequest {
   type: "control_request";
   request_id: string;
@@ -120,6 +201,7 @@ export type NdjsonMessage =
   | ClaudeStreamEventMessage
   | ClaudeResultMessage
   | ClaudeSystemMessage
+  | ClaudeTaskEvent
   | ClaudeControlRequest
   | ClaudeAssistantEnvelope
   | ClaudeUserEnvelope