@saccolabs/pi-claude-cli 0.4.13 → 0.4.14

package/README.md

@@ -51,6 +51,9 @@ Requires the `claude` binary on your login-shell PATH (`npm install -g @anthropi
 - 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

@@ -80,7 +80,15 @@ function publishTaskProgress(state: TaskTrackerState): void {
   if (json === lastSubagentsJson) return;
   lastSubagentsJson = json;
   try {
-    setStatus.call(uiContext!.ui, SUBAGENTS_STATUS_KEY, json);
+    // 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 */
   }

package/package.json

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

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

@@ -62,6 +62,49 @@ 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;
@@ -240,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`,
@@ -289,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();
@@ -424,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();
         }
@@ -495,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

@@ -30,6 +30,23 @@
  * 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 {
@@ -38,8 +55,48 @@ import type {
   TaskTrackerState,
 } from "./types.js";
 
-/** Marker argument previews are truncated to keep one row on one line. */
-const ARGS_PREVIEW_LIMIT = 120;
+/**
+ * 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.
@@ -73,24 +130,34 @@ export interface TaskTracker {
   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>();
 
-  function upsert(id: string, patch: Partial<TaskSnapshot>): 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);
-    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;
+    if (!existing) return undefined;
+    Object.assign(existing, changes);
+    return existing;
   }
 
   return {
@@ -100,20 +167,32 @@ export function createTaskTracker(): TaskTracker {
 
       switch (event.subtype) {
         case "task_started": {
-          const task = upsert(id, {
+          // 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: task.description,
+            description: clipDescription(task.description),
             subagent_type: task.subagentType,
+            task_id: task.taskId,
           });
         }
 
         case "task_progress": {
-          upsert(id, {
+          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.
@@ -129,27 +208,33 @@ export function createTaskTracker(): TaskTracker {
 
         case "task_updated": {
           const status = event.patch?.status;
-          upsert(id, status ? { status } : {});
+          if (status) patch(id, { status });
           return undefined;
         }
 
         case "task_notification": {
-          const task = upsert(id, {
+          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: task.description,
+            description: clipDescription(task.description),
+            task_id: task.taskId,
             tool_uses: task.toolUses,
             total_tokens: task.totalTokens,
             duration_ms: task.durationMs,
@@ -169,6 +254,14 @@ export function createTaskTracker(): TaskTracker {
         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;
+    },
   };
 }
 

package/src/types.ts

@@ -139,6 +139,14 @@ export interface ClaudeTaskEvent {
   /** 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;
@@ -152,6 +160,14 @@ export interface TaskSnapshot {
   /** 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;
@@ -160,6 +176,8 @@ export interface TaskSnapshot {
   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. */