@saccolabs/pi-claude-cli 0.4.13 → 0.4.15

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
@@ -123,9 +126,14 @@ misleading, `pi` mode rewrites pi's tool sections — which name pi's tools
 restyles its prompt so the `Available tools:` / `Guidelines:` anchors are
 missing, the prompt passes through untouched rather than being mangled.
 
-Only the session-creating turn sends a system prompt — the CLI keeps it for
-the life of the session — so a change takes effect on the next new session,
-not the current one.
+The system prompt goes on **every** spawn, not just the session-creating one:
+the CLI does not keep `--system-prompt` across `--resume`, and a resumed
+session without it silently reverts to Claude Code's default prompt from turn
+2 onwards. Because an identical prefix is what keeps the prompt cache warm,
+the prompt a session was created with is stored in the sidecar
+(`~/.pi/agent/pi-claude-cli/sysprompt/<cli-session-id>.txt`) and replayed
+verbatim rather than rebuilt. A change to the mode therefore takes effect on
+the next new session, not the current one.
 
 ## License
 

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.15",
   "description": "Pi coding agent extension that routes LLM calls through the Claude Code CLI",
   "main": "index.ts",
   "keywords": [

package/src/process-manager.ts

@@ -33,6 +33,15 @@ function isHermetic(): boolean {
   return value === "1" || value === "true" || value === "yes";
 }
 
+/**
+ * Where a spawn's system prompt is staged. Scoped to the CLI session so
+ * concurrent turns in one pi process cannot clobber each other.
+ */
+function systemPromptFilePath(sessionKey?: string): string {
+  const suffix = sessionKey ? `-${sessionKey}` : "";
+  return join(tmpdir(), `pi-claude-cli-sysprompt-${process.pid}${suffix}.txt`);
+}
+
 export function spawnClaude(
   modelId: string,
   systemPrompt?: string,
@@ -58,6 +67,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.
@@ -81,9 +100,13 @@ export function spawnClaude(
   if (systemPrompt) {
     // Write system prompt to a temp file to avoid ENAMETOOLONG on Windows.
     // Both flags accept a file path or literal text.
-    const tmpFile = join(
-      tmpdir(),
-      `pi-claude-cli-sysprompt-${process.pid}.txt`,
+    //
+    // Keyed by CLI session, not just pid: the prompt goes on every spawn
+    // (see provider.ts), and pi can run two turns of one process at once —
+    // its own sub-agents do. A shared per-pid path would let one turn
+    // overwrite the prompt another turn is about to read.
+    const tmpFile = systemPromptFilePath(
+      options?.resumeSessionId ?? options?.newSessionId,
     );
     writeFileSync(tmpFile, systemPrompt, "utf-8");
     // `pi` mode replaces Claude Code's prompt outright; `claude` mode layers
@@ -122,10 +145,13 @@ export function spawnClaude(
 /**
  * Clean up the temp system prompt file created by spawnClaude.
  * Safe to call multiple times or when no file exists.
+ *
+ * Pass the same CLI session key the spawn used; omitting it cleans the
+ * unscoped path, which is all a spawn without a session id creates.
  */
-export function cleanupSystemPromptFile(): void {
+export function cleanupSystemPromptFile(sessionKey?: string): void {
   try {
-    unlinkSync(join(tmpdir(), `pi-claude-cli-sysprompt-${process.pid}.txt`));
+    unlinkSync(systemPromptFilePath(sessionKey));
   } catch {
     // File doesn't exist or already deleted — ignore
   }

package/src/provider.ts

@@ -49,6 +49,9 @@ import {
   getCliSession,
   setCliSession,
   clearCliSession,
+  getSystemPrompt,
+  setSystemPrompt,
+  clearSystemPrompt,
 } from "./session-map.js";
 import { randomUUID } from "node:crypto";
 /** Inactivity timeout: kill subprocess if no stdout for 180 seconds (3 minutes). */
@@ -62,6 +65,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;
@@ -135,6 +181,9 @@ export function streamViaCli(
     let selfInterrupted = false;
     // Set on pi-initiated abort so the turn ends quietly, not as an error.
     let aborted = false;
+    // CLI session this attempt staged its system prompt under, so the finally
+    // below can remove the right file. Set once the ids are resolved.
+    let promptFileKey: string | undefined;
 
     try {
       const cwd = options?.cwd ?? process.cwd();
@@ -155,6 +204,7 @@ export function streamViaCli(
       // Fresh sessions get a provider-minted id, never pi's: the CLI refuses
       // a --session-id it has already seen, and forks reuse pi ids.
       const newCliId = resumeSessionId ? undefined : randomUUID();
+      promptFileKey = resumeSessionId ?? newCliId;
 
       // Resume sends only the delta since the last assistant turn (new user
       // text, handoff tool results). Create/import sends the full history.
@@ -162,14 +212,19 @@ export function streamViaCli(
         ? buildResumePrompt(context)
         : buildPrompt(context);
       // Resolved per spawn rather than once at module load so a host can flip
-      // the setting between sessions without restarting pi. Only the
-      // session-creating turn carries a system prompt — the CLI keeps it for
-      // the life of the session — so switching mid-session takes effect on
-      // the next new session, not this one.
+      // the setting between sessions without restarting pi. Switching
+      // mid-session takes effect on the next NEW session, not this one: a
+      // resumed session replays the prompt it was created with (below).
       const systemPromptMode = resolveSystemPromptMode();
-      const systemPrompt = resumeSessionId
-        ? undefined
-        : buildSystemPrompt(context, cwd, systemPromptMode);
+      // The CLI does not keep --system-prompt across --resume, so it goes on
+      // EVERY spawn. On resume, replay the stored bytes rather than rebuilding
+      // them: an identical prompt keeps the cached prefix, a drifted one
+      // re-bills the whole transcript as cache write. See src/session-map.ts.
+      const storedSystemPrompt = resumeSessionId
+        ? getSystemPrompt(resumeSessionId)
+        : undefined;
+      const systemPrompt =
+        storedSystemPrompt ?? buildSystemPrompt(context, cwd, systemPromptMode);
 
       // Compute effort level from reasoning options
       const effort = mapThinkingEffort(
@@ -191,6 +246,9 @@ export function streamViaCli(
       // Record the mapping as soon as the session exists on disk. On a turn
       // that later errors, the mapping is cleared so the next turn reimports.
       if (piSessionId && newCliId) setCliSession(piSessionId, newCliId);
+      // Store the created prompt so every later turn re-passes these exact
+      // bytes. Without it, resume falls back to a rebuild that can drift.
+      if (newCliId && systemPrompt) setSystemPrompt(newCliId, systemPrompt);
       const getStderr = captureStderr(proc);
 
       // Register in global process registry for teardown cleanup
@@ -240,9 +298,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 +379,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();
@@ -409,12 +500,17 @@ export function streamViaCli(
               // Recoverable: the sidecar pointed at a CLI session that no
               // longer exists. Clear it; the driver reimports once.
               if (piSessionId) clearCliSession(piSessionId);
+              clearSystemPrompt(resumeSessionId);
               resumeMiss = true;
               broken = true;
             } else {
               // A failed turn may leave the CLI session ending on a user
               // entry; resuming that would splice filler. Reimport next turn.
               if (piSessionId) clearCliSession(piSessionId);
+              // This CLI session will never be resumed, so its stored prompt
+              // is dead weight.
+              const deadCliId = resumeSessionId ?? newCliId;
+              if (deadCliId) clearSystemPrompt(deadCliId);
               endStreamWithError(errMsg);
             }
           }
@@ -424,8 +520,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();
         }
@@ -474,6 +601,9 @@ export function streamViaCli(
       if (options?.signal && abortHandler) {
         options.signal.removeEventListener("abort", abortHandler);
       }
+      // Staged prompt file is per CLI session, so it is removed here where
+      // the ids are in scope — a resume-miss retry stages a second one.
+      cleanupSystemPromptFile(promptFileKey);
     }
   }
 
@@ -494,7 +624,16 @@ export function streamViaCli(
       } as any);
       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/session-map.ts

@@ -10,7 +10,7 @@
  * given pi session at a time.
  */
 
-import { readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { readFileSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
 
@@ -65,3 +65,61 @@ export function clearCliSession(piSessionId: string): void {
     writeMap(map);
   }
 }
+
+// ---------------------------------------------------------------------------
+// Per-CLI-session system prompt.
+//
+// The CLI does NOT persist --system-prompt across --resume: a resumed session
+// runs under Claude Code's DEFAULT prompt unless the flag is passed again.
+// That is both a correctness bug (pi's instructions vanish from turn 2 on) and
+// the single largest token cost in a pi session, because swapping the prompt
+// invalidates the cached prefix and re-bills the whole transcript as cache
+// WRITE. Verified 2026-08-29 with a shimmed `claude`: re-passing the same
+// prompt on resume cost 112 tokens where dropping it cost 9,761.
+//
+// Re-passing is only cheap when the bytes are IDENTICAL, and rebuilding is not
+// byte-stable — buildSystemPrompt() appends a tool-results paragraph the
+// moment history contains a toolResult, and pi may restyle its own prompt
+// between turns. So the prompt the session was CREATED with is stored here and
+// replayed verbatim for the life of that CLI session.
+//
+// One file per session rather than a field in session-map.json: prompts run to
+// tens of kilobytes, and the map is read on every spawn.
+// ---------------------------------------------------------------------------
+
+function systemPromptPath(cliSessionId: string): string {
+  return join(stateDir(), "sysprompt", `${cliSessionId}.txt`);
+}
+
+/**
+ * The system prompt a CLI session was created with, if it was recorded.
+ *
+ * Undefined for sessions created before this was stored, which correctly falls
+ * back to rebuilding: less cache-stable than a verbatim replay, still far
+ * better than sending no prompt at all.
+ */
+export function getSystemPrompt(cliSessionId: string): string | undefined {
+  try {
+    return readFileSync(systemPromptPath(cliSessionId), "utf-8");
+  } catch {
+    return undefined;
+  }
+}
+
+export function setSystemPrompt(cliSessionId: string, prompt: string): void {
+  try {
+    mkdirSync(join(stateDir(), "sysprompt"), { recursive: true });
+    writeFileSync(systemPromptPath(cliSessionId), prompt, "utf-8");
+  } catch {
+    // Best effort: an unwritable sidecar degrades to rebuilding the prompt.
+  }
+}
+
+/** Drop a stored prompt. Paired with clearCliSession on a resume miss. */
+export function clearSystemPrompt(cliSessionId: string): void {
+  try {
+    rmSync(systemPromptPath(cliSessionId), { force: true });
+  } catch {
+    // Already gone, or unwritable — both are fine.
+  }
+}

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. */