@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/plans/0169-extract-run-context-from-run-options.md

@@ -1,194 +0,0 @@
----
-issue: 169
-issue_title: "refactor(pi-subagents): extract RunContext from RunOptions (12 fields)"
----
-
-# Extract RunContext from RunOptions
-
-## Problem Statement
-
-`RunOptions` in `agent-runner.ts` has 12 fields mixing two distinct concerns: parent execution context ("where/who is running") and per-call execution parameters ("how to run").
-Extracting the context cluster into a named `RunContext` interface makes the separation explicit and reduces the flat field count from 12 to 9 (8 execution fields + 1 nested context).
-
-## Goals
-
-- Define a `RunContext` interface grouping the 4 parent-context fields: `exec`, `registry`, `cwd`, and `parentSession`.
-- Nest `RunContext` inside `RunOptions` as `context: RunContext`, replacing the 4 flat fields.
-- Update `runAgent()` to read context fields from `options.context.*`.
-- Update `AgentManager.startAgent()` to construct the nested `context` object when building `RunOptions`.
-- Update all test files that construct or assert on `RunOptions` fields.
-- Non-breaking refactor — `RunOptions` is not part of the public API (`service.ts` export boundary).
-
-## Non-Goals
-
-- Changing the `AgentRunner` interface signature — `run()` keeps its 4 positional parameters; `RunContext` is nested inside `RunOptions`, not a separate parameter.
-- Extracting `RunContext` into its own file — the interface is small (4 fields) and co-located with its consumer (`runAgent`).
-- Further splitting the remaining 8 execution fields — they form a coherent "how to run" cluster.
-- Hoisting `RunContext` construction to `AgentManager` instance level — two of the four fields (`cwd`, `parentSession`) vary per spawn, so a per-spawn construction is appropriate.
-
-## Background
-
-Issue #164 (closed) reorganized source into domain directories; the runner now lives at `src/lifecycle/agent-runner.ts`.
-Issue #166 (closed) extracted `ParentSessionInfo` and nested it inside `RunOptions.parentSession`.
-Issue #167 (closed) split `RunnerIO` into `EnvironmentIO` and `SessionFactoryIO`.
-Issue #168 (closed) extracted `ToolFilterConfig` from `SessionConfig`.
-
-This issue continues the structural improvement by separating the two concerns mixed in `RunOptions`.
-
-### Field analysis
-
-| Field              | Concern   | Usage in `runAgent()`                      |
-| ------------------ | --------- | ------------------------------------------ |
-| `exec`             | Context   | `io.detectEnv(options.exec, effectiveCwd)` |
-| `registry`         | Context   | Passed to `assembleSessionConfig`          |
-| `cwd`              | Context   | Override working directory (worktree)      |
-| `parentSession`    | Context   | Session dir derivation + session linking   |
-| `model`            | Execution | Per-call model override                    |
-| `maxTurns`         | Execution | Turn limit                                 |
-| `signal`           | Execution | Abort forwarding                           |
-| `isolated`         | Execution | Extension isolation flag                   |
-| `thinkingLevel`    | Execution | Thinking level override                    |
-| `onSessionCreated` | Execution | Session delivery callback                  |
-| `defaultMaxTurns`  | Execution | Fallback turn limit from runtime config    |
-| `graceTurns`       | Execution | Grace window after soft limit              |
-
-### Consumer analysis
-
-`AgentManager.startAgent()` is the sole constructor of `RunOptions`.
-The context fields come from two sources:
-
-- Manager instance fields: `this.exec`, `this.registry`
-- Per-spawn values: `worktreeCwd` (computed locally), `options.parentSession` (from `AgentSpawnConfig`)
-
-## Design Overview
-
-### `RunContext` interface
-
-```typescript
-export interface RunContext {
-  /** Shell-exec callback for detectEnv — injected from pi.exec(). */
-  exec: ShellExec;
-  /** Agent config lookup — provides resolveAgentConfig and getToolNamesForType. */
-  registry: AgentConfigLookup;
-  /** Override working directory (e.g. for worktree isolation). */
-  cwd?: string;
-  /** Parent session identity (file path + session ID). */
-  parentSession?: ParentSessionInfo;
-}
-```
-
-### Updated `RunOptions`
-
-```typescript
-export interface RunOptions {
-  /** Parent execution context — where/who is running. */
-  context: RunContext;
-  model?: Model<any>;
-  maxTurns?: number;
-  signal?: AbortSignal;
-  isolated?: boolean;
-  thinkingLevel?: ThinkingLevel;
-  onSessionCreated?: (session: AgentSession) => void;
-  defaultMaxTurns?: number;
-  graceTurns?: number;
-}
-```
-
-### Call-site sketch — `AgentManager.startAgent`
-
-```typescript
-const promise = this.runner.run(snapshot, type, prompt, {
-  context: {
-    exec: this.exec,
-    registry: this.registry,
-    cwd: worktreeCwd,
-    parentSession: options.parentSession,
-  },
-  model: options.model,
-  maxTurns: options.maxTurns,
-  // ... remaining execution fields
-});
-```
-
-### Access pattern in `runAgent`
-
-```typescript
-const effectiveCwd = options.context.cwd ?? snapshot.cwd;
-const env = await io.detectEnv(options.context.exec, effectiveCwd);
-// ...
-const sessionDir = io.deriveSessionDir(
-  options.context.parentSession?.parentSessionFile,
-  cfg.effectiveCwd,
-);
-```
-
-## Module-Level Changes
-
-### `src/lifecycle/agent-runner.ts`
-
-1. Add `RunContext` interface (4 fields, exported) before `RunOptions`.
-2. Replace the 4 flat context fields on `RunOptions` with `context: RunContext`.
-3. Update all `options.*` reads in `runAgent()`:
-   - `options.exec` → `options.context.exec`
-   - `options.cwd` → `options.context.cwd`
-   - `options.parentSession` → `options.context.parentSession`
-   - `options.registry` → `options.context.registry`
-4. Move JSDoc from the removed flat fields to `RunContext` interface members.
-5. Export `RunContext`.
-
-### `src/lifecycle/agent-manager.ts`
-
-1. Update the `RunOptions` object literal in `startAgent()` to nest the four context fields under `context: { ... }`.
-2. No import changes needed — `RunOptions` is consumed via the `AgentRunner` interface, not imported directly.
-
-### No changes needed
-
-- `src/lifecycle/agent-runner.ts` — `AgentRunner` interface signature unchanged (`options: RunOptions`).
-- `src/lifecycle/agent-runner.ts` — `createAgentRunner()` unchanged.
-- `src/index.ts` — no changes (doesn't import `RunOptions`).
-- `src/runtime.ts` — comment-only reference to `RunOptions`; update comment if desired.
-- `src/session/session-config.ts` — comment-only reference; update comment if desired.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-The extraction does not enable new test surfaces — `RunContext` is a plain data carrier with no behavior.
-A type-check verification (`pnpm run check`) confirms the structural compatibility.
-
-### Existing tests that need updates
-
-1. `test/lifecycle/agent-runner.test.ts` — 9 `runAgent()` call sites: wrap `exec`, `registry`, `cwd`, and `parentSession` fields in `context: { ... }`.
-2. `test/lifecycle/agent-runner-extension-tools.test.ts` — 7 `runAgent()` call sites: same wrapping.
-3. `test/lifecycle/agent-manager.test.ts` — 3 assertion sites: update `runOpts.parentSession` → `runOpts.context.parentSession`, `runOpts.defaultMaxTurns` stays flat (execution field).
-
-### Tests that stay as-is
-
-- `test/lifecycle/agent-runner-settings.test.ts` — tests `normalizeMaxTurns` (pure function, no `RunOptions` involvement).
-- All other test files — no `RunOptions` construction or assertion.
-
-## TDD Order
-
-1. **Define `RunContext` and update `RunOptions`** — add `RunContext` interface, replace 4 flat fields with `context: RunContext` on `RunOptions`.
-   Update all `options.*` reads in `runAgent()` to `options.context.*`.
-   Update `agent-manager.ts` `startAgent()` to construct nested context.
-   Update `agent-runner.test.ts` (9 call sites) and `agent-runner-extension-tools.test.ts` (7 call sites) to nest context fields.
-   Update `agent-manager.test.ts` assertions (3 sites) to read from `runOpts.context.*`.
-   Run `pnpm run check` and `pnpm vitest run` to verify.
-   Commit: `refactor: extract RunContext from RunOptions (#169)`
-
-2. **Update comments** — update comment references in `runtime.ts` and `session-config.ts` that mention `RunOptions` field names.
-   Commit: `docs: update RunOptions field references in comments (#169)`
-
-## Risks and Mitigations
-
-| Risk                                                              | Mitigation                                                                                                                               |
-| ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
-| Test factories using spread patterns lose context fields silently | No test factory returns `Partial<RunOptions>` — all call sites construct the options inline, so TypeScript will reject missing `context` |
-| `agent-manager.test.ts` assertions on execution fields break      | Only context-field assertions change; execution-field assertions (`defaultMaxTurns`, `graceTurns`) remain on `runOpts.*`                 |
-| Nested access adds verbosity to `runAgent()`                      | Only 6 access sites gain the `.context` prefix; readability trade-off is minimal for the structural clarity gained                       |
-
-## Open Questions
-
-None — the extraction follows the natural "where/who vs. how" seam identified in the issue body.
-The issue's proposed flat `parentSessionFile`/`parentSessionId` fields have been superseded by the already-implemented `parentSession?: ParentSessionInfo` grouping from #166.

package/docs/plans/0170-reduce-build-content-lines-complexity.md

@@ -1,225 +0,0 @@
----
-issue: 170
-issue_title: "refactor(pi-subagents): reduce buildContentLines complexity (cognitive 71)"
----
-
-# Reduce `buildContentLines` complexity
-
-## Problem Statement
-
-`buildContentLines` in `ui/conversation-viewer.ts` has cyclomatic complexity 30 and cognitive complexity 71 — the highest in the codebase (fallow #2 refactoring target, score 9.7).
-The method formats session events for display, handling user messages, assistant messages, tool calls, tool results, bash execution output, and a streaming indicator in a single function.
-
-## Goals
-
-- Extract per-content-type formatting into standalone pure functions in a new module.
-- Reduce `buildContentLines` to a dispatch loop that delegates to formatters.
-- Make each formatter independently testable with clear input/output.
-
-## Non-Goals
-
-- Changing the visual output or behavior of the conversation viewer.
-- Refactoring `render()` or the chrome/scrolling logic.
-- Restructuring the `ConversationViewer` class itself (constructor, options, etc.).
-
-## Background
-
-Issue #164 (reorganize source into domain directories) is implemented — files are already in `src/ui/`.
-
-`buildContentLines` currently handles five concerns in a single method body:
-
-1. **User messages** — extract text from string or content array, wrap, push with `[User]` header.
-2. **Assistant messages** — separate text parts from tool calls, wrap text, append `[Tool: name]` lines.
-3. **Tool results** — extract text, truncate to 500 chars, wrap in dim styling.
-4. **Bash execution** — render command line, truncate/wrap output.
-5. **Streaming indicator** — append activity description for running agents.
-
-Each branch uses `this.theme` and `this.wrapText` but has no other instance dependencies.
-The method also manages separator logic (`needsSeparator`) and applies a final `truncateToWidth` safety net.
-
-Dependencies consumed by the formatters:
-
-- `Theme` from `display.ts` — for `fg()` and `bold()`.
-- `truncateToWidth` from `@earendil-works/pi-tui`.
-- `extractText` from `session/context.ts`.
-- `getToolCallName` and `isBashExecution` — file-local helpers in `conversation-viewer.ts`.
-
-## Design Overview
-
-### New module: `ui/message-formatters.ts`
-
-A new file containing pure functions that convert a single message into display lines.
-Each formatter receives the message, a `width`, and a narrow `FormatterContext` (theme + wrapText).
-Each returns `string[]` — the formatted lines for that message, **excluding** separators and the final `truncateToWidth` pass (those remain in `buildContentLines`).
-
-```typescript
-/** Narrow context shared by all message formatters. */
-export interface FormatterContext {
-  theme: Theme;
-  wrapText: (text: string, width: number) => string[];
-}
-
-export function formatUserMessage(
-  content: string | unknown[],
-  width: number,
-  ctx: FormatterContext,
-): string[] | null;
-
-export function formatAssistantMessage(
-  content: Array<{ type: string; text?: string }>,
-  width: number,
-  ctx: FormatterContext,
-): string[];
-
-export function formatToolResult(
-  content: unknown[],
-  width: number,
-  ctx: FormatterContext,
-): string[] | null;
-
-export function formatBashExecution(
-  msg: BashExecutionMessage,
-  width: number,
-  ctx: FormatterContext,
-): string[];
-
-export function formatStreamingIndicator(
-  activeTools: ReadonlyMap<string, string>,
-  responseText: string | undefined,
-  width: number,
-  theme: Theme,
-): string[];
-```
-
-`formatUserMessage` and `formatToolResult` return `null` when the content is empty (matching the current `continue` behavior), letting the caller skip the separator.
-
-### Relocated helpers
-
-`getToolCallName`, the `ToolCallContent` interface, `BashExecutionMessage`, and `isBashExecution` move to `message-formatters.ts` — they are consumed only by the formatters.
-The type guard `isBashExecution` remains exported so `buildContentLines` can use it in the dispatch condition.
-
-### Simplified `buildContentLines`
-
-After extraction, `buildContentLines` becomes a ~25-line dispatch loop:
-
-```typescript
-private buildContentLines(width: number): string[] {
-  if (width <= 0) return [];
-  const ctx = { theme: this.theme, wrapText: this.wrapText };
-  const messages = this.session.messages;
-  if (messages.length === 0) {
-    return [this.theme.fg("dim", "(waiting for first message...)")];
-  }
-  const lines: string[] = [];
-  let needsSeparator = false;
-  for (const msg of messages) {
-    const formatted = formatMessage(msg, width, ctx);
-    if (!formatted) continue;
-    if (needsSeparator) lines.push(this.theme.fg("dim", "───"));
-    lines.push(...formatted);
-    needsSeparator = true;
-  }
-  if (this.record.status === "running" && this.activity) {
-    lines.push(...formatStreamingIndicator(
-      this.activity.activeTools, this.activity.responseText, width, this.theme,
-    ));
-  }
-  return lines.map(l => truncateToWidth(l, width));
-}
-```
-
-A private `formatMessage` dispatcher selects the right formatter by `msg.role`, keeping the per-role logic in the new module.
-The `formatMessage` function lives in `message-formatters.ts` and encapsulates the role-based dispatch:
-
-```typescript
-export function formatMessage(
-  msg: { role: string; [key: string]: unknown },
-  width: number,
-  ctx: FormatterContext,
-): string[] | null;
-```
-
-### Design principles applied
-
-- **SRP**: Each formatter has one reason to change (its content type's display rules).
-- **ISP**: `FormatterContext` is a 2-field interface — narrower than `ConversationViewerOptions`.
-- **Tell-Don't-Ask**: The caller tells the formatter "format this message at this width" and receives lines back — no interrogation of the message's internals in the caller.
-- **No output arguments**: Formatters return new arrays; they don't mutate a shared `lines` accumulator.
-
-## Module-Level Changes
-
-### New file: `src/ui/message-formatters.ts`
-
-- `FormatterContext` interface.
-- `ToolCallContent` interface (moved from `conversation-viewer.ts`).
-- `BashExecutionMessage` interface (moved from `conversation-viewer.ts`).
-- `getToolCallName` function (moved from `conversation-viewer.ts`).
-- `isBashExecution` type guard (moved from `conversation-viewer.ts`).
-- `formatUserMessage` function.
-- `formatAssistantMessage` function.
-- `formatToolResult` function.
-- `formatBashExecution` function.
-- `formatStreamingIndicator` function.
-- `formatMessage` dispatcher function.
-
-### Modified: `src/ui/conversation-viewer.ts`
-
-- Remove `ToolCallContent`, `BashExecutionMessage`, `getToolCallName`, `isBashExecution` (moved to `message-formatters.ts`).
-- Import `formatMessage`, `formatStreamingIndicator` from `message-formatters.ts`.
-- Replace `buildContentLines` body with the dispatch loop above.
-
-### New file: `test/message-formatters.test.ts`
-
-- Unit tests for each formatter function and the `formatMessage` dispatcher.
-
-### Modified: `test/conversation-viewer.test.ts`
-
-- Existing tests remain as-is — they exercise the integrated `render()` and `buildContentLines` paths (width-safety and clamping), which are genuine integration tests for the viewer.
-- No tests become redundant; the new unit tests cover formatter logic that was previously only reachable through the viewer's `render()` method.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled**: Each formatter can now be tested in isolation — verifying header labels, text wrapping, truncation thresholds (500-char limit), tool-call name extraction, empty-content null returns, and streaming indicator formatting — without constructing a full `ConversationViewer` with mock `TUI`, `AgentSession`, and `AgentRecord`.
-2. **No existing tests become redundant**: The existing `conversation-viewer.test.ts` tests are render-width-safety integration tests.
-   They exercise the full `render()` → `buildContentLines` → `truncateToWidth` pipeline and should remain.
-3. **Existing tests stay as-is**: They test the viewer's chrome, scrolling, and width-clamping behavior — concerns orthogonal to the per-message formatting logic being extracted.
-
-## TDD Order
-
-1. **Red → Green**: Add unit tests for `formatUserMessage` — plain string content, content-array content, empty content returning null, header and wrapping behavior.
-   Commit: `test: add formatUserMessage unit tests`
-
-2. **Red → Green**: Add unit tests for `formatAssistantMessage` — text-only content, tool-call-only content, mixed content, empty text parts.
-   Commit: `test: add formatAssistantMessage unit tests`
-
-3. **Red → Green**: Add unit tests for `formatToolResult` — normal content, content exceeding 500 chars (truncation), empty content returning null.
-   Commit: `test: add formatToolResult unit tests`
-
-4. **Red → Green**: Add unit tests for `formatBashExecution` — command rendering, output wrapping, long output truncation, empty output.
-   Commit: `test: add formatBashExecution unit tests`
-
-5. **Red → Green**: Add unit tests for `formatStreamingIndicator` — active tools, response text fallback, no-activity "thinking" fallback.
-   Commit: `test: add formatStreamingIndicator unit tests`
-
-6. **Red → Green**: Add unit tests for `formatMessage` dispatcher — correct delegation by role, unknown role returning null.
-   Commit: `test: add formatMessage dispatcher tests`
-
-7. **Green → Refactor**: Create `message-formatters.ts` with all formatter functions and the dispatcher.
-   Move `ToolCallContent`, `BashExecutionMessage`, `getToolCallName`, `isBashExecution` from `conversation-viewer.ts`.
-   Commit: `refactor: extract message formatters from conversation-viewer`
-
-8. **Green → Refactor**: Simplify `buildContentLines` to use the new `formatMessage` dispatcher and `formatStreamingIndicator`.
-   Verify all existing `conversation-viewer.test.ts` tests still pass.
-   Commit: `refactor: simplify buildContentLines to dispatch loop`
-
-## Risks and Mitigations
-
-| Risk                                                                                | Mitigation                                                                                                                                                        |
-| ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Formatter output differs subtly from inline code (missing separator, wrong styling) | Steps 7–8 keep all existing integration tests passing — any visual regression fails the width-safety suite.                                                       |
-| `FormatterContext` grows over time as new formatters need more dependencies         | The interface is deliberately minimal (2 fields); if a future formatter needs something new, it should accept it as a parameter rather than widening the context. |
-| `msg` type is `unknown`-heavy due to Pi SDK not exporting narrow types              | Preserve the existing file-local type guards and interfaces — they already handle the runtime shape safely.                                                       |
-
-## Open Questions
-
-- None — the extraction is mechanical and the issue's approach section is unambiguous.

package/docs/plans/0171-reduce-render-result-complexity.md

@@ -1,200 +0,0 @@
----
-issue: 171
-issue_title: "refactor(pi-subagents): reduce renderResult complexity (cognitive 43)"
----
-
-# Reduce `renderResult` complexity
-
-## Problem Statement
-
-`renderResult` in `tools/agent-tool.ts` has cyclomatic complexity 26 and cognitive complexity 43.
-It formats the agent result text returned to the parent LLM, branching on status (completed, error, aborted, stopped, steered) and handling fallback notes, duration, stats, and worktree info.
-Fallow ranks this as the #1 refactoring target (score 13.4).
-
-## Goals
-
-- Extract per-status result formatting into standalone pure functions in a new module.
-- Extract the inline `stats()` helper as a shared, testable function.
-- Reduce `renderResult` to a thin guard (no-details fallback) plus a dispatcher call.
-- Make each formatter independently testable with clear input/output.
-
-## Non-Goals
-
-- Changing the visual output or behavior of any status rendering.
-- Refactoring `renderCall`, `execute`, or other parts of `createAgentTool`.
-- Changing the `AgentDetails` interface shape.
-- Modifying the widget renderer (`widget-renderer.ts`) — it has its own rendering pipeline.
-
-## Background
-
-Issue #164 (reorganize source into domain directories) is implemented — files are already in `src/tools/`.
-
-`renderResult` currently handles six concerns in a single method body:
-
-1. **No-details guard** — when `result.details` is absent, fall back to raw text.
-2. **Running/partial** — spinner frame + stats + activity line.
-3. **Background** — dim "Running in background" message with agent ID.
-4. **Completed/steered** — success/warning icon + stats + duration + optional expanded result text (first 50 lines).
-5. **Stopped** — dim stop icon + stats + "Stopped" message.
-6. **Error/aborted** — error icon + stats + error message or "Aborted (max turns exceeded)".
-
-An inline `stats()` closure builds the "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens" string used by every branch except no-details and background.
-
-The existing `Theme` type in `display.ts` already captures the `fg()`/`bold()` pattern the formatters need.
-
-The sister module `widget-renderer.ts` in `ui/` demonstrates the established pattern: pure rendering functions that receive data and a theme, returning formatted strings.
-The new module follows the same shape.
-
-## Design Overview
-
-### New module: `src/tools/result-renderer.ts`
-
-A new file containing pure functions that convert an `AgentDetails` snapshot into a formatted result string for a specific status.
-Each formatter receives `AgentDetails`, a `Theme`, and any status-specific data (result text, expanded flag).
-Each returns a `string` — the formatted lines for that status.
-
-```typescript
-import type { AgentDetails, Theme } from "#src/ui/display";
-
-/** Build the stats string: "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens". */
-export function renderStats(details: AgentDetails, theme: Theme): string;
-
-/** Render running/partial status: spinner + stats + activity. */
-export function renderRunning(details: AgentDetails, theme: Theme): string;
-
-/** Render background launch status. */
-export function renderBackground(details: AgentDetails, theme: Theme): string;
-
-/** Render completed or steered status with optional expanded result text. */
-export function renderCompleted(
-  details: AgentDetails,
-  resultText: string,
-  expanded: boolean,
-  theme: Theme,
-): string;
-
-/** Render stopped status: dim icon + stats. */
-export function renderStopped(details: AgentDetails, theme: Theme): string;
-
-/** Render error or aborted status: error icon + stats + message. */
-export function renderFailed(details: AgentDetails, theme: Theme): string;
-
-/** Dispatch to the per-status renderer. */
-export function renderAgentResult(
-  details: AgentDetails,
-  resultText: string,
-  expanded: boolean,
-  isPartial: boolean,
-  theme: Theme,
-): string;
-```
-
-### Grouping decisions
-
-- **Completed + steered** stay in one function — they share 90% of logic, differing only in icon color (`success` vs `warning`) and collapsed text (`"Done"` vs `"Wrapped up (turn limit)"`).
-  A discriminator inside the function is justified because both statuses represent the same structural outcome (agent finished with result).
-- **Error + aborted** stay in one function — they share icon+stats structure, differing only in the status line.
-  Both represent failure-class outcomes.
-
-### Simplified `renderResult`
-
-After extraction, `renderResult` becomes a ~10-line method:
-
-```typescript
-renderResult(result: any, { expanded, isPartial }: any, theme: any) {
-  const details = result.details as AgentDetails | undefined;
-  if (!details) {
-    const text = result.content[0]?.type === "text" ? result.content[0].text : "";
-    return new Text(text, 0, 0);
-  }
-  const resultText = result.content[0]?.type === "text" ? result.content[0].text : "";
-  return new Text(
-    renderAgentResult(details, resultText, expanded, isPartial, theme),
-    0, 0,
-  );
-}
-```
-
-The no-details guard stays inline because it needs the SDK-specific `Text` constructor and raw `result` content access — extracting it would pull SDK concerns into the pure module.
-
-### Design principles applied
-
-- **SRP**: Each formatter has one reason to change (its status's display rules).
-- **ISP**: Formatters use the existing narrow `Theme` interface (2 methods) rather than the full SDK theme object.
-- **No output arguments**: Formatters return strings; they don't mutate shared state.
-- **Stepdown rule**: `renderAgentResult` dispatcher at the top of the module, per-status formatters below, `renderStats` helper at the bottom.
-
-## Module-Level Changes
-
-### New file: `src/tools/result-renderer.ts`
-
-- `renderStats` — extracted from the inline `stats()` closure.
-- `renderRunning` — running/partial branch.
-- `renderBackground` — background branch.
-- `renderCompleted` — completed/steered branch.
-- `renderStopped` — stopped branch.
-- `renderFailed` — error/aborted branch.
-- `renderAgentResult` — dispatcher function.
-
-### Modified: `src/tools/agent-tool.ts`
-
-- Remove the inline `stats()` closure.
-- Remove the five status branches from `renderResult`.
-- Import `renderAgentResult` from `result-renderer.ts`.
-- Reduce `renderResult` body to guard + dispatcher call.
-- The `SPINNER` import is removed (moved to `result-renderer.ts`).
-- The `formatMs`, `formatTurns` imports are removed (consumed only by the extracted code).
-
-### New file: `test/tools/result-renderer.test.ts`
-
-- Unit tests for `renderStats`, each per-status renderer, and the `renderAgentResult` dispatcher.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled**: Each formatter can now be tested in isolation — verifying icon selection, stats assembly, expanded-text truncation (50-line limit), activity text, and error message rendering — without constructing a full `createAgentTool` or mocking the Pi SDK `Text` class.
-2. **No existing tests become redundant**: The existing `agent-tool.test.ts` tests cover `execute` paths (resume, background, foreground), `renderCall`, and tool definition properties.
-   None of them test `renderResult` — there are zero existing `renderResult` tests.
-3. **Existing tests stay as-is**: All `agent-tool.test.ts` tests exercise `execute` and tool metadata, orthogonal to the rendering extraction.
-
-## TDD Order
-
-1. **Red → Green**: Add unit tests for `renderStats` — model name, tags, turn count with/without max, tool uses singular/plural, tokens, empty details producing empty string.
-   Commit: `test: add renderStats unit tests`
-
-2. **Red → Green**: Add unit tests for `renderRunning` — spinner frame, stats inclusion, activity text, default "thinking…" fallback.
-   Commit: `test: add renderRunning unit tests`
-
-3. **Red → Green**: Add unit tests for `renderBackground` — agent ID in output, dim styling.
-   Commit: `test: add renderBackground unit tests`
-
-4. **Red → Green**: Add unit tests for `renderCompleted` — completed icon (success), steered icon (warning), duration formatting, expanded view with result text, expanded view truncation at 50 lines, collapsed view "Done" vs "Wrapped up (turn limit)" text.
-   Commit: `test: add renderCompleted unit tests`
-
-5. **Red → Green**: Add unit tests for `renderStopped` — dim icon, stats, "Stopped" text.
-   Commit: `test: add renderStopped unit tests`
-
-6. **Red → Green**: Add unit tests for `renderFailed` — error status with error message, error with missing message defaulting to "unknown", aborted status with "max turns exceeded" text.
-   Commit: `test: add renderFailed unit tests`
-
-7. **Red → Green**: Add unit tests for `renderAgentResult` dispatcher — correct delegation by status (running, background, completed, steered, stopped, error, aborted), `isPartial` triggering running renderer.
-   Commit: `test: add renderAgentResult dispatcher tests`
-
-8. **Green → Refactor**: Create `result-renderer.ts` with all renderer functions and the dispatcher, extracted from `renderResult` in `agent-tool.ts`.
-   Commit: `refactor: extract result renderers from agent-tool`
-
-9. **Green → Refactor**: Simplify `renderResult` in `agent-tool.ts` to the guard + dispatcher pattern.
-   Remove unused imports (`SPINNER`, `formatMs`, `formatTurns`).
-   Verify all existing `agent-tool.test.ts` tests still pass.
-   Commit: `refactor: simplify renderResult to dispatcher`
-
-## Risks and Mitigations
-
-| Risk                                                                               | Mitigation                                                                                                                                                    |
-| ---------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Formatter output differs subtly from inline code (wrong icon, missing newline)     | Steps 1–7 lock in the expected output before extraction; step 9 confirms no regressions via existing tests.                                                   |
-| `theme` parameter is `any` in the tool hook — extracted functions use `Theme` type | The `Theme` interface in `display.ts` already matches the runtime shape; existing `widget-renderer.ts` demonstrates this pattern works.                       |
-| Future statuses added to `AgentDetails["status"]` need a new formatter             | The dispatcher's fallback branch (currently the error/aborted block) handles unknown statuses; adding a status requires one new function + one dispatch case. |
-
-## Open Questions
-
-- None — the extraction is mechanical and the issue's approach section is unambiguous.