@pi-unipi/fusion 2.17.1 → 2.18.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/fusion",
-  "version": "2.17.1",
+  "version": "2.18.0",
   "description": "Devin-style model picker, fusion presets (lead + sidekick), and Local Fusion runtime for UniPi",
   "type": "module",
   "main": "src/index.ts",
@@ -32,8 +32,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@pi-unipi/core": "2.17.0",
-    "@pi-unipi/subagents": "2.17.0"
+    "@pi-unipi/core": "2.18.0",
+    "@pi-unipi/subagents": "2.18.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-ai": "^0.84.0",

package/src/index.ts

@@ -37,7 +37,8 @@ import { ModelPicker, type PickerModel, type PickerResult } from "./picker.js";
 import { PresetEditor, type PresetEditorResult } from "./preset-editor.js";
 import { SidekickRuntime } from "./sidekick-runtime.js";
 import { estimateSavings } from "./savings.js";
-import { FIRST_EDIT_NUDGE, leadPolicy, sidekickSystemPrompt, type FusionIdentity } from "./prompts.js";
+import { EDIT_NUDGE, bashNudge, leadPolicy, sidekickSystemPrompt, type FusionIdentity } from "./prompts.js";
+import { isTrivialShell, BASH_NUDGE_EVERY } from "./nudge.js";
 import { registerFusionTools } from "./tools.js";
 
 export const MODEL_COMMAND = `${UNIPI_PREFIX}model`;
@@ -113,7 +114,10 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   let active: ActiveSelection | undefined;
   let runtime: SidekickRuntime | undefined;
-  let nudged = false;
+  let lastCtx: ExtensionContext | undefined;
+  let leadToolCalls = 0;
+  let editNudgedThisTurn = false;
+  let bashStreak = 0;
 
   function identity(ctx: ExtensionContext): FusionIdentity {
     const reg = registryOf(ctx);
@@ -136,6 +140,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   }
 
   function publishStatus(ctx: ExtensionContext): void {
+    lastCtx = ctx;
     const reg = registryOf(ctx);
     const names = (k: string) => findModel(reg, k)?.name || splitModelKey(k)?.id || k;
     if (active?.kind === "fusion") {
@@ -147,12 +152,19 @@ export default function fusionExtension(pi: ExtensionAPI): void {
         sidekickName: names(active.sidekick),
         sidekickEffort: active.sidekickEffort ?? "",
         savedUsd: statusSavings(ctx),
+        busy: runtime?.isBusy() ?? false,
+        leadToolCalls,
+        sidekickToolCalls: runtime?.totalToolCalls() ?? 0,
       });
     } else {
       setSharedFusionStatus(undefined);
     }
   }
 
+  function publishStatusLater(): void {
+    if (lastCtx) publishStatus(lastCtx);
+  }
+
   function leadSessionId(ctx: ExtensionContext): string {
     const manager = ctx.sessionManager as { getSessionId?: () => string | undefined } | undefined;
     return manager?.getSessionId?.() ?? "default";
@@ -167,6 +179,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
         thinking: active.sidekickEffort ?? "medium",
         sessionFile: sidekickSessionPath(leadSessionId(ctx)),
         systemPrompt: sidekickSystemPrompt(identity(ctx)),
+        onProgress: () => publishStatusLater(),
       });
     }
     return runtime;
