@jopqior/pi-subagents 1.0.0

package/docs/architecture/client-server-opportunities.md

@@ -0,0 +1,127 @@
+# Client-server architecture: opportunities for pi-subagents
+
+This note is forward-looking.
+Pi's client-server split is **not on the near-term roadmap** — it is a long-term vision recorded in Mario Zechner's [pi session sync unification][session-sync] plan.
+This document captures what that architecture would let pi-subagents do, so the opportunity is on record alongside the existing [Architecture direction](./architecture.md#architecture-direction) section.
+
+It assumes the session-sync plan's shape:
+
+- `AgentSession` owns all authoritative intra-session state and emits all sync events.
+- `AgentSessionServer` owns multiple `AgentSession` runtimes, session lifecycle, client subscriptions, snapshots, and deltas.
+- `AgentSessionClient` is the only thing a renderer (interactive mode, web mode) talks to.
+- The sync model is **snapshot plus delta**: a client joins a session, receives one canonical snapshot, then a stream of deltas.
+- Commands go up; state deltas come down.
+- A client can `watch` (read-only) or `join` (interactive) a session, and can hold synchronized caches for many sessions at once.
+- Session lifecycle (`new`, `resume`, `fork`, `import`, `join`, `leave`, `watch`, `unwatch`) is normal server API, not hidden local runtime replacement.
+
+## The key realization
+
+A subagent **is** a child `AgentSession`. pi-subagents already creates one via `createSubagentSession`, drives its turn loop through `SubagentSession`, and disposes it.
+
+Today that child session is an in-process object visible only through machinery pi-subagents had to invent because Pi has no session-sync client:
+
+- `record-observer` re-derives live activity from raw session events.
+- the 80 ms `SubagentManager.listAgents()` widget poll.
+- the [#277] Law-of-Demeter accessors (`Subagent.getConversation()`, `.messages`, `.subscribeToUpdates()`, `.getContextPercent()`) that re-expose session internals.
+- the bespoke `ConversationViewer`, and [ADR-0004]'s replacement, native session navigation.
+- [ADR-0004]'s dual-source-by-liveness split (tracked agent → in-memory record; evicted → file snapshot).
+
+Every one of those is pi-subagents reinventing an `AgentSessionClient`.
+The session-sync plan supplies the real one.
+If subagent child sessions are registered as first-class sessions in the `AgentSessionServer`, all three target capabilities reduce to the same primitive the operator's own session already uses: `watch`/`join` a session id, receive a snapshot, then a delta stream.
+
+## Capability 1 — viewing live subagent sessions
+
+`watchSession(subagentSessionId)` gives the operator's client a canonical `SessionSnapshot` (current streaming message, pending tool executions with partial results, queue contents, context usage, active tools) followed by the live delta stream (`message_update`, `tool_execution_start/update/end`, `turn_start/end`).
+
+What changes versus today:
+
+1. **Late-join correctness.**
+   The snapshot carries in-flight state, so an operator attaching to an already-running subagent immediately sees its current streaming message and pending tools — not just future events.
+   Today the conversation viewer only catches future deltas plus whatever happens to be in the in-memory record.
+2. **The widget and viewer become thin renderers** of synchronized session state.
+   The 80 ms poll, `record-observer`, and the [#277] accessors disappear — they were all substitutes for `subscribeSession`.
+3. **A unified, reconnect-safe live session list.**
+   The global event scope (`session_created`, `session_status_changed` idle/busy) means the operator sees every subagent the instant it spawns, with a live status badge per agent — replacing both `listAgents()` polling and the hand-rolled `subagents:*` broadcast tier.
+4. **Multi-session client state** lets one operator client hold synchronized caches for N subagents at once.
+   This is the clean foundation for the parallel-agent navigation gesture that [ADR-0004]'s spike (entry-criterion #3) struggled to design — tabbed or split views of multiple live subagents fall out of the model with no redesign.
+
+## Capability 2 — viewing suspended subagent sessions
+
+Today "suspended" is a dead end: once a background subagent completes and `disposeSession()` fires, the live `AgentSession` is gone, and the only artifact is the persisted JSONL read one-shot via `parseSessionEntries`.
+That is a static file dump with no liveness and no path back to interaction.
+
+Under the server model, the live/suspended distinction collapses at the client.
+Session lifecycle is normal server API (`resume_session`, `join_session`, `import_session`), so a suspended subagent is just a session the server can rehydrate from `SessionManager` on demand:
+
+1. The operator calls `joinSession(id)` (or the server lazily reloads the `AgentSession` from JSONL when a client joins a dormant session), gets a snapshot, and renders it through the same components as a live session.
+   [ADR-0004]'s two-code-path split (in-memory record vs file snapshot) stops being the client's problem — whether the session is resident or rehydrated is the server's private concern.
+2. A genuinely paused subagent (one parked by the `ConcurrencyLimiter` awaiting capacity, or deliberately held) becomes representable: the server holds the runtime idle, the operator can `watch` its frozen state, and then sees it transition to `busy` via `session_status_changed` when capacity frees up.
+3. Subagents can outlive the operator's TUI.
+   Because the server is a separate process, if the operator's interactive client restarts it reconnects and re-lists or re-joins subagent sessions that survived — impossible in today's single-process model.
+
+## Capability 3 — operators interacting via an editor and submitting messages
+
+Today the only inbound channel to a running subagent is `steer_subagent` — a single buffer-or-deliver message through `Subagent.steer`.
+No editor, no takeover, no real conversation.
+
+The plan's `join` versus `watch` split is the right primitive:
+
+1. **`watch` is read-only** (Capability 1).
+   **`join` is interactive participation**: the operator's client sends session commands scoped to the subagent's session id — `prompt`, `abort`, `set model`, `set thinking level`, `set active tools`, `navigate tree`, `compact`, `run bash`.
+2. **Editor flow.**
+   The operator opens the subagent session in their client, types in the editor (editor text, focus, and overlays are explicitly client-local UI state, never synchronized), and submits a `prompt` command targeting the subagent's session id.
+   The command goes up; the server applies it to the subagent's `AgentSession` (which already owns prompt submission, queued steering, and follow-up messages); canonical deltas flow back down to all subscribers.
+   This is precisely "commands go up, state deltas come down," applied to a subagent session instead of the operator's own.
+3. **`steer` generalizes into the full command surface.**
+   pi-subagents' bespoke buffer-or-deliver logic (`Subagent.steer` rejecting when not running) is subsumed by `AgentSession`'s queued-steering machinery, and the custom buffering becomes redundant.
+4. **Multiple clients on one session.**
+   The plan supports this explicitly, with deltas broadcast to all subscribers including the initiator, so an operator can jump into a subagent the parent agent spawned, inject guidance, and the parent's view stays consistent.
+5. **Fork and rewind, not just append.**
+   `navigate tree` plus `fork_session` let an operator rewind a subagent or fork it at an entry — full session editing, far beyond appending a steer message.
+
+## What pi-subagents itself becomes
+
+This validates and sharpens the direction the architecture doc is already heading. pi-subagents' stated core job — spawn a child session derived from the parent, run the turn loop, track and stream and collect the result, gate concurrency, support resume, and publish its lifecycle — is almost exactly the `AgentSessionServer`'s job for child sessions.
+
+- **The observation tier dissolves.**
+  This confirms [Phase 18]'s own finding that "the activity/metrics push tier is provisional" — under the server it genuinely does not need to exist in pi-subagents.
+- **The recursion principle gets its real substrate.**
+  The architecture doc's "a subagent is a recursive Pi" framing maps directly onto the plan's session model: a subagent session is just another session in the server, with the same snapshot, delta, and command surface.
+- **pi-subagents keeps only its semantic layer** — agent type, description, result text, token totals, concurrency admission, and the recursion guard — the things a generic session server does not know.
+  The liveness and activity channel rides on session sync instead of a hand-rolled broadcast.
+
+### Bespoke machinery the server would retire
+
+| Today (pi-subagents reinvents it)                                        | Under the server architecture                              |
+| ------------------------------------------------------------------------ | ---------------------------------------------------------- |
+| `record-observer` re-deriving live activity                              | `subscribeSession` delta stream                            |
+| 80 ms `listAgents()` widget poll                                         | `session_created` / `session_status_changed` global events |
+| [#277] accessors (`messages`, `subscribeToUpdates`, `getContextPercent`) | `SessionSnapshot` + deltas                                 |
+| `ConversationViewer` / native session navigation                         | client renders the snapshot through Pi's own components    |
+| dual-source-by-liveness split                                            | server rehydrates; client sees one session shape           |
+| `steer_subagent` buffer-or-deliver                                       | `join` + `prompt` / queued-steering commands               |
+| `subagents:*` activity broadcasts                                        | session sync (semantic events stay; liveness moves)        |
+
+## Prerequisites and open questions
+
+Being honest about the constraints the plan itself raises:
+
+1. **Registry-local provider state is a hard prerequisite** (the plan states this explicitly).
+   Subagents run in-process under a multi-session server — exactly the scenario where process-global provider registration would corrupt one session's model view from another's extension load. pi-subagents is well-positioned (it already snapshots model and registry into `ParentSnapshot`), but the underlying Pi change must land first.
+2. **The recursion guard stays pi-subagents' invariant.**
+   A subagent session created through the server must still have pi-subagents' three tools stripped, and an operator-joined subagent must not be able to spawn observers of itself in a loop.
+3. **Workspace context must travel in the snapshot.**
+   Subagents can run in a different cwd or git worktree (`pi-subagents-worktrees`).
+   The plan's `SessionSnapshot.cwd` field already accounts for this, so an operator's client renders and interacts in the correct workspace.
+4. **Operator-submitted versus parent-submitted command permissions.**
+   Commands an operator joins and submits flow through the subagent's `AgentSession`, so pi-permission-system's in-child gating still applies — but whether an operator's `run bash` or `prompt` should carry a different permission posture than the parent agent's is a genuine open design question, not something to assume.
+
+## Net assessment
+
+This architecture turns all three capabilities from bespoke, fragile features pi-subagents must build and maintain into thin clients of one uniform session-sync surface — and in doing so lets pi-subagents shed most of the observation infrastructure it only built because that surface did not exist yet.
+
+[session-sync]: https://jot.mariozechner.at/s/zgzbq9n4f4mfck
+[ADR-0004]: ../decisions/0004-reconsider-ui-direction.md
+[Phase 18]: ./history/phase-18-reconsider-ui.md
+[#277]: https://github.com/gotgenes/pi-packages/issues/277

package/docs/architecture/history/phase-1-api-boundary.md

@@ -0,0 +1,8 @@
+# Phase 1: Export SubagentsService from this package
+
+Added the `SubagentsService` interface, serializable types, `Symbol.for()` accessor functions, and `SUBAGENT_EVENTS` constants as public exports.
+Wired `service-adapter.ts` to wrap `AgentManager` and call `publishSubagentsService()` at extension init.
+
+## Related issues
+
+- #48 — Export SubagentsService from this package

package/docs/architecture/history/phase-10-structural-decomposition.md

@@ -0,0 +1,141 @@
+# Phase 10: Domain organization, bag decomposition, and complexity reduction
+
+Target: reorganize source into domain directories; decompose remaining wide parameter bags into focused value objects; reduce cyclomatic complexity in rendering functions; eliminate production code duplication.
+
+## Current smells
+
+| Smell                                                   | Location                                           | Evidence                                                                                                              | Severity |
+| ------------------------------------------------------- | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- | -------- |
+| Flat `src/` directory                                   | `src/` root                                        | 20+ files in a single directory with no domain grouping; hard to see module boundaries                                | Medium   |
+| `ResolvedSpawnConfig` is a 15-field bag                 | `spawn-config.ts`                                  | Mixes identity (name, slug), execution (model, permissions), and presentation (icon, color) concerns in one interface | Medium   |
+| `AgentSpawnConfig` threads parent session fields        | `agent-manager.ts`                                 | `parentSessionFile`, `parentSessionId`, `toolCallId` always travel together but are separate parameters               | Low      |
+| `RunnerIO` is too wide                                  | `foreground-runner.ts`                             | 9 methods spanning environment concerns (cwd, env) and session factory concerns (create, attach, resume)              | Medium   |
+| `SessionConfig` mixes tool filtering with session setup | `session-config.ts`                                | `toolNames`, `disallowedSet`, `extensions` are a cohesive filter group buried in a larger config                      | Low      |
+| `RunOptions` is a 12-field bag                          | `foreground-runner.ts`                             | Mixes execution context (exec, registry, cwd) with per-run options (model, prompt, permissions)                       | Medium   |
+| `buildContentLines` high complexity                     | `ui/build-content-lines.ts`                        | ~60-line function with a switch over every content type; each branch is an independent formatter                      | Medium   |
+| `renderResult` high complexity                          | `tools/agent-tool.ts`                              | ~80-line function with status-based branching; each status is an independent rendering concern                        | Medium   |
+| Duplicated turn-formatting logic                        | `session/session-runner.ts`, `tools/agent-tool.ts` | 18 lines of identical `ToolCallContent` extraction and `getToolCallName` logic in two production files                | Low      |
+
+## Step 1: Reorganize source into domain directories (#164)
+
+Moved files into `config/`, `session/`, `lifecycle/`, `observation/`, and `service/` subdirectories.
+All `src/` internal imports now use `#src/` path aliases.
+Root `src/` reduced to 5 files + 8 directories.
+
+Impact: domain boundaries are visible in the directory tree; imports communicate intent via path alias.
+
+## Step 2: Decompose ResolvedSpawnConfig (#165)
+
+Split the 15-field `ResolvedSpawnConfig` into three focused value objects:
+
+- `SpawnIdentity` — name, slug, key
+- `SpawnExecution` — model, permissions, tools, prompt, systemPrompt
+- `SpawnPresentation` — icon, color, description
+
+`ResolvedSpawnConfig` composes these three plus the remaining spawn-level fields.
+
+Impact: each consumer receives only the fields it needs; adding a presentation field no longer touches execution code.
+
+## Step 3: Extract ParentSessionInfo from AgentSpawnConfig (#166)
+
+Extracted `parentSessionFile`, `parentSessionId`, and `toolCallId` into `ParentSessionInfo`.
+`AgentSpawnConfig` and `AgentManager.spawn()` accept the single value object instead of three separate parameters.
+
+Impact: eliminated parameter co-travel; the three fields that always move together are now a single concept.
+
+## Step 4: Narrow RunnerIO (#167)
+
+Split `RunnerIO` into two focused interfaces:
+
+- `EnvironmentIO` (3 methods) — cwd, env, platform concerns
+- `SessionFactoryIO` (5+1 methods) — create, attach, resume, and related session lifecycle
+
+`RunnerIO` kept as a backward-compatible type alias (`EnvironmentIO & SessionFactoryIO`).
+
+Impact: consumers declare which IO surface they actually need; test doubles shrink to the relevant subset.
+
+## Step 5: Extract ToolFilterConfig from SessionConfig (#168)
+
+Grouped `toolNames`, `disallowedSet`, and `extensions` into `ToolFilterConfig`.
+`filterActiveTools` accepts a single `ToolFilterConfig` argument instead of three separate parameters.
+
+Impact: tool-filtering concern is encapsulated; `SessionConfig` is narrower and more focused.
+
+## Step 6: Extract RunContext from RunOptions (#169)
+
+Extracted `exec`, `registry`, `cwd`, and `parentSession` into `RunContext`.
+`RunOptions` reduced from 12 fields to 9 (the 4 extracted fields replaced by a single `context` field, plus the remaining per-run options).
+
+Impact: execution context is a reusable value object; `RunOptions` focuses on per-run configuration.
+
+## Step 7: Reduce buildContentLines complexity (#170)
+
+Extracted per-content-type formatters into `ui/message-formatters.ts`.
+Each content type (text, tool-use, tool-result, image, etc.) has a dedicated pure function.
+`buildContentLines` is now a ~30-line dispatch loop that delegates to the appropriate formatter.
+
+Impact: cyclomatic complexity of `buildContentLines` dropped from ~15 to ~5; each formatter is independently testable.
+
+## Step 8: Reduce renderResult complexity (#171)
+
+Extracted per-status formatters into `tools/result-renderer.ts`.
+Each result status (success, error, timeout, cancelled) has a dedicated pure function.
+`renderResult` reduced from ~80 lines to a 10-line guard that dispatches to the appropriate renderer.
+
+Impact: cyclomatic complexity of `renderResult` dropped from ~10 to ~3; status rendering is independently testable.
+
+## Step 9: Extract shared turn-formatting logic (#172)
+
+Extracted `ToolCallContent`, `getToolCallName`, and `extractAssistantContent` into `session/content-items.ts`.
+Both `session/session-runner.ts` and `tools/agent-tool.ts` import from the shared module.
+
+Impact: eliminated 18 lines of production code duplication; single source of truth for turn-content extraction.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    subgraph bag["Bag decomposition track"]
+        S2["2: Decompose ResolvedSpawnConfig #165"] --> S3["3: Extract ParentSessionInfo #166"]
+        S4["4: Narrow RunnerIO #167"]
+        S5["5: Extract ToolFilterConfig #168"]
+        S6["6: Extract RunContext #169"]
+    end
+    subgraph complexity["Complexity reduction track"]
+        S7["7: Reduce buildContentLines #170"]
+        S8["8: Reduce renderResult #171"]
+        S9["9: Extract turn-formatting #172"]
+    end
+    S1["1: Reorganize into domain dirs #164"] --> bag
+    S1 --> complexity
+```
+
+Step 1 unblocked all other steps.
+Within the bag decomposition track, Step 2 enabled Step 3.
+The bag decomposition and complexity reduction tracks were independent of each other.
+
+## Impact
+
+| Metric                         | Before                         | After                                         |
+| ------------------------------ | ------------------------------ | --------------------------------------------- |
+| Health score                   | ~65                            | 75                                            |
+| `src/` root files              | 20+                            | 5 files + 8 directories                       |
+| `ResolvedSpawnConfig` fields   | 15                             | 3 composed value objects                      |
+| `RunOptions` fields            | 12                             | 9                                             |
+| `RunnerIO` methods             | 9                              | 3 (`EnvironmentIO`) + 6 (`SessionFactoryIO`)  |
+| `buildContentLines` complexity | ~15                            | ~5                                            |
+| `renderResult` lines           | ~80                            | ~10                                           |
+| Production duplication         | 18 lines                       | 0                                             |
+| Test duplication               | ~1,400 lines (69 clone groups) | ~1,400 lines (69 clone groups) — not targeted |
+
+## Related issues
+
+- #164 — Reorganize source into domain directories
+- #165 — Decompose ResolvedSpawnConfig
+- #166 — Extract ParentSessionInfo from AgentSpawnConfig
+- #167 — Narrow RunnerIO
+- #168 — Extract ToolFilterConfig from SessionConfig
+- #169 — Extract RunContext from RunOptions
+- #170 — Reduce buildContentLines complexity
+- #171 — Reduce renderResult complexity
+- #172 — Extract shared turn-formatting logic

package/docs/architecture/history/phase-11-closure-to-class.md

@@ -0,0 +1,100 @@
+# Phase 11: Closure factories to classes
+
+Target: convert all closure factories to classes, eliminating adapter closure density in `index.ts` (the package's #1 churn hotspot) and making the composition root a pure construction site.
+
+## Root cause
+
+The 44 adapter closures in `index.ts` existed because tool factories accepted narrow interfaces that didn't structurally match the real objects.
+Four structural misalignments prevented direct wiring:
+
+1. `SubagentRuntime.currentCtx` was typed `{ pi: unknown; ctx: unknown }` — every consumer had to `as any` cast.
+2. Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) lived as closures in `index.ts` instead of methods on the state holder.
+3. `AgentToolManager` mixed fields from `AgentManager` and `SettingsManager` (source mismatch).
+4. `AgentToolWidget` used different method names than `SubagentRuntime` (name mismatch).
+
+## Layer 0: Define SessionContext narrow interface (#192)
+
+Defined a `SessionContext` interface capturing the 5 fields `SubagentRuntime` actually needs.
+Replaced the `{ pi: unknown; ctx: unknown }` typing with `SessionContext | undefined`.
+
+Impact: typed foundation for all subsequent layers; no `as any` needed by consumers.
+
+## Layer 1: SubagentRuntime stores typed context, owns its queries (#193)
+
+Changed `currentCtx` to `SessionContext | undefined`.
+The single `as SessionContext` cast moved into `handleSessionStart` — the SDK boundary.
+Added typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessionInfo()`.
+
+Impact: 3 closure queries in `index.ts` → 0; 4 `as any` casts eliminated; `SubagentRuntime` is self-sufficient for tool deps.
+
+## Layer 2: Align interfaces for structural typing (#194)
+
+Three alignment changes:
+
+1. Moved `getMaxConcurrent` off `AgentToolManager` — it reads from `SettingsManager`, not `AgentManager`.
+2. Renamed widget methods — aligned `SubagentRuntime` method names with `AgentToolWidget`.
+3. Removed dead re-export `getToolCallName` in `ui/message-formatters.ts`.
+
+Impact: `AgentManager` structurally satisfies `AgentToolManager`; `SubagentRuntime` structurally satisfies `AgentToolWidget`; 0 dead exports.
+
+## Layer 3: Convert closure factories to classes (#195, #196)
+
+All five closure factories converted to classes:
+
+| Factory                          | Class                 | Issue |
+| -------------------------------- | --------------------- | ----- |
+| `createAgentTool({...})`         | `AgentTool`           | #195  |
+| `createGetResultTool(...)`       | `GetResultTool`       | #195  |
+| `createSteerTool(...)`           | `SteerTool`           | #195  |
+| `createAgentRunner(runnerIO)`    | `ConcreteAgentRunner` | #196  |
+| `createAgentsMenuHandler({...})` | `AgentsMenuHandler`   | #196  |
+
+Each class satisfies the existing interface via structural typing.
+Tool classes expose `toToolDefinition()` for Pi tool registration.
+`getModelLabel` internalized into `AgentsMenuHandler` (was a 7-line closure in `index.ts`).
+
+Impact: deps are constructor params (inspectable, testable); no captured closures.
+
+## Layer 4: Simplify index.ts (#196)
+
+With all factories converted and `AgentManager` satisfying `AgentMenuManager` structurally:
+
+- 4 adapter closures eliminated (3 manager method adapters + `getModelLabel`).
+- 4 unused imports removed.
+- Remaining ~15 closures are structural (event registrations, SDK factory callbacks).
+
+Impact: adapter closure count halved; `AgentManager` passed directly without wrappers; churn hotspot stabilized.
+
+## Step dependencies
+
+```mermaid
+flowchart LR
+    L0["Layer 0: SessionContext #192"] --> L1["Layer 1: Runtime queries #193"]
+    L1 --> L3["Layer 3: Classes #195 #196"]
+    L2["Layer 2: Align interfaces #194"] --> L3
+    L3 --> L4["Layer 4: Simplify index.ts #196"]
+```
+
+Layers 0 and 2 were independent.
+Layer 1 depended on Layer 0.
+Layer 3 depended on both Layer 1 and Layer 2.
+Layer 4 depended on Layer 3.
+
+## Impact
+
+| Metric                         | Before     | After                 |
+| ------------------------------ | ---------- | --------------------- |
+| Health score                   | 75/100 (B) | 76/100 (B)            |
+| Adapter closures in `index.ts` | 44         | ~15 (structural only) |
+| `as any` casts in `index.ts`   | 5          | 1 (SDK boundary)      |
+| Dead exports                   | 1          | 0                     |
+| Closure factories              | 5          | 0                     |
+| `index.ts` fan-out             | 25 imports | 21 imports            |
+
+## Related issues
+
+- #192 — Define SessionContext narrow interface
+- #193 — Runtime owns context queries
+- #194 — Align tool interfaces for structural typing
+- #195 — Convert tool factories to classes
+- #196 — Convert AgentRunner and AgentsMenuHandler to classes, simplify index.ts

package/docs/architecture/history/phase-12-complexity-test-fixtures.md

@@ -0,0 +1,55 @@
+# Phase 12: Complexity reduction and test fixture extraction
+
+## Summary
+
+Phase 12 decomposed the three remaining high-complexity UI functions and extracted shared test fixtures into `test/helpers/`.
+
+## Steps
+
+### Step 1: Decompose `renderWidgetLines` (cognitive 44) — [#205]
+
+`renderWidgetLines` in `ui/widget-renderer.ts` handled agent-status formatting, tree connectors, overflow, and empty states.
+Extracted per-status renderers and a tree-connector utility.
+
+- Target: `src/ui/widget-renderer.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 2: Decompose `showAgentDetail` (cognitive 33) — [#206]
+
+`showAgentDetail` in `ui/agent-config-editor.ts` handled display, edit, eject, and delete flows.
+Extracted sub-functions per menu action.
+
+- Target: `src/ui/agent-config-editor.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 3: Decompose `update` in `agent-widget.ts` (cognitive 31) — [#207]
+
+`update` mixed timer lifecycle, agent list assembly, render delegation, and visibility state.
+Extracted `assembleWidgetState` (pure) and timer management.
+
+- Target: `src/ui/agent-widget.ts`
+- Outcome: cognitive complexity < 10
+
+### Step 4: Extract shared test fixtures — [#208]
+
+The 3 heaviest clone families:
+
+- `agent-runner.test.ts` + `agent-runner-extension-tools.test.ts` (60-line shared setup)
+- `agent-menu.test.ts` + `agent-creation-wizard.test.ts` + `agent-config-editor.test.ts` (54+51+24 lines)
+- `agent-manager.test.ts` (18 internal clone groups, 210 duplicated lines)
+
+Extracted shared factories into `test/helpers/runner-io.ts` and `test/helpers/ui-stubs.ts`.
+Test duplication reduced from 71 clone groups (1,424 lines) to 59 clone groups (1,046 lines).
+
+## Metrics change
+
+| Metric                     | Before                 | After                  |
+| -------------------------- | ---------------------- | ---------------------- |
+| Health score               | 75/100 (B)             | 78/100 (B)             |
+| Fallow refactoring targets | 4                      | 1                      |
+| Test duplication           | 71 groups, 1,424 lines | 59 groups, 1,046 lines |
+
+[#205]: https://github.com/gotgenes/pi-packages/issues/205
+[#206]: https://github.com/gotgenes/pi-packages/issues/206
+[#207]: https://github.com/gotgenes/pi-packages/issues/207
+[#208]: https://github.com/gotgenes/pi-packages/issues/208

package/docs/architecture/history/phase-13-remaining-smells.md

@@ -0,0 +1,88 @@
+# Phase 13: Remaining structural smells
+
+## Summary
+
+Phase 13 addressed the remaining fallow refactoring target, oversized methods, production duplication, SDK boundary coupling, and test clone families.
+All six steps are closed: [#214], [#215], [#216], [#217], [#218], [#219].
+
+## Steps
+
+### Step 1: Convert remaining closure factories to classes — [#214]
+
+Three closure factories converted to classes, making their dependencies explicit as constructor parameters.
+
+| Factory → Class                                        | File                          |
+| ------------------------------------------------------ | ----------------------------- |
+| `createAgentConfigEditor()` → `AgentConfigEditor`      | `ui/agent-config-editor.ts`   |
+| `createAgentCreationWizard()` → `AgentCreationWizard`  | `ui/agent-creation-wizard.ts` |
+| `createSubagentsService()` → `SubagentsServiceAdapter` | `service/service-adapter.ts`  |
+
+- Outcome: 0 remaining closure factories (excluding pure-function factories)
+
+### Step 2: Decompose `buildParentContext` (cognitive 30) — [#215]
+
+`buildParentContext` in `session/context.ts` was the only remaining fallow refactoring target.
+Extracted per-entry-type formatters: `formatMessageEntry()` and `formatCompactionEntry()`.
+
+- Target: `src/session/context.ts`
+- Outcome: cognitive complexity < 10, function < 15 LOC, 0 fallow refactoring targets
+
+### Step 3: Decompose `startAgent` in `agent-manager.ts` — [#216]
+
+`startAgent` had two mutable closure variables and duplicated finalization logic in `.then()`/`.catch()`.
+Introduced `RunHandle` lifecycle object (private to `agent-manager.ts`) that owns per-run cleanup state.
+`WorktreeState` gained `performCleanup()` to eliminate ask-tell at cleanup sites.
+
+Extracted:
+
+1. `RunHandle` class — owns `unsub`/`detachFn`, `complete()`, `fail()`, idempotent `fireOnFinished()`.
+2. `finalizeBackgroundRun()` — shared background finalization.
+3. `setupWorktree()` — worktree creation with strict failure.
+4. `flushPendingSteers()` — drain buffered steers on session creation.
+5. `WorktreeState.performCleanup()` — self-cleanup eliminating ask-tell.
+
+- Target: `src/lifecycle/agent-manager.ts`, `src/lifecycle/worktree-state.ts`
+- Outcome: `startAgent` reduced to ~40 LOC; zero mutable `let` bindings in `.then()`/`.catch()`
+
+### Step 4: Extract overwrite guard from UI — [#217]
+
+Extracted the 20-line pattern duplicated between `agent-config-editor.ts` and `agent-creation-wizard.ts` into `writeAgentFile()` in `src/ui/agent-file-writer.ts`.
+
+- Target: new `src/ui/agent-file-writer.ts`
+- Outcome: 0 production clone groups (at the time; one internal group re-emerged later in `agent-config-editor.ts`)
+
+### Step 5: Push SDK boundary in `settings.ts` — [#218]
+
+Injected `agentDir: string` as a constructor parameter to `SettingsManager`, replacing the module-level `getAgentDir()` SDK call.
+
+- Target: `src/settings.ts`, `src/index.ts`
+- Outcome: `settings.ts` has 0 Pi SDK imports; `loadSettings`/`saveSettings` fully testable without SDK stubs
+
+### Step 6: Reduce test duplication — top 3 clone families — [#219]
+
+Extracted shared setup/assertion helpers for the three heaviest test clone families.
+
+- Target: `test/lifecycle/agent-manager.test.ts`, `test/conversation-viewer.test.ts`, `test/ui/agent-config-editor.test.ts`
+- Outcome: test duplication significantly reduced
+
+## Metrics change
+
+| Metric                     | Before                 | After                             |
+| -------------------------- | ---------------------- | --------------------------------- |
+| Health score               | 78/100 (B)             | 78/100 (B)                        |
+| Source files               | 53                     | 56                                |
+| Total LOC                  | 8,180                  | 8,382                             |
+| Dead code                  | 0 files, 0 exports     | 0 files, 0 exports                |
+| Maintainability index      | 90.7                   | 90.8                              |
+| Avg cyclomatic complexity  | 1.5                    | 1.4                               |
+| Fallow refactoring targets | 1                      | 0                                 |
+| Production duplication     | 0 clone groups         | 1 internal clone group (11 lines) |
+| Test duplication           | 59 groups, 1,046 lines | 38 groups, 645 lines (overall)    |
+| Churn hotspots             | 6 accelerating         | 1 accelerating (`index.ts`)       |
+
+[#214]: https://github.com/gotgenes/pi-packages/issues/214
+[#215]: https://github.com/gotgenes/pi-packages/issues/215
+[#216]: https://github.com/gotgenes/pi-packages/issues/216
+[#217]: https://github.com/gotgenes/pi-packages/issues/217
+[#218]: https://github.com/gotgenes/pi-packages/issues/218
+[#219]: https://github.com/gotgenes/pi-packages/issues/219

package/docs/architecture/history/phase-14-strip-policy.md

@@ -0,0 +1,49 @@
+# Phase 14: Strip policy from core
+
+## Summary
+
+Phase 14 removed tool and extension policy enforcement from pi-subagents.
+This code duplicated what pi-permission-system already provides with richer semantics (allow/ask/deny vs. binary hide).
+Removing it simplified `runAgent`, shrunk `AgentConfig` and `SessionConfig`, and prepared a cleaner codebase for Phase 15's domain-model work.
+
+All four steps are closed: [#237], [#238], [#239], [#242].
+
+## Steps
+
+### Step 1: Remove `disallowed_tools` — [#237]
+
+Removed the `disallowedTools` field from `AgentConfig` and all code that processed it.
+Users migrate to `permission:` frontmatter for tool restrictions.
+
+- Target: `types.ts`, `custom-agents.ts`, `session-config.ts`, `agent-runner.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
+- Outcome: single source of truth for access control in pi-permission-system
+
+### Step 2: Remove `extensions` filtering — [#238]
+
+Removed the `extensions: string[]` allowlist and simplified the field to a boolean.
+The `extensions: false` case (used by `isolated`) was retained for Phase 16.
+
+- Target: `types.ts`, `agent-runner.ts`, `session-config.ts`, `ui/agent-config-editor.ts`, `ui/agent-creation-wizard.ts`
+- Outcome: `filterActiveTools` reduced to two concerns: recursion guard and `extensions: false` passthrough
+
+### Step 3: Collapse `filterActiveTools` to recursion guard — [#239]
+
+With Steps 1–2 complete, `filterActiveTools` was reduced to its essential purpose: filtering `EXCLUDED_TOOL_NAMES` to prevent recursive agent spawning.
+
+- Removed `ToolFilterConfig` — the function no longer needs a config bag.
+- Removed the pre-bind filter call — extension tools aren't in the active set pre-bind.
+- Flattened `SessionConfig` — removed `toolFilter: ToolFilterConfig`; `toolNames` and `extensions` are top-level fields.
+- Target: `agent-runner.ts`, `session-config.ts`
+- Outcome: `filterActiveTools` is a one-liner; the pre-bind/post-bind dance is gone
+
+### Step 4: Rename `Agent` tool to `subagent` — [#242]
+
+Renamed the `Agent` tool to `subagent` to align with Pi's built-in tool naming convention (all lowercase).
+
+- Target: `tools/agent-tool.ts`, `lifecycle/agent-runner.ts`, `docs/`, `../pi-permission-system/docs/`
+- Outcome: all three tools use consistent lowercase naming
+
+[#237]: https://github.com/gotgenes/pi-packages/issues/237
+[#238]: https://github.com/gotgenes/pi-packages/issues/238
+[#239]: https://github.com/gotgenes/pi-packages/issues/239
+[#242]: https://github.com/gotgenes/pi-packages/issues/242

package/docs/architecture/history/phase-15-domain-model-evolution.md

@@ -0,0 +1,73 @@
+# Phase 15: Domain model evolution
+
+## Summary
+
+Phase 15 evolved `Agent` from a passive state machine (`AgentRecord`) into an object that **owns its entire execution lifecycle**.
+Before Phase 15, `AgentManager` orchestrated everything: calling the runner, handling session creation, wiring observers, and cleaning up worktrees — reaching into Agent 10+ times across `spawn()` and `startAgent()`.
+After Phase 15, Agent is born complete with all dependencies and configuration, owns `run()` and `resume()`, and manages its own observer and worktree lifecycle.
+
+All six steps are closed: [#227], [#228], [#231], [#229], [#230], [#232].
+
+## Key changes
+
+- `AgentRecord` renamed to `Agent` with full behavioral surface.
+- `Agent.run()` encapsulates the entire execution lifecycle: worktree setup, runner invocation, session-creation handling, observer wiring, worktree cleanup, and status transitions.
+- `Agent.resume()` manages its own observer subscription lifecycle.
+- `startAgent` deleted from `AgentManager` — replaced by `agent.run()`.
+- `ConcurrencyQueue` extracted from `AgentManager` — scheduling is independently testable.
+- `SpawnArgs` deleted — the queue stores agent IDs, not config objects.
+- `onSessionCreated` callback replaced by `AgentLifecycleObserver` passed at construction.
+- `exec` and `registry` relay-only dependencies moved from `AgentManager` to `ConcreteAgentRunner`.
+- `AgentManagerOptions` shrunk from 7 to 5 fields.
+
+## Steps
+
+### Step 1: Evolve AgentRecord into Agent with behavior — [#227]
+
+Renamed `AgentRecord` → `Agent`.
+Moved per-agent behavior from `AgentManager` into the agent: `abort()`, `queueSteer()` / `flushPendingSteers()`, `setupWorktree()`.
+
+### Step 2: Convert startAgent to async/await — [#228]
+
+Converted `startAgent` to `async` with `try/catch` and dissolved `RunHandle` into `Agent` methods.
+Agent gained run lifecycle methods: `completeRun`, `failRun`, `wireSignal`, `attachObserver`, `releaseListeners`.
+
+### Step 3: Push exec/registry relay deps to runner construction — [#231]
+
+`exec` and `registry` moved from `AgentManager` to `ConcreteAgentRunner` via `RunnerDeps`.
+`RunContext` shrunk from 4 to 2 per-call fields.
+
+### Step 4: Agent born complete — Agent.run() absorbs startAgent — [#229]
+
+Agent receives `runner`, `worktrees`, and a lifecycle observer at construction.
+`Agent.run()` encapsulates the entire execution lifecycle.
+`startAgent`, `SpawnArgs`, `onSessionCreated` callback deleted.
+
+### Step 5: Extract ConcurrencyQueue from AgentManager — [#230]
+
+Extracted `queue[]`, `runningBackground`, `_getMaxConcurrent`, `drainQueue()`, `finalizeBackgroundRun()` into `ConcurrencyQueue`.
+`AgentManager` lost 3 fields and 3 methods (~40 lines).
+
+### Step 6: Agent.resume() with internal observer lifecycle — [#232]
+
+`Agent.resume(prompt, signal)` manages its own observer subscription lifecycle.
+`AgentManager.resume()` became a one-liner delegation.
+
+## Findings summary
+
+| Finding                                                            | Category     | Status                |
+| ------------------------------------------------------------------ | ------------ | --------------------- |
+| `AgentRecord` anemic — no behavior, manager reaches in 37×         | B: Oversized | ✅ Resolved           |
+| Agent cannot run itself — manager orchestrates 10 external touches | C: Coupling  | ✅ Resolved           |
+| Scheduling tangled into `AgentManager` (3 fields, 3 methods)       | A: Coupling  | ✅ Resolved           |
+| `startAgent` uses `.then()`/`.catch()` instead of async/await      | C: Callbacks | ✅ Resolved           |
+| `onSessionCreated` callback flows through 3 layers                 | C: Callbacks | ✅ Subsumed by Step 4 |
+| `resume()` duplicates observer subscribe/unsubscribe pattern       | A: Redundant | ✅ Resolved           |
+| `exec`/`registry` relay-only deps on `AgentManager`                | C: Coupling  | ✅ Resolved           |
+
+[#227]: https://github.com/gotgenes/pi-packages/issues/227
+[#228]: https://github.com/gotgenes/pi-packages/issues/228
+[#229]: https://github.com/gotgenes/pi-packages/issues/229
+[#230]: https://github.com/gotgenes/pi-packages/issues/230
+[#231]: https://github.com/gotgenes/pi-packages/issues/231
+[#232]: https://github.com/gotgenes/pi-packages/issues/232