@gotgenes/pi-subagents 6.8.3 → 6.9.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.0...pi-subagents-v6.9.1) (2026-05-22)
+
+
+### Documentation
+
+* plan decompose agent-tool.ts into foreground/background modules ([#115](https://github.com/gotgenes/pi-packages/issues/115)) ([4b9aefb](https://github.com/gotgenes/pi-packages/commit/4b9aefb18fe0431a033d90f10bcbe7d37c53a6b8))
+* **retro:** add retro notes for issue [#114](https://github.com/gotgenes/pi-packages/issues/114) ([e6095e7](https://github.com/gotgenes/pi-packages/commit/e6095e7465f482ac18756305b9740f1101dbd41a))
+* update architecture for E1 agent-tool decomposition ([#115](https://github.com/gotgenes/pi-packages/issues/115)) ([8bccf0a](https://github.com/gotgenes/pi-packages/commit/8bccf0ab90787d906c82c5a362c0763d3b7bd2f5))
+
+## [6.9.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.3...pi-subagents-v6.9.0) (2026-05-22)
+
+
+### Features
+
+* add onAgentCreated to AgentManagerObserver ([e2f1c12](https://github.com/gotgenes/pi-packages/commit/e2f1c1273ce560231cc98ef3c7e214efd2c20f47))
+
+
+### Documentation
+
+* mark D2 done, update field counts in architecture.md ([#114](https://github.com/gotgenes/pi-packages/issues/114)) ([702caf4](https://github.com/gotgenes/pi-packages/commit/702caf4187bfa015b0d80361b06b6360fddc31b1))
+* plan narrow AgentToolDeps and AgentMenuDeps ([#114](https://github.com/gotgenes/pi-packages/issues/114)) ([0f7e953](https://github.com/gotgenes/pi-packages/commit/0f7e95362043109c4113cfe3f7b848e296f118c9))
+* **retro:** add retro notes for issue [#113](https://github.com/gotgenes/pi-packages/issues/113) ([6b3c280](https://github.com/gotgenes/pi-packages/commit/6b3c2800e6d7728b8b620172e4acb1068b65e6c4))
+
 ## [6.8.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.2...pi-subagents-v6.8.3) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -54,10 +54,12 @@ settings.ts               — persistent operational settings; `SettingsManager`
 service.ts                — SubagentsService interface + Symbol.for() accessors
 service-adapter.ts        — SubagentsService implementation wrapping AgentManager
 
-tools/agent-tool.ts       — Agent tool definition + execute
-tools/get-result-tool.ts  — get_subagent_result tool
-tools/steer-tool.ts       — steer_subagent tool
-tools/helpers.ts          — shared tool utilities
+tools/agent-tool.ts          — Agent tool definition, parameter validation, dispatch
+tools/foreground-runner.ts   — foreground execution loop (spinner, streaming, result)
+tools/background-spawner.ts  — background spawn (activity setup, notification wiring)
+tools/get-result-tool.ts     — get_subagent_result tool
+tools/steer-tool.ts          — steer_subagent tool
+tools/helpers.ts             — shared tool utilities (textResult, buildDetails, getStatusNote, …)
 
 handlers/lifecycle.ts     — session_start, session_before_switch, session_shutdown
 handlers/tool-start.ts    — tool_execution_start handler
@@ -259,10 +261,12 @@ src/
 ├── index.ts                  — slimmed entry point: init, tool registration
 ├── runtime.ts                — SubagentRuntime: session-scoped state + methods
 ├── tools/
-│   ├── agent-tool.ts         — Agent tool definition + execute
+│   ├── agent-tool.ts         — Agent tool definition, parameter validation, dispatch
+│   ├── foreground-runner.ts  — foreground execution loop (spinner, streaming, result)
+│   ├── background-spawner.ts — background spawn (activity setup, notification wiring)
 │   ├── get-result-tool.ts    — get_subagent_result tool
 │   ├── steer-tool.ts         — steer_subagent tool
-│   └── helpers.ts            — shared tool utilities
+│   └── helpers.ts            — shared tool utilities (textResult, buildDetails, getStatusNote, …)
 ├── handlers/
 │   ├── lifecycle.ts          — session_start, session_before_switch, session_shutdown
 │   └── tool-start.ts         — tool_execution_start handler
@@ -377,17 +381,17 @@ Each step is sequenced so it makes the next step easier.
 
 ### Current smells
 
-| 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)                                                                                                       |
-| ~~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 |
-| Wide dependency bags           | `AgentToolDeps` (7), `AgentMenuDeps` (8) | Settings narrowed (#109); registry narrowed (#108); more narrowing planned in D steps                                                                                     |
+| 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)                                                                                                               |
+| ~~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         |
+| ~~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)
 
@@ -437,7 +441,7 @@ Split post-construction mutation into phase-specific collaborators, each born co
 
 - **`ExecutionState`** (`session`, `outputFile`) — constructed in `onSessionCreated`, attached as `record.execution`.
 - **`WorktreeState`** (`path`, `branch`, `cleanupResult`) — constructed at worktree setup, attached as `record.worktreeState`.
-- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by agent-tool after spawn, attached as `record.notification`.
+- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by `AgentManager.spawn()` when `toolCallId` is provided in `AgentSpawnConfig`, attached as `record.notification`.
 - **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`; steer-tool and service-adapter call `manager.queueSteer()`.
 - Stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods (`incrementToolUses`, `addUsage`, `incrementCompactions`) with read-only getters.
 - `AgentRecordInit` trimmed from 19 optional fields to 4 construction-time fields.
@@ -462,19 +466,26 @@ With the registry class, settings manager, and observer in place, the dependency
 Internal `SpawnOptions` in `agent-manager.ts` renamed to `AgentSpawnConfig`.
 Public `SpawnOptions` in `service.ts` is unchanged.
 
-#### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114)
+#### D2. Narrow `AgentToolDeps` and `AgentMenuDeps` (#114) ✅
 
-| Bag             | Before    | After | How                                                                                                                    |
-| --------------- | --------- | ----- | ---------------------------------------------------------------------------------------------------------------------- |
-| `AgentToolDeps` | 9 fields  | ~5    | Registry owns reload; activity tracker is a collaborator; `emitEvent` moves to observer                                |
-| `AgentMenuDeps` | 13 fields | ~6    | Settings manager absorbs 6 fields (#109); apply methods remove `notifyConcurrencyChanged` (#118); registry owns reload |
+**Done.**
+`AgentToolDeps` 9 → 6: removed `emitEvent` (moved to `AgentManagerObserver.onAgentCreated`), `typeListText`, `availableTypesText` (derived inside `createAgentTool`); `agentActivity` narrowed to `AgentActivityAccess`.
+`AgentMenuDeps` 8 → 7: removed dead `emitEvent` field; `agentActivity` narrowed to `AgentActivityReader`.
+`buildTypeListText` extracted to `tools/helpers.ts`.
+
+| Bag             | Before   | After | How                                                                                                           |
+| --------------- | -------- | ----- | ------------------------------------------------------------------------------------------------------------- |
+| `AgentToolDeps` | 9 fields | 6     | `emitEvent` → observer; `typeListText`/`availableTypesText` derived from registry; `agentActivity` narrowed   |
+| `AgentMenuDeps` | 8 fields | 7     | Dead `emitEvent` removed; `agentActivity` narrowed to read-only `AgentActivityReader`                         |
 
 ### Step E: Decompose large files and relocate types (parallel)
 
-#### E1. Split `agent-tool.ts` foreground/background (#115)
+#### E1. Split `agent-tool.ts` foreground/background (#115) ✅
 
-Extract the foreground execution loop (spinner, streaming, result rendering) and background spawn path into separate modules.
-The 654-line file splits along a natural seam.
+**Done.**
+Fixed two upstream API gaps before extracting: `onSessionCreated` now receives `(session, record)` (eliminating a `listAgents()` reverse-search), and `AgentSpawnConfig` accepts `toolCallId` (moving `NotificationState` wiring into `AgentManager.spawn()`).
+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)
 
@@ -494,8 +505,8 @@ The 654-line file splits along a natural seam.
 | 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~~ **7** (−6 registry #108, −1 settings #109 → +1 settings obj)               | ~5      |
-| `AgentMenuDeps` fields                     | ~~13~~ **8** (−6 settings #109 collapsed to 1; −1 registry #108)                 | ~6 ✓    |
+| `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       |

package/docs/plans/0114-narrow-agent-tool-menu-deps.md

@@ -0,0 +1,279 @@
+---
+issue: 114
+issue_title: "refactor(pi-subagents): narrow AgentToolDeps and AgentMenuDeps"
+---
+
+# Narrow AgentToolDeps and AgentMenuDeps
+
+## Problem Statement
+
+With the foundational extractions complete — `AgentTypeRegistry` (#108), `SettingsManager` (#109), `AgentActivityTracker` (#110), and `AgentManagerObserver` (#112) — the two widest dependency bags in the extension still carry fields that belong on their collaborators.
+
+`AgentToolDeps` has 9 fields: 3 are description-text strings derivable from the registry, 1 is a raw `emitEvent` callback that the observer should own, and the `agentActivity` Map is passed as raw mutable state.
+`AgentMenuDeps` has 8 fields: `emitEvent` is defined but never referenced in the module (dead field).
+
+Each excess field inflates test mock construction and obscures the real dependency surface.
+
+## Goals
+
+- Remove `emitEvent` from both `AgentToolDeps` and `AgentMenuDeps`.
+- Remove `typeListText` and `availableTypesText` from `AgentToolDeps` — derive them from `registry` inside `createAgentTool`.
+- Add `onAgentCreated` to `AgentManagerObserver` so the `subagents:created` event is emitted by the observer, not the tool.
+- Narrow `agentActivity` in both interfaces to a typed read/write interface instead of raw `Map`.
+- Final counts: `AgentToolDeps` 9 → 6, `AgentMenuDeps` 8 → 7.
+
+## Non-Goals
+
+- Removing `agentDir` from `AgentToolDeps` — it is not derivable from the registry (it comes from the Pi SDK's `getAgentDir()`).
+- Adding presentation methods to `AgentTypeRegistry` — that would mix SRP concerns.
+- Splitting `agent-tool.ts` foreground/background (tracked in #115).
+- Removing `personalAgentsDir` / `projectAgentsDir` from `AgentMenuDeps` — they are genuine menu-level concerns (file management UI).
+
+## Background
+
+### Prerequisite status
+
+All prerequisites are implemented and merged:
+
+| Issue | Title                                          | Status  |
+| ----- | ---------------------------------------------- | ------- |
+| #108  | Extract `AgentTypeRegistry`                    | ✅ Done |
+| #109  | Extract `SettingsManager`                      | ✅ Done |
+| #110  | `AgentActivityTracker`                         | ✅ Done |
+| #112  | Replace `AgentManager` callbacks with observer | ✅ Done |
+| #113  | Disambiguate `SpawnOptions`                    | ✅ Done |
+| #118  | `SettingsManager` apply methods                | ✅ Done |
+
+### Current interfaces
+
+```typescript
+// tools/agent-tool.ts — 9 fields
+interface AgentToolDeps {
+  manager: AgentToolManager;
+  widget: AgentToolWidget;
+  agentActivity: Map<string, AgentActivityTracker>;
+  emitEvent: (name: string, data: unknown) => void;
+  registry: AgentTypeRegistry;
+  typeListText: string;
+  availableTypesText: string;
+  agentDir: string;
+  settings: { readonly defaultMaxTurns: number | undefined };
+}
+
+// ui/agent-menu.ts — 8 fields
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: Map<string, AgentActivityTracker>;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  emitEvent: (name: string, data: unknown) => void;   // ← dead field
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+### Relevant design principles
+
+- **Dependency width** (code-design skill): do not pass a shared bag to functions that only use a subset.
+- **Output arguments**: `agentActivity` is a raw `Map` mutated via `.set()` and `.delete()` — encapsulate behind methods.
+- **ISP**: consumers should depend on the narrowest interface they need.
+
+## Design Overview
+
+### 1. Move `subagents:created` to observer
+
+The `AgentManagerObserver` interface gains an `onAgentCreated` method.
+`AgentManager.spawn()` calls `observer.onAgentCreated(record)` after creating the record.
+The observer implementation in `index.ts` emits `pi.events.emit("subagents:created", ...)`.
+The tool no longer calls `deps.emitEvent(...)`.
+
+The event payload includes `id`, `type`, `description`, and `isBackground`.
+Since `isBackground` is known at spawn-time (it's part of the spawn config), the observer has all needed data.
+
+```typescript
+interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+  onAgentCreated(record: AgentRecord): void;  // ← new
+}
+```
+
+### 2. Derive description text from registry
+
+Move `buildTypeListText()` from `index.ts` to `tools/helpers.ts` as a pure function that accepts the registry and `agentDir`:
+
+```typescript
+function buildTypeListText(
+  registry: AgentConfigLookup & { getDefaultAgentNames(): string[]; getUserAgentNames(): string[] },
+  agentDir: string,
+): string;
+```
+
+Inside `createAgentTool`, compute both strings from `deps.registry` and `deps.agentDir`:
+
+```typescript
+const typeListText = buildTypeListText(deps.registry, deps.agentDir);
+const availableTypesText = deps.registry.getAvailableTypes().join(", ");
+```
+
+This removes `typeListText` and `availableTypesText` from the interface.
+The helper requires `getModelLabelFromConfig`, which already lives in `tools/helpers.ts`.
+
+### 3. Narrow agentActivity to a typed interface
+
+Instead of `Map<string, AgentActivityTracker>`, both interfaces accept a narrow typed interface matching their actual usage:
+
+```typescript
+/** Read/write interface for agent-tool's activity tracking needs. */
+interface AgentActivityAccess {
+  get(id: string): AgentActivityTracker | undefined;
+  set(id: string, tracker: AgentActivityTracker): void;
+  delete(id: string): void;
+}
+```
+
+The `AgentMenuDeps` only reads (`.get()`), so it gets a narrower read-only type:
+
+```typescript
+/** Read-only interface for menu's conversation viewer. */
+interface AgentActivityReader {
+  get(id: string): AgentActivityTracker | undefined;
+}
+```
+
+The runtime's `Map<string, AgentActivityTracker>` satisfies both interfaces structurally.
+No wrapper class is needed — `Map` already implements `get/set/delete`.
+The benefit is that the type signature communicates the actual usage pattern.
+
+### 4. Remove dead `emitEvent` from `AgentMenuDeps`
+
+This field is defined in the interface but never referenced inside `agent-menu.ts`.
+Remove it from the interface and from the construction site in `index.ts`.
+
+### Final interfaces
+
+```typescript
+// tools/agent-tool.ts — 6 fields (was 9)
+interface AgentToolDeps {
+  manager: AgentToolManager;
+  widget: AgentToolWidget;
+  agentActivity: AgentActivityAccess;
+  registry: AgentTypeRegistry;
+  agentDir: string;
+  settings: { readonly defaultMaxTurns: number | undefined };
+}
+
+// ui/agent-menu.ts — 7 fields (was 8)
+interface AgentMenuDeps {
+  manager: AgentMenuManager;
+  registry: AgentTypeRegistry;
+  agentActivity: AgentActivityReader;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
+  settings: AgentMenuSettings;
+  personalAgentsDir: string;
+  projectAgentsDir: string;
+}
+```
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/agent-manager.ts`** — Call `observer.onAgentCreated(record)` in `spawn()` after creating the record.
+   Update `AgentManagerObserver` interface to include `onAgentCreated`.
+
+2. **`src/tools/agent-tool.ts`** — Remove `emitEvent`, `typeListText`, `availableTypesText` from `AgentToolDeps`.
+   Add `AgentActivityAccess` interface.
+   Derive description text from `registry` + `agentDir` inside `createAgentTool`.
+   Remove `deps.emitEvent(...)` call.
+   Replace `Map<string, AgentActivityTracker>` with `AgentActivityAccess`.
+
+3. **`src/tools/helpers.ts`** — Add `buildTypeListText(registry, agentDir)` extracted from `index.ts`.
+
+4. **`src/ui/agent-menu.ts`** — Remove `emitEvent` from `AgentMenuDeps`.
+   Add `AgentActivityReader` interface.
+   Replace `Map<string, AgentActivityTracker>` with `AgentActivityReader`.
+
+5. **`src/index.ts`** — Remove `buildTypeListText` closure.
+   Remove `typeListText`, `availableTypesText`, `emitEvent` from the `AgentToolDeps` construction.
+   Remove `emitEvent` from the `AgentMenuDeps` construction.
+   Add `onAgentCreated` to the observer object.
+
+6. **`test/tools/agent-tool.test.ts`** — Update `makeDeps` factory: remove `emitEvent`, `typeListText`, `availableTypesText`.
+   Update assertions that check `emitEvent` was called.
+
+7. **`test/ui/agent-menu.test.ts`** — Update `makeDeps` factory: remove `emitEvent`.
+
+8. **`test/agent-manager.test.ts`** — Add test for `observer.onAgentCreated` being called during spawn.
+
+## Test Impact Analysis
+
+1. **New tests enabled**: `observer.onAgentCreated` can be tested in `agent-manager.test.ts` — verify it fires during `spawn()` with the correct record.
+
+2. **Tests that simplify**: `agent-tool.test.ts` mock factory drops 3 fields (`emitEvent`, `typeListText`, `availableTypesText`).
+   Tests asserting `deps.emitEvent` was called become assertions that the observer was invoked (tested at the manager level instead).
+   `agent-menu.test.ts` mock factory drops 1 field (`emitEvent`).
+
+3. **Tests that stay**: all tool-behavior tests (spawn paths, resume, error handling) remain — they test the tool's own logic, not the narrowed plumbing.
+
+## TDD Order
+
+1. **Add `onAgentCreated` to observer interface and manager.**
+   Add the method to `AgentManagerObserver`.
+   Call it in `AgentManager.spawn()`.
+   Test: verify `observer.onAgentCreated` fires with the created record.
+   Commit: `feat: add onAgentCreated to AgentManagerObserver`
+
+2. **Extract `buildTypeListText` to helpers.**
+   Move the function from `index.ts` to `tools/helpers.ts` as a pure function.
+   Test: unit test `buildTypeListText` with a mock registry.
+   Update `index.ts` to import and call the extracted helper.
+   Commit: `refactor: extract buildTypeListText to tools/helpers`
+
+3. **Derive description text inside `createAgentTool`.**
+   Remove `typeListText` and `availableTypesText` from `AgentToolDeps`.
+   Compute them from `deps.registry` + `deps.agentDir` inside `createAgentTool`.
+   Update `index.ts` construction site.
+   Update `agent-tool.test.ts` mock factory.
+   Test: verify tool description still contains expected text.
+   Commit: `refactor: derive description text from registry in createAgentTool`
+
+4. **Remove `emitEvent` from `AgentToolDeps`.**
+   Remove the field from the interface.
+   Remove the `deps.emitEvent(...)` call in the background spawn path.
+   Wire `onAgentCreated` in the `index.ts` observer to emit `subagents:created`.
+   Update `agent-tool.test.ts` (remove `emitEvent` from factory, remove/update related assertions).
+   Commit: `refactor: remove emitEvent from AgentToolDeps`
+
+5. **Remove dead `emitEvent` from `AgentMenuDeps`.**
+   Remove the field from the interface.
+   Remove from `index.ts` construction site.
+   Update `agent-menu.test.ts` mock factory.
+   Commit: `refactor: remove dead emitEvent from AgentMenuDeps`
+
+6. **Narrow `agentActivity` to typed interfaces.**
+   Add `AgentActivityAccess` interface to `agent-tool.ts`.
+   Add `AgentActivityReader` interface to `agent-menu.ts`.
+   Replace `Map<string, AgentActivityTracker>` with the narrow type in both interfaces.
+   Update test factories (no functional change — `Map` satisfies both interfaces).
+   Commit: `refactor: narrow agentActivity to typed interfaces`
+
+## Risks and Mitigations
+
+| Risk                                                                                    | Mitigation                                                                                                                                                                                            |
+| --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `subagents:created` event data changes shape when moved to observer                     | Observer receives the full `AgentRecord` which contains `id`, `type`, `description`. `isBackground` must be derivable from the record or spawn config — verify the record carries this at spawn time. |
+| `buildTypeListText` depends on `getModelLabelFromConfig` which is in `tools/helpers.ts` | This is already the target file — no circular dependency risk.                                                                                                                                        |
+| Third-party consumers rely on `emitEvent` presence in `AgentToolDeps`                   | `AgentToolDeps` is not in the public `exports` — it's internal. No external API breakage.                                                                                                             |
+| `AgentActivityAccess` interface is structurally identical to a subset of `Map`          | This is intentional — the `Map` satisfies it without a wrapper. If a non-Map implementation is needed later, the interface is already in place.                                                       |
+
+## Open Questions
+
+1. Should `onAgentCreated` receive the full `AgentRecord` or a narrow payload?
+   The other observer methods receive `AgentRecord` — consistency suggests the same.
+   The `isBackground` flag is needed for the event payload; verify it's available on the record at creation time (it should be, since background is set at spawn).
+2. Should `steer-tool.ts`'s `emitEvent` (emits `subagents:steered`) also move to the observer?
+   It's a separate concern (tool-level steering) and a different event.
+   Defer to a follow-up if desired.