@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/plans/0112-replace-agent-manager-callbacks.md

@@ -1,241 +0,0 @@
----
-issue: 112
-issue_title: "refactor(pi-subagents): replace AgentManager callbacks with observer interface"
----
-
-# Replace AgentManager callbacks with observer interface
-
-## Problem Statement
-
-`AgentManagerOptions` accepts three fire-and-forget callbacks — `onStart`, `onComplete`, `onCompact` — that `index.ts` wires as closure lambdas capturing `runtime`, `pi`, `notifications`, and other extension state.
-This is the same callback-threading pattern that was replaced with direct session subscriptions in #100, but one level up.
-The callbacks are notification-style (fire-and-forget, no return value) and match the observer pattern exactly.
-
-## Goals
-
-- Replace the three callback parameters on `AgentManagerOptions` with a single `observer?: AgentManagerObserver` interface.
-- `index.ts` constructs one observer object instead of three independent closure lambdas.
-- `AgentManagerOptions` shrinks by two net fields (remove 3 callbacks, add 1 observer).
-- Preserve all existing behavior: lifecycle events, record persistence, notification dispatch, compaction events.
-- Non-breaking refactor — no public API changes (the callbacks are internal to the package).
-
-## Non-Goals
-
-- Extracting the observer implementation from `index.ts` into its own module — that can follow if the object grows.
-- Changing `RecordObserverOptions` (session-level observer) — it remains a separate concern at a different layer.
-- Narrowing `AgentToolDeps` or `AgentMenuDeps` — tracked in #114.
-- Disambiguating `SpawnOptions` — tracked in #113.
-
-## Background
-
-### Current callback wiring
-
-`agent-manager.ts` defines three callback type aliases and stores them as private fields:
-
-```typescript
-export type OnAgentStart = (record: AgentRecord) => void;
-export type OnAgentComplete = (record: AgentRecord) => void;
-export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
-```
-
-`AgentManager` invokes them at three points:
-
-1. `onStart` — called in `startAgent()` after `record.markRunning()`.
-2. `onComplete` — called in `startAgent()`'s `.then()` and `.catch()` handlers for background agents, and in `drainQueue()` on late failure.
-3. `onCompact` — relayed through `subscribeRecordObserver()` → `RecordObserverOptions.onCompact`.
-
-`index.ts` builds ~30 lines of closure lambdas (lines 73–116) that capture `pi`, `notifications`, and `buildEventData`.
-
-### Observer pattern already established
-
-`record-observer.ts` and `ui/ui-observer.ts` are session-level observers that subscribe directly to session events.
-This refactoring applies the same principle at the manager level — grouping related notification callbacks into a single interface.
-
-### Dependency: issue #111 (AgentRecord lifecycle split)
-
-Issue #111 is closed.
-The observer interface is designed against the current record shape, which reflects the post-#111 lifecycle split.
-
-### Architecture reference
-
-Phase 7, Step C in `docs/architecture/architecture.md`.
-
-## Design Overview
-
-### Observer interface
-
-```typescript
-export interface AgentManagerObserver {
-  onAgentStarted(record: AgentRecord): void;
-  onAgentCompleted(record: AgentRecord): void;
-  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
-}
-```
-
-All three methods are fire-and-forget (void return, no async).
-The interface uses past-tense naming (`Started`, `Completed`, `Compacted`) to signal that these are after-the-fact notifications, not hooks that influence the operation.
-
-### `AgentManagerOptions` change
-
-```typescript
-export interface AgentManagerOptions {
-  runner: AgentRunner;
-  worktrees: WorktreeManager;
-  exec: ShellExec;
-  registry: AgentTypeRegistry;
-  getMaxConcurrent?: () => number;
-  getRunConfig?: () => RunConfig;
-  observer?: AgentManagerObserver;  // replaces onStart, onComplete, onCompact
-}
-```
-
-Fields go from 9 → 7 (remove 3 callbacks, add 1 observer).
-
-### AgentManager internal changes
-
-The three private fields (`onStart`, `onComplete`, `onCompact`) become one: `private observer?: AgentManagerObserver`.
-Call sites change from `this.onStart?.(record)` to `this.observer?.onAgentStarted(record)`.
-
-The `onCompact` relay into `subscribeRecordObserver` changes from:
-
-```typescript
-onCompact: (r, info) => this.onCompact?.(r, info),
-```
-
-to:
-
-```typescript
-onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
-```
-
-### `CompactionInfo` stays in `agent-manager.ts`
-
-`CompactionInfo` is a data shape consumed by the observer interface and already defined in `agent-manager.ts`.
-It stays co-located since both `AgentManagerObserver` and `CompactionInfo` are exported from the same module.
-`record-observer.ts` continues to import `CompactionInfo` from `agent-manager.ts`.
-
-### Observer construction in `index.ts`
-
-The three closure lambdas collapse into one object literal:
-
-```typescript
-const observer: AgentManagerObserver = {
-  onAgentStarted(record) {
-    pi.events.emit("subagents:started", {
-      id: record.id, type: record.type, description: record.description,
-    });
-  },
-  onAgentCompleted(record) {
-    const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
-    const eventData = buildEventData(record);
-    if (isError) pi.events.emit("subagents:failed", eventData);
-    else pi.events.emit("subagents:completed", eventData);
-
-    pi.appendEntry("subagents:record", { /* same fields as today */ });
-
-    if (record.notification?.resultConsumed) {
-      notifications.cleanupCompleted(record.id);
-      return;
-    }
-    notifications.sendCompletion(record);
-  },
-  onAgentCompacted(record, info) {
-    pi.events.emit("subagents:compacted", {
-      id: record.id, type: record.type, description: record.description,
-      reason: info.reason, tokensBefore: info.tokensBefore,
-      compactionCount: record.compactionCount,
-    });
-  },
-};
-```
-
-Passed as `observer` to `new AgentManager({ ..., observer })`.
-
-### Removed exports
-
-The three callback type aliases are removed:
-
-- `OnAgentStart`
-- `OnAgentComplete`
-- `OnAgentCompact`
-
-These are only imported in `agent-manager.test.ts` — no production consumers outside `agent-manager.ts`.
-
-## Module-Level Changes
-
-### `src/agent-manager.ts`
-
-- Add `AgentManagerObserver` interface (3 methods).
-- Remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact` type aliases.
-- Replace `onStart`, `onComplete`, `onCompact` fields in `AgentManagerOptions` with `observer?: AgentManagerObserver`.
-- Replace three private fields with `private observer?: AgentManagerObserver`.
-- Update constructor to assign `this.observer = options.observer`.
-- Update all call sites: `this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.
-- The `onCompact` relay to `subscribeRecordObserver` uses `this.observer?.onAgentCompacted`.
-
-### `src/index.ts`
-
-- Replace the three closure-lambda properties (`onComplete:`, `onStart:`, `onCompact:`) with a single `observer` object literal.
-- Import `AgentManagerObserver` from `agent-manager.ts`.
-- Remove any now-unused callback type imports.
-
-### `src/record-observer.ts`
-
-- No changes.
-  `RecordObserverOptions.onCompact` stays as-is — it is the session-level relay, not the manager-level observer.
-  `CompactionInfo` import from `agent-manager.ts` stays unchanged.
-
-### `test/agent-manager.test.ts`
-
-- Update imports: remove `OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`; add `AgentManagerObserver`.
-- Update `createManager` helper: replace the three callback overrides with `observer?: Partial<AgentManagerObserver>`.
-  The factory spreads a no-op default observer with test-provided overrides.
-- Update each test that wires a callback to construct an observer object instead.
-
-## Test Impact Analysis
-
-1. No new unit tests are enabled by this refactoring — it's a 1:1 shape change.
-2. No existing tests become redundant — each test exercises a specific lifecycle scenario (race condition, foreground vs background, error handling, queue drain).
-3. All existing `agent-manager.test.ts` tests stay, with mechanical updates to the observer wiring.
-   The assertions remain the same (e.g., "observer.onAgentCompleted fires with `resultConsumed=false` when `markConsumed` called after await").
-
-## TDD Order
-
-### Step 1: Introduce `AgentManagerObserver` interface alongside existing callbacks
-
-Add the interface to `agent-manager.ts`.
-No production behavior changes — the interface is unused at this point.
-
-- Commit: `refactor: add AgentManagerObserver interface`
-
-### Step 2: Switch `AgentManager` internals to observer
-
-1. Replace the three `onStart`/`onComplete`/`onCompact` fields on `AgentManagerOptions` with `observer?: AgentManagerObserver`.
-2. Replace the three private fields with one `private observer?: AgentManagerObserver`.
-3. Update all internal call sites (`this.onStart?.(record)` → `this.observer?.onAgentStarted(record)`, etc.).
-4. Remove the three callback type aliases (`OnAgentStart`, `OnAgentComplete`, `OnAgentCompact`).
-5. Update `test/agent-manager.test.ts`: change imports, update `createManager` helper and all test call sites to construct observer objects instead of individual callbacks.
-6. Run `pnpm run check` to verify types.
-
-- Commit: `refactor: replace AgentManager callbacks with observer interface (#112)`
-
-### Step 3: Update `index.ts` to construct observer
-
-1. Replace the three closure-lambda properties in the `new AgentManager({...})` call with a single `observer` object.
-2. Import `AgentManagerObserver` type.
-3. Remove unused callback type imports.
-4. Run full test suite.
-
-- Commit: `refactor: construct AgentManagerObserver in index.ts (#112)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                                | Mitigation                                                                                                                                                                  |
-| ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Tests break silently because esbuild ignores excess properties — old `onComplete` fields pass through without error | Step 2 removes the type aliases, so TypeScript catches any test still using the old shape via `pnpm run check`                                                              |
-| `onComplete` error-swallowing behavior changes                                                                      | The `try/catch` around `this.onComplete?.(record)` in the `.then()` path moves exactly to `this.observer?.onAgentCompleted(record)` — same guard, same catch, same debugLog |
-| `Partial<AgentManagerObserver>` in test factory silently drops required methods                                     | Tests that need a specific method construct it explicitly; the factory only provides a convenient default for tests that don't care about any observer method               |
-
-## Open Questions
-
-- None — the issue's proposed design is unambiguous and aligns with the established session-observer pattern.

package/docs/plans/0113-disambiguate-spawn-options.md

@@ -1,155 +0,0 @@
----
-issue: 113
-issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
----
-
-# Disambiguate SpawnOptions (public vs internal)
-
-## Problem Statement
-
-`SpawnOptions` is defined in two places with the same name but incompatible shapes:
-
-- `service.ts` (public API): 8 fields, JSON-friendly (`model` is `string`, `thinkingLevel` is `string`, uses `foreground` not `isBackground`).
-- `agent-manager.ts` (internal): 13 fields, runtime types (`model` is `Model<any>`, `thinkingLevel` is `ThinkingLevel`, includes `signal`, `onSessionCreated`, `invocation`).
-
-The name collision makes it ambiguous which type a reader is working with when they see `SpawnOptions` in a signature.
-`service-adapter.ts` manually converts between the two shapes.
-
-## Goals
-
-- Rename the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig`.
-- Keep the public `SpawnOptions` in `service.ts` unchanged — it's the published API.
-- Update all internal consumers (`agent-tool.ts`, `agent-menu.ts`, `agent-manager.ts`) to use the new name.
-- Update the `SpawnArgs` internal interface in `agent-manager.ts` to reference `AgentSpawnConfig`.
-- Non-breaking refactor — the public API surface is unchanged.
-
-## Non-Goals
-
-- Splitting `AgentSpawnConfig` into agent-configuration fields vs execution/lifecycle fields — the issue mentions this as a "consider" item; defer to a follow-up if the type grows further.
-- Narrowing `AgentToolDeps` or `AgentMenuDeps` — tracked in #114.
-- Removing `onSessionCreated` — it's a legitimate per-spawn callback used by `agent-tool.ts` for UI streaming, structurally different from the lifecycle observer (#112).
-
-## Background
-
-### Current consumers of internal `SpawnOptions`
-
-| File                  | How it references `SpawnOptions`                                                            |
-| --------------------- | ------------------------------------------------------------------------------------------- |
-| `agent-manager.ts`    | Defines the type; uses it in `spawn()`, `spawnAndWait()`, and `SpawnArgs`                   |
-| `tools/agent-tool.ts` | Imports and uses in `AgentToolManager.spawn` and `AgentToolManager.spawnAndWait` signatures |
-| `ui/agent-menu.ts`    | Imports and uses in `AgentMenuManager.spawnAndWait` signature                               |
-
-### Public `SpawnOptions` in `service.ts`
-
-Defined alongside `SubagentsService`.
-Used by `service-adapter.ts` at the conversion boundary.
-Published via `package.json` exports — **not touched by this change**.
-
-### Dependency: issue #112 (observer refactor)
-
-Issue #112 is closed.
-The observer eliminated `onStart`/`onComplete`/`onCompact` from `AgentManagerOptions`.
-`onSessionCreated` remains on the internal `SpawnOptions` (now `AgentSpawnConfig`) — it's per-spawn, not per-manager.
-
-### Architecture reference
-
-Phase 7, Step D1 in `docs/architecture/architecture.md`.
-
-## Design Overview
-
-This is a pure rename — no structural or behavioral changes.
-The internal `SpawnOptions` becomes `AgentSpawnConfig`.
-Every `import type { SpawnOptions }` from `"../agent-manager.js"` or `"./agent-manager.js"` becomes `import type { AgentSpawnConfig }`.
-
-The name `AgentSpawnConfig` was chosen because:
-
-1. It disambiguates from the public `SpawnOptions`.
-2. It follows the established naming convention in this package (`AgentRecord`, `AgentInvocation`, `AgentTypeRegistry`).
-3. "Config" conveys that this is a configuration bag assembled by the caller and consumed by the manager — not a service-level options type.
-
-### Type shape (unchanged)
-
-```typescript
-export interface AgentSpawnConfig {
-  description: string;
-  model?: Model<any>;
-  maxTurns?: number;
-  isolated?: boolean;
-  inheritContext?: boolean;
-  thinkingLevel?: ThinkingLevel;
-  isBackground?: boolean;
-  bypassQueue?: boolean;
-  isolation?: IsolationMode;
-  invocation?: AgentInvocation;
-  signal?: AbortSignal;
-  onSessionCreated?: (session: AgentSession) => void;
-  parentSessionFile?: string;
-  parentSessionId?: string;
-}
-```
-
-## Module-Level Changes
-
-### `src/agent-manager.ts`
-
-- Rename `export interface SpawnOptions` → `export interface AgentSpawnConfig`.
-- Update `SpawnArgs.options` type from `SpawnOptions` to `AgentSpawnConfig`.
-- Update `spawn()` parameter type from `SpawnOptions` to `AgentSpawnConfig`.
-- Update `spawnAndWait()` parameter type from `Omit<SpawnOptions, "isBackground">` to `Omit<AgentSpawnConfig, "isBackground">`.
-
-### `src/tools/agent-tool.ts`
-
-- Change import from `SpawnOptions` to `AgentSpawnConfig`.
-- Update `AgentToolManager.spawn` and `AgentToolManager.spawnAndWait` signatures.
-
-### `src/ui/agent-menu.ts`
-
-- Change import from `SpawnOptions` to `AgentSpawnConfig`.
-- Update `AgentMenuManager.spawnAndWait` signature.
-
-### `src/service.ts`
-
-- No changes — the public `SpawnOptions` stays as-is.
-
-### `src/service-adapter.ts`
-
-- No changes — it already uses `unknown` for the spawn options parameter in `AgentManagerLike`.
-
-### `test/agent-manager.test.ts`
-
-- No import changes needed — the test file does not import `SpawnOptions`.
-- One test description string mentions "SpawnOptions" → update to "AgentSpawnConfig" for accuracy.
-
-## Test Impact Analysis
-
-1. No new tests are enabled by this rename — it's a 1:1 name substitution.
-2. No existing tests become redundant.
-3. All existing tests stay as-is — they construct raw object literals that structurally satisfy the type regardless of its name.
-
-## TDD Order
-
-### Step 1: Rename `SpawnOptions` to `AgentSpawnConfig` and update all consumers
-
-1. Rename the interface in `agent-manager.ts`.
-2. Update `SpawnArgs`, `spawn()`, and `spawnAndWait()` in `agent-manager.ts`.
-3. Update the import and signatures in `tools/agent-tool.ts`.
-4. Update the import and signature in `ui/agent-menu.ts`.
-5. Update the test description string in `test/agent-manager.test.ts`.
-6. Run `pnpm run check` to verify types.
-7. Run `pnpm vitest run` to verify all tests pass.
-
-- Commit: `refactor: rename internal SpawnOptions to AgentSpawnConfig (#113)`
-
-This is a single-step refactor because the rename is mechanical and all consumers must be updated atomically for the type checker to stay green.
-
-## Risks and Mitigations
-
-| Risk                                                     | Mitigation                                                                                                                 |
-| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Missed consumer still references old name                | `pnpm run check` will catch any unresolved `SpawnOptions` import from `agent-manager.ts` since the export no longer exists |
-| Test descriptions become misleading                      | Grep for "SpawnOptions" in test files and update any description strings that reference the old name                       |
-| Confusion with `service.ts` `SpawnOptions` during review | The plan is scoped to internal-only changes; `service.ts` is explicitly listed as "no changes"                             |
-
-## Open Questions
-
-- None — the rename is unambiguous and aligns with both the issue proposal and the architecture doc.

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

@@ -1,279 +0,0 @@
----
-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.