@nredd/pi-subagents 0.0.0-stage → 0.22.0-nredd.5

package/src/nested-tools.ts

@@ -0,0 +1,448 @@
+import type { Model } from "@earendil-works/pi-ai";
+import {
+  type AgentSession,
+  defineTool,
+  type ExtensionAPI,
+  type ExtensionContext,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { abortable } from "./abortable.js";
+import {
+  buildAgentRegistry,
+  getAgentConfigIn,
+  getAvailableTypesIn,
+  resolveEnabledTypeIn,
+  resolveTypeIn,
+} from "./agent-types.js";
+import { loadCustomAgents } from "./custom-agents.js";
+import { isolationParam, resolveAgentInvocationConfig } from "./invocation-config.js";
+import { resolveModel } from "./model-resolver.js";
+import { checkModelScope } from "./model-scope.js";
+import {
+  createOutputFilePath,
+  getOutputTranscriptDefault,
+  streamToOutputFile,
+  writeInitialEntry,
+} from "./output-file.js";
+import { getForegroundOutcomeNote, getStatusNote, partialOutputSuffix } from "./status-note.js";
+import type {
+  AgentConfig,
+  AgentInvocation,
+  AgentRecord,
+  IsolationMode,
+  ThinkingLevel,
+} from "./types.js";
+import { addUsage } from "./usage.js";
+import { isWorktreeIsolationEnabled } from "./worktree.js";
+
+/**
+ * Hard ceiling on nesting for every branch: main session = 0, its subagents = 1,
+ * their children = 2. `0`/`1` disables nesting entirely. Set from
+ * `subagents.json` (`maxSubagentDepth`). Read when a subagent session is built,
+ * so a change applies to sessions started after it.
+ */
+let maxSubagentDepth = 2;
+
+export function getMaxSubagentDepth(): number { return maxSubagentDepth; }
+export function setMaxSubagentDepth(n: number): void { maxSubagentDepth = Math.max(0, Math.floor(n)); }
+
+const NESTED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"] as const;
+
+/**
+ * Why a subagent may not start background work. A detached child's completion
+ * is delivered as a follow-up to the session that spawned it, and a subagent
+ * session ends the moment it returns its answer, so the notice would go to a
+ * session that no longer exists and the work would be aborted with its owner.
+ */
+export const NESTED_BACKGROUND_ERROR =
+  "Background agents are not available inside a subagent: when you finish, this session ends and nothing is left to receive the result. "
+  + "Omit run_in_background; the call blocks and returns the child's result inline.";
+
+/** Same reasoning for workflow tools, which run in the background and notify on completion. */
+export const NESTED_WORKFLOW_ERROR =
+  "Workflows are not available inside a subagent: a workflow runs in the background and reports to the session that started it, "
+  + "and this session ends when you return your answer. Do the work directly, or call Agent in the foreground.";
+
+/**
+ * `NESTED_WORKFLOW_ERROR` for a child that was never given `Agent` (depth cap,
+ * isolation, `disallowed_tools`, or no `allowed_subagents`). Cause-neutral on purpose. Pointing it at a tool it does not have
+ * sends it hunting, and then shelling out to a CLI that escapes every limit.
+ */
+export const NESTED_WORKFLOW_NO_AGENT_ERROR =
+  "Workflows are not available inside a subagent: a workflow runs in the background and reports to the session that started it, "
+  + "and this session ends when you return your answer. Nested subagents are disabled for this session, so there is no Agent tool either. "
+  + "Do the work directly.";
+
+interface NestedSpawnOptions {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  isolation?: IsolationMode;
+  invocation?: AgentInvocation;
+  signal?: AbortSignal;
+  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
+  onSessionCreated?: (session: AgentSession) => void;
+  depth: number;
+  parentAgentId: string;
+  maxSubagentDepth: number;
+  configCwd?: string;
+  /** Trust decision for `configCwd`; always set together with it. */
+  configProjectTrusted?: boolean;
+  rootSessionId?: string;
+}
+
+export interface NestedAgentManager {
+  spawn(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: string,
+    prompt: string,
+    options: NestedSpawnOptions,
+  ): string;
+  /** Resolves once the spawned agent is running; rejects on a startup failure. */
+  awaitStartup(id: string): Promise<void>;
+  spawnAndWait(
+    pi: ExtensionAPI,
+    ctx: ExtensionContext,
+    type: string,
+    prompt: string,
+    options: Omit<NestedSpawnOptions, "isBackground">,
+    /** Fires synchronously after spawn, before the session exists — where the transcript is attached. */
+    onSpawned?: (id: string) => void,
+  ): Promise<{ id: string; record: AgentRecord }>;
+  getRecord(id: string): AgentRecord | undefined;
+  resume(id: string, prompt: string, signal?: AbortSignal, options?: { maxTurns?: number }): Promise<AgentRecord | undefined>;
+}
+
+export interface NestedToolContext {
+  manager: NestedAgentManager;
+  pi: ExtensionAPI;
+  parentAgentId: string;
+  depth: number;
+  maxSubagentDepth: number;
+  /** "all" = any enabled agent; string[] = only those types. Never empty. */
+  allowedSubagents: "all" | string[];
+  /** Root used for agent/config discovery; may differ from the agent's working directory. */
+  configCwd: string;
+  /**
+   * The spawning session's project-trust decision for `configCwd`, as the runner
+   * resolved it for the child's own settings. Gates project agent files in the
+   * registry built here; read from the session's state it would answer for the
+   * child's cwd, which is untrusted for a cross-directory spawn.
+   */
+  projectTrusted: boolean;
+}
+
+function textResult(text: string, isError = false) {
+  return { content: [{ type: "text" as const, text }], isError, details: {} };
+}
+
+function ownsRecord(record: AgentRecord | undefined, parentAgentId: string): record is AgentRecord {
+  return record?.parentAgentId === parentAgentId;
+}
+
+/**
+ * How the caller received this record, which decides the outcome wording.
+ *
+ *   - "inline": a foreground spawn or a resume. The full output is in this very
+ *     result and no agent id was handed back, so the note must say there is
+ *     nothing left to fetch — otherwise the parent invents an id, calls
+ *     `get_subagent_result`, and hits "not owned by this parent" (#174, the same
+ *     trap the top-level foreground path fell into).
+ *   - "fetched": `get_subagent_result` on a background child. The parent holds a
+ *     valid id and can poll again, so the background wording applies.
+ */
+type ResultPosition = "inline" | "fetched";
+
+function formatRecord(record: AgentRecord, position: ResultPosition): string {
+  if (record.status === "error") {
+    return `Agent failed: ${record.error ?? "unknown error"}${partialOutputSuffix(record)}`;
+  }
+  if (record.status === "queued" || record.status === "running") {
+    return `Agent ${record.id} is ${record.status}.`;
+  }
+  // A truncated run must not read as a finished one. The top-level path carries
+  // this in its result headline; a nested result has no headline, so the note
+  // leads — appended, it would look like part of the child's own output.
+  const text = record.result?.trim() || record.error?.trim() || "No output.";
+  const note = position === "inline"
+    ? getForegroundOutcomeNote(record.status)
+    : getStatusNote(record.status);
+  return note ? `Nested agent${note}.\n\n${text}` : text;
+}
+
+/** Build child-safe orchestration tools scoped to one parent agent instance. */
+export function createNestedSubagentTools(context: NestedToolContext): ToolDefinition[] {
+  // Agents resolve from a registry built for THIS branch's config root (under
+  // worktree isolation, the copy). Never via registerAgents — that is
+  // process-global state shared with the main session and every other agent.
+  const loadRegistry = () => buildAgentRegistry(loadCustomAgents(context.configCwd, false, { projectTrusted: context.projectTrusted }));
+  const allowedTypesIn = (registry: Map<string, AgentConfig>): Set<string> | undefined =>
+    context.allowedSubagents === "all"
+      ? undefined
+      : new Set(context.allowedSubagents.map(name => resolveTypeIn(registry, name) ?? name));
+  const availableIn = (registry: Map<string, AgentConfig>): string[] => {
+    const allowed = allowedTypesIn(registry);
+    return getAvailableTypesIn(registry).filter(name => allowed === undefined || allowed.has(name));
+  };
+
+  const agentTool = defineTool({
+    name: NESTED_TOOL_NAMES[0],
+    label: "Agent",
+    description:
+      "Launch a child-safe nested subagent for bounded delegated work. " +
+      "Only use agent types allowed by this parent agent; nesting is depth-limited.",
+    parameters: Type.Object({
+      prompt: Type.String({ description: "Self-contained task for the nested agent." }),
+      description: Type.String({ description: "Short 3-5 word task description." }),
+      subagent_type: Type.String({ description: `Allowed nested agent type. Available: ${availableIn(loadRegistry()).join(", ") || "none"}.` }),
+      model: Type.Optional(Type.String({ description: "Optional provider/model override." })),
+      thinking: Type.Optional(Type.String({ description: "Optional thinking level." })),
+      max_turns: Type.Optional(Type.Number({ minimum: 1 })),
+      run_in_background: Type.Optional(
+        Type.Boolean({
+          description: "Not supported inside a subagent: nested spawns always block and return the child's result inline. Passing true returns an error.",
+        }),
+      ),
+      resume: Type.Optional(Type.String({ description: "Resume a nested agent owned by this parent." })),
+      isolated: Type.Optional(Type.Boolean()),
+      inherit_context: Type.Optional(Type.Boolean()),
+      ...isolationParam(isWorktreeIsolationEnabled()),
+    }),
+    execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+      if (params.run_in_background === true) return textResult(NESTED_BACKGROUND_ERROR, true);
+      if (params.resume) {
+        const existing = context.manager.getRecord(params.resume);
+        if (!ownsRecord(existing, context.parentAgentId)) {
+          return textResult(`Nested agent not found or not owned by this parent: "${params.resume}".`, true);
+        }
+        // Frontmatter authoritative, as on the spawn path; the manager falls
+        // back to the limit the child was spawned with, then the default.
+        const resumed = await context.manager.resume(params.resume, params.prompt, signal, {
+          maxTurns: getAgentConfigIn(loadRegistry(), existing.type)?.maxTurns ?? params.max_turns,
+        });
+        return resumed
+          ? textResult(formatRecord(resumed, "inline"), resumed.status === "error")
+          : textResult(`Failed to resume nested agent "${params.resume}".`, true);
+      }
+
+      if (context.depth >= context.maxSubagentDepth) {
+        return textResult(
+          `Nested subagent call blocked (depth=${context.depth}, max=${context.maxSubagentDepth}). Complete the task directly.`,
+          true,
+        );
+      }
+
+      // Reloaded per call so new agent files are picked up without a restart.
+      const registry = loadRegistry();
+      const rawType = params.subagent_type;
+      // Strict resolve, never the fallback policy: a project-level
+      // `fallbackSubagent` must not hand a nested caller an agent its allowlist
+      // never named. The list stays allowlist-filtered so a typo can't enumerate
+      // agents this parent may not reach.
+      const resolvedType = resolveEnabledTypeIn(registry, rawType);
+      if (resolvedType === undefined) {
+        return textResult(
+          `Unknown or disabled nested agent type: "${rawType}". Allowed: ${availableIn(registry).join(", ") || "none"}.`,
+          true,
+        );
+      }
+      const allowed = allowedTypesIn(registry);
+      if (allowed !== undefined && !allowed.has(resolvedType)) {
+        return textResult(
+          `Nested agent type "${resolvedType}" is not allowed for this parent. Allowed: ${[...allowed].join(", ")}.`,
+          true,
+        );
+      }
+
+      const config = getAgentConfigIn(registry, resolvedType);
+      // Foreground regardless of `backgroundByDefault` — see the reasoning on
+      // ResolveOptions. An explicit `true` here still opts in.
+      const invocation = resolveAgentInvocationConfig(config, params, {
+        agentType: resolvedType,
+        worktreeAllowed: isWorktreeIsolationEnabled(),
+        defaultRunInBackground: false,
+      });
+      let model = ctx.model;
+      if (invocation.modelInput) {
+        const resolvedModel = resolveModel(invocation.modelInput, ctx.modelRegistry);
+        if (typeof resolvedModel === "string") {
+          if (invocation.modelFromParams) return textResult(resolvedModel, true);
+        } else {
+          model = resolvedModel;
+        }
+      }
+
+      // Same scopeModels policy as the top-level Agent tool — a nested spawn
+      // must not escape the allowlist. A "warn" verdict proceeds silently:
+      // child sessions have no UI surface to toast to.
+      const scopeVerdict = checkModelScope({
+        model,
+        cwd: context.configCwd,
+        modelRegistry: ctx.modelRegistry,
+        callerSupplied: invocation.modelFromParams,
+        agentLabel: config?.displayName ?? resolvedType,
+        modelInput: invocation.modelInput,
+      });
+      if (scopeVerdict.kind === "error") return textResult(scopeVerdict.message, true);
+
+      // The whole branch shares the root session's transcript directory; read it
+      // off the owning parent rather than this child session's own id.
+      const rootSessionId = context.manager.getRecord(context.parentAgentId)?.rootSessionId;
+      const childDepth = context.depth + 1;
+      const options: NestedSpawnOptions = {
+        description: params.description,
+        model,
+        maxTurns: invocation.maxTurns,
+        isolated: invocation.isolated,
+        inheritContext: invocation.inheritContext,
+        thinkingLevel: invocation.thinking,
+        isolation: invocation.isolation,
+        invocation: {
+          thinking: invocation.thinking,
+          maxTurns: invocation.maxTurns,
+          isolated: invocation.isolated,
+          inheritContext: invocation.inheritContext,
+          isolation: invocation.isolation,
+        },
+        // Nested children are hidden from every reporting surface, so their spend
+        // would otherwise be unattributable. Fold it into every ancestor's record:
+        // the top-level one appears in lifecycle events, completion notifications,
+        // and `/agents`, and those all read `lifetimeUsage`. The whole chain is
+        // walked, not just the immediate parent — a spawn callback only fires for
+        // that child's OWN turns, so stopping at one level would hide a
+        // great-grandchild from the only record anyone can see. (The live
+        // widget/fleet counters read their own per-agent activity tracker, which
+        // still sees only the top-level agent's own turns.)
+        onAssistantUsage: (usage) => {
+          for (let id: string | undefined = context.parentAgentId; id !== undefined; ) {
+            const ancestor = context.manager.getRecord(id);
+            if (!ancestor) break;
+            addUsage(ancestor.lifetimeUsage, usage);
+            id = ancestor.parentAgentId;
+          }
+        },
+        depth: childDepth,
+        parentAgentId: context.parentAgentId,
+        maxSubagentDepth: context.maxSubagentDepth,
+        configCwd: context.configCwd,
+        configProjectTrusted: context.projectTrusted,
+        rootSessionId,
+      };
+
+      // Transcript wiring, same gate as the top-level path: the child's
+      // `output_transcript` frontmatter wins, else the project default. Without
+      // it a nested run leaves no artifact but the string it returned — the
+      // parent's own transcript records the call and the answer, never the tool
+      // calls in between, which is exactly what a misbehaving child needs to
+      // explain itself. Filed under the ROOT session and this branch's config
+      // root, so a nested transcript lands in the same `tasks/` directory as its
+      // ancestors' rather than in a directory of its own.
+      const transcriptSessionId =
+        rootSessionId !== undefined && (config?.outputTranscript ?? getOutputTranscriptDefault())
+          ? rootSessionId
+          : undefined;
+      let childId: string | undefined;
+      const attachTranscript = (id: string): void => {
+        childId = id;
+        if (transcriptSessionId === undefined) return;
+        const rec = context.manager.getRecord(id);
+        if (!rec) return;
+        rec.outputFile = createOutputFilePath(context.configCwd, id, transcriptSessionId);
+        writeInitialEntry(rec.outputFile, id, params.prompt, ctx.cwd);
+      };
+      options.onSessionCreated = (session) => {
+        const rec = childId === undefined ? undefined : context.manager.getRecord(childId);
+        if (rec?.outputFile && childId !== undefined) {
+          rec.outputCleanup = streamToOutputFile(session, rec.outputFile, childId, ctx.cwd);
+        }
+      };
+
+      // `ctx` is forwarded to the manager unmodified, never captured at tool-build
+      // time: each AgentSession builds its own ExtensionRunner from that session's
+      // cwd/sessionManager/modelRegistry, so this is the CHILD's context. Capturing
+      // one earlier would silently give a grandchild the wrong worktree base, the
+      // wrong conversation under inherit_context, and the wrong inherited model.
+      //
+      // spawn() throws on strict worktree-isolation failure and cwd validation —
+      // report it as a tool error, like the top-level Agent tool does, instead of
+      // letting it escape into the child's turn.
+      try {
+        const { record } = await context.manager.spawnAndWait(
+          context.pi,
+          ctx,
+          resolvedType,
+          params.prompt,
+          { ...options, signal },
+          attachTranscript,
+        );
+        return textResult(formatRecord(record, "inline"), record.status === "error");
+      } catch (err) {
+        return textResult(err instanceof Error ? err.message : String(err), true);
+      }
+    },
+  });
+
+  const resultTool = defineTool({
+    name: NESTED_TOOL_NAMES[1],
+    label: "Get Nested Agent Result",
+    description: "Check or wait for a background nested agent owned by this parent.",
+    parameters: Type.Object({
+      agent_id: Type.String(),
+      wait: Type.Optional(Type.Boolean()),
+    }),
+    execute: async (_toolCallId, params, signal) => {
+      const record = context.manager.getRecord(params.agent_id);
+      if (!ownsRecord(record, context.parentAgentId)) {
+        return textResult(`Nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+      }
+      // Wait for completion if requested. Cancellation (e.g. the parent's tool
+      // call is aborted) stops only this wait; the nested child keeps running and
+      // stays unconsumed. Queued records have no promise until the manager starts
+      // them, so poll — abortably — until they leave the queue, then await.
+      if (params.wait && (record.status === "queued" || record.status === "running")) {
+        while (record.status === "queued") {
+          await abortable(new Promise<void>(resolve => setTimeout(resolve, 250)), signal);
+        }
+        if (record.promise) await abortable(record.promise, signal);
+      }
+      return textResult(formatRecord(record, "fetched"), record.status === "error");
+    },
+  });
+
+  const steerTool = defineTool({
+    name: NESTED_TOOL_NAMES[2],
+    label: "Steer Nested Agent",
+    description: "Send guidance to a running nested agent owned by this parent.",
+    parameters: Type.Object({
+      agent_id: Type.String(),
+      message: Type.String(),
+    }),
+    execute: async (_toolCallId, params) => {
+      const record = context.manager.getRecord(params.agent_id);
+      if (!ownsRecord(record, context.parentAgentId) || record.status !== "running") {
+        return textResult(`Running nested agent not found or not owned by this parent: "${params.agent_id}".`, true);
+      }
+      // Session not ready yet — queue the steer. The manager flushes pending
+      // steers when the session is created (same contract as the top-level tool).
+      if (!record.session) {
+        if (!record.pendingSteers) record.pendingSteers = [];
+        record.pendingSteers.push(params.message);
+        return textResult(`Steering message queued for nested agent ${params.agent_id}.`);
+      }
+      try {
+        await record.session.steer(params.message);
+      } catch (err) {
+        return textResult(`Failed to steer nested agent: ${err instanceof Error ? err.message : String(err)}`, true);
+      }
+      return textResult(`Steering message sent to nested agent ${params.agent_id}.`);
+    },
+  });
+
+  return [agentTool, resultTool, steerTool];
+}

package/src/output-file.ts

@@ -0,0 +1,164 @@
+/**
+ * output-file.ts — Streaming JSONL output file for agent transcripts.
+ *
+ * Creates a per-agent output file that streams conversation turns as JSONL,
+ * matching Claude Code's task output file format.
+ */
+
+import { appendFileSync, chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AgentSession, AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Project/global default for writing a subagent's `.output` transcript; a custom
+ * agent's `output_transcript` overrides it per agent.
+ *
+ * State lives here rather than in an index.ts closure because both spawn paths
+ * need it — the top-level Agent tool and the nested delegation tools. Same
+ * reason `scopeModels` lives in model-scope.ts: a setting only one path can read
+ * is a setting the other path silently ignores.
+ */
+let outputTranscriptDefault = true;
+
+export function getOutputTranscriptDefault(): boolean { return outputTranscriptDefault; }
+export function setOutputTranscriptDefault(b: boolean): void { outputTranscriptDefault = b; }
+
+/**
+ * Encode a cwd path as a filesystem-safe directory name. Handles:
+ *   - POSIX:   "/home/user/project"        → "home-user-project"
+ *   - Windows: "C:\Users\foo\project"      → "Users-foo-project"
+ *   - UNC:     "\\\\server\\share\\project"  → "server-share-project"
+ */
+export function encodeCwd(cwd: string): string {
+  return cwd
+    .replace(/[/\\]/g, "-")        // both separators → dash
+    .replace(/^[A-Za-z]:-/, "")    // strip Windows drive prefix ("C:-")
+    .replace(/^-+/, "");           // strip leading dashes (POSIX root, UNC)
+}
+
+/**
+ * The per-session scratch directory, created if missing.
+ * Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks
+ *
+ * Shared with the workflow tool, which persists each invocation's script here so
+ * iterating on one is edit-file-then-rerun — the same convention, one directory.
+ */
+export function sessionTaskDir(cwd: string, sessionId: string): string {
+  const encoded = encodeCwd(cwd);
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  // chmod is a no-op on Windows and throws on some Windows filesystems.
+  // On Unix we still want to enforce 0o700 past umask, so only swallow on Windows.
+  try {
+    chmodSync(root, 0o700);
+  } catch (err) {
+    if (process.platform !== "win32") throw err;
+  }
+  const dir = join(root, encoded, sessionId, "tasks");
+  mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+/** Create the output file path, ensuring the directory exists. */
+export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
+  return join(sessionTaskDir(cwd, sessionId), `${agentId}.output`);
+}
+
+/**
+ * Ensure a transcript file exists without disturbing what is already in it.
+ *
+ * A resume reuses the agent's existing transcript (same deterministic path), so
+ * it must never call `writeInitialEntry` — that truncates, discarding turns the
+ * completion notification still points the user at, and any history the session
+ * has since compacted away is gone for good. Appending nothing creates the file
+ * when this is the agent's first transcript and is a no-op when it is not.
+ */
+export function ensureOutputFile(path: string): void {
+  try {
+    appendFileSync(path, "", "utf-8");
+  } catch { /* ignore — streaming writes are best-effort too */ }
+}
+
+/** Write the initial user prompt entry. */
+export function writeInitialEntry(path: string, agentId: string, prompt: string, cwd: string): void {
+  const entry = {
+    isSidechain: true,
+    agentId,
+    type: "user",
+    message: { role: "user", content: prompt },
+    timestamp: new Date().toISOString(),
+    cwd,
+  };
+  writeFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+}
+
+/**
+ * Subscribe to session events and flush new messages to the output file on each turn_end.
+ * Returns a cleanup function that does a final flush and unsubscribes.
+ */
+export function streamToOutputFile(
+  session: AgentSession,
+  path: string,
+  agentId: string,
+  cwd: string,
+  startIndex?: number,
+): () => void {
+  // Index of the first message this stream is responsible for. A resume hands
+  // in the session's length as of just before the run: the session already
+  // holds every prior turn, and re-emitting those would duplicate history that
+  // is already in the file. A spawn has already written its prompt as the
+  // initial entry, so it starts after the first user message — found on the
+  // first flush, because pi puts a system message ahead of it and adds both
+  // only once the prompt runs.
+  let writtenCount = startIndex;
+
+  const flush = () => {
+    const messages = session.messages;
+    if (writtenCount === undefined) {
+      const prompt = messages.findIndex((m) => m.role === "user");
+      if (prompt === -1) return;
+      writtenCount = prompt + 1;
+    }
+    while (writtenCount < messages.length) {
+      const msg = messages[writtenCount++];
+      // Pi's prompt and tool-loadout records; a Claude Code transcript has no
+      // such entry.
+      if (msg.role === "system") continue;
+      const entry = {
+        isSidechain: true,
+        agentId,
+        type: msg.role === "assistant" ? "assistant" : msg.role === "user" ? "user" : "toolResult",
+        message: msg,
+        timestamp: new Date().toISOString(),
+        cwd,
+      };
+      try {
+        appendFileSync(path, JSON.stringify(entry) + "\n", "utf-8");
+      } catch { /* ignore write errors */ }
+    }
+  };
+
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "turn_end") flush();
+    // Compaction replaces session.messages with a shorter, summarized array,
+    // leaving writtenCount past the new end — without re-anchoring, the flush
+    // loop would never match again and streaming would halt for good (#145).
+    // Flush before it runs so any not-yet-flushed tail still reaches the file,
+    // then re-anchor to the rebuilt array once it lands. The re-anchor is
+    // deferred a microtask because on the overflow-retry path pi trims the
+    // trailing error assistant message AFTER emitting compaction_end —
+    // anchoring synchronously would sit one past the trimmed array and skip
+    // the first post-compaction message. Aborted/failed compactions leave
+    // session.messages untouched, so only successful ones re-anchor.
+    if (event.type === "compaction_start") flush();
+    if (event.type === "compaction_end" && !event.aborted && event.result) {
+      queueMicrotask(() => { writtenCount = session.messages.length; });
+    }
+  });
+
+  return () => {
+    flush();
+    unsubscribe();
+  };
+}