@gotgenes/pi-subagents 6.9.1 → 6.9.2

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).
 
+## [6.9.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.1...pi-subagents-v6.9.2) (2026-05-22)
+
+
+### Documentation
+
+* mark E2 type housekeeping done in architecture ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([89f18a8](https://github.com/gotgenes/pi-packages/commit/89f18a82fac39b4a62be8e440355b859afaa6d2f))
+* plan type housekeeping and small structural cleanups ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([e1cbd26](https://github.com/gotgenes/pi-packages/commit/e1cbd269961a1bff3b11e2e916733a79c39a087d))
+* **retro:** add retro notes for issue [#115](https://github.com/gotgenes/pi-packages/issues/115) ([05b8809](https://github.com/gotgenes/pi-packages/commit/05b88093f7b70ea886b6c7cb5f0cc96161a95df6))
+
 ## [6.9.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.0...pi-subagents-v6.9.1) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -384,13 +384,13 @@ Each step is sequenced so it makes the next step easier.
 | Smell                          | Location                                     | Evidence                                                                                                                                                                          |
 | ------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ~~Global mutable state~~       | ~~`agent-types.ts`~~                         | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                         |
-| Closure bag as class           | `createNotificationSystem()`                 | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                               |
+| ~~Closure bag as class~~       | ~~`createNotificationSystem()`~~             | **Fixed #116**: `NotificationManager` class; `pendingNudges` and timer state are private fields                                                                                   |
 | ~~Mutable state bag~~          | ~~`AgentActivity` (7 fields)~~               | **Fixed #110**: `AgentActivityTracker` class; `ui-observer.ts` calls transition methods; widget, notification, agent-tool use read-only accessors                                 |
 | ~~Settings relay~~             | ~~`AgentMenuDeps` (13 fields)~~              | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                                 |
 | ~~Post-construction mutation~~ | ~~`AgentRecord` non-transition state~~       | **Fixed #111**: `ExecutionState`, `WorktreeState`, `NotificationState` collaborators; `pendingSteers` moved to `AgentManager`; stats encapsulated behind mutation methods         |
 | ~~Fire-and-forget callbacks~~  | ~~`AgentManagerOptions`~~                    | **Fixed #112**: `AgentManagerObserver` interface; `observer` replaces 3 callbacks; `index.ts` constructs one observer object instead of 3 closure lambdas                         |
 | ~~Duplicate `SpawnOptions`~~   | ~~`service.ts` + `agent-manager.ts`~~        | **Fixed #113**: internal type renamed to `AgentSpawnConfig`; public `SpawnOptions` in `service.ts` unchanged                                                                      |
-| Type dumping ground            | `types.ts`                                   | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each         |
+| ~~Type dumping ground~~        | ~~`types.ts`~~                               | **Fixed #116**: `NotificationDetails` → `notification.ts`; `ParentSnapshot` → `parent-snapshot.ts`; `EnvInfo` → `env.ts`; `AgentIdentity` and `AgentPromptConfig` narrow subsets  |
 | ~~Wide dependency bags~~       | ~~`AgentToolDeps` (9), `AgentMenuDeps` (8)~~ | **Fixed #114**: `AgentToolDeps` 9 → 6; `AgentMenuDeps` 8 → 7; `emitEvent` removed from both; description text derived from registry; `agentActivity` narrowed to typed interfaces |
 
 ### Step A: Extract state into classes (foundation, parallel)
@@ -487,29 +487,28 @@ Fixed two upstream API gaps before extracting: `onSessionCreated` now receives `
 Extracted `foreground-runner.ts` (~175 lines) and `background-spawner.ts` (~116 lines).
 `agent-tool.ts` reduced from 579 → 411 lines (orchestrator + rendering).
 
-#### E2. Type housekeeping (#116)
+#### ~~E2. Type housekeeping (#116)~~ — **Done**
 
-- Move `NotificationDetails` from `types.ts` to `notification.ts`.
-- Move `DEFAULT_AGENT_NAMES` from `types.ts` to the registry.
-- Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.
-- Move `EnvInfo` from `types.ts` to `env.ts`.
-- Convert `createNotificationSystem` closure to `NotificationManager` class.
-- Convert `ConversationViewer` constructor from 6 positional parameters to an options bag.
-- Define narrow `AgentConfig` subset interfaces for consumers that use 2–4 fields of the 21-field type.
+- Moved `NotificationDetails` from `types.ts` to `notification.ts`.
+- Moved `ParentSnapshot` from `types.ts` to `parent-snapshot.ts` (`DEFAULT_AGENT_NAMES` was already moved in #108).
+- Moved `EnvInfo` from `types.ts` to `env.ts`.
+- Converted `createNotificationSystem` closure to `NotificationManager` class.
+- Converted `ConversationViewer` constructor from 7 positional parameters to `ConversationViewerOptions` bag.
+- Defined `AgentIdentity` and `AgentPromptConfig` narrow subsets; `AgentConfig extends` both; `buildAgentPrompt` narrowed to `AgentPromptConfig`.
 
 ### Expected impact
 
-| Metric                                     | Before                                                                           | After   |
-| ------------------------------------------ | -------------------------------------------------------------------------------- | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                     | **0** ✓ |
-| Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**)     | 0       |
-| Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**) | 0 ✓     |
-| `AgentManagerOptions` fields               | 8                                                                                | 5       |
-| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed) | 6 ✓     |
-| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)        | 7 ✓     |
-| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                           | 0       |
-| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain     | 0       |
-| Types in `types.ts` without a natural home | 4                                                                                | 0       |
+| Metric                                     | Before                                                                                 | After   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------- | ------- |
+| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                           | **0** ✓ |
+| Closure-bag "classes"                      | ~~2~~ ~~1~~ **0** (`createNotificationSystem` **fixed #116**; settings **fixed #109**) | 0 ✓     |
+| Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**)       | 0 ✓     |
+| `AgentManagerOptions` fields               | 8                                                                                      | 5       |
+| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed)       | 6 ✓     |
+| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)              | 7 ✓     |
+| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                                 | 0       |
+| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain           | 0       |
+| Types in `types.ts` without a natural home | ~~4~~ **0** ✓ (all moved #116)                                                         | 0 ✓     |
 
 ### Dependency graph
 

package/docs/plans/0116-type-housekeeping.md

@@ -0,0 +1,351 @@
+---
+issue: 116
+issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
+---
+
+# Type housekeeping and small structural cleanups
+
+## Problem Statement
+
+`types.ts` is a type dumping ground — it collects types that don't have a natural home because the module that should own them didn't exist yet.
+With foundation extractions (#108 registry, `parent-snapshot.ts`, `env.ts`, `notification.ts`) now in place, most of these types have a natural home.
+Several other small housekeeping items share the same "polish" character: a closure-bag factory that is a class in disguise, a positional constructor that creates test friction, and a 22-field `AgentConfig` interface consumed by modules that touch 2–4 of its fields.
+
+## Goals
+
+- Move `NotificationDetails` to `notification.ts`, `ParentSnapshot` to `parent-snapshot.ts`, and `EnvInfo` to `env.ts`.
+- Convert `createNotificationSystem` closure to a `NotificationManager` class.
+- Convert `ConversationViewer` constructor from 7 positional parameters to an options bag.
+- Define narrow `AgentConfig` subset interfaces for consumers that use only a few fields.
+- Leave `types.ts` containing only genuinely cross-cutting types: `SubagentType`, `MemoryScope`, `IsolationMode`, `AgentConfig`, `AgentInvocation`, `ShellExec`, and re-exports (`AgentRecord`, `ThinkingLevel`).
+
+## Non-Goals
+
+- Refactoring `AgentConfig` itself (field additions, removals, renames).
+- Changing the `NotificationDeps` interface shape.
+- Modifying `agent-menu.ts` to use narrow subsets — it legitimately reads most `AgentConfig` fields as a config editor/viewer.
+- Touching `invocation-config.ts` — it already receives `AgentConfig | undefined` and only reads invocation-default fields; narrowing its parameter is a separate concern.
+
+## Background
+
+### Prerequisite status
+
+| Issue | Title                             | Status  |
+| ----- | --------------------------------- | ------- |
+| #108  | Extract `AgentTypeRegistry` class | ✅ Done |
+
+`DEFAULT_AGENT_NAMES` was already moved to `AgentTypeRegistry.DEFAULT_AGENT_NAMES` as part of #108.
+The remaining work from the issue's checklist is type relocations, two structural conversions, and narrow subset interfaces.
+
+### Current `types.ts` exports
+
+| Export                                             | Kind      | Should stay?                    |
+| -------------------------------------------------- | --------- | ------------------------------- |
+| `AgentRecord` (re-export)                          | class     | ✅ Cross-cutting                |
+| `AgentRecordInit`, `AgentRecordStatus` (re-export) | type      | ✅ Cross-cutting                |
+| `ThinkingLevel` (re-export)                        | type      | ✅ Cross-cutting                |
+| `SubagentType`                                     | type      | ✅ Cross-cutting                |
+| `MemoryScope`                                      | type      | ✅ Cross-cutting                |
+| `IsolationMode`                                    | type      | ✅ Cross-cutting                |
+| `AgentConfig`                                      | interface | ✅ Cross-cutting                |
+| `AgentInvocation`                                  | interface | ✅ Cross-cutting                |
+| `ShellExec`                                        | type      | ✅ Cross-cutting                |
+| `NotificationDetails`                              | interface | ❌ Move to `notification.ts`    |
+| `ParentSnapshot`                                   | interface | ❌ Move to `parent-snapshot.ts` |
+| `EnvInfo`                                          | interface | ❌ Move to `env.ts`             |
+
+### `createNotificationSystem` closure analysis
+
+The factory in `notification.ts` shares `pendingNudges` (a `Map`) and timer state across 4 inner functions (`cancelNudge`, `scheduleNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`).
+This is a class in disguise — mutable state + methods that read/write it.
+Converting to a `NotificationManager` class makes the state explicit and lets tests use instance methods directly.
+
+### `ConversationViewer` constructor
+
+The constructor takes 7 positional parameters:
+
+```typescript
+constructor(tui, session, record, activity, theme, done, registry)
+```
+
+Every test must reconstruct all 7 in order.
+An options bag reduces friction and is resilient to new parameters.
+
+### `AgentConfig` field usage by consumer
+
+| Consumer                                                   | Fields used                                                                                  |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `agent-widget.ts` (`getDisplayName`, `getPromptModeLabel`) | `name`, `displayName`, `promptMode`                                                          |
+| `tools/helpers.ts` (`formatAgentList`)                     | `name`, `description`, `model`                                                               |
+| `prompts.ts` (`buildAgentPrompt`)                          | `name`, `promptMode`, `systemPrompt`                                                         |
+| `session-config.ts` (`assembleSessionConfig`)              | `name`, `model`, `thinking`, `maxTurns`, `extensions`, `skills`, `memory`, `disallowedTools` |
+| `agent-menu.ts`                                            | Nearly all fields (config viewer/editor)                                                     |
+
+Natural clusters for narrow interfaces:
+
+- **`AgentIdentity`**: `name`, `displayName`, `description`, `promptMode` — UI display and agent listing.
+- **`AgentPromptConfig`**: `name`, `promptMode`, `systemPrompt` — prompt assembly.
+
+`session-config.ts` uses 8 fields; narrowing it yields limited value vs. complexity.
+`invocation-config.ts` receives `AgentConfig | undefined` and reads invocation-default fields; this is a separate concern.
+
+## Design Overview
+
+### Type relocations
+
+Move each type to its natural home module and re-export from `types.ts` during an interim step.
+After updating all importers to point at the new home, remove the re-export.
+This two-phase approach (move + re-export, then update importers + remove re-export) avoids a big-bang commit.
+
+However, since importers are few (2–4 each) and the types are only used internally, a single step per type is simpler: move the type, update all importers in the same commit.
+
+### `NotificationManager` class
+
+Replace the `createNotificationSystem` factory with a class that owns its state:
+
+```typescript
+export class NotificationManager {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void { /* ... */ }
+  sendCompletion(record: AgentRecord): void { /* ... */ }
+  cleanupCompleted(id: string): void { /* ... */ }
+  dispose(): void { /* ... */ }
+
+  // private helpers
+  private scheduleNudge(key: string, send: () => void, delay?: number): void { /* ... */ }
+  private emitIndividualNudge(record: AgentRecord): void { /* ... */ }
+}
+```
+
+The `NotificationSystem` interface stays as-is — `NotificationManager implements NotificationSystem`.
+The `NotificationDeps` interface is unchanged.
+Callers in `index.ts` switch from `createNotificationSystem(deps)` to `new NotificationManager(deps)`.
+
+Consumer call site (index.ts):
+
+```typescript
+const notifications = new NotificationManager({
+  sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
+  agentActivity: runtime.agentActivity,
+  markFinished: (id) => runtime.markFinished(id),
+  updateWidget: () => runtime.updateWidget(),
+});
+```
+
+### `ConversationViewer` options bag
+
+Replace positional parameters with a named options interface:
+
+```typescript
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+}
+
+export class ConversationViewer {
+  constructor(private options: ConversationViewerOptions) {
+    // destructure into private fields or use options.field access
+  }
+}
+```
+
+The existing private fields (`tui`, `session`, `record`, etc.) become reads from `this.options.*` or are destructured in the constructor to named private fields.
+The constructor body (session subscription) is unchanged.
+
+### Narrow `AgentConfig` subset interfaces
+
+Define two narrow interfaces in `types.ts` and make `AgentConfig` extend them:
+
+```typescript
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
+  name: string;
+  displayName?: string;
+  description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
+  // remaining fields unchanged
+}
+```
+
+Then update consumers to accept the narrow interface:
+
+- `agent-widget.ts`: `getDisplayName(type, registry)` and `getPromptModeLabel(type, registry)` — these go through `AgentConfigLookup.resolveAgentConfig()`, which returns `AgentConfig`.
+  The narrowing applies to the *return type usage*, not the function signature.
+  No change needed here — the function already destructures only `displayName`, `name`, `promptMode`.
+- `tools/helpers.ts`: `formatAgentList` reads `description`, `model` — these are not in `AgentIdentity`.
+  `model` is session-config territory.
+  Leave as-is.
+- `prompts.ts`: `buildAgentPrompt(config: AgentPromptConfig, ...)` — narrow the parameter type.
+- `AgentConfigLookup.resolveAgentConfig()` return type stays `AgentConfig` — the registry always has the full config.
+
+Since `AgentConfig extends AgentIdentity, AgentPromptConfig`, any code passing an `AgentConfig` to a function expecting the narrow type works without casts.
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/types.ts`**
+   - Remove `NotificationDetails`, `ParentSnapshot`, `EnvInfo` interface definitions.
+   - Add `AgentIdentity` and `AgentPromptConfig` interfaces.
+   - Make `AgentConfig` extend `AgentIdentity` and `AgentPromptConfig`.
+   - Remove fields from `AgentConfig` body that are now inherited (`name`, `displayName`, `description`, `promptMode`, `systemPrompt`).
+
+2. **`src/notification.ts`**
+   - Add `NotificationDetails` interface (moved from `types.ts`).
+   - Replace `createNotificationSystem` factory with `NotificationManager` class implementing `NotificationSystem`.
+   - Export `NotificationManager` (named export) and keep `NotificationSystem` interface export.
+   - Remove `createNotificationSystem` export.
+
+3. **`src/parent-snapshot.ts`**
+   - Add `ParentSnapshot` interface (moved from `types.ts`).
+
+4. **`src/env.ts`**
+   - Add `EnvInfo` interface (moved from `types.ts`).
+
+5. **`src/prompts.ts`**
+   - Change `config` parameter type from `AgentConfig` to `AgentPromptConfig`.
+   - Update import to use `AgentPromptConfig` from `./types.js`.
+
+6. **`src/index.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+   - Replace `createNotificationSystem(deps)` with `new NotificationManager(deps)`.
+   - Update import: `NotificationManager` from `./notification.js`.
+
+7. **`src/renderer.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+
+8. **`src/agent-runner.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+9. **`src/agent-manager.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+10. **`src/session-config.ts`**
+    - Update `EnvInfo` import from `./types.js` to `./env.js`.
+
+11. **`src/ui/conversation-viewer.ts`**
+    - Define `ConversationViewerOptions` interface.
+    - Replace 7 positional constructor parameters with single `options: ConversationViewerOptions` parameter.
+    - Assign private fields from `options` in constructor body.
+
+### Unchanged files
+
+- `src/agent-types.ts` — `DEFAULT_AGENT_NAMES` already moved in #108.
+- `src/invocation-config.ts` — narrowing is a separate concern.
+- `src/ui/agent-menu.ts` — legitimately uses most `AgentConfig` fields.
+
+### Test files
+
+12. **`test/notification.test.ts`**
+    - Replace `createNotificationSystem(deps)` calls with `new NotificationManager(deps)`.
+    - Update import.
+    - All existing assertions stay — the public API is identical.
+
+13. **`test/conversation-viewer.test.ts`**
+    - Replace positional `new ConversationViewer(tui, session, record, activity, theme, done, registry)` calls with `new ConversationViewer({ tui, session, record, activity, theme, done, registry })`.
+    - All existing assertions stay.
+
+14. **`test/prompts.test.ts`**
+    - Verify existing test fixtures satisfy `AgentPromptConfig` (they should — tests already pass `name`, `promptMode`, `systemPrompt`).
+    - May need to narrow mock type annotations.
+
+15. **Other test files importing relocated types** (`test/parent-snapshot.test.ts`, `test/renderer.test.ts`)
+    - Update import paths if they import directly from `types.ts` (most import from the source module already).
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:**
+   - `NotificationManager` as a class can be tested with standard `new` + method calls — no factory indirection.
+     However, the existing factory tests are already clean and simply switch to `new NotificationManager(deps)`.
+     No fundamentally new test capabilities.
+
+2. **Existing tests that simplify:**
+   - `conversation-viewer.test.ts` — the options bag makes test construction more readable and resilient to parameter additions.
+     Each test only needs to specify the fields it cares about (with a helper providing defaults).
+   - `prompts.test.ts` — narrower `AgentPromptConfig` parameter means test fixtures can omit 19 irrelevant `AgentConfig` fields.
+
+3. **Existing tests that must stay as-is:**
+   - `notification.test.ts` — all factory tests stay, just switch constructor syntax.
+   - `conversation-viewer.test.ts` — all render and input tests stay, just switch constructor syntax.
+   - `parent-snapshot.test.ts`, `env.test.ts`, `renderer.test.ts` — behavior unchanged.
+
+## TDD Order
+
+1. **Move `NotificationDetails` from `types.ts` to `notification.ts`.**
+   Cut the interface from `types.ts`, paste into `notification.ts`.
+   Update importers: `index.ts`, `renderer.ts` (change import from `./types.js` to `./notification.js`).
+   `notification.ts` already imports from `./types.js` for `AgentRecord` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move NotificationDetails to notification.ts`
+
+2. **Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.**
+   Cut the interface from `types.ts`, paste into `parent-snapshot.ts`.
+   Update importers: `agent-manager.ts`, `agent-runner.ts` (change import from `./types.js` to `./parent-snapshot.js`).
+   Run `pnpm run check`.
+   Commit: `refactor: move ParentSnapshot to parent-snapshot.ts`
+
+3. **Move `EnvInfo` from `types.ts` to `env.ts`.**
+   Cut the interface from `types.ts`, paste into `env.ts`.
+   Update importers: `session-config.ts`, `prompts.ts` (change import from `./types.js` to `./env.js`).
+   `env.ts` already imports `ShellExec` from `./types.js` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move EnvInfo to env.ts`
+
+4. **Convert `createNotificationSystem` to `NotificationManager` class.**
+   Replace the factory with a class implementing `NotificationSystem`.
+   Move `pendingNudges` and timer logic to private instance state.
+   Convert inner functions to methods.
+   Keep `NotificationSystem` interface, `NotificationDeps` interface, and `NUDGE_HOLD_MS` constant unchanged.
+   Remove `createNotificationSystem` export, add `NotificationManager` export.
+   Update `index.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`.
+   Update `test/notification.test.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`, update import.
+   Run `pnpm vitest run test/notification.test.ts`.
+   Commit: `refactor: convert createNotificationSystem to NotificationManager class`
+
+5. **Convert `ConversationViewer` constructor to options bag.**
+   Define `ConversationViewerOptions` interface.
+   Replace 7 positional parameters with `options: ConversationViewerOptions`.
+   Assign private fields from options in constructor body.
+   Update all call sites in `test/conversation-viewer.test.ts` and `src/index.ts` (or wherever `new ConversationViewer(...)` is called).
+   Run `pnpm vitest run test/conversation-viewer.test.ts`.
+   Commit: `refactor: convert ConversationViewer to options bag constructor`
+
+6. **Define narrow `AgentIdentity` and `AgentPromptConfig` interfaces.**
+   Add interfaces to `types.ts`.
+   Make `AgentConfig` extend both; remove inherited fields from `AgentConfig` body.
+   Narrow `prompts.ts` `buildAgentPrompt` parameter from `AgentConfig` to `AgentPromptConfig`.
+   Update `test/prompts.test.ts` type annotations if needed.
+   Run `pnpm run check` and `pnpm vitest run`.
+   Commit: `refactor: define AgentIdentity and AgentPromptConfig subset interfaces`
+
+## Risks and Mitigations
+
+| Risk                                                                                    | Mitigation                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Moving types breaks import paths in files not caught by grep                            | Run `pnpm run check` (full `tsc --noEmit`) after each type relocation step.                                                                   |
+| `NotificationManager` class changes test mock patterns (e.g., spreading instances)      | Tests already use the factory return as an opaque object — switching to `new` is mechanical. No spread patterns in notification tests.        |
+| `ConversationViewer` options bag breaks all test call sites at once                     | All 314 lines of tests use the same 7-arg pattern. A search-and-replace handles it. The options bag is a single-step change.                  |
+| `AgentConfig extends AgentIdentity, AgentPromptConfig` changes structural compatibility | `extends` is purely additive — existing code passing `AgentConfig` anywhere still works. Narrowed consumers gain type safety, nothing breaks. |
+| `prompts.ts` parameter narrowing breaks callers passing `AgentConfig`                   | `AgentConfig extends AgentPromptConfig`, so all existing call sites are compatible without changes.                                           |
+
+## Open Questions
+
+- Whether to define an `AgentSessionConfig` subset for `session-config.ts` (8 fields) — deferred because the narrowing ratio (8 of 22) yields less clarity benefit than `AgentIdentity` (4 of 22) or `AgentPromptConfig` (3 of 22).

package/docs/retro/0115-decompose-agent-tool.md

@@ -0,0 +1,51 @@
+---
+issue: 115
+issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
+---
+
+# Retro: #115 — decompose agent-tool.ts into foreground/background modules
+
+## Final Retrospective (2026-05-21T22:30:00-04:00)
+
+### Session summary
+
+Decomposed the 579-line `tools/agent-tool.ts` into focused modules: `foreground-runner.ts` (spinner, streaming, cleanup) and `background-spawner.ts` (activity setup, notification wiring), with `agent-tool.ts` remaining as the orchestrator (411 lines).
+Before extracting, fixed two upstream API gaps: widened `onSessionCreated` callback to `(session, record)` to eliminate a `listAgents()` reverse-search, and added `toolCallId` to `AgentSpawnConfig` so the manager wires `NotificationState` at spawn time.
+Test count increased from 641 to 690.
+Released as `pi-subagents-v6.9.1`.
+
+### Observations
+
+#### What went well
+
+- The revised plan (after user feedback) was structurally clean — fixing API gaps first made the extraction trivial; each extracted module received only what it needed without workarounds.
+- TDD execution was smooth: 6 steps, all green after each commit, only minor deviations (type annotation issue, `index.ts` call-site fix).
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` (user-caught) — The initial plan was a mechanical code-move that defined 4 new interfaces (`ForegroundRunDeps`, `BackgroundSpawnDeps`, `ForegroundRunParams`, `BackgroundSpawnParams`) to paper over two upstream API gaps: a `listAgents()` reverse-search in the foreground `onSessionCreated` callback, and a post-spawn `record.notification` mutation in the background path.
+  The user asked *"What dependencies are still missing for these split tools, that they want, rather than some low level state or collaborators that they have?"*
+  — redirecting me to fix the API surface before extracting.
+  Impact: entire plan rewritten (~15 minutes), but the revised plan was significantly cleaner and the implementation went smoothly.
+
+- `missing-context` (self-identified) — During step 5 (foreground extraction), two tests in `foreground-runner.test.ts` failed because mock sessions were `{}` objects lacking a `subscribe` method required by `subscribeUIObserver`.
+  The function's dependency on `SubscribableSession` (requiring `.subscribe()`) wasn't accounted for in the test mock.
+  Impact: one test fix cycle (~2 minutes), no rework.
+
+- `missing-context` (self-identified) — Annotating `runForeground` with an explicit `Promise<AgentToolResult<any>>` return type widened the content array type from `{ type: "text", text: string }[]` to `(TextContent | ImageContent)[]`, breaking existing `content[0].text` patterns in tests.
+  Fixed by removing the explicit annotation and letting TypeScript infer the narrow type.
+  Impact: three edit cycles to diagnose and fix (~5 minutes).
+
+- `missing-context` (self-identified) — Step 1 removed `listAgents` from `AgentToolManager` but didn't update the construction site in `index.ts`.
+  `pnpm run check` caught it in step 4.
+  Impact: one-line fix in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- The initial plan's size and mechanical nature required a user redirect.
+  The `/plan-issue` prompt's Design Overview section asks to sketch consumer call sites for *new collaborators*, but the same Tell-Don't-Ask check should apply to *extracted* modules' interactions with their upstream dependencies.
+  A prompt tweak could help the agent catch this pattern earlier.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added extraction-specific Tell-Don't-Ask verification step to the Design Overview section: sketch the extracted module's upstream interactions before planning the extraction, fix API gaps first.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.9.1",
+  "version": "6.9.2",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -14,10 +14,11 @@ import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
 import { NotificationState } from "./notification-state.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 

package/src/agent-runner.ts

@@ -15,9 +15,10 @@ import {
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
 import { detectEnv } from "./env.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { assembleSessionConfig } from "./session-config.js";
 import { deriveSubagentSessionDir } from "./session-dir.js";
-import type { ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];

package/src/env.ts

@@ -3,7 +3,13 @@
  */
 
 import { debugLog } from "./debug.js";
-import type { EnvInfo, ShellExec } from "./types.js";
+import type { ShellExec } from "./types.js";
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}
 
 export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
   let isGitRepo = false;

package/src/index.ts

@@ -18,7 +18,7 @@ import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { buildEventData, createNotificationSystem } from "./notification.js";
+import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
@@ -28,7 +28,6 @@ import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
 import { createSteerTool } from "./tools/steer-tool.js";
-import { type NotificationDetails } from "./types.js";
 import { createAgentsMenuHandler } from "./ui/agent-menu.js";
 import {
   AgentWidget,
@@ -48,7 +47,7 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = createNotificationSystem({
+  const notifications = new NotificationManager({
     sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
     agentActivity: runtime.agentActivity,
     markFinished: (id) => runtime.markFinished(id),

package/src/notification.ts

@@ -1,8 +1,23 @@
 import { debugLog } from "./debug.js";
-import type { AgentRecord, NotificationDetails } from "./types.js";
+import type { AgentRecord } from "./types.js";
 import type { AgentActivityTracker } from "./ui/agent-activity-tracker.js";
 import { getLifetimeTotal, getSessionContextPercent } from "./usage.js";
 
+/** Details attached to custom notification messages for visual rendering. */
+export interface NotificationDetails {
+  id: string;
+  description: string;
+  status: string;
+  toolUses: number;
+  turnCount: number;
+  maxTurns?: number;
+  totalTokens: number;
+  durationMs: number;
+  outputFile?: string;
+  error?: string;
+  resultPreview: string;
+}
+
 // ---- Pure helpers (exported for unit testing) ----
 
 /** Escape XML special characters to prevent injection in structured notifications. */
@@ -129,23 +144,43 @@ export interface NotificationSystem {
 
 const NUDGE_HOLD_MS = 200;
 
-export function createNotificationSystem(deps: NotificationDeps): NotificationSystem {
-  const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+export class NotificationManager implements NotificationSystem {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  function cancelNudge(key: string) {
-    const timer = pendingNudges.get(key);
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void {
+    const timer = this.pendingNudges.get(key);
     if (timer != null) {
       clearTimeout(timer);
-      pendingNudges.delete(key);
+      this.pendingNudges.delete(key);
     }
   }
 
-  function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
-    cancelNudge(key);
-    pendingNudges.set(
+  sendCompletion(record: AgentRecord): void {
+    this.deps.agentActivity.delete(record.id);
+    this.deps.markFinished(record.id);
+    this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
+    this.deps.updateWidget();
+  }
+
+  cleanupCompleted(id: string): void {
+    this.deps.agentActivity.delete(id);
+    this.deps.markFinished(id);
+    this.deps.updateWidget();
+  }
+
+  dispose(): void {
+    for (const timer of this.pendingNudges.values()) clearTimeout(timer);
+    this.pendingNudges.clear();
+  }
+
+  private scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS): void {
+    this.cancelNudge(key);
+    this.pendingNudges.set(
       key,
       setTimeout(() => {
-        pendingNudges.delete(key);
+        this.pendingNudges.delete(key);
         try {
           send();
         } catch (err) {
@@ -155,41 +190,21 @@ export function createNotificationSystem(deps: NotificationDeps): NotificationSy
     );
   }
 
-  function emitIndividualNudge(record: AgentRecord) {
+  private emitIndividualNudge(record: AgentRecord): void {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
     const outputFile = record.execution?.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    deps.sendMessage(
+    this.deps.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );
   }
-
-  function sendCompletion(record: AgentRecord) {
-    deps.agentActivity.delete(record.id);
-    deps.markFinished(record.id);
-    scheduleNudge(record.id, () => emitIndividualNudge(record));
-    deps.updateWidget();
-  }
-
-  function cleanupCompleted(id: string) {
-    deps.agentActivity.delete(id);
-    deps.markFinished(id);
-    deps.updateWidget();
-  }
-
-  function dispose() {
-    for (const timer of pendingNudges.values()) clearTimeout(timer);
-    pendingNudges.clear();
-  }
-
-  return { cancelNudge, sendCompletion, cleanupCompleted, dispose };
 }

package/src/parent-snapshot.ts

@@ -4,7 +4,26 @@
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildParentContext } from "./context.js";
-import type { ParentSnapshot } from "./types.js";
+
+/**
+ * Plain data snapshot of the parent session state captured at spawn time.
+ * Replaces live `ExtensionContext` references so queued agents don't read stale state.
+ */
+export interface ParentSnapshot {
+  /** Parent working directory. */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  systemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  model: unknown;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+  /** Pre-built parent conversation text (when inheritContext was requested). */
+  parentContext?: string;
+}
 
 /**
  * Build an immutable snapshot of the parent session state.

package/src/prompts.ts

@@ -2,7 +2,8 @@
  * prompts.ts — System prompt builder for agents.
  */
 
-import type { AgentConfig, EnvInfo } from "./types.js";
+import type { EnvInfo } from "./env.js";
+import type { AgentPromptConfig } from "./types.js";
 
 /** Extra sections to inject into the system prompt (memory, skills, etc.). */
 export interface PromptExtras {
@@ -27,7 +28,7 @@ export interface PromptExtras {
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
  */
 export function buildAgentPrompt(
-  config: AgentConfig,
+  config: AgentPromptConfig,
   cwd: string,
   env: EnvInfo,
   parentSystemPrompt?: string,

package/src/renderer.ts

@@ -1,5 +1,5 @@
 import { Text } from "@earendil-works/pi-tui";
-import type { NotificationDetails } from "./types.js";
+import type { NotificationDetails } from "./notification.js";
 import { formatMs, formatTokens, formatTurns } from "./ui/agent-widget.js";
 
 /** Narrow theme interface — only the methods the renderer actually calls. */

package/src/session-config.ts

@@ -15,10 +15,11 @@ import {
   getMemoryToolNames,
   getReadOnlyMemoryToolNames,
 } from "./agent-types.js";
+import type { EnvInfo } from "./env.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
 import { preloadSkills } from "./skill-loader.js";
-import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+import type { SubagentType, ThinkingLevel } from "./types.js";
 
 // ── Public interfaces ────────────────────────────────────────────────────────
 

package/src/types.ts

@@ -18,11 +18,23 @@ export type MemoryScope = "user" | "project" | "local";
 /** Isolation mode for agent execution. */
 export type IsolationMode = "worktree";
 
-/** Unified agent configuration — used for both default and user-defined agents. */
-export interface AgentConfig {
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
   name: string;
   displayName?: string;
   description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+/** Unified agent configuration — used for both default and user-defined agents. */
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
   builtinToolNames?: string[];
   /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
   disallowedTools?: string[];
@@ -33,8 +45,6 @@ export interface AgentConfig {
   model?: string;
   thinking?: ThinkingLevel;
   maxTurns?: number;
-  systemPrompt: string;
-  promptMode: "replace" | "append";
   /** Default for spawn: fork parent conversation. undefined = caller decides. */
   inheritContext?: boolean;
   /** Default for spawn: run in background. undefined = caller decides. */
@@ -64,48 +74,6 @@ export interface AgentInvocation {
   isolation?: IsolationMode;
 }
 
-/** Details attached to custom notification messages for visual rendering. */
-export interface NotificationDetails {
-  id: string;
-  description: string;
-  status: string;
-  toolUses: number;
-  turnCount: number;
-  maxTurns?: number;
-  totalTokens: number;
-  durationMs: number;
-  outputFile?: string;
-  error?: string;
-  resultPreview: string;
-
-}
-
-/**
- * Plain data snapshot of the parent session state captured at spawn time.
- * Replaces live `ExtensionContext` references so queued agents don't read stale state.
- */
-export interface ParentSnapshot {
-  /** Parent working directory. */
-  cwd: string;
-  /** Parent's effective system prompt (for append-mode agents). */
-  systemPrompt: string;
-  /** Parent's current model instance (fallback when agent config has no model). */
-  model: unknown;
-  /** Model registry for resolving config.model strings and creating sessions. */
-  modelRegistry: {
-    find(provider: string, modelId: string): unknown;
-    getAvailable?(): Array<{ provider: string; id: string }>;
-  };
-  /** Pre-built parent conversation text (when inheritContext was requested). */
-  parentContext?: string;
-}
-
-export interface EnvInfo {
-  isGitRepo: boolean;
-  branch: string;
-  platform: string;
-}
-
 /**
  * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
  * Matches the shape of `pi.exec()` without carrying an SDK dependency.

package/src/ui/agent-menu.ts

@@ -220,7 +220,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
 
     await ctx.ui.custom<undefined>(
       (tui: any, theme: any, _keybindings: any, done: any) => {
-        return new ConversationViewer(tui, session, record, activity, theme, done, deps.registry);
+        return new ConversationViewer({ tui, session, record, activity, theme, done, registry: deps.registry });
       },
       {
         overlay: true,

package/src/ui/conversation-viewer.ts

@@ -20,6 +20,16 @@ const MIN_VIEWPORT = 3;
 /** Height ceiling shared by the overlay's `maxHeight` and the viewer's internal viewport cap. */
 export const VIEWPORT_HEIGHT_PCT = 70;
 
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+}
+
 export class ConversationViewer implements Component {
   private scrollOffset = 0;
   private autoScroll = true;
@@ -27,16 +37,23 @@ export class ConversationViewer implements Component {
   private lastInnerW = 0;
   private closed = false;
 
-  constructor(
-    private tui: TUI,
-    private session: AgentSession,
-    private record: AgentRecord,
-    private activity: AgentActivityTracker | undefined,
-    private theme: Theme,
-    private done: (result: undefined) => void,
-    private registry: AgentConfigLookup,
-  ) {
-    this.unsubscribe = session.subscribe(() => {
+  private tui: TUI;
+  private session: AgentSession;
+  private record: AgentRecord;
+  private activity: AgentActivityTracker | undefined;
+  private theme: Theme;
+  private done: (result: undefined) => void;
+  private registry: AgentConfigLookup;
+
+  constructor(options: ConversationViewerOptions) {
+    this.tui = options.tui;
+    this.session = options.session;
+    this.record = options.record;
+    this.activity = options.activity;
+    this.theme = options.theme;
+    this.done = options.done;
+    this.registry = options.registry;
+    this.unsubscribe = options.session.subscribe(() => {
       if (this.closed) return;
       this.tui.requestRender();
     });