@gotgenes/pi-subagents 17.3.0 → 17.4.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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).
 
+## [17.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.3.0...pi-subagents-v17.4.0) (2026-06-23)
+
+
+### Features
+
+* add getToolDefinition accessor on subagent record ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([e0bfdac](https://github.com/gotgenes/pi-packages/commit/e0bfdacec33120d0f52e6294f3676f4776aee4af))
+* expose getToolDefinition on the transcript source seam ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([669f5ff](https://github.com/gotgenes/pi-packages/commit/669f5ff71523122ebb011adc6875b54d7001d53a))
+* render /subagent-sessions transcript with Pi per-entry components ([#462](https://github.com/gotgenes/pi-packages/issues/462)) ([b832a43](https://github.com/gotgenes/pi-packages/commit/b832a437c97378f701033ef8e98c6f7805d7e7a8))
+
 ## [17.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v17.2.0...pi-subagents-v17.3.0) (2026-06-22)
 
 

package/docs/architecture/architecture.md

@@ -918,9 +918,9 @@ The end state deletes `agent-menu.ts` — the god-command that bundles four unre
 Rather than surgically mutate that doomed module (and the #1 churn hotspot `index.ts`) once per option, Phase 19 first stands up the replacement surfaces additively, then removes the now-orphaned subtree in a single terminal cut.
 This keeps every responsibility's old surface live until its replacement exists (ADR-0004's no-interim-regression invariant), turns the three replacement steps into genuinely parallel work (none touch `agent-menu.ts`), and reduces `index.ts` edits from four surgical removals to one deregistration.
 
-Seven steps in three phases:
+Seven numbered steps in three phases, plus two follow-ups (Steps 4a–4b) carved from the #445 slice:
 
-- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation (Steps 1–4).
+- **Phase A — stand up replacements (additive):** spike, settings command, background widget, native session navigation and its renderer/source follow-ups (Steps 1–4, 4a–4b).
 - **Phase B — dissolve `/agents` (terminal cut):** delete the orphaned subtree in two deletion commits, one per subtree (Steps 5–6).
 - **Phase C — test health:** consolidate the test clones that survive the cut (Step 7).
 
@@ -987,7 +987,7 @@ Outcome: widget shows only background agents; foreground/widget duplication elim
 
 `Release: independent`
 
-### Step 4 — Implement native session navigation ([#445])
+### ✅ Step 4 — Implement native session navigation ([#445])
 
 Smell: Category C (coupling) — the bespoke `ConversationViewer` re-implements session-transcript rendering when Pi's own machinery targets the already-persisted child session JSONL.
 This step adds the new surface alongside the existing viewer; it does not touch `agent-menu.ts`.
@@ -1013,11 +1013,41 @@ Outcome: operator views any subagent's session through Pi's native machinery —
 Landed ([#445], sliced): #445 shipped the first releasable vertical slice — the `/subagent-sessions` command (`src/ui/session-navigator.ts`), the pure selection/sourcing/text-render core (`src/ui/session-navigation.ts`), and the typed `agentMessages` accessor (`SessionMessage` on `SubagentSession`/`Subagent`).
 It is **live-source only** behind a renderer-agnostic `TranscriptSource` seam, rendered via Pi's `serializeConversation` text.
 With the `manager.listAgents()`-only candidate set, no listed record is ever session-disposed (dispose-and-delete are atomic), so the file-snapshot branch has no reachable caller and was deferred to keep `fallow dead-code` clean.
-Two follow-ups complete the step behind the same seam: (a) upgrade the renderer from `serializeConversation` text to Pi's per-entry TUI components; (b) broaden the candidate set to evicted agents and add the file-snapshot source (`parseSessionEntries` → `buildSessionContext`).
-The step heading stays unchecked until both land.
+Step 4 (#445, the slice) is complete and released (`pi-subagents` v17.3.0); the remaining work is now tracked as two follow-up steps behind the same seam: Step 4a ([#462]) upgrades the renderer from `serializeConversation` text to Pi's per-entry TUI components (gates Step 5 for rendering parity); Step 4b ([#463]) broadens the candidate set to evicted agents and adds the file-snapshot source (`parseSessionEntries` → `buildSessionContext`, independent).
 
 `Release: independent` (spike-gated)
 
+### ✅ Step 4a — Upgrade native-navigation renderer to Pi TUI components ([#462])
+
+Smell: Category C (coupling) — the #445 slice renders the transcript as `serializeConversation` plain text, while the bespoke `ConversationViewer` it replaces renders richer per-message formatting.
+Until the native renderer reaches parity, the terminal cut (Step 5) cannot delete the bespoke viewer without a fidelity regression.
+This step swaps the renderer behind the existing `TranscriptSource` seam (`src/ui/session-navigation.ts` / `session-navigator.ts`) for Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / …); selection and sourcing are untouched.
+
+Gates Step 5: per [ADR-0004]'s no-interim-regression invariant, the native navigator must reach rendering parity with the bespoke viewer before Step 5 deletes it.
+
+Outcome: native session navigation renders at parity with the removed `ConversationViewer`; Step 5 can delete the bespoke viewer with no fidelity regression.
+
+Landed ([#462]): the renderer now mounts Pi's per-entry components (`AssistantMessageComponent` / `ToolExecutionComponent` / `BashExecutionComponent` / `UserMessageComponent` / `CompactionSummaryMessageComponent` / `BranchSummaryMessageComponent` / `SkillInvocationMessageComponent`) into a `Container`, mirroring Pi's own `renderSessionContext` mapping.
+The `TranscriptOverlay` caches that `Container` and rebuilds it on source change only (Pi's `rebuildChatFromMessages` path), keeping the lightweight `◍` streaming indicator.
+Tool calls render with their real `ToolDefinition`, resolved through a dependency-safe `getToolDefinition` read accessor on the record (mirroring `agentMessages`) surfaced on the `TranscriptSource` seam — no inbound call into the core.
+The pure `session-navigation.ts` sheds `renderTranscriptLines`/`serializeConversation`; rendering now lives in the SDK/TUI `session-navigator.ts`, which threads `cwd` from the command context.
+`custom`-role messages are skipped (the bespoke viewer never rendered them either).
+Selection and sourcing are untouched; native navigation now renders at parity, unblocking Step 5 for rendering fidelity.
+
+`Release: independent`
+
+### Step 4b — File-snapshot source for evicted agents ([#463])
+
+Smell: Category C (coupling) — the #445 slice sources transcripts live from `manager.listAgents()` only; an agent evicted by the 10-minute cleanup sweep has a persisted session JSONL but no live record, so it is unreachable.
+This step adds the file-snapshot `TranscriptSource` branch (`parseSessionEntries(readFile(outputFile))` → drop the `SessionHeader` → `buildSessionContext(...).messages`) and broadens the candidate set to enumerate evicted agents, behind the same seam; the renderer is untouched.
+
+Independent: this is a new capability the bespoke viewer never had, so it gates nothing and is not a Step 5 prerequisite.
+Best sequenced after Step 4a (shared renderer), but carries no hard dependency.
+
+Outcome: the operator can view a fully-evicted agent's transcript from its persisted session file; the dual-source design recorded in [ADR-0004] Addendum 2 is fully realized.
+
+`Release: independent`
+
 ### Step 5 — Dissolve `/agents` and remove the conversation-viewer subtree ([#442])
 
 Smell: Category A (dead subsystem) plus Category B (oversized) — once Steps 2–4 re-home all four menu responsibilities, the `/agents` command and everything reachable only from `agent-menu.ts` is an unreferenced subtree.
@@ -1079,20 +1109,25 @@ flowchart LR
     S1["✅ Step 1 - Spike (#446)"]
     S2["✅ Step 2 - Settings command (#447)"]
     S3["✅ Step 3 - Background widget (#444)"]
-    S4["Step 4 - Native session nav (#445)"]
+    S4["✅ Step 4 - Native session nav slice (#445)"]
+    S4a["✅ Step 4a - Renderer to TUI components (#462)"]
+    S4b["Step 4b - File-snapshot source (#463)"]
     S5["Step 5 - Dissolve /agents + viewer (#442)"]
     S6["Step 6 - Remove definition mgmt (#441)"]
     S7["Step 7 - Test clones (#443)"]
 
     S1 --> S4
+    S4 --> S4a
+    S4 --> S4b
     S2 --> S5
     S3 --> S5
-    S4 --> S5
+    S4a --> S5
     S5 --> S6
     S6 --> S7
 ```
 
-The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation (Step 4) — because each of the four `/agents` options must have its responsibility re-homed before its branch can die.
+The terminal cut (Step 5) depends on all three replacements — settings (Step 2), widget (Step 3), and session navigation **at rendering parity** (Step 4a, which completes the #445 slice) — because each of the four `/agents` options must have its responsibility re-homed, and the viewer replacement at parity, before its branch can die.
+Step 4b (file-snapshot source) is a new capability and gates nothing.
 The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes it explicit.
 
 ### Parallel tracks
@@ -1100,6 +1135,7 @@ The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes i
 - **Track A — Replacements (Steps 1–4):** the spike gates session navigation (Step 1 → Step 4); settings (Step 2) and the background widget (Step 3) are independent of the spike and of each other.
   None of these steps edits `agent-menu.ts`, so they carry no shared-file collision on the menu — genuinely parallelizable, unlike the prior plan's Steps 2/3/5, which all collided on `agent-menu.ts` and `index.ts`.
   Steps 2 and 4 each append a command registration to `index.ts` (additive, low-conflict).
+  Steps 4a (renderer parity) and 4b (file-snapshot source) complete the #445 slice behind its `TranscriptSource` seam; Step 4a gates Step 5, Step 4b is independent.
 - **Track B — Dissolution (Steps 5 → 6):** the terminal cut, gated on all of Track A landing.
   Hub-first ordering is forced: Step 5 deletes `agent-menu.ts` (orphaning the leaves), then Step 6 `git rm`s the now-orphaned definition-management subtree.
 - **Track C — Test health (Step 7):** clone consolidation, run after the cut so no surviving helper is extracted into a doomed file.
@@ -1108,7 +1144,7 @@ The old `S1 → S6 → S7` chain hid the widget dependency; this diagram makes i
 
 - **Batch "dissolve-agents":** Steps 5, 6 (ship together; tail = Step 6).
   Depends on Steps 2, 3, 4 already merged.
-- Independently releasable: Steps 1, 2, 3, 4, 7.
+- Independently releasable: Steps 1, 2, 3, 4, 4a, 4b, 7.
 
 ## Refactoring history
 
@@ -1230,5 +1266,7 @@ The upstream test suite is run periodically as a regression canary for the sessi
 [#445]: https://github.com/gotgenes/pi-packages/issues/445
 [#446]: https://github.com/gotgenes/pi-packages/issues/446
 [#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463
 [ADR-0002]: ../decisions/0002-extensions-on-a-minimal-core.md
 [ADR-0004]: ../decisions/0004-reconsider-ui-direction.md

package/docs/plans/0462-navigation-renderer-tui-components.md

@@ -0,0 +1,338 @@
+---
+issue: 462
+issue_title: "pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components"
+---
+
+# Upgrade `/subagent-sessions` renderer to Pi per-entry TUI components
+
+## Release Recommendation
+
+**Release:** ship independently
+
+Phase 19 Step 4a ([#462]) carries `Release: independent` in the architecture roadmap.
+It swaps the renderer behind the existing `TranscriptSource` seam; it is not a member of Phase 19's only batch ("dissolve-agents", Steps 5–6, [#442]/[#441]).
+Step 4a gates Step 5 ([#442]) for rendering parity, but a gate is a sequencing dependency, not a release batch — this step ships on its own once it lands.
+
+## Problem Statement
+
+The #445 slice ([#445]) stood up native session navigation — list → pick → read-only scrollable transcript — behind a renderer-agnostic `TranscriptSource` seam, using Pi's `serializeConversation` plain text as the first renderer.
+That text dump is lower fidelity than the bespoke `ConversationViewer` it is slated to replace, which renders richer per-message formatting (tool call/result blocks, bash execution, markdown).
+ADR-0004 Decision B's full intent is native-fidelity rendering through Pi's **own** interactive components ([ADR-0004] Addendum, Finding 1): `AssistantMessageComponent`, `ToolExecutionComponent`, `UserMessageComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, and the skill-block components.
+This follow-up swaps the renderer behind the same seam — selection and sourcing are untouched — so the native navigator reaches rendering parity with the bespoke viewer, which unblocks Step 5's deletion of that viewer without a fidelity regression.
+
+## Goals
+
+- Replace the `serializeConversation` text path with a per-entry Pi TUI component tree, mirroring Pi's own `renderSessionContext` message→component mapping.
+- Drive the component tree by **rebuild-on-change**: on each `TranscriptSource` change, clear and reconstruct the cached component `Container` from the current message snapshot (Pi's own `rebuildChatFromMessages` path); each paint reuses the cached tree, so markdown highlighting does not re-run per frame.
+- Render tool calls at full fidelity by passing each tool's real `ToolDefinition`, sourced through a new dependency-safe `getToolDefinition` read accessor on the record (mirroring the existing `agentMessages` accessor) and surfaced on the `TranscriptSource` seam.
+- Keep the existing lightweight `◍ describeActivity` streaming-indicator line for a running agent's live activity (the high-frequency streaming text it absorbs is why rebuild-on-change stays cheap).
+- Confirm rendering parity with the bespoke `ConversationViewer` so Step 5 ([#442]) can delete it with no fidelity regression.
+
+Non-breaking: this is an internal renderer swap behind the seam.
+No public export, command name, default, or observable behavior changes.
+The internal `renderTranscriptLines` export is removed, but its only consumers are within this package (the overlay and its tests).
+
+## Non-Goals
+
+- Do **not** implement the **file-snapshot** source branch (`parseSessionEntries` → `buildSessionContext`) or broaden the candidate set to evicted agents — that is Step 4b ([#463]), independent and unblocked by this step.
+- Do **not** add in-session steering or any interactive gesture — the overlay stays strictly read-only; steering remains in `steer_subagent` and the widget.
+- Do **not** touch `agent-menu.ts`, `conversation-viewer.ts`, or `message-formatters.ts` — they stay live until the terminal cut (Step 5, [#442]).
+- Do **not** change `listNavigableAgents` selection or the `liveSource` sourcing semantics — only the renderer changes, plus the additive `getToolDefinition` accessor.
+- Do **not** render `custom`-role messages through `CustomMessageComponent` — it requires the session's `extensionRunner.getMessageRenderer`, which the navigator does not hold (see Open Questions); custom messages are skipped, matching the bespoke viewer, which never rendered them either.
+
+## Background
+
+Relevant existing modules:
+
+- `src/ui/session-navigation.ts` (pure) — owns selection and sourcing: `listNavigableAgents`, `liveSource`, and the interfaces `NavigableSubagent`, `NavigationEntry`, `StreamingState`, `TranscriptSource`.
+  It currently also owns `renderTranscriptLines(source): string[]` (the `serializeConversation` text path) and its `toMessages` adapter — these are text rendering via a pure SDK utility.
+- `src/ui/session-navigator.ts` (SDK/TUI consumer) — owns `TranscriptOverlay` (a read-only scrollable `Component`) and `SessionNavigatorHandler`.
+  `TranscriptOverlay.buildContentLines` currently calls `renderTranscriptLines(this.source)`, then wraps each line with the injected `wrapText`.
+- `src/lifecycle/subagent-session.ts` — `SubagentSession` wraps `_session: AgentSession`.
+  It already exposes `get agentMessages(): readonly SessionMessage[]` returning `this._session.messages`.
+  The SDK `AgentSession` exposes `getToolDefinition(name: string): ToolDefinition | undefined` (a definition-first registry retained per session).
+- `src/lifecycle/subagent.ts` — `Subagent` delegates `get agentMessages()` to `this.subagentSession?.agentMessages ?? []`; this is the exact pattern the new `getToolDefinition` accessor follows.
+- `src/ui/display.ts` — `describeActivity(activeTools, responseText)`, `getDisplayName`, `formatDuration`.
+- `src/index.ts` — registers the `subagent-sessions` command; the handler already receives `ctx` (which carries `ctx.cwd: string` and `ctx.ui`).
+
+Pi SDK facts verified for this plan (against the bundled `@earendil-works/pi-coding-agent`):
+
+- The per-entry components are all re-exported from the public root barrel: `AssistantMessageComponent`, `UserMessageComponent`, `ToolExecutionComponent`, `BashExecutionComponent`, `CompactionSummaryMessageComponent`, `BranchSummaryMessageComponent`, `SkillInvocationMessageComponent`, `CustomMessageComponent`.
+  `parseSkillBlock`, `getMarkdownTheme`, and the `ToolDefinition` type are also public.
+- Component constructors are heterogeneous and stateful (`Container` subclasses):
+  - `AssistantMessageComponent(message?, hideThinkingBlock?, markdownTheme?, hiddenThinkingLabel?)`.
+  - `UserMessageComponent(text: string, markdownTheme?)`.
+  - `ToolExecutionComponent(toolName, toolCallId, args, options, toolDefinition, ui: TUI, cwd: string)`, with `updateResult(result)` called separately to attach the tool result.
+  - `BashExecutionComponent(command, ui: TUI, excludeFromContext?)`, with `appendOutput` / `setComplete`.
+  - `CompactionSummaryMessageComponent(message, markdownTheme?)` / `BranchSummaryMessageComponent(message, markdownTheme?)`.
+- Pi's own message→component mapping is `interactive-mode.ts`'s `renderSessionContext(sessionContext)` (and the `addMessageToChat` helper it calls); `rebuildChatFromMessages()` is `chatContainer.clear()` + `renderSessionContext(buildSessionContext())`.
+  This plan mirrors that mapping; the `toolResult` → pending-tool match (`renderedPendingTools.get(toolCallId).updateResult(message)`) is reproduced.
+- `Container` (from `@earendil-works/pi-tui`) exposes `addChild`, `clear`, and `render(width): string[]`, which stacks children vertically — so a `Container` of per-entry components renders to the `string[]` the existing scroll overlay already consumes.
+- No higher-level "message list" / "transcript" renderer is exported from the SDK — the mapping must be mirrored, not imported.
+
+AGENTS.md / package constraints:
+
+- pi-subagents is a minimal core; the navigator is an in-core reactive consumer with **no inbound call** into the core.
+  The new `getToolDefinition` accessor is a read-only getter (like `agentMessages`) — it adds no inbound call and preserves the Phase 18 spine invariants ([#422]–[#425]).
+  This is the dependency-safe answer to "wire real tool definitions": arrows still point inward (navigator → record getter → wrapped `AgentSession.getToolDefinition`); `SubagentManager` tracks nothing extra and no dependency is inverted.
+- Keep Pi SDK *coupling* out of pure helpers: per-entry components require a `TUI`, `cwd`, and `markdownTheme`, so the component-building renderer lives in the SDK/TUI module `session-navigator.ts`, not in the pure `session-navigation.ts`.
+  The `serializeConversation` text renderer leaves the pure module entirely.
+- Use narrow interface types (not the concrete `Subagent`) at the seam — unchanged from the slice.
+
+## Design Overview
+
+The `TranscriptSource` seam is the change point.
+Its sourcing surface (`getMessages` / `subscribe` / `streaming`) is unchanged except for one additive method (`getToolDefinition`); the **renderer** moves from the pure module into the SDK/TUI module and changes shape from text to a component tree.
+
+### Dependency-safe tool definitions
+
+The SDK `AgentSession` already retains a definition-first tool registry and exposes `getToolDefinition(name)`.
+A new read accessor surfaces it through the record, mirroring `agentMessages`:
+
+```typescript
+// SubagentSession
+getToolDefinition(name: string): ToolDefinition | undefined {
+  return this._session.getToolDefinition(name);
+}
+
+// Subagent
+getToolDefinition(name: string): ToolDefinition | undefined {
+  return this.subagentSession?.getToolDefinition(name);
+}
+```
+
+This is a pure outward read — no inbound call, no `SubagentManager` bookkeeping, no dependency inversion.
+
+### Seam: `TranscriptSource` gains `getToolDefinition`
+
+`TranscriptSource` (and the `NavigableSubagent` record interface it sources from) gain the lookup; `liveSource` delegates to the record:
+
+```typescript
+export interface TranscriptSource {
+  getMessages(): readonly SessionMessage[];
+  subscribe(onChange: () => void): (() => void) | undefined;
+  streaming(): StreamingState | undefined;
+  getToolDefinition(name: string): ToolDefinition | undefined; // new
+}
+```
+
+A future file-snapshot source (Step 4b) returns `undefined` here → generic fallback tool rendering, with no renderer change.
+Placing the lookup on the seam (not on the renderer's separate params) keeps the seam the single change point across both follow-ups.
+
+### Renderer: per-entry component tree (`session-navigator.ts`)
+
+A new function builds a `Container` of per-entry components from a message snapshot, mirroring `renderSessionContext`:
+
+```typescript
+function buildTranscriptComponents(
+  messages: readonly SessionMessage[],
+  opts: { tui: TUI; cwd: string; markdownTheme: MarkdownTheme; getToolDefinition: (name: string) => ToolDefinition | undefined },
+): Container {
+  const container = new Container();
+  const pendingTools = new Map<string, ToolExecutionComponent>();
+  for (const message of messages) {
+    switch (message.role) {
+      case "assistant": { /* AssistantMessageComponent + per-toolCall ToolExecutionComponent (track pending by id) */ }
+      case "toolResult": { /* pendingTools.get(toolCallId)?.updateResult(message) */ }
+      case "user": { /* parseSkillBlock → SkillInvocation(+UserMessage) | UserMessageComponent */ }
+      case "bashExecution": { /* BashExecutionComponent + appendOutput + setComplete */ }
+      case "compactionSummary": { /* CompactionSummaryMessageComponent */ }
+      case "branchSummary": { /* BranchSummaryMessageComponent */ }
+      // custom: skipped (no message renderer available — see Open Questions)
+    }
+  }
+  return container;
+}
+```
+
+`ToolExecutionComponent` is constructed with `opts.getToolDefinition(content.name)` for its definition, `opts.tui`, and `opts.cwd`, and `{ showImages: false }` (the read-only viewer does not render images).
+Spacers between entries follow Pi's own spacing in `addMessageToChat`.
+
+### Overlay: rebuild-on-change with a cached `Container`
+
+`TranscriptOverlay` caches the component tree and rebuilds it only when the source changes — never per frame:
+
+```typescript
+// constructor: build once, then subscribe
+this.content = this.rebuild();
+this.unsubscribe = source.subscribe(() => {
+  if (this.closed) return;
+  this.content = this.rebuild();      // rebuild on change only
+  this.tui.requestRender();
+});
+
+private rebuild(): Container {
+  return buildTranscriptComponents(this.source.getMessages(), {
+    tui: this.tui, cwd: this.cwd, markdownTheme: this.markdownTheme,
+    getToolDefinition: (name) => this.source.getToolDefinition(name),
+  });
+}
+
+private buildContentLines(innerW: number): string[] {
+  const lines = this.content.render(innerW);           // components own their own wrapping
+  const streaming = this.source.streaming();
+  if (streaming) lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+  return lines.map((l) => truncateToWidth(l, innerW)); // defensive truncate; no re-wrap
+}
+```
+
+The per-frame `render(width)` chrome (header/footer/scroll math) is unchanged; only the content source changes from `renderTranscriptLines(source)` to the cached `Container`.
+Because the components already wrap to width, the overlay no longer re-wraps each line — the injected `wrapText` collaborator is removed from `TranscriptOverlayOptions` and the handler call site.
+
+### Handler / registration
+
+`SessionNavigatorParams` gains `cwd: string`; `index.ts` passes `ctx.cwd`:
+
+```typescript
+await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry, cwd: ctx.cwd });
+```
+
+The handler obtains `markdownTheme` via `getMarkdownTheme()` (current theme; Pi has initialized it at startup) and threads `cwd` + `markdownTheme` into the `TranscriptOverlay` it mounts through `ui.custom`.
+`manager.listAgents()` is still called in the registration, never inside the navigator — the navigator stays a reactive consumer with no inbound core call.
+
+### Consumer call-site sketch (Tell-Don't-Ask / LoD check)
+
+The renderer talks only to `TranscriptSource`: it reads `source.getMessages()` and `source.getToolDefinition(name)`, never reaching through the record to a stranger.
+`liveSource.getToolDefinition` delegates to `record.getToolDefinition` (the record's own getter), which delegates to the wrapped `AgentSession` internally — a one-hop delegation, not a `record.session.x.y` chain.
+No output arguments: the renderer constructs and returns a `Container`; nothing writes back into the record or the source.
+
+### Design-review findings
+
+| Smell                          | Location                       | Evidence                                                                                             | Result                                                            |
+| ------------------------------ | ------------------------------ | ---------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Dependency width               | `TranscriptSource` (4 methods) | renderer reads `getMessages`/`streaming`/`getToolDefinition`; overlay reads `subscribe`              | Acceptable — cohesive sourcing seam; every method is a real read  |
+| LoD violation                  | `liveSource.getToolDefinition` | one-hop delegation `record.getToolDefinition` → `AgentSession.getToolDefinition`                     | None — delegation through the record's own getter, no chain       |
+| Output argument                | `buildTranscriptComponents`    | returns a `Container`; `updateResult` mutates the tool component it owns, not a received bag         | None                                                              |
+| Concrete-class leak            | seam interfaces                | renderer depends on `TranscriptSource`, not the concrete `Subagent`                                  | None — narrow interface                                           |
+| Pi SDK coupling in pure module | `session-navigation.ts`        | component rendering moves out to `session-navigator.ts`; pure module keeps selection + sourcing only | Improved — pure module sheds the `serializeConversation` renderer |
+
+The new collaborator (`buildTranscriptComponents`) gives behavior to data — it maps message data to stateful components and returns a renderable tree — not procedure-splitting.
+
+### Edge cases
+
+- Empty history (`getMessages()` is `[]`) → empty `Container`; the overlay renders an empty viewport (no crash); the existing "no sessions" notify path is unchanged at the selection layer.
+- Running agent → component tree for finalized messages plus the appended `◍ describeActivity` indicator; a `subscribeToUpdates` event rebuilds the tree and re-renders.
+- A partially-streamed assistant message present in `getMessages()` → rendered by `AssistantMessageComponent`; the indicator also shows activity (parity with the bespoke viewer, which showed both).
+- `toolResult` with no matching pending tool (out-of-order / truncated history) → no-op (matches Pi's `renderedPendingTools.get` miss).
+- `getToolDefinition` returns `undefined` (definition not registered, or a future file source) → `ToolExecutionComponent` generic fallback rendering.
+- Very narrow terminal width → `render` returns `[]` below the minimum width (unchanged chrome guard).
+
+## Module-Level Changes
+
+- **Changed** `src/types.ts` — re-export or reference the SDK `ToolDefinition` type for the seam interfaces (import from `@earendil-works/pi-coding-agent`); confirm a consumer imports it from the barrel if added there (no speculative re-export).
+- **Changed** `src/lifecycle/subagent-session.ts` — add `getToolDefinition(name): ToolDefinition | undefined` delegating to `this._session.getToolDefinition(name)`.
+- **Changed** `src/lifecycle/subagent.ts` — add `getToolDefinition(name): ToolDefinition | undefined` delegating to `this.subagentSession?.getToolDefinition(name)`.
+- **Changed** `src/ui/session-navigation.ts` — add `getToolDefinition` to `NavigableSubagent` and `TranscriptSource`; `liveSource` delegates it.
+  **Remove** `renderTranscriptLines`, its `toMessages` adapter, and the `serializeConversation` + `describeActivity` imports (rendering moves to `session-navigator.ts`).
+- **Changed** `src/ui/session-navigator.ts` — add `buildTranscriptComponents`; rewrite `TranscriptOverlay` to cache + rebuild the `Container` (drop `wrapText` from `TranscriptOverlayOptions`); add `describeActivity`, `getMarkdownTheme`, `Container`, and the per-entry component imports; add `cwd` (+ `markdownTheme` wiring) to `SessionNavigatorParams`/the overlay.
+- **Changed** `src/index.ts` — pass `cwd: ctx.cwd` into `sessionNavigator.handle(...)`.
+- **Changed** `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts` — add `getToolDefinition` accessor tests.
+- **Changed** `test/ui/session-navigation.test.ts` — remove the `renderTranscriptLines` describe block; add `liveSource.getToolDefinition` delegation; add `getToolDefinition` to the `makeNavigable` factory.
+- **Changed** `test/ui/session-navigator.test.ts` — assert component-rendered content (text still appears via markdown), add a tool-call render test (stub `getToolDefinition`), add `getToolDefinition` to `fakeSource`/`makeNavigable`, pass `cwd` in handler tests, drop `wrapText`.
+
+Removed-symbol grep: `renderTranscriptLines` is the sole removed export.
+Its consumers are `src/ui/session-navigator.ts` (rewritten this issue) and `test/ui/session-navigation.test.ts` (block removed); confirmed no other `src/`/`test/` references and no `.pi/skills/package-pi-subagents/SKILL.md` mention.
+
+Doc / skill updates:
+
+- `docs/architecture/architecture.md` — flip Step 4a's status to landed (mirroring the Step 4 "Landed" note style) and update the Phase 19 Mermaid node label `S4a` from pending to done; record that the native navigator now renders at parity, unblocking Step 5.
+  Defer the status-line/Mermaid flip to ship time if preferred (matches the [#447] precedent), but the rescoping note belongs in this issue's doc step.
+- `.pi/skills/package-pi-subagents/SKILL.md` — the UI domain count is a coarse summary (no file added or removed here); leave unless the operator asks otherwise.
+
+## Test Impact Analysis
+
+1. **New tests enabled.**
+   The `getToolDefinition` accessor gets direct unit tests on `SubagentSession` and `Subagent` (mirroring `agentMessages`).
+   The component renderer is exercised through `TranscriptOverlay` against a `fakeSource` — asserting that message text renders (via the components) and that a tool call renders with its definition.
+2. **Existing tests that become redundant.**
+   The `renderTranscriptLines` describe block in `session-navigation.test.ts` is removed — the function it tests is gone (rendering moved and changed shape).
+   No other tests become redundant.
+3. **Existing tests that must stay as-is.**
+   `listNavigableAgents` and `liveSource` selection/sourcing tests stay (selection and sourcing semantics are unchanged; `liveSource` only gains the `getToolDefinition` delegation).
+   All bespoke-viewer and menu tests (`conversation-viewer.test.ts`, `message-formatters.test.ts`, `agent-menu.test.ts`) stay untouched — Step 5 deletes those.
+
+## Invariants at risk
+
+This issue swaps a renderer behind the seam, adds one read accessor, and threads `cwd`; it does not touch the Phase 18 spine.
+The relevant `Outcome:` invariants and their pins:
+
+- **[#422] — runtime holds zero UI state.**
+  The overlay holds its own cached `Container` + scroll state; nothing is pushed onto the runtime.
+  Pinned by the runtime/service-spine tests; unchanged.
+- **[#423] — UI is a reactive consumer with no inbound calls from core spawn tools.**
+  The navigator reads via the injected `manager.listAgents()` snapshot and record getters only; the new `getToolDefinition` accessor is a read-only getter.
+  Pinned by the navigator-reads-only test from the slice (extend it to assert the handler reads `getToolDefinition` only through the source).
+- **[#424] — the `subagent` tool depends only on manager/runtime/settings/registry.**
+  No tool change.
+- **[#425] — declared event channels equal emitted channels, no vacant hook.**
+  The navigator subscribes to existing record updates; it declares/emits no new channel.
+  Pinned by the events-contract suite; unchanged.
+
+A later phase step (Step 4b file source, Step 5 deletion) must not regress these with a green suite — the navigator-reads-only test pins #423 for the seam.
+
+## TDD Order
+
+1. **Red→Green: `getToolDefinition` read accessor on the record.**
+   Test surface: `test/lifecycle/subagent-session.test.ts`, `test/lifecycle/subagent.test.ts`.
+   Tests: `SubagentSession.getToolDefinition` delegates to the wrapped session; `Subagent.getToolDefinition` delegates to the session and returns `undefined` when no session.
+   Implementation: reference the SDK `ToolDefinition` type (via `src/types.ts` or a direct import); add the two getters.
+   Run `pnpm run check` (verifies `AgentSession.getToolDefinition` resolves).
+   Commit: `feat: add getToolDefinition accessor on subagent record (#462)`.
+2. **Red→Green: surface `getToolDefinition` on the seam (additive).**
+   Test surface: `test/ui/session-navigation.test.ts`.
+   Tests: `liveSource.getToolDefinition` delegates to `record.getToolDefinition`; add `getToolDefinition` to the `makeNavigable` factory.
+   Implementation: add `getToolDefinition` to `NavigableSubagent` and `TranscriptSource`; `liveSource` delegates.
+   This step is pure addition — `renderTranscriptLines` still exists and compiles.
+   Commit: `feat: expose getToolDefinition on the transcript source seam (#462)`.
+3. **Red→Green: component-tree renderer + overlay rewrite + `cwd` wiring.**
+   Test surface: `test/ui/session-navigator.test.ts` (+ remove the `renderTranscriptLines` block from `test/ui/session-navigation.test.ts`).
+   Tests:
+   - `TranscriptOverlay.render` paints component-rendered content for user/assistant messages (text appears); a tool call renders via `ToolExecutionComponent` using a stubbed `getToolDefinition`; the `◍` streaming indicator still appends while running; rebuild-on-change re-renders after a `subscribe` callback; `esc`/`q` calls `done`; `dispose` unsubscribes.
+   - `SessionNavigatorHandler.handle`: empty entries → `notify`, no `custom`; cancel → no `custom`; valid pick → `custom` opened with an overlay sourced from the picked record and the passed `cwd`.
+   Implementation (one commit — removing `renderTranscriptLines` breaks the overlay and its tests at the type level, so the rewrite, the export removal, the test updates, and the `index.ts` call-site update land together):
+   - Add `buildTranscriptComponents` and rewrite `TranscriptOverlay` (cached `Container`, rebuild-on-change, drop `wrapText`) in `session-navigator.ts`.
+   - Remove `renderTranscriptLines`/`toMessages`/`serializeConversation`/`describeActivity` from `session-navigation.ts`.
+   - Add `cwd` to `SessionNavigatorParams`; update `index.ts` to pass `ctx.cwd`.
+   - Remove the `renderTranscriptLines` describe block from `session-navigation.test.ts`.
+   Run `pnpm run check` immediately (shared-interface + single-call-site change) and `pnpm fallow dead-code` before pushing (confirms no orphaned helper after the renderer move).
+   Commit: `feat: render /subagent-sessions transcript with Pi per-entry components (#462)`.
+4. **Docs: record rendering parity and flip Step 4a.**
+   Test surface: none (docs).
+   Update `docs/architecture/architecture.md` Step 4a status to landed and the `S4a` Mermaid node; note the native navigator now renders at parity, unblocking Step 5.
+   Commit: `docs: mark native-navigation renderer upgrade landed (#462)`.
+
+## Risks and Mitigations
+
+- **Risk: Pi's per-entry components depend on interactive-mode globals (e.g. `initTheme`) not initialized in this context.**
+  Mitigation: the navigator runs inside a live Pi session where theme is already initialized; `getMarkdownTheme()` returns the active theme.
+  The overlay-render tests construct components against a mock `TUI` and assert text appears — a smoke test that the components render outside interactive mode.
+  If a component throws without a global, narrow the role set or supply the missing default at the boundary.
+- **Risk: rebuilding the component tree re-runs markdown highlighting and is expensive under live streaming.**
+  Mitigation: rebuild happens on **source change only** (cached `Container`), not per frame, and the high-frequency streaming text is absorbed by the `◍` indicator (so the tree changes at message granularity).
+  Incremental `updateContent`/`updateResult` reconciliation remains a clean follow-up behind the same seam if profiling ever shows cost (track-and-watch).
+- **Risk: `ToolExecutionComponent` needs `cwd`/`tui`/options not previously threaded.**
+  Mitigation: `cwd` comes from `ctx.cwd` (verified present on the command context), `tui` from the `ui.custom` factory, options default to `{ showImages: false }`.
+- **Risk: removing `renderTranscriptLines` and its tests leaves orphaned imports.**
+  Mitigation: Step 3 removes the `serializeConversation`/`describeActivity` imports from `session-navigation.ts` in the same commit; `pnpm fallow dead-code` and a re-read of the file confirm no orphans (Biome `noUnusedImports` is warning-level).
+- **Risk: parity is asserted only by "text appears", missing richer formatting differences.**
+  Mitigation: the goal is *native-fidelity via Pi's own components* — using the same components Pi uses **is** the parity definition; the tests assert the component path is taken (tool call renders via `ToolExecutionComponent`, bash via `BashExecutionComponent`), not byte-equality with the bespoke output.
+
+## Open Questions
+
+- **`custom`-role messages** — `CustomMessageComponent` requires the session's `extensionRunner.getMessageRenderer(customType)`, which the navigator does not hold.
+  This issue skips custom messages (the bespoke viewer never rendered them either, so this is not a parity regression).
+  If custom-message fidelity is later wanted, a follow-up would surface a message-renderer lookup on the seam — not filed now (speculative).
+- **Step 4a doc flip timing** — flip the architecture status line and Mermaid node in this issue's doc step, or defer to a Phase 19 doc-sync ([#447] precedent); the plan does it in-issue (TDD step 4) by default.
+
+[#441]: https://github.com/gotgenes/pi-packages/issues/441
+[#442]: https://github.com/gotgenes/pi-packages/issues/442
+[#445]: https://github.com/gotgenes/pi-packages/issues/445
+[#447]: https://github.com/gotgenes/pi-packages/issues/447
+[#462]: https://github.com/gotgenes/pi-packages/issues/462
+[#463]: https://github.com/gotgenes/pi-packages/issues/463
+[#422]: https://github.com/gotgenes/pi-packages/issues/422
+[#423]: https://github.com/gotgenes/pi-packages/issues/423
+[#424]: https://github.com/gotgenes/pi-packages/issues/424
+[#425]: https://github.com/gotgenes/pi-packages/issues/425
+
+[ADR-0004]: https://github.com/gotgenes/pi-packages/blob/main/packages/pi-subagents/docs/decisions/0004-reconsider-ui-direction.md

package/docs/retro/0445-native-session-navigation.md

@@ -55,3 +55,68 @@ Pre-completion reviewer returned PASS.
 - **Reviewer verdict: PASS.**
   Two WARN notes, both intentional and plan-sanctioned: Step 4 heading unchecked (correct for a partial slice) and the deferred `SKILL.md` count.
 - **Open at ship time:** confirm command name `subagent-sessions`; file the two follow-up issues (component renderer; evicted-agent file source).
+
+## Stage: User Note (2026-06-22T18:26:37Z)
+
+When new issues are identified during planning, file them before leaving the planning stage rather than deferring to ship time.
+Two motivations: the planning session uses a very capable model, and it already has all the context needed to write the issues well.
+Applied here: the two follow-up issues (#462 renderer upgrade, #463 file-snapshot source) were identified during planning but filed only at ship time — they should have been created at the end of the planning commit instead.
+
+## Stage: Final Retrospective (2026-06-22T18:28:31Z)
+
+### Session summary
+
+One continuous session carried #445 from planning through TDD, ship, and a mid-session retro note.
+It delivered the sliced Phase 19 Step 4 — the `/subagent-sessions` command, the live `TranscriptSource`, and the typed `agentMessages` accessor — across three `feat:` commits plus docs, released as `pi-subagents` v17.3.0, with two follow-ups (#462, #463) filed at ship.
+Execution was notably clean: the plan anticipated both hard risks, and every implementation slip was absorbed by the feedback loops within its active TDD cycle.
+
+### Observations
+
+#### What went well
+
+1. **The plan pre-empted the two hardest risks.**
+   `AgentMessage`→`Message` non-assignability and the unreachable file-snapshot branch were both called out in planning and both materialized exactly as predicted; the planned mitigations (the `toMessages` adapter; shipping the live source only) applied with zero rework.
+2. **The `TranscriptSource` seam earned its keep.**
+   The pure `session-navigation.ts` was unit-tested with light stubs (no full `Subagent`/`TUI`/`AgentSession`), and the seam cleanly hosts both deferred follow-ups — testability justified it independent of the follow-ups.
+3. **Tight, incremental feedback loops.**
+   Per-cycle affected-file test runs, `pnpm run check` after every type-touching step, and full suite + lint + `fallow dead-code` after the last step caught every slip within seconds.
+4. **Two `ask_user` rounds during planning converted a large issue into a releasable slice** (the operator's Kent Beck nudge) — the central design win of the issue.
+
+#### What caused friction (agent side)
+
+1. `missing-context` — wrote test assertions before checking helper behavior: `formatMs` yields `3.0s` not `3s`, `getDisplayName` falls back to `Agent`, `TOOL_DISPLAY` keys are lowercase, and `AgentTypeRegistry` takes `() => new Map()` not `() => []`.
+   Impact: ~4 assertion fixes within one Green iteration; no rework beyond the cycle.
+2. `missing-context` — `SessionContext` name collision: imported the SDK type into `types.ts` without noticing a local `SessionContext` interface already existed.
+   Impact: one aliasing edit (`SdkSessionContext`), caught immediately by biome `noRedeclare`.
+3. `other` (mechanical) — a stray `}` when wrapping a new `describe` block (AGENTS.md already warns about brace-pair edits), and `SessionMessage` imported from the wrong module in the navigator test.
+   Impact: one fix each, caught by autoformat and `tsc`.
+4. `instruction-violation` (self-identified, hook-caught) — two lint nits the `testing` skill already documents: an unnecessary optional chain and an unnecessary `!` on `mock.calls[0][0]`.
+   Impact: two inline fixes; no rework.
+
+None of the agent-side slips caused rework beyond their active TDD cycle — the autoformat/biome/`tsc`/vitest/pre-commit loops absorbed all of them.
+
+#### What caused friction (user side)
+
+1. The dominant cross-session finding (recorded separately as the User Note stage): follow-up issues identified during planning (#462, #463) were filed only at ship time.
+   The workflow itself encodes the deferral — the plan said "file at ship time" and `/ship-issue` step 4c creates them.
+   The operator wants them filed during planning, while the capable planning model still holds full context.
+   Opportunity: move follow-up creation into `/plan-issue`.
+
+### Diagnostic details
+
+- **Model-performance correlation** — the only subagent dispatch was the `pre-completion-reviewer` on `anthropic/claude-sonnet-4-6`, a judgment-heavy review task; appropriate match.
+  Planning ran on a capable model, which the operator explicitly values.
+  No mismatch.
+- **Escalation-delay tracking** — no rabbit-holes; the longest same-area sequence was 4 assertion fixes inside one Green iteration (under the 5-call flag).
+- **Unused-tool detection** — the `missing-context` slips were caught trivially by running tests; reading `display.ts` helpers first would have pre-empted them, but the cost was negligible and no Explore/`colgrep` dispatch was warranted.
+- **Feedback-loop gap analysis** — verification ran incrementally and completely (per-cycle tests, `check` after type changes, full gate after the last step); no gap.
+  This is a win, not a gap.
+
+### Changes made
+
+Moved follow-up issue creation from ship time to planning time, with the backstop relocated to pre-completion (operator-directed):
+
+1. `.pi/prompts/plan-issue.md` — added a `## File follow-up issues` section before `## Commit`: file plan-named follow-ups during planning with `gh issue create` and record each number in the plan; nothing speculative.
+2. `.pi/agents/pre-completion-reviewer.md` — added checklist section `2i. Planned follow-up issues` and its report stanza: WARN when the plan names a follow-up but records no issue number; also added the case to the severity model's WARN list.
+3. `.pi/prompts/ship-issue.md` — removed step `4c. Create planned follow-up issues` (follow-ups are now filed during planning; the close comment in step 5 references the recorded numbers).
+4. `AGENTS.md` — extended the pre-completion-reviewer coverage enumeration to include planned follow-up filing.

package/docs/retro/0462-navigation-renderer-tui-components.md

@@ -0,0 +1,49 @@
+---
+issue: 462
+issue_title: "pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components"
+---
+
+# Retro: #462 — pi-subagents: upgrade /subagent-sessions renderer to Pi per-entry TUI components
+
+## Stage: Planning (2026-06-22T00:00:00Z)
+
+### Session summary
+
+Planned Phase 19 Step 4a: swap the `/subagent-sessions` renderer from `serializeConversation` plain text to Pi's per-entry TUI components behind the existing `TranscriptSource` seam.
+Verified the SDK surface (per-entry components, `parseSkillBlock`, `getMarkdownTheme`, `ToolDefinition`, `AgentSession.getToolDefinition`) and mirrored Pi's own `renderSessionContext`/`rebuildChatFromMessages` mapping.
+Wrote a four-step TDD plan at `packages/pi-subagents/docs/plans/0462-navigation-renderer-tui-components.md` and committed it.
+
+### Observations
+
+- Three design decisions were surfaced via `ask_user` and locked by the operator:
+  1. **Rebuild-on-change** (mirror Pi's `rebuildChatFromMessages`) over incremental `updateContent`/`updateResult` — the seam exposes only a full `getMessages()` snapshot plus a coarse `onChange`, so incremental would still diff snapshots while replicating Pi's `pendingTools` streaming state machine for marginal benefit.
+  2. **Keep the lightweight `◍ describeActivity` text indicator** — this absorbs the high-frequency streaming text, so the persisted component tree only changes at message granularity, which is what keeps rebuild-on-change cheap.
+  3. **Wire real tool definitions** — the operator flagged a dependency-inversion risk ("can't `SubagentManager` track this?").
+     Resolved dependency-safely: the SDK `AgentSession` already exposes `getToolDefinition(name)`, so a new read accessor on `SubagentSession`/`Subagent` (mirroring the existing `agentMessages` accessor) surfaces it through the record and onto the `TranscriptSource` seam — arrows stay inward, no `SubagentManager` bookkeeping.
+- Key structural move: the component renderer must leave the pure `session-navigation.ts` (per-entry components need `TUI`/`cwd`/`markdownTheme`) and live in the SDK/TUI `session-navigator.ts`.
+  The pure module sheds `renderTranscriptLines`/`serializeConversation` entirely, becoming selection + sourcing only.
+- The `renderTranscriptLines` removal, overlay rewrite, `session-navigation.ts` edits, `index.ts` `cwd` wiring, and test updates must land in **one commit** (TDD step 3) — removing the export breaks the overlay and its tests at the type level.
+- Non-breaking internal renderer swap; `Release: independent` per the roadmap.
+  Step 4a gates Step 5 ([#442]) for rendering parity but is not part of any release batch.
+- Follow-up [#463] (Step 4b, file-snapshot source) already exists and is open — referenced as a Non-Goal, nothing new to file.
+- Parity is defined as *using Pi's own components*, not byte-equality with the bespoke viewer; `custom`-role messages are skipped (the bespoke viewer never rendered them either), noted as an Open Question.
+
+## Stage: Implementation — TDD (2026-06-22T21:30:00Z)
+
+### Session summary
+
+Executed all four planned TDD steps: the `getToolDefinition` read accessor on `SubagentSession`/`Subagent`, the seam method on `TranscriptSource`/`NavigableSubagent`, the per-entry component renderer + overlay rewrite + `cwd` wiring, and the architecture doc flip (Step 4a `✅`).
+The renderer now mounts Pi's interactive components into a cached `Container` rebuilt on source change, mirroring Pi's `renderSessionContext`.
+Test count went from 1084 to 1088 (+4 net: +4 accessor/seam tests, +3 new navigator tests, −3 removed `renderTranscriptLines` tests), all green; one post-review `test:` commit pins invariant #423.
+
+### Observations
+
+- The production code (`session-navigation.ts`, `session-navigator.ts`, `index.ts`) type-checked clean on the first `tsc` run — the SDK message-union narrowing (`switch (message.role)`), component construction, and `updateResult(toolResultMessage)` all resolved without casts.
+  `SessionMessage` (= the SDK `AgentMessage` union) narrows by `role` even though `@earendil-works/pi-agent-core` is not a direct dependency.
+- Two deviations from the plan's Module-Level Changes, both intentional: (1) `src/types.ts` was *not* changed — `ToolDefinition` is imported directly from `@earendil-works/pi-coding-agent` in each consumer rather than re-exported through the barrel (avoids a speculative re-export `fallow` would flag); (2) `test/helpers/mock-session.ts` gained a `getToolDefinition` stub (needed for the step-1 accessor tests, not listed in the plan).
+- Pi's per-entry components read a *global* interactive theme initialized by `initTheme()`; Pi does this at startup, but tests had to call `initTheme(undefined, false)` in `beforeAll`.
+  An early probe with `AssistantMessageComponent` passed without it, but `UserMessageComponent`/`ToolExecutionComponent` throw `"Theme not initialized"` — so the global-theme dependency is component-specific and only surfaced once the broader role set was exercised.
+- `setComplete`'s `TruncationResult` param requires more fields than `BashExecutionMessage` carries, so the bash component is completed with `undefined` truncation info (command + output still render).
+  Pi's own JS passes `{ truncated: true }` but that path is untyped.
+- Pre-completion reviewer verdict: **WARN** (no failures; 3 non-blocking findings).
+  Reviewer warnings: (1) `package-pi-subagents/SKILL.md` UI module count is stale (10 listed vs 13 actual) — predates this issue, plan left it deliberately; (2) `addMessageComponents` mutates the received `pendingTools` accumulator (output-argument pattern) — intentional, mirrors Pi's own `renderedPendingTools` local and was plan-reviewed; (3) invariant #423 held and is type-enforced but lacked an explicit spy pin — **addressed** by the follow-up `test:` commit asserting the handler never calls `record.getToolDefinition` directly.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "17.3.0",
+  "version": "17.4.0",
   "type": "module",
   "exports": {
     ".": {

package/src/index.ts

@@ -201,7 +201,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerCommand("subagent-sessions", {
     description: "View a subagent's session transcript (read-only)",
     handler: async (_args, ctx) => {
-      await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry });
+      await sessionNavigator.handle({ ui: ctx.ui, agents: manager.listAgents(), registry, cwd: ctx.cwd });
     },
   });
 }

package/src/lifecycle/subagent-session.ts

@@ -13,6 +13,7 @@
 import {
   type AgentSession,
   type AgentSessionEvent,
+  type ToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import type { ChildLifecyclePublisher } from "#src/lifecycle/child-lifecycle";
 import { normalizeMaxTurns } from "#src/lifecycle/turn-limits";
@@ -184,6 +185,11 @@ export class SubagentSession {
     return this._session.messages;
   }
 
+  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+  getToolDefinition(name: string): ToolDefinition | undefined {
+    return this._session.getToolDefinition(name);
+  }
+
   /** Tear down: session.dispose() + emit `disposed` (registry unregister). */
   dispose(): void {
     // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- dispose may not exist on all session implementations

package/src/lifecycle/subagent.ts

@@ -7,7 +7,7 @@
  */
 
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSessionEvent } from "@earendil-works/pi-coding-agent";
+import type { AgentSessionEvent, ToolDefinition } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "#src/debug";
 import type { CreateSubagentSessionParams } from "#src/lifecycle/create-subagent-session";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
@@ -167,6 +167,11 @@ export class Subagent {
 		return this.subagentSession?.agentMessages ?? [];
 	}
 
+	/** Resolve a registered tool definition by name, or undefined if no session. */
+	getToolDefinition(name: string): ToolDefinition | undefined {
+		return this.subagentSession?.getToolDefinition(name);
+	}
+
 	constructor(init: SubagentInit) {
 		// Identity
 		this.id = init.id;

package/src/ui/session-navigation.ts

@@ -2,20 +2,21 @@
  * session-navigation.ts — Pure selection and transcript-sourcing for native session navigation.
  *
  * Splits the unit-testable core of the `/subagent-sessions` command from its TUI
- * wiring (`session-navigator.ts`): which subagents are navigable, how a picked
- * agent's transcript is sourced (live, in this slice), and how the transcript
- * renders to plain text via Pi's own `serializeConversation`.
+ * wiring (`session-navigator.ts`): which subagents are navigable and how a picked
+ * agent's transcript is sourced (live, in this slice).
  *
  * The `TranscriptSource` seam decouples *how messages are sourced* (live record
- * here; a file snapshot in a follow-up) from *how they render* (text here; Pi's
- * per-entry components in a follow-up). The renderer talks only to this seam.
+ * here; a file snapshot in a follow-up) from *how they render* — the renderer
+ * (`session-navigator.ts`, which mounts Pi's per-entry components) talks only to
+ * this seam. Rendering lives in the SDK/TUI module because the per-entry
+ * components require a `TUI`, `cwd`, and markdown theme.
  */
 
-import { serializeConversation } from "@earendil-works/pi-coding-agent";
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
 import type { SubagentStatus } from "#src/lifecycle/subagent-state";
 import type { AgentSessionEvent, SessionMessage, SubagentType } from "#src/types";
-import { describeActivity, formatDuration, getDisplayName } from "#src/ui/display";
+import { formatDuration, getDisplayName } from "#src/ui/display";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -33,6 +34,7 @@ export interface NavigableSubagent {
   readonly agentMessages: readonly SessionMessage[];
   isSessionReady(): boolean;
   subscribeToUpdates(fn: (event: AgentSessionEvent) => void): (() => void) | undefined;
+  getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
 /** A navigable entry: a record plus the label shown in the picker. */
@@ -55,6 +57,8 @@ export interface TranscriptSource {
   subscribe(onChange: () => void): (() => void) | undefined;
   /** Running-agent streaming state, or undefined when not streaming. */
   streaming(): StreamingState | undefined;
+  /** Resolve a registered tool definition by name, for Pi's tool-execution components. */
+  getToolDefinition(name: string): ToolDefinition | undefined;
 }
 
 /** Filter the agents to those with a viewable session and label each for the picker. */
@@ -76,37 +80,10 @@ export function liveSource(record: NavigableSubagent): TranscriptSource {
       record.status === "running"
         ? { activeTools: record.activeTools, responseText: record.responseText }
         : undefined,
+    getToolDefinition: (name) => record.getToolDefinition(name),
   };
 }
 
-/** Render a source's transcript to plain text lines via Pi's `serializeConversation`. */
-export function renderTranscriptLines(source: TranscriptSource): string[] {
-  const messages = source.getMessages();
-  const lines =
-    messages.length === 0 ? ["(no messages yet)"] : serializeConversation(toMessages(messages)).split("\n");
-
-  const streaming = source.streaming();
-  if (streaming) {
-    lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
-  }
-  return lines;
-}
-
-/**
- * Bridge the session's `AgentMessage[]` to `serializeConversation`'s `Message[]`.
- *
- * `AgentMessage` is a superset of `Message` (it adds session-display variants such
- * as `BashExecutionMessage`); `serializeConversation` renders the shared shape and
- * best-effort text for the rest. `Message` is not re-exported from the public
- * `@earendil-works/pi-ai` barrel, so the parameter type is referenced via the
- * function signature rather than imported by name.
- */
-function toMessages(
-  messages: readonly SessionMessage[],
-): Parameters<typeof serializeConversation>[0] {
-  return messages as unknown as Parameters<typeof serializeConversation>[0];
-}
-
 function buildLabel(record: NavigableSubagent, registry: AgentConfigLookup): string {
   const name = getDisplayName(record.type, registry);
   const duration = formatDuration(record.startedAt, record.completedAt);

package/src/ui/session-navigator.ts

@@ -1,26 +1,46 @@
 /**
  * session-navigator.ts — The `/subagent-sessions` command: pick a subagent and
- * read its transcript through Pi's own session-rendering text.
+ * read its transcript through Pi's own per-entry session components.
  *
  * SDK/TUI consumer half of native session navigation. The unit-testable core
- * (selection, sourcing, text rendering) lives in `session-navigation.ts`; this
- * module wires that core to the command picker and a read-only scrollable overlay.
+ * (selection, sourcing) lives in `session-navigation.ts`; this module wires that
+ * core to the command picker and a read-only scrollable overlay, and owns the
+ * renderer — it mounts Pi's interactive components (`AssistantMessageComponent`,
+ * `ToolExecutionComponent`, …) into a `Container`, mirroring Pi's own
+ * `renderSessionContext` mapping. Rendering lives here, not in the pure module,
+ * because the components require a `TUI`, `cwd`, and markdown theme.
  *
  * The overlay is strictly read-only — steering stays in the `steer_subagent` tool
- * and the widget. It consumes a `TranscriptSource`, so the renderer-upgrade and
- * evicted-agent-source follow-ups swap the source/renderer without touching it.
+ * and the widget. It consumes a `TranscriptSource`, so the evicted-agent-source
+ * follow-up swaps the source without touching the renderer or the overlay.
  */
 
-import { type Component, matchesKey, type TUI, truncateToWidth, visibleWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-import type { AgentConfigLookup } from "#src/config/agent-types";
-import type { Theme } from "#src/ui/display";
 import {
-  listNavigableAgents,
-  liveSource,
-  type NavigableSubagent,
-  renderTranscriptLines,
-  type TranscriptSource,
-} from "#src/ui/session-navigation";
+  AssistantMessageComponent,
+  BashExecutionComponent,
+  BranchSummaryMessageComponent,
+  CompactionSummaryMessageComponent,
+  getMarkdownTheme,
+  parseSkillBlock,
+  SkillInvocationMessageComponent,
+  type ToolDefinition,
+  ToolExecutionComponent,
+  UserMessageComponent,
+} from "@earendil-works/pi-coding-agent";
+import {
+  type Component,
+  Container,
+  type MarkdownTheme,
+  matchesKey,
+  Spacer,
+  type TUI,
+  truncateToWidth,
+  visibleWidth,
+} from "@earendil-works/pi-tui";
+import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { SessionMessage } from "#src/types";
+import { describeActivity, type Theme } from "#src/ui/display";
+import { listNavigableAgents, liveSource, type NavigableSubagent, type TranscriptSource } from "#src/ui/session-navigation";
 
 // ─────────────────────────────────────────────────────────────────────────────
 
@@ -49,6 +69,8 @@ export interface SessionNavigatorParams {
   ui: SessionNavigatorUI;
   agents: readonly NavigableSubagent[];
   registry: AgentConfigLookup;
+  /** Working directory for tool-call rendering (relative path display). */
+  cwd: string;
 }
 
 /** Options for the read-only transcript overlay. */
@@ -57,7 +79,8 @@ export interface TranscriptOverlayOptions {
   theme: Theme;
   source: TranscriptSource;
   done: (result: undefined) => void;
-  wrapText: (text: string, width: number) => string[];
+  cwd: string;
+  markdownTheme: MarkdownTheme;
 }
 
 /**
@@ -68,7 +91,7 @@ export interface TranscriptOverlayOptions {
  * manager, so it stays a reactive consumer with no inbound call into the core.
  */
 export class SessionNavigatorHandler {
-  async handle({ ui, agents, registry }: SessionNavigatorParams): Promise<void> {
+  async handle({ ui, agents, registry, cwd }: SessionNavigatorParams): Promise<void> {
     const entries = listNavigableAgents(agents, registry);
     if (entries.length === 0) {
       ui.notify("No subagent sessions to view.", "info");
@@ -83,9 +106,10 @@ export class SessionNavigatorHandler {
     if (!entry) return;
 
     const source = liveSource(entry.record);
+    const markdownTheme = getMarkdownTheme();
     await ui.custom<undefined>(
       (tui, theme, _keybindings, done) =>
-        new TranscriptOverlay({ tui, theme, source, done, wrapText: wrapTextWithAnsi }),
+        new TranscriptOverlay({ tui, theme, source, done, cwd, markdownTheme }),
       {
         overlay: true,
         overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },
@@ -97,9 +121,11 @@ export class SessionNavigatorHandler {
 /**
  * Read-only scrollable transcript overlay.
  *
- * Re-renders on every source update (live agents); the transcript text is Pi's
- * `serializeConversation` output from `renderTranscriptLines` — this class owns
- * only scroll state and chrome, no message formatting.
+ * Caches a `Container` of Pi's per-entry components and rebuilds it only when the
+ * source changes (live agents) — each paint reuses the cached tree, so markdown
+ * highlighting does not re-run per frame. This class owns scroll state, chrome,
+ * and the running-agent streaming indicator; the component mapping lives in
+ * `buildTranscriptComponents`.
  */
 export class TranscriptOverlay implements Component {
   private scrollOffset = 0;
@@ -111,16 +137,21 @@ export class TranscriptOverlay implements Component {
   private readonly theme: Theme;
   private readonly source: TranscriptSource;
   private readonly done: (result: undefined) => void;
-  private readonly wrapText: (text: string, width: number) => string[];
+  private readonly cwd: string;
+  private readonly markdownTheme: MarkdownTheme;
+  private content: Container;
 
-  constructor({ tui, theme, source, done, wrapText }: TranscriptOverlayOptions) {
+  constructor({ tui, theme, source, done, cwd, markdownTheme }: TranscriptOverlayOptions) {
     this.tui = tui;
     this.theme = theme;
     this.source = source;
     this.done = done;
-    this.wrapText = wrapText;
+    this.cwd = cwd;
+    this.markdownTheme = markdownTheme;
+    this.content = this.rebuild();
     this.unsubscribe = source.subscribe(() => {
       if (this.closed) return;
+      this.content = this.rebuild();
       this.tui.requestRender();
     });
   }
@@ -199,7 +230,7 @@ export class TranscriptOverlay implements Component {
 
   // fallow-ignore-next-line unused-class-member
   invalidate(): void {
-    /* no cached state to clear */
+    this.content.invalidate();
   }
 
   // fallow-ignore-next-line unused-class-member
@@ -224,14 +255,139 @@ export class TranscriptOverlay implements Component {
 
   private buildContentLines(innerW: number): string[] {
     if (innerW <= 0) return [];
-    const wrapped: string[] = [];
-    for (const line of renderTranscriptLines(this.source)) {
-      if (line === "") {
-        wrapped.push("");
-        continue;
+    const lines = this.content.render(innerW);
+    const streaming = this.source.streaming();
+    if (streaming) {
+      lines.push("", `◍ ${describeActivity(streaming.activeTools, streaming.responseText)}`);
+    }
+    return lines.map((l) => truncateToWidth(l, innerW));
+  }
+
+  private rebuild(): Container {
+    return buildTranscriptComponents(this.source.getMessages(), {
+      tui: this.tui,
+      cwd: this.cwd,
+      markdownTheme: this.markdownTheme,
+      getToolDefinition: (name) => this.source.getToolDefinition(name),
+    });
+  }
+}
+
+/** Dependencies the per-entry component tree needs from the SDK/TUI environment. */
+interface TranscriptRenderOptions {
+  tui: TUI;
+  cwd: string;
+  markdownTheme: MarkdownTheme;
+  getToolDefinition: (name: string) => ToolDefinition | undefined;
+}
+
+/**
+ * Build a `Container` of Pi's per-entry components from a message snapshot,
+ * mirroring Pi's own interactive-mode `renderSessionContext` mapping. Tool
+ * results are matched to their tool-call components by id, exactly as Pi does.
+ * `custom`-role messages are skipped — rendering them needs the child session's
+ * message-renderer registry, which the navigator does not hold.
+ */
+function buildTranscriptComponents(
+  messages: readonly SessionMessage[],
+  opts: TranscriptRenderOptions,
+): Container {
+  const container = new Container();
+  const pendingTools = new Map<string, ToolExecutionComponent>();
+  for (const message of messages) {
+    addMessageComponents(container, message, pendingTools, opts);
+  }
+  return container;
+}
+
+function addMessageComponents(
+  container: Container,
+  message: SessionMessage,
+  pendingTools: Map<string, ToolExecutionComponent>,
+  opts: TranscriptRenderOptions,
+): void {
+  switch (message.role) {
+    case "assistant": {
+      container.addChild(new AssistantMessageComponent(message, false, opts.markdownTheme));
+      for (const content of message.content) {
+        if (content.type !== "toolCall") continue;
+        const tool = new ToolExecutionComponent(
+          content.name,
+          content.id,
+          content.arguments,
+          { showImages: false },
+          opts.getToolDefinition(content.name),
+          opts.tui,
+          opts.cwd,
+        );
+        tool.setExpanded(true);
+        container.addChild(tool);
+        pendingTools.set(content.id, tool);
       }
-      wrapped.push(...this.wrapText(line, innerW));
+      break;
+    }
+    case "toolResult": {
+      pendingTools.get(message.toolCallId)?.updateResult(message);
+      pendingTools.delete(message.toolCallId);
+      break;
+    }
+    case "user": {
+      addUserComponents(container, message.content, opts.markdownTheme);
+      break;
+    }
+    case "bashExecution": {
+      const bash = new BashExecutionComponent(message.command, opts.tui, message.excludeFromContext);
+      if (message.output) bash.appendOutput(message.output);
+      bash.setComplete(message.exitCode, message.cancelled, undefined, message.fullOutputPath);
+      container.addChild(bash);
+      break;
+    }
+    case "compactionSummary": {
+      container.addChild(new Spacer(1));
+      const summary = new CompactionSummaryMessageComponent(message, opts.markdownTheme);
+      summary.setExpanded(true);
+      container.addChild(summary);
+      break;
+    }
+    case "branchSummary": {
+      container.addChild(new Spacer(1));
+      const summary = new BranchSummaryMessageComponent(message, opts.markdownTheme);
+      summary.setExpanded(true);
+      container.addChild(summary);
+      break;
     }
-    return wrapped.map((l) => truncateToWidth(l, innerW));
   }
 }
+
+/** Render a user message (skill block + text) into the container, mirroring Pi. */
+function addUserComponents(
+  container: Container,
+  content: string | readonly { type: string; text?: string }[],
+  markdownTheme: MarkdownTheme,
+): void {
+  const text = userMessageText(content);
+  if (!text) return;
+  if (container.children.length > 0) container.addChild(new Spacer(1));
+
+  const skillBlock = parseSkillBlock(text);
+  if (!skillBlock) {
+    container.addChild(new UserMessageComponent(text, markdownTheme));
+    return;
+  }
+  const skill = new SkillInvocationMessageComponent(skillBlock, markdownTheme);
+  skill.setExpanded(true);
+  container.addChild(skill);
+  if (skillBlock.userMessage) {
+    container.addChild(new Spacer(1));
+    container.addChild(new UserMessageComponent(skillBlock.userMessage, markdownTheme));
+  }
+}
+
+/** Concatenate the text blocks of a user message's content (mirrors Pi). */
+function userMessageText(content: string | readonly { type: string; text?: string }[]): string {
+  if (typeof content === "string") return content;
+  return content
+    .filter((block) => block.type === "text")
+    .map((block) => block.text ?? "")
+    .join("");
+}