@tintinweb/pi-subagents 0.4.6 → 0.4.9

package/CHANGELOG.md

@@ -5,6 +5,39 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.4.9] - 2026-03-18
+
+### Fixed
+- **Conversation viewer crash in narrow terminals** ([#7](https://github.com/tintinweb/pi-subagents/issues/7)) — `buildContentLines()` in the live conversation viewer could return lines wider than the terminal when `wrapTextWithAnsi()` misjudged visible width on ANSI-heavy input (e.g. tool output with embedded escape codes, long URLs, wide tables). All content lines are now clamped with `truncateToWidth()` before returning. Same class of bug as the widget fix in v0.2.7, different component.
+
+### Added
+- **Conversation viewer width-safety tests** — 17 tests covering `render()` and `buildContentLines()` across varied content (plain text, ANSI codes, unicode, tables, long URLs, narrow terminals). Includes mock-based regression tests that simulate upstream `wrapTextWithAnsi` returning overwidth lines, ensuring the safety net catches them.
+
+## [0.4.8] - 2026-03-18
+
+### Added
+- **Cross-extension RPC** — other pi extensions can spawn subagents via `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`). Emits `subagents:ready` on load.
+- **Session persistence for agent records** — completed agent records are persisted via `pi.appendEntry("subagents:record", ...)` for cross-extension history reconstruction.
+
+### Fixed
+- **Background agent notification race condition** — `pi.sendMessage()` is fire-and-forget, so completion notifications sent eagerly from `onComplete` could not be retracted when `get_subagent_result` was called in the same turn. Notifications are now held behind a 200ms cancellable timer; `get_subagent_result` cancels the pending timer before it fires, eliminating duplicate notifications. Group notifications also re-check `resultConsumed` at send time so consumed agents are filtered out.
+
+## [0.4.7] - 2026-03-17
+
+### Added
+- **Custom notification renderer** — background agent completion notifications now render as styled, themed boxes instead of raw XML. Uses `pi.registerMessageRenderer()` with the `"subagent-notification"` custom message type. The LLM continues to receive `<task-notification>` XML via `content`; only the user-facing display changes.
+- **Group notification rendering** — group completions render each agent as its own styled block (icon, description, stats, result preview) instead of showing only the first agent.
+- **Output file streaming for background agents** — background agents now get the same output file transcript as foreground agents, with `onSessionCreated` wiring and proper cleanup on completion/error.
+- `NotificationDetails` type in `types.ts` — structured details for the notification renderer, with optional `others` array for group notifications.
+- `buildNotificationDetails()` helper — extracts renderer-facing details from an `AgentRecord`.
+
+### Changed
+- **Notification delivery** — `sendIndividualNudge` and group notification now use `pi.sendMessage()` (custom message) instead of `pi.sendUserMessage()` (plain text), enabling renderer-controlled display.
+- **Steered status rendering** — steered agents show "completed (steered)" in the notification box instead of plain "completed".
+
+### Fixed
+- **Output file cleanup on completion** — `agent-manager.ts` now calls `record.outputCleanup()` in both the success and error paths of agent completion, ensuring the streaming subscription is flushed and released.
+
 ## [0.4.6] - 2026-03-16
 
 ### Fixed
@@ -274,6 +307,9 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.4.9]: https://github.com/tintinweb/pi-subagents/compare/v0.4.8...v0.4.9
+[0.4.8]: https://github.com/tintinweb/pi-subagents/compare/v0.4.7...v0.4.8
+[0.4.7]: https://github.com/tintinweb/pi-subagents/compare/v0.4.6...v0.4.7
 [0.4.6]: https://github.com/tintinweb/pi-subagents/compare/v0.4.5...v0.4.6
 [0.4.5]: https://github.com/tintinweb/pi-subagents/compare/v0.4.4...v0.4.5
 [0.4.4]: https://github.com/tintinweb/pi-subagents/compare/v0.4.3...v0.4.4

package/README.md

@@ -27,7 +27,9 @@ https://github.com/user-attachments/assets/8685261b-9338-4fea-8dfe-1c590d5df543
 - **Git worktree isolation** — run agents in isolated repo copies; changes auto-committed to branches on completion
 - **Skill preloading** — inject named skill files from `.pi/skills/` into agent system prompts
 - **Tool denylist** — block specific tools via `disallowed_tools` frontmatter
