@saccolabs/pi-claude-cli 0.4.12 → 0.4.13

package/README.md

@@ -48,6 +48,9 @@ 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
 - 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,33 @@ 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 {
+    setStatus.call(uiContext!.ui, SUBAGENTS_STATUS_KEY, json);
+  } catch {
+    /* never break a turn over a status push */
+  }
+}
+
 let mcpConfigPath: string | undefined;
 let mcpConfigResolved = false;
 
@@ -130,6 +158,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 +175,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.13",
   "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/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";
@@ -66,6 +68,12 @@ type StreamViaCLiOptions = SimpleStreamOptions & {
   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 +201,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.
@@ -352,6 +363,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

package/src/task-tracker.ts

@@ -0,0 +1,191 @@
+/**
+ * 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.
+ */
+
+import type {
+  ClaudeTaskEvent,
+  TaskSnapshot,
+  TaskTrackerState,
+} from "./types.js";
+
+/** Marker argument previews are truncated to keep one row on one line. */
+const ARGS_PREVIEW_LIMIT = 120;
+
+/**
+ * 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;
+}
+
+export function createTaskTracker(): TaskTracker {
+  /** Insertion-ordered, so the snapshot reads in launch order. */
+  const tasks = new Map<string, TaskSnapshot>();
+
+  function upsert(id: string, patch: Partial<TaskSnapshot>): TaskSnapshot {
+    const existing = tasks.get(id);
+    const next: TaskSnapshot = existing ?? {
+      taskId: id,
+      // A progress event can arrive before the start it belongs to if the CLI
+      // reorders; the id is a truthful placeholder until the start names it.
+      description: id,
+      status: "running",
+    };
+    Object.assign(next, patch);
+    tasks.set(id, next);
+    return next;
+  }
+
+  return {
+    apply(event: ClaudeTaskEvent): string | undefined {
+      const id = event.task_id;
+      if (!id) return undefined;
+
+      switch (event.subtype) {
+        case "task_started": {
+          const task = upsert(id, {
+            description: event.description ?? id,
+            subagentType: event.subagent_type,
+            status: "running",
+          });
+          return taskMarker({
+            status: "started",
+            description: task.description,
+            subagent_type: task.subagentType,
+          });
+        }
+
+        case "task_progress": {
+          upsert(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;
+          upsert(id, status ? { status } : {});
+          return undefined;
+        }
+
+        case "task_notification": {
+          const task = upsert(id, {
+            status: event.status ?? "completed",
+            outputFile: event.output_file,
+            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,
+          });
+          // 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: task.description,
+            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,
+      };
+    },
+  };
+}
+
+/** 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,69 @@ 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;
+  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;
+  status: string;
+  /** The step running right now, cleared when the task ends. */
+  currentStep?: string;
+  lastToolName?: string;
+  toolUses?: number;
+  totalTokens?: number;
+  durationMs?: number;
+  outputFile?: 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 +183,7 @@ export type NdjsonMessage =
   | ClaudeStreamEventMessage
   | ClaudeResultMessage
   | ClaudeSystemMessage
+  | ClaudeTaskEvent
   | ClaudeControlRequest
   | ClaudeAssistantEnvelope
   | ClaudeUserEnvelope