@@ -175,6 +188,7 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   function stopRuntime(): void {
     runtime?.kill();
     runtime = undefined;
+    leadToolCalls = 0;
   }
 
   function savingsStats(ctx: ExtensionContext): string {
@@ -193,16 +207,38 @@ export default function fusionExtension(pi: ExtensionAPI): void {
   registerFusionTools(pi, {
     getRuntime,
     onReport: (ctx) => publishStatus(ctx),
+    onHandoffStart: (ctx) => publishStatus(ctx),
   });
   pi.registerCommand("unipi:fusion-stats", {
     description: "Estimated Fusion savings (sidekick tokens priced at lead rates)",
     handler: async (_args, ctx) => ctx.ui.notify(savingsStats(ctx), "info"),
   });
   pi.on("before_agent_start", (event, ctx) => active?.kind === "fusion" ? { systemPrompt: `${event.systemPrompt}\n\n${leadPolicy(identity(ctx))}` } : undefined);
+  pi.on("turn_start", () => {
+    editNudgedThisTurn = false;
+  });
   pi.on("tool_result", (event) => {
-    if (active?.kind !== "fusion" || nudged || (event.toolName !== "edit" && event.toolName !== "write")) return;
-    nudged = true;
-    return { content: [...event.content, { type: "text", text: FIRST_EDIT_NUDGE }] };
+    if (active?.kind !== "fusion") return;
+    const toolName: string = event.toolName;
+    if (toolName === "sidekick" || toolName === "read_subagent") {
+      bashStreak = 0;
+      return;
+    }
+    leadToolCalls += 1;
+    publishStatusLater();
+    if (toolName === "edit" || toolName === "write") {
+      if (editNudgedThisTurn) return;
+      editNudgedThisTurn = true;
+      return { content: [...event.content, { type: "text" as const, text: EDIT_NUDGE }] };
+    }
+    if (toolName !== "bash") return;
+    const command = typeof event.input.command === "string" ? event.input.command : "";
+    if (isTrivialShell(command)) return;
+    bashStreak += 1;
+    if (bashStreak < BASH_NUDGE_EVERY) return;
+    const content = [...event.content, { type: "text" as const, text: bashNudge(bashStreak) }];
+    bashStreak = 0;
+    return { content };
   });
 
   async function applyResult(ctx: ExtensionContext, result: PickerResult, preset: FusionPreset, loaded: { globalPath: string; projectPath: string; hasProjectLayer: boolean }): Promise<void> {
@@ -355,7 +391,8 @@ export default function fusionExtension(pi: ExtensionAPI): void {
 
   pi.on("session_start", async (_e, ctx) => {
     stopRuntime();
-    nudged = false;
+    editNudgedThisTurn = false;
+    bashStreak = 0;
     modelBykey.clear();
     active = loadPreset(ctx.cwd ?? process.cwd()).preset.active;
     if (active?.kind === "fusion" && (!ctx.model || modelKey(ctx.model) !== active.lead)) {

package/src/nudge.ts

@@ -0,0 +1,7 @@
+export const BASH_NUDGE_EVERY = 4;
+
+const TRIVIAL = /^\s*(?:cd\s+\S+\s*(?:&&|;)\s*)?(?:git\s+(?:status|log|diff|branch|show|remote|rev-parse)|ls|pwd|cat|head|tail|wc|echo|which|type|rg|grep|find|stat|file|du|df|env|printenv|date|whoami|tmux\s+capture-pane|npm\s+(?:view|whoami|ls))\b[^|;&]*$/;
+
+export function isTrivialShell(command: string): boolean {
+  return TRIVIAL.test(command.trim());
+}

package/src/prompts.ts

@@ -68,9 +68,25 @@ You have a \`sidekick\` tool: a persistent subagent that works alongside you on
 - **Promoting a delegated hypothesis to a confirmed conclusion.** When a report ranks candidate causes, the ranking is not a verdict. Present a cause as the root cause only if evidence shows its code path actually executes in the reported scenario; otherwise present it as the leading hypothesis and name the check that would settle it.`;
 }
 
-/** One-time reminder appended to the lead's first direct edit/write while Fusion is active. */
-export const FIRST_EDIT_NUDGE =
-  "<system_guidance>You made a direct edit yourself instead of delegating to the sidekick. That is fine for a trivially small change (one you can make and confirm in 1-2 turns with nothing left to test). For anything larger — multiple files, anything that needs a test run, anything you would want to look over again — write a brief and hand it to `sidekick` instead: you design and review, it implements and verifies. This reminder is shown once.</system_guidance>";
+/**
+ * Recurring reminder appended to a direct edit/write by the lead while Fusion
+ * is active (at most once per agent turn). Mirrors Devin's harness, which
+ * re-issues this guidance on every direct implementation action rather than once.
+ */
+export const EDIT_NUDGE =
+  "<system_guidance>You made a direct edit yourself instead of delegating to the sidekick. This is a reminder that implementation and verification are to be delegated by default. ONLY implement a step yourself if it is trivially small (you can make the edit AND confirm it in 1-2 of your own turns, with nothing left to test afterwards) or correctness-critical (queries against shared data systems, eval/grading text, pipeline or threshold configuration — you author and check those regardless of size). For anything else, write a brief and hand it to `sidekick`: you design and review, it implements and verifies.</system_guidance>";
+
+/** Kept for compatibility with earlier imports; the nudge is no longer one-time. */
+export const FIRST_EDIT_NUDGE = EDIT_NUDGE;
+
+/**
+ * Appended after the lead has run several consecutive non-trivial shell
+ * commands itself without a handoff. Builds, tests, installs, environment
+ * repair and multi-step shell work are the sidekick's job by default.
+ */
+export function bashNudge(count: number): string {
+  return `<system_guidance>You have run ${String(count)} non-trivial shell commands yourself since the last handoff. Builds, test runs, installs, environment setup or repair, and any multi-step shell work are to be delegated to the \`sidekick\` by default; it runs on the same machine and remembers earlier handoffs, so a short brief with the goal, the exact commands or checks you want, and the done-criteria is enough. Keep running commands yourself only when a single read-only command answers a question you need right now, or when the user is waiting on an urgent deliverable.</system_guidance>`;
+}
 
 export function sidekickSystemPrompt(id: FusionIdentity): string {
   return `## Role: Fusion sidekick

package/src/sidekick-runtime.ts

@@ -14,6 +14,7 @@ export interface SidekickSpawnConfig {
   systemPrompt: string;
   spawn?: typeof defaultSpawn;
   command?: { command: string; args: string[] };
+  onProgress?: () => void;
 }
 
 export interface SidekickUsage {
@@ -24,11 +25,20 @@ export interface SidekickUsage {
   cost: number;
 }
 
+export type SidekickEvent =
+  | { kind: "text"; text: string; open: boolean }
+  | { kind: "tool"; toolCallId: string; name: string; args: Record<string, unknown> | undefined; output: string; isError: boolean; done: boolean; startedAt: number; endedAt?: number };
+
+export const MAX_EVENTS = 300;
+export const MAX_TOOL_OUTPUT = 4000;
+
 export interface HandoffProgress {
   toolCalls: number;
   recentTools: string[];
   textTail: string;
   startedAt: number;
+  events: SidekickEvent[];
+  droppedEvents: number;
 }
 
 export interface HandoffReport {
@@ -38,6 +48,7 @@ export interface HandoffReport {
   usage: SidekickUsage;
   toolCalls: number;
   durationMs: number;
+  events: SidekickEvent[];
   error?: string;
 }
 
@@ -79,6 +90,47 @@ export class SidekickRuntime {
     return this.pending !== undefined;
   }
 
+  totalToolCalls(): number {
+    let total = this.pending?.progress.toolCalls ?? 0;
+    for (const report of this.reports.values()) total += report.toolCalls;
+    return total;
+  }
+
+  private notifyProgress(): void {
+    try {
+      this.cfg.onProgress?.();
+    } catch {
+      // Progress updates must not affect the handoff.
+    }
+  }
+
+  private appendEvent(event: SidekickEvent): void {
+    const progress = this.pending?.progress;
+    if (!progress) return;
+    progress.events.push(event);
+    if (progress.events.length > MAX_EVENTS) {
+      progress.events.shift();
+      progress.droppedEvents += 1;
+    }
+  }
+
+  private closeOpenText(): void {
+    const events = this.pending?.progress.events;
+    const last = events?.at(-1);
+    if (last?.kind === "text" && last.open) last.open = false;
+  }
+
+  private toolOutput(result: unknown): string {
+    if (typeof result === "object" && result !== null && Array.isArray((result as { content?: unknown }).content)) {
+      return ((result as { content: unknown[] }).content)
+        .map((part) => typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : typeof part === "string" ? part : "")
+        .filter(Boolean)
+        .join("\n")
+        .slice(-MAX_TOOL_OUTPUT);
+    }
+    return String(result ?? "").slice(-MAX_TOOL_OUTPUT);
+  }
+
   private send(value: Record<string, unknown>): void {
     if (!this.child?.stdin?.writable) throw new Error("Sidekick process is not writable");
     this.child.stdin.write(`${JSON.stringify(value)}\n`);
@@ -169,19 +221,39 @@ export class SidekickRuntime {
     }
     if (this.pending === undefined) return;
     if (message.type === "tool_execution_start") {
+      this.closeOpenText();
       this.pending.progress.toolCalls += 1;
-      const args = message.args === undefined ? "" : JSON.stringify(message.args).replace(/\s+/gu, " ");
-      const summary = `${String(message.toolName ?? "tool")}(${args})`.slice(0, 40);
+      const args = message.args !== undefined && typeof message.args === "object" && message.args !== null ? message.args as Record<string, unknown> : undefined;
+      const argsText = args === undefined ? "" : JSON.stringify(args).replace(/\s+/gu, " ");
+      const summary = `${String(message.toolName ?? "tool")}(${argsText})`.slice(0, 40);
       this.pending.progress.recentTools = [...this.pending.progress.recentTools, summary].slice(-6);
+      this.appendEvent({ kind: "tool", toolCallId: String(message.toolCallId ?? ""), name: String(message.toolName ?? "tool"), args, output: "", isError: false, done: false, startedAt: Date.now() });
+      this.notifyProgress();
+    } else if (message.type === "tool_execution_end") {
+      const toolCallId = String(message.toolCallId ?? "");
+      const event = [...this.pending.progress.events].reverse().find((entry): entry is Extract<SidekickEvent, { kind: "tool" }> => entry.kind === "tool" && entry.toolCallId === toolCallId);
+      if (event) {
+        event.done = true;
+        event.endedAt = Date.now();
+        event.isError = message.isError === true;
+        event.output = this.toolOutput(message.result);
+      }
+      this.notifyProgress();
     } else if (message.type === "message_update") {
-      const event = (message.assistantMessageEvent ?? message) as Record<string, unknown>;
-      if (event.type === "text_delta") {
-        const delta = typeof event.delta === "string" ? event.delta : typeof event.text === "string" ? event.text : "";
+      const streamEvent = (message.assistantMessageEvent ?? message) as Record<string, unknown>;
+      if (streamEvent.type === "text_delta") {
+        const delta = typeof streamEvent.delta === "string" ? streamEvent.delta : typeof streamEvent.text === "string" ? streamEvent.text : "";
         this.pending.progress.textTail = `${this.pending.progress.textTail}${delta}`.slice(-400);
+        const last = this.pending.progress.events.at(-1);
+        if (last?.kind === "text" && last.open) last.text += delta;
+        else this.appendEvent({ kind: "text", text: delta, open: true });
+        this.notifyProgress();
       }
     } else if (message.type === "message_end") {
       const msg = message.message as Record<string, unknown> | undefined;
       if (msg?.role === "assistant") {
+        this.closeOpenText();
+        this.notifyProgress();
         if (msg.stopReason === "error" && typeof msg.errorMessage === "string") this.pendingError = msg.errorMessage;
         const usage = msg.usage as Record<string, unknown> | undefined;
         if (usage) {
@@ -231,11 +303,13 @@ export class SidekickRuntime {
       usage: { ...current.usage },
       toolCalls: current.progress.toolCalls,
       durationMs: Date.now() - current.startedAt,
+      events: current.progress.events.map((event) => ({ ...event })),
       ...(error === undefined ? {} : { error }),
     };
     this.reports.set(report.id, report);
     if (this.latestHandoff?.id === report.id) this.latestHandoff.report = report;
     current.resolve(report);
+    this.notifyProgress();
     this.abortRequested = false;
     this.pendingError = undefined;
   }
@@ -259,7 +333,7 @@ export class SidekickRuntime {
       id,
       startedAt,
       usage: emptyUsage(),
-      progress: { toolCalls: 0, recentTools: [], textTail: "", startedAt },
+      progress: { toolCalls: 0, recentTools: [], textTail: "", startedAt, events: [], droppedEvents: 0 },
       resolve,
       reject,
     };
@@ -273,7 +347,9 @@ export class SidekickRuntime {
   }
 
   progress(id?: string): HandoffProgress | undefined {
-    if (this.pending !== undefined && (id === undefined || id === this.pending.id)) return { ...this.pending.progress, recentTools: [...this.pending.progress.recentTools] };
+    if (this.pending !== undefined && (id === undefined || id === this.pending.id)) {
+      return { ...this.pending.progress, recentTools: [...this.pending.progress.recentTools], events: this.pending.progress.events.map((event) => ({ ...event })) };
+    }
     return undefined;
   }
 

package/src/tools.ts

@@ -1,7 +1,8 @@
-import { Box, Text } from "@earendil-works/pi-tui";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Markdown, Text, type Component } from "@earendil-works/pi-tui";
+import { getMarkdownTheme, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import type { SidekickRuntime, HandoffReport } from "./sidekick-runtime.js";
+import type { SidekickRuntime, HandoffProgress, HandoffReport } from "./sidekick-runtime.js";
+import { frameSidekick, renderSidekickTranscript, type ThemeLike as TranscriptTheme } from "./transcript.js";
 
 const SidekickParams = Type.Object({
   message: Type.String({ description: "A concrete implementation or verification brief for the sidekick" }),
@@ -16,12 +17,17 @@ const ReadSubagentParams = Type.Object({
 export interface FusionToolDeps {
   getRuntime: (ctx: ExtensionContext) => SidekickRuntime | undefined;
   onReport?: (ctx: ExtensionContext, report: HandoffReport) => void;
+  onHandoffStart?: (ctx: ExtensionContext) => void;
 }
 
 function duration(ms: number): string {
   return `${(ms / 1000).toFixed(1)}s`;
 }
 
+function firstLine(value: string): string {
+  return value.split("\n", 1)[0] ?? "";
+}
+
 function progressText(runtime: SidekickRuntime, id: string): string {
   const progress = runtime.progress(id);
   if (!progress) return "No active handoff progress.";
@@ -33,7 +39,9 @@ function progressText(runtime: SidekickRuntime, id: string): string {
 
 function progressKey(runtime: SidekickRuntime, id: string): string {
   const progress = runtime.progress(id);
-  return progress === undefined ? "" : `${String(progress.toolCalls)}|${progress.recentTools.join("|")}|${progress.textTail}`;
+  if (!progress) return "";
+  const last = progress.events.at(-1);
+  return `${String(progress.toolCalls)}|${progress.recentTools.join("|")}|${progress.textTail}|${String(progress.events.length)}|${last?.kind === "tool" ? `${String(last.output.length)}|${String(last.done)}` : last?.kind === "text" ? `${String(last.text.length)}|${String(last.open)}` : ""}`;
 }
 
 function reportText(report: HandoffReport): string {
@@ -70,7 +78,7 @@ async function waitForReport(
     const key = progressKey(runtime, id);
     if (key !== lastProgressKey) {
       lastProgressKey = key;
-      onUpdate?.({ content: [{ type: "text", text: progress }] });
+      onUpdate?.({ content: [{ type: "text", text: progress }], details: { progress: runtime.progress(id) } });
     }
   }
 }
@@ -90,15 +98,52 @@ type ThemeLike = {
   bold: (text: string) => string;
 };
 
-function renderCompletionCard(theme: ThemeLike, report: HandoffReport | undefined): Box {
-  const tone = report?.status === "completed" ? "toolSuccessBg" : "toolErrorBg";
-  const head = report
-    ? `${theme.fg(report.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`sidekick done · ${report.id}`))} ${theme.fg("dim", `· ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)}`)}`
-    : `${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`;
-  const lines = [head, ...(report?.text.split("\n").slice(0, 6).map((line) => theme.fg("dim", line)) ?? [])];
-  const box = new Box(1, 0, (text) => theme.bg(tone, text));
-  box.addChild(new Text(lines.join("\n"), 0, 0));
-  return box;
+function transcriptTheme(theme: ThemeLike): TranscriptTheme {
+  return { fg: (color, text) => theme.fg(color, text), bold: (text) => theme.bold(text) };
+}
+
+function markdownText(markdown: string): Markdown {
+  return new Markdown(markdown, 0, 0, getMarkdownTheme());
+}
+
+function contentText(content: unknown): string {
+  if (!Array.isArray(content)) return String(content ?? "");
+  return content.map((part) => typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string" ? (part as { text: string }).text : "").filter(Boolean).join("\n");
+}
+
+function renderToolTranscript(result: { content?: unknown; details?: unknown; isError?: boolean }, options: { expanded?: boolean }, theme: ThemeLike, label: "sidekick" | "read_subagent"): Component {
+  const details = result.details as (HandoffReport & { progress?: HandoffProgress }) | { progress?: HandoffProgress } | undefined;
+  const progress = details?.progress;
+  const report = progress ? undefined : details as HandoffReport | undefined;
+  const events = progress?.events ?? report?.events;
+  const partial = progress !== undefined;
+  const status = partial ? "working" : report?.status === "completed" && !result.isError ? "completed" : "error";
+  if (!events) return frameSidekick(theme, status, new Text(contentText(result.content), 0, 0));
+  const header = partial
+    ? `${theme.fg("accent", theme.bold(`◆ ${label} working`))} ${theme.fg("dim", `· ${String(progress.toolCalls)} tool calls · ${duration(Date.now() - progress.startedAt)}`)}`
+    : `${theme.fg(report?.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`${label} ${report?.status ?? "done"}`))} ${theme.fg("dim", report ? `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)} · in ${String(report.usage.input)} / out ${String(report.usage.output)} tokens` : "")}`;
+  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+    events,
+    droppedEvents: progress?.droppedEvents,
+    header,
+    expanded: options.expanded === true,
+    isPartial: partial,
+    report,
+    renderText: markdownText,
+  }));
+}
+
+function renderCompletionCard(theme: ThemeLike, report: HandoffReport | undefined): Component {
+  const status = report?.status === "completed" ? "completed" : "error";
+  if (!report) return frameSidekick(theme, "error", new Text(`${theme.fg("accent", "◆")} ${theme.fg("accent", theme.bold("sidekick done"))}`, 0, 0));
+  return frameSidekick(theme, status, renderSidekickTranscript(transcriptTheme(theme), {
+    events: report.events ?? [],
+    header: `${theme.fg(report.status === "completed" ? "success" : "error", "◆")} ${theme.fg("accent", theme.bold(`sidekick ${report.status}`))} ${theme.fg("dim", `· ${report.id} · ${String(report.toolCalls)} tool calls · ${duration(report.durationMs)}`)}`,
+    expanded: false,
+    isPartial: false,
+    report,
+    renderText: markdownText,
+  }));
 }
 
 export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): void {
@@ -109,10 +154,15 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     label: "Sidekick",
     description: "Hand off work to your persistent sidekick subagent (one per session; context and shells persist across handoffs; runs on the same machine). block:true (default) waits and returns the report. block:false returns immediately and the report arrives later as a <subagent_completion_notification>. Calling again while a handoff is running injects the message as an interrupt rather than starting a second sidekick.",
     parameters: SidekickParams,
+    renderShell: "self",
+    renderCall: (args, theme) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ sidekick"))} ${theme.fg("dim", firstLine(String(args.message)).slice(0, 100))}`, 0, 0)),
+    renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "sidekick"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const runtime = deps.getRuntime(ctx);
       if (!runtime) return result("Fusion is not active — pick a Fusion pair with /unipi:model.", undefined, true);
+      const wasBusy = runtime.isBusy();
       const handoff = runtime.handoff(params.message);
+      if (!wasBusy) deps.onHandoffStart?.(ctx);
       if (params.block === false) {
         void handoff.done.then((report) => {
           deps.onReport?.(ctx, report);
@@ -136,6 +186,9 @@ export function registerFusionTools(pi: ExtensionAPI, deps: FusionToolDeps): voi
     label: "Read Sidekick",
     description: "Read a sidekick handoff report by agent_id (omit for the latest). block:true waits for completion (default timeout 2700s when omitted); block:false returns the current progress snapshot immediately.",
     parameters: ReadSubagentParams,
+    renderShell: "self",
+    renderCall: (args, theme) => frameSidekick(theme as unknown as ThemeLike, "working", new Text(`${theme.fg("toolTitle", theme.bold("◆ read_subagent"))} ${theme.fg("dim", args.agent_id ?? "latest")}`, 0, 0)),
+    renderResult: (result, options, theme) => renderToolTranscript(result, options, theme as unknown as ThemeLike, "read_subagent"),
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
       const runtime = deps.getRuntime(ctx);
       if (!runtime) return result("Fusion is not active — pick a Fusion pair with /unipi:model.", undefined, true);

package/src/transcript.ts

@@ -0,0 +1,108 @@
+import { Box, Container, Text, type Component } from "@earendil-works/pi-tui";
+import type { SidekickEvent } from "./sidekick-runtime.js";
+
+export interface ThemeLike {
+  fg: (color: string, text: string) => string;
+  bold: (text: string) => string;
+}
+
+export class RailComponent implements Component {
+  constructor(private readonly inner: Component, private readonly rail: string) {}
+
+  render(width: number): string[] {
+    return this.inner.render(Math.max(1, width - 2)).map((line) => `${this.rail} ${line}`);
+  }
+
+  invalidate(): void {
+    this.inner.invalidate?.();
+  }
+
+  handleInput(data: string): void {
+    this.inner.handleInput?.(data);
+  }
+}
+
+export function frameSidekick(theme: ThemeLike & { bg: (color: string, text: string) => string }, status: "working" | "completed" | "error", content: Component): Component {
+  const railColor = status === "working" ? "accent" : status === "completed" ? "success" : "error";
+  const rail = theme.fg(railColor, "▍");
+  const boxed = new Box(1, 0, (text) => theme.bg("customMessageBg", text));
+  boxed.addChild(new RailComponent(content, rail));
+  return boxed;
+}
+
+export interface TranscriptOptions {
+  events: readonly SidekickEvent[];
+  droppedEvents?: number;
+  header: string;
+  expanded: boolean;
+  isPartial: boolean;
+  report?: { text: string };
+  renderText: (markdown: string) => Component;
+}
+
+function firstLine(value: string): string {
+  return value.split("\n", 1)[0] ?? "";
+}
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, Math.max(0, max - 1))}…` : value;
+}
+
+export function primaryArg(name: string, args: Record<string, unknown> | undefined): string {
+  if (!args) return "";
+  const value = name === "bash"
+    ? args.command
+    : name === "read" || name === "edit" || name === "write"
+      ? args.path ?? args.file_path ?? args.filePath
+      : name === "sidekick"
+        ? args.message
+        : Object.values(args).find((entry) => typeof entry === "string");
+  return typeof value === "string" ? truncate(firstLine(value), 100) : "";
+}
+
+function toolComponent(theme: ThemeLike, event: Extract<SidekickEvent, { kind: "tool" }>, expanded: boolean): Text {
+  const title = `${event.isError ? theme.fg("error", "✗ ") : ""}${theme.fg("toolTitle", theme.bold(event.name))}`;
+  const argument = primaryArg(event.name, event.args);
+  const lines = [`${title}${argument.length > 0 ? ` ${theme.fg("accent", argument)}` : ""}`];
+  if (!event.done) {
+    lines[0] += theme.fg("warning", " ⋯ running");
+  } else if (event.output.length > 0) {
+    const output = event.output.split("\n");
+    const visible = expanded ? output.slice(-40) : output.slice(-3);
+    lines.push(...visible.map((line) => theme.fg("toolOutput", truncate(line, 160))));
+  }
+  return new Text(lines.join("\n"), 0, 0);
+}
+
+export function renderSidekickTranscript(theme: ThemeLike, opts: TranscriptOptions): Component {
+  const box = new Container();
+  box.addChild(new Text(opts.header, 0, 0));
+
+  if (!opts.isPartial && !opts.expanded) {
+    if (opts.report?.text) box.addChild(opts.renderText(opts.report.text));
+    box.addChild(new Text(theme.fg("dim", `${String(opts.events.length)} steps · expand to see the transcript`), 0, 0));
+    return box;
+  }
+
+  const dropped = opts.droppedEvents ?? 0;
+  const start = opts.expanded ? 0 : Math.max(0, opts.events.length - 8);
+  if (opts.expanded && dropped > 0) {
+    box.addChild(new Text(theme.fg("dim", `… ${String(dropped)} earliest steps dropped`), 0, 0));
+  } else if (start > 0) {
+    box.addChild(new Text(theme.fg("dim", `… ${String(start + dropped)} earlier steps`), 0, 0));
+  }
+
+  for (const event of opts.events.slice(start)) {
+    if (event.kind === "tool") box.addChild(toolComponent(theme, event, opts.expanded));
+    else if (event.text.trim()) box.addChild(opts.renderText(event.text.trim()));
+  }
+
+  if (!opts.isPartial && opts.expanded && opts.report?.text) {
+    // The final assistant message usually IS the report; don't print it twice.
+    const last = opts.events.at(-1);
+    if (last?.kind === "text" && last.text.trim() === opts.report.text.trim()) return box;
+    box.addChild(new Text(theme.fg("dim", "── report ──"), 0, 0));
+    box.addChild(opts.renderText(opts.report.text));
+  }
+  return box;
+}