+- **Styled completion notifications** — background agent results render as themed, compact notification boxes (icon, stats, result preview) instead of raw XML. Expandable to show full output. Group completions render each agent individually
 - **Event bus** — lifecycle events (`subagents:created`, `started`, `completed`, `failed`, `steered`) emitted via `pi.events`, enabling other extensions to react to sub-agent activity
+- **Cross-extension RPC** — other pi extensions can spawn subagents via the `pi.events` event bus (`subagents:rpc:ping`, `subagents:rpc:spawn`). Emits `subagents:ready` on load
 
 ## Install
 
@@ -82,6 +84,17 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
+Background agent completion notifications render as styled boxes:
+
+```
+✓ Find auth files completed
+  3 tool uses · 12.4k token · 4.1s
+  ⎿  Found 5 files related to authentication...
+  transcript: .pi/output/agent-abc123.jsonl
+```
+
+Group completions render each agent as a separate block. The LLM receives structured `<task-notification>` XML for parsing, while the user sees the themed visual.
+
 ## Default Agent Types
 
 | Type | Tools | Model | Prompt Mode | Description |
@@ -272,6 +285,58 @@ Agent lifecycle events are emitted via `pi.events.emit()` so other extensions ca
 | `subagents:completed` | Agent finished successfully | `id`, `type`, `durationMs`, `tokens`, `toolUses`, `result` |
 | `subagents:failed` | Agent errored, stopped, or aborted | same as completed + `error`, `status` |
 | `subagents:steered` | Steering message sent | `id`, `message` |
+| `subagents:ready` | Extension loaded and RPC handlers registered | — |
+
+## Cross-Extension RPC
+
+Other pi extensions can spawn subagents programmatically via the `pi.events` event bus, without importing this package directly.
+
+### Discovery
+
+Listen for `subagents:ready` to know when RPC handlers are available:
+
+```typescript
+pi.events.on("subagents:ready", () => {
+  // RPC handlers are registered — safe to call ping/spawn
+});
+```
+
+### Ping
+
+Check if the subagents extension is loaded:
+
+```typescript
+const requestId = crypto.randomUUID();
+const unsub = pi.events.on(`subagents:rpc:ping:reply:${requestId}`, () => {
+  unsub();
+  // Extension is alive
+});
+pi.events.emit("subagents:rpc:ping", { requestId });
+```
+
+### Spawn
+
+Spawn a subagent and receive its ID:
+
+```typescript
+const requestId = crypto.randomUUID();
+const unsub = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (reply) => {
+  unsub();
+  if (reply.error) {
+    console.error("Spawn failed:", reply.error);
+  } else {
+    console.log("Agent ID:", reply.id);
+  }
+});
+pi.events.emit("subagents:rpc:spawn", {
+  requestId,
+  type: "general-purpose",
+  prompt: "Do something useful",
+  options: { description: "My task", run_in_background: true },
+});
+```
+
+Reply channels are scoped per `requestId`, so concurrent requests don't interfere.
 
 ## Persistent Agent Memory
 
@@ -342,10 +407,12 @@ src/
   agent-types.ts      # Unified agent registry (defaults + user), tool factories
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
+  cross-extension-rpc.ts # RPC handlers for cross-extension spawn/ping via pi.events
   group-join.ts       # Group join manager: batched completion notifications with timeout
   custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
   memory.ts           # Persistent agent memory (resolve, read, build prompt blocks)
   skill-loader.ts     # Preload skill files from .pi/skills/
+  output-file.ts      # Streaming output file transcripts for agent sessions
   worktree.ts         # Git worktree isolation (create, cleanup, prune)
   prompts.ts          # Config-driven system prompt builder
   context.ts          # Parent conversation context for inherit_context

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.4.6",
+  "version": "0.4.9",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -21,9 +21,9 @@
     "autonomous"
   ],
   "dependencies": {
-    "@mariozechner/pi-ai": "^0.57.1",
-    "@mariozechner/pi-coding-agent": "^0.57.1",
-    "@mariozechner/pi-tui": "^0.57.1",
+    "@mariozechner/pi-ai": "^0.60.0",
+    "@mariozechner/pi-coding-agent": "^0.60.0",
+    "@mariozechner/pi-tui": "^0.60.0",
     "@sinclair/typebox": "latest"
   },
   "scripts": {

package/src/agent-manager.ts

@@ -171,6 +171,12 @@ export class AgentManager {
         record.session = session;
         record.completedAt ??= Date.now();
 
+        // Final flush of streaming output file
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
         // Clean up worktree if used
         if (record.worktree) {
           const wtResult = cleanupWorktree(ctx.cwd, record.worktree, options.description);
@@ -196,6 +202,12 @@ export class AgentManager {
         record.error = err instanceof Error ? err.message : String(err);
         record.completedAt ??= Date.now();
 
+        // Final flush of streaming output file on error
+        if (record.outputCleanup) {
+          try { record.outputCleanup(); } catch { /* ignore */ }
+          record.outputCleanup = undefined;
+        }
+
         // Best-effort worktree cleanup on error
         if (record.worktree) {
           try {

package/src/cross-extension-rpc.ts

@@ -0,0 +1,61 @@
+/**
+ * Cross-extension RPC handlers for the subagents extension.
+ *
+ * Exposes ping and spawn RPCs over the pi.events event bus,
+ * using per-request scoped reply channels.
+ */
+
+/** Minimal event bus interface needed by the RPC handlers. */
+export interface EventBus {
+  on(event: string, handler: (data: unknown) => void): () => void;
+  emit(event: string, data: unknown): void;
+}
+
+/** Minimal AgentManager interface needed by the spawn RPC. */
+export interface SpawnCapable {
+  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: any): string;
+}
+
+export interface RpcDeps {
+  events: EventBus;
+  pi: unknown;                    // passed through to manager.spawn
+  getCtx: () => unknown | undefined;  // returns current ExtensionContext
+  manager: SpawnCapable;
+}
+
+export interface RpcHandle {
+  unsubPing: () => void;
+  unsubSpawn: () => void;
+}
+
+/**
+ * Register ping and spawn RPC handlers on the event bus.
+ * Returns unsub functions for cleanup.
+ */
+export function registerRpcHandlers(deps: RpcDeps): RpcHandle {
+  const { events, pi, getCtx, manager } = deps;
+
+  const unsubPing = events.on("subagents:rpc:ping", (raw: unknown) => {
+    const { requestId } = raw as { requestId: string };
+    events.emit(`subagents:rpc:ping:reply:${requestId}`, {});
+  });
+
+  const unsubSpawn = events.on("subagents:rpc:spawn", async (raw: unknown) => {
+    const { requestId, type, prompt, options } = raw as {
+      requestId: string; type: string; prompt: string; options?: any;
+    };
+    const ctx = getCtx();
+    if (!ctx) {
+      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: "No active session" });
+      return;
+    }
+    try {
+      const id = manager.spawn(pi, ctx, type, prompt, options ?? {});
+      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { id });
+    } catch (err: any) {
+      events.emit(`subagents:rpc:spawn:reply:${requestId}`, { error: err.message });
+    }
+  });
+
+  return { unsubPing, unsubSpawn };
+}

package/src/index.ts

@@ -10,7 +10,8 @@
  *   /agents                 — Interactive agent management menu
  */
 
-import type { ExtensionAPI, ExtensionCommandContext } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, ExtensionCommandContext, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { existsSync, mkdirSync, unlinkSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -18,11 +19,12 @@ import { Text } from "@mariozechner/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
 import { steerAgent, getAgentConversation, getDefaultMaxTurns, setDefaultMaxTurns, getGraceTurns, setGraceTurns } from "./agent-runner.js";
-import { DEFAULT_AGENT_NAMES, type SubagentType, type ThinkingLevel, type AgentConfig, type JoinMode, type AgentRecord } from "./types.js";
+import { DEFAULT_AGENT_NAMES, type SubagentType, type ThinkingLevel, type AgentConfig, type JoinMode, type AgentRecord, type NotificationDetails } from "./types.js";
 import { GroupJoinManager } from "./group-join.js";
 import { getAvailableTypes, getAllTypes, getDefaultAgentNames, getUserAgentNames, getAgentConfig, resolveType, registerAgents, BUILTIN_TOOL_NAMES } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { resolveModel, type ModelRegistry } from "./model-resolver.js";
+import { createOutputFilePath, writeInitialEntry, streamToOutputFile } from "./output-file.js";
 import {
   AgentWidget,
   SPINNER,
@@ -103,6 +105,42 @@ function getStatusNote(status: string): string {
   }
 }
 
+/** Escape XML special characters to prevent injection in structured notifications. */
+function escapeXml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Format a structured task notification matching Claude Code's <task-notification> XML. */
+function formatTaskNotification(record: AgentRecord, resultMaxLen: number): string {
+  const status = getStatusLabel(record.status, record.error);
+  const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
+  let totalTokens = 0;
+  try {
+    if (record.session) {
+      const stats = record.session.getSessionStats();
+      totalTokens = stats.tokens?.total ?? 0;
+    }
+  } catch { /* session stats unavailable */ }
+
+  const resultPreview = record.result
+    ? record.result.length > resultMaxLen
+      ? record.result.slice(0, resultMaxLen) + "\n...(truncated, use get_subagent_result for full output)"
+      : record.result
+    : "No output.";
+
+  return [
+    `<task-notification>`,
+    `<task-id>${record.id}</task-id>`,
+    record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
+    record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
+    `<status>${escapeXml(status)}</status>`,
+    `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+    `<result>${escapeXml(resultPreview)}</result>`,
+    `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses><duration_ms>${durationMs}</duration_ms></usage>`,
+    `</task-notification>`,
+  ].filter(Boolean).join('\n');
+}
+
 /** Build AgentDetails from a base + record-specific fields. */
 function buildDetails(
   base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
@@ -121,7 +159,79 @@ function buildDetails(
   };
 }
 
+/** Build notification details for the custom message renderer. */
+function buildNotificationDetails(record: AgentRecord, resultMaxLen: number): NotificationDetails {
+  let totalTokens = 0;
+  try {
+    if (record.session) totalTokens = record.session.getSessionStats().tokens?.total ?? 0;
+  } catch {}
+
+  return {
+    id: record.id,
+    description: record.description,
+    status: record.status,
+    toolUses: record.toolUses,
+    totalTokens,
+    durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
+    outputFile: record.outputFile,
+    error: record.error,
+    resultPreview: record.result
+      ? record.result.length > resultMaxLen
+        ? record.result.slice(0, resultMaxLen) + "…"
+        : record.result
+      : "No output.",
+  };
+}
+
 export default function (pi: ExtensionAPI) {
+  // ---- Register custom notification renderer ----
+  pi.registerMessageRenderer<NotificationDetails>(
+    "subagent-notification",
+    (message, { expanded }, theme) => {
+      const d = message.details;
+      if (!d) return undefined;
+
+      function renderOne(d: NotificationDetails): string {
+        const isError = d.status === "error" || d.status === "stopped" || d.status === "aborted";
+        const icon = isError ? theme.fg("error", "✗") : theme.fg("success", "✓");
+        const statusText = isError ? d.status
+          : d.status === "steered" ? "completed (steered)"
+          : "completed";
+
+        // Line 1: icon + agent description + status
+        let line = `${icon} ${theme.bold(d.description)} ${theme.fg("dim", statusText)}`;
+
+        // Line 2: stats
+        const parts: string[] = [];
+        if (d.toolUses > 0) parts.push(`${d.toolUses} tool use${d.toolUses === 1 ? "" : "s"}`);
+        if (d.totalTokens > 0) parts.push(formatTokens(d.totalTokens));
+        if (d.durationMs > 0) parts.push(formatMs(d.durationMs));
+        if (parts.length) {
+          line += "\n  " + parts.map(p => theme.fg("dim", p)).join(" " + theme.fg("dim", "·") + " ");
+        }
+
+        // Line 3: result preview (collapsed) or full (expanded)
+        if (expanded) {
+          const lines = d.resultPreview.split("\n").slice(0, 30);
+          for (const l of lines) line += "\n" + theme.fg("dim", `  ${l}`);
+        } else {
+          const preview = d.resultPreview.split("\n")[0]?.slice(0, 80) ?? "";
+          line += "\n  " + theme.fg("dim", `⎿  ${preview}`);
+        }
+
+        // Line 4: output file link (if present)
+        if (d.outputFile) {
+          line += "\n  " + theme.fg("muted", `transcript: ${d.outputFile}`);
+        }
+
+        return line;
+      }
+
+      const all = [d, ...(d.others ?? [])];
+      return new Text(all.map(renderOne).join("\n"), 0, 0);
+    }
+  );
+
   /** Reload agents from .pi/agents/*.md and merge with defaults (called on init and each Agent invocation). */
   const reloadCustomAgents = () => {
     const userAgents = loadCustomAgents(process.cwd());
@@ -134,71 +244,79 @@ export default function (pi: ExtensionAPI) {
   // ---- Agent activity tracking + widget ----
   const agentActivity = new Map<string, AgentActivity>();
 
+  // ---- Cancellable pending notifications ----
+  // Holds notifications briefly so get_subagent_result can cancel them
+  // before they reach pi.sendMessage (fire-and-forget).
+  const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+  const NUDGE_HOLD_MS = 200;
+
+  function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
+    cancelNudge(key);
+    pendingNudges.set(key, setTimeout(() => {
+      pendingNudges.delete(key);
+      send();
+    }, delay));
+  }
+
+  function cancelNudge(key: string) {
+    const timer = pendingNudges.get(key);
+    if (timer != null) {
+      clearTimeout(timer);
+      pendingNudges.delete(key);
+    }
+  }
+
   // ---- Individual nudge helper (async join mode) ----
-  function sendIndividualNudge(record: AgentRecord) {
-    const displayName = getDisplayName(record.type);
-    const duration = formatDuration(record.startedAt, record.completedAt);
-    const status = getStatusLabel(record.status, record.error);
-    const resultPreview = record.result
-      ? record.result.length > 500
-        ? record.result.slice(0, 500) + "\n...(truncated, use get_subagent_result for full output)"
-        : record.result
-      : "No output.";
+  function emitIndividualNudge(record: AgentRecord) {
+    if (record.resultConsumed) return;  // re-check at send time
+
+    const notification = formatTaskNotification(record, 500);
+    const footer = record.outputFile ? `\nFull transcript available at: ${record.outputFile}` : '';
+
+    pi.sendMessage<NotificationDetails>({
+      customType: "subagent-notification",
+      content: notification + footer,
+      display: true,
+      details: buildNotificationDetails(record, 500),
+    }, { deliverAs: "followUp" });
+  }
 
+  function sendIndividualNudge(record: AgentRecord) {
     agentActivity.delete(record.id);
     widget.markFinished(record.id);
-
-    const tokens = safeFormatTokens(record.session);
-    const toolStats = tokens ? `Tool uses: ${record.toolUses} | ${tokens}` : `Tool uses: ${record.toolUses}`;
-    pi.sendUserMessage(
-      `Background agent completed: ${displayName} (${record.description})\n` +
-      `Agent ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n\n` +
-      resultPreview,
-      { deliverAs: "followUp" },
-    );
+    scheduleNudge(record.id, () => emitIndividualNudge(record));
     widget.update();
   }
 
-  /** Format a single agent's summary for grouped notification. */
-  function formatAgentSummary(record: AgentRecord): string {
-    const displayName = getDisplayName(record.type);
-    const duration = formatDuration(record.startedAt, record.completedAt);
-    const status = getStatusLabel(record.status, record.error);
-    const resultPreview = record.result
-      ? record.result.length > 300
-        ? record.result.slice(0, 300) + "\n...(truncated)"
-        : record.result
-      : "No output.";
-    const tokens = safeFormatTokens(record.session);
-    const toolStats = tokens ? `Tools: ${record.toolUses} | ${tokens}` : `Tools: ${record.toolUses}`;
-    return `- ${displayName} (${record.description})\n  ID: ${record.id} | Status: ${status} | ${toolStats} | Duration: ${duration}\n  ${resultPreview}`;
-  }
-
   // ---- Group join manager ----
   const groupJoin = new GroupJoinManager(
     (records, partial) => {
-      // Filter out agents whose results were already consumed via get_subagent_result
-      const unconsumed = records.filter(r => !r.resultConsumed);
-
-      for (const r of records) {
-        agentActivity.delete(r.id);
-        widget.markFinished(r.id);
-      }
-
-      // If all results were already consumed, skip the notification entirely
-      if (unconsumed.length === 0) {
-        widget.update();
-        return;
-      }
-
-      const total = unconsumed.length;
-      const label = partial ? `${total} agent(s) finished (partial — others still running)` : `${total} agent(s) finished`;
-      const summary = unconsumed.map(r => formatAgentSummary(r)).join("\n\n");
+      for (const r of records) { agentActivity.delete(r.id); widget.markFinished(r.id); }
+
+      const groupKey = `group:${records.map(r => r.id).join(",")}`;
+      scheduleNudge(groupKey, () => {
+        // Re-check at send time
+        const unconsumed = records.filter(r => !r.resultConsumed);
+        if (unconsumed.length === 0) { widget.update(); return; }
+
+        const notifications = unconsumed.map(r => formatTaskNotification(r, 300)).join('\n\n');
+        const label = partial
+          ? `${unconsumed.length} agent(s) finished (partial — others still running)`
+          : `${unconsumed.length} agent(s) finished`;
+
+        const [first, ...rest] = unconsumed;
+        const details = buildNotificationDetails(first, 300);
+        if (rest.length > 0) {
+          details.others = rest.map(r => buildNotificationDetails(r, 300));
+        }
 
-      pi.sendUserMessage(
-        `Background agent group completed: ${label}\n\n${summary}\n\nUse get_subagent_result for full output.`,
-        { deliverAs: "followUp" },
-      );
+        pi.sendMessage<NotificationDetails>({
+          customType: "subagent-notification",
+          content: `Background agent group completed: ${label}\n\n${notifications}\n\nUse get_subagent_result for full output.`,
+          display: true,
+          details,
+        }, { deliverAs: "followUp" });
+      });
       widget.update();
     },
     30_000,
@@ -242,6 +360,13 @@ export default function (pi: ExtensionAPI) {
       pi.events.emit("subagents:completed", eventData);
     }
 
+    // Persist final record for cross-extension history reconstruction
+    pi.appendEntry("subagents:record", {
+      id: record.id, type: record.type, description: record.description,
+      status: record.status, result: record.result, error: record.error,
+      startedAt: record.startedAt, completedAt: record.completedAt,
+    });
+
     // Skip notification if result was already consumed via get_subagent_result
     if (record.resultConsumed) {
       agentActivity.delete(record.id);
@@ -284,15 +409,37 @@ export default function (pi: ExtensionAPI) {
     getRecord: (id: string) => manager.getRecord(id),
   };
 
-  // Clear completed tasks when a new session starts (e.g. /new) so stale records don't persist
-  pi.on("session_start", () => { manager.clearCompleted(); });
+  // --- Cross-extension RPC via pi.events ---
+  let currentCtx: ExtensionContext | undefined;
+
+  // Capture ctx from session_start for RPC spawn handler
+  pi.on("session_start", async (_event, ctx) => {
+    currentCtx = ctx;
+    manager.clearCompleted();           // preserve existing behavior
+  });
+
   pi.on("session_switch", () => { manager.clearCompleted(); });
 
+  const { unsubPing: unsubPingRpc, unsubSpawn: unsubSpawnRpc } = registerRpcHandlers({
+    events: pi.events,
+    pi,
+    getCtx: () => currentCtx,
+    manager,
+  });
+
+  // Broadcast readiness so extensions loaded after us can discover us
+  pi.events.emit("subagents:ready", {});
+
   // On shutdown, abort all agents immediately and clean up.
   // If the session is going down, there's nothing left to consume agent results.
   pi.on("session_shutdown", async () => {
+    unsubSpawnRpc();
+    unsubPingRpc();
+    currentCtx = undefined;
     delete (globalThis as any)[MANAGER_KEY];
     manager.abortAll();
+    for (const timer of pendingNudges.values()) clearTimeout(timer);
+    pendingNudges.clear();
     manager.dispose();
   });
 
@@ -564,7 +711,7 @@ Guidelines:
 
     // ---- Execute ----
 
-    execute: async (_toolCallId, params, signal, onUpdate, ctx) => {
+    execute: async (toolCallId, params, signal, onUpdate, ctx) => {
       // Ensure we have UI context for widget rendering
       widget.setUICtx(ctx.ui as UICtx);
 
@@ -647,7 +794,20 @@ Guidelines:
       if (runInBackground) {
         const { state: bgState, callbacks: bgCallbacks } = createActivityTracker();
 
-        const id = manager.spawn(pi, ctx, subagentType, params.prompt, {
+        // Wrap onSessionCreated to wire output file streaming.
+        // The callback lazily reads record.outputFile (set right after spawn)
+        // rather than closing over a value that doesn't exist yet.
+        let id: string;
+        const origBgOnSession = bgCallbacks.onSessionCreated;
+        bgCallbacks.onSessionCreated = (session: any) => {
+          origBgOnSession(session);
+          const rec = manager.getRecord(id);
+          if (rec?.outputFile) {
+            rec.outputCleanup = streamToOutputFile(session, rec.outputFile, id, ctx.cwd);
+          }
+        };
+
+        id = manager.spawn(pi, ctx, subagentType, params.prompt, {
           description: params.description,
           model,
           maxTurns: params.max_turns,
@@ -659,10 +819,16 @@ Guidelines:
           ...bgCallbacks,
         });
 
-        // Determine join mode and track for batching
+        // Set output file + join mode synchronously after spawn, before the
+        // event loop yields — onSessionCreated is async so this is safe.
         const joinMode: JoinMode = params.join_mode ?? defaultJoinMode;
         const record = manager.getRecord(id);
-        if (record) record.joinMode = joinMode;
+        if (record) {
+          record.joinMode = joinMode;
+          record.toolCallId = toolCallId;
+          record.outputFile = createOutputFilePath(ctx.cwd, id, ctx.sessionManager.getSessionId());
+          writeInitialEntry(record.outputFile, id, params.prompt, ctx.cwd);
+        }
 
         if (joinMode === 'async') {
           // Explicit async — not part of any batch
@@ -693,6 +859,7 @@ Guidelines:
           `Agent ID: ${id}\n` +
           `Type: ${displayName}\n` +
           `Description: ${params.description}\n` +
+          (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
           (isQueued ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n` : "") +
           `\nYou will be notified when this agent completes.\n` +
           `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
@@ -823,6 +990,7 @@ Guidelines:
       // Setting the flag here prevents a redundant follow-up notification.
       if (params.wait && record.status === "running" && record.promise) {
         record.resultConsumed = true;
+        cancelNudge(params.agent_id);
         await record.promise;
       }
 
@@ -847,6 +1015,7 @@ Guidelines:
       // Mark result as consumed — suppresses the completion notification
       if (record.status !== "running" && record.status !== "queued") {
         record.resultConsumed = true;
+        cancelNudge(params.agent_id);
       }
 
       // Verbose: include full conversation

package/src/output-file.ts

@@ -0,0 +1,77 @@
+/**
+ * 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 { tmpdir } from "node:os";
+import { join } from "node:path";
+import { mkdirSync, chmodSync, appendFileSync, writeFileSync } from "node:fs";
+import type { AgentSession, AgentSessionEvent } from "@mariozechner/pi-coding-agent";
+
+/** Create the output file path, ensuring the directory exists.
+ *  Mirrors Claude Code's layout: /tmp/{prefix}-{uid}/{encoded-cwd}/{sessionId}/tasks/{agentId}.output */
+export function createOutputFilePath(cwd: string, agentId: string, sessionId: string): string {
+  const encoded = cwd.replace(/\//g, "-").replace(/^-/, "");
+  const root = join(tmpdir(), `pi-subagents-${process.getuid?.() ?? 0}`);
+  mkdirSync(root, { recursive: true, mode: 0o700 });
+  chmodSync(root, 0o700);
+  const dir = join(root, encoded, sessionId, "tasks");
+  mkdirSync(dir, { recursive: true });
+  return join(dir, `${agentId}.output`);
+}
+
+/** 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,
+): () => void {
+  let writtenCount = 1; // initial user prompt already written
+
+  const flush = () => {
+    const messages = session.messages;
+    while (writtenCount < messages.length) {
+      const msg = messages[writtenCount];
+      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 */ }
+      writtenCount++;
+    }
+  };
+
+  const unsubscribe = session.subscribe((event: AgentSessionEvent) => {
+    if (event.type === "turn_end") flush();
+  });
+
+  return () => {
+    flush();
+    unsubscribe();
+  };
+}

package/src/types.ts

@@ -79,6 +79,27 @@ export interface AgentRecord {
   worktree?: { path: string; branch: string };
   /** Worktree cleanup result after agent completion. */
   worktreeResult?: { hasChanges: boolean; branch?: string };
+  /** The tool_use_id from the original Agent tool call. */
+  toolCallId?: string;
+  /** Path to the streaming output transcript file. */
+  outputFile?: string;
+  /** Cleanup function for the output file stream subscription. */
+  outputCleanup?: () => void;
+}
+
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  status: string;
+  toolUses: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+  /** Additional agents in a group notification. */
+  others?: NotificationDetails[];
 }
 
 export interface EnvInfo {

package/src/ui/conversation-viewer.ts

@@ -238,6 +238,6 @@ export class ConversationViewer implements Component {
       lines.push(truncateToWidth(th.fg("accent", "▍ ") + th.fg("dim", act), width));
     }
 
-    return lines;
+    return lines.map(l => truncateToWidth(l, width));
   }
 }