@gotgenes/pi-subagents 6.8.3 → 6.9.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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.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

@@ -377,17 +377,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)
 
@@ -462,12 +462,17 @@ 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)
 
@@ -494,8 +499,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.

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

@@ -0,0 +1,29 @@
+---
+issue: 113
+issue_title: "refactor(pi-subagents): disambiguate SpawnOptions (public vs internal)"
+---
+
+# Retro: #113 — disambiguate SpawnOptions (public vs internal)
+
+## Final Retrospective (2026-05-21T21:10:00-04:00)
+
+### Session summary
+
+Renamed the internal `SpawnOptions` in `agent-manager.ts` to `AgentSpawnConfig` to disambiguate it from the public `SpawnOptions` in `service.ts`.
+Pure mechanical rename across 4 files with zero test-count delta (652/652).
+Released as `pi-subagents-v6.8.3`.
+
+### Observations
+
+#### What went well
+
+- Completely frictionless execution — single-step plan executed exactly as written with no corrections, rework, or failed edits.
+- The session benefited from context already loaded during the preceding #112 cycle (same package, same skills, same source files), which made planning and execution faster.
+
+#### What caused friction (agent side)
+
+- Nothing — the rename was purely mechanical and the plan matched reality exactly.
+
+#### What caused friction (user side)
+
+- Nothing — no user intervention needed.

package/package.json

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

package/src/agent-manager.ts

@@ -27,6 +27,8 @@ export interface AgentManagerObserver {
   onAgentStarted(record: AgentRecord): void;
   onAgentCompleted(record: AgentRecord): void;
   onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+  /** Fires synchronously after a background agent record is created (before startAgent). */
+  onAgentCreated(record: AgentRecord): void;
 }
 
 /** Default max concurrent background agents. */
@@ -153,6 +155,10 @@ export class AgentManager {
     });
     this.agents.set(id, record);
 
+    if (options.isBackground) {
+      this.observer?.onAgentCreated(record);
+    }
+
     const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 

package/src/index.ts

@@ -110,6 +110,15 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
+    onAgentCreated(record) {
+      // Emit created event for background agents (before startAgent / queue drain).
+      pi.events.emit("subagents:created", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+        isBackground: true,
+      });
+    },
   };
 
   const manager = new AgentManager({
@@ -151,33 +160,6 @@ export default function (pi: ExtensionAPI) {
   const toolStart = new ToolStartHandler(runtime);
   pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
-  /** Build the full type list text dynamically from the unified registry. */
-  const buildTypeListText = () => {
-    const defaultNames = registry.getDefaultAgentNames();
-    const userNames = registry.getUserAgentNames();
-
-    const defaultDescs = defaultNames.map((name) => {
-      const cfg = registry.resolveAgentConfig(name);
-      const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-      return `- ${name}: ${cfg.description}${modelSuffix}`;
-    });
-
-    const customDescs = userNames.map((name) => {
-      const cfg = registry.resolveAgentConfig(name);
-      return `- ${name}: ${cfg.description}`;
-    });
-
-    return [
-      "Default agents:",
-      ...defaultDescs,
-      ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
-      "",
-      `Custom agents can be defined in .pi/agents/<name>.md (project) or ${getAgentDir()}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
-    ].join("\n");
-  };
-
-  const typeListText = buildTypeListText();
-
   // ---- Agent tool ----
 
   pi.registerTool(defineTool(createAgentTool({
@@ -196,10 +178,7 @@ export default function (pi: ExtensionAPI) {
       markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,
-    emitEvent: (name, data) => pi.events.emit(name, data),
     registry,
-    typeListText,
-    availableTypesText: registry.getAvailableTypes().join(", "),
     agentDir: getAgentDir(),
     settings,
   })));
@@ -242,7 +221,6 @@ export default function (pi: ExtensionAPI) {
       return getModelLabelFromConfig(cfg.model);
     },
     settings,
-    emitEvent: (name, data) => pi.events.emit(name, data),
     personalAgentsDir: join(getAgentDir(), 'agents'),
     projectAgentsDir: join(process.cwd(), '.pi', 'agents'),
   });

package/src/tools/agent-tool.ts

@@ -23,7 +23,7 @@ import {
 } from "../ui/agent-widget.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { LifetimeUsage } from "../usage.js";
-import { formatLifetimeTokens, textResult } from "./helpers.js";
+import { buildTypeListText, formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
@@ -91,14 +91,21 @@ export interface AgentToolWidget {
   markFinished: (id: string) => void;
 }
 
+/**
+ * Narrow read/write interface for the agent-tool's agentActivity access.
+ * The full Map satisfies this structurally — no wrapper needed.
+ */
+export interface AgentActivityAccess {
+  get(id: string): AgentActivityTracker | undefined;
+  set(id: string, tracker: AgentActivityTracker): void;
+  delete(id: string): void;
+}
+
 export interface AgentToolDeps {
   manager: AgentToolManager;
   widget: AgentToolWidget;
-  agentActivity: Map<string, AgentActivityTracker>;
-  emitEvent: (name: string, data: unknown) => void;
+  agentActivity: AgentActivityAccess;
   registry: AgentTypeRegistry;
-  typeListText: string;
-  availableTypesText: string;
   agentDir: string;
   /** Narrow settings accessor — only the default max turns is needed here. */
   settings: { readonly defaultMaxTurns: number | undefined };
@@ -108,6 +115,8 @@ export interface AgentToolDeps {
 
 /** Create the Agent tool definition (without Pi SDK wrapper). */
 export function createAgentTool(deps: AgentToolDeps) {
+  const typeListText = buildTypeListText(deps.registry, deps.agentDir);
+  const availableTypesText = deps.registry.getAvailableTypes().join(", ");
   return {
     name: "Agent" as const,
     label: "Agent",
@@ -116,7 +125,7 @@ export function createAgentTool(deps: AgentToolDeps) {
 The Agent tool launches specialized agents that autonomously handle complex tasks. Each agent type has specific capabilities and tools available to it.
 
 Available agent types:
-${deps.typeListText}
+${typeListText}
 
 Guidelines:
 - For parallel work, use run_in_background: true on each agent. Foreground calls run sequentially — only one executes at a time.
@@ -140,7 +149,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${deps.availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
+        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -439,14 +448,6 @@ Guidelines:
         deps.widget.ensureTimer();
         deps.widget.update();
 
-        // Emit created event
-        deps.emitEvent("subagents:created", {
-          id,
-          type: subagentType,
-          description: params.description,
-          isBackground: true,
-        });
-
         const isQueued = record?.status === "queued";
         return textResult(
           `Agent ${isQueued ? "queued" : "started"} in background.\n` +

package/src/tools/helpers.ts

@@ -1,3 +1,4 @@
+import type { AgentConfigLookup } from "../agent-types.js";
 import { formatTokens } from "../ui/agent-widget.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
@@ -12,6 +13,43 @@ export function formatLifetimeTokens(o: { lifetimeUsage: LifetimeUsage }): strin
   return t > 0 ? formatTokens(t) : "";
 }
 
+/**
+ * Narrow registry interface needed by buildTypeListText.
+ * Extends AgentConfigLookup with the two name-listing methods.
+ */
+export interface TypeListRegistry extends AgentConfigLookup {
+  getDefaultAgentNames(): string[];
+  getUserAgentNames(): string[];
+}
+
+/**
+ * Build the full agent-type list text for the Agent tool description.
+ * Extracted from index.ts so it can be called inside createAgentTool.
+ */
+export function buildTypeListText(registry: TypeListRegistry, agentDir: string): string {
+  const defaultNames = registry.getDefaultAgentNames();
+  const userNames = registry.getUserAgentNames();
+
+  const defaultDescs = defaultNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+    return `- ${name}: ${cfg.description}${modelSuffix}`;
+  });
+
+  const customDescs = userNames.map((name) => {
+    const cfg = registry.resolveAgentConfig(name);
+    return `- ${name}: ${cfg.description}`;
+  });
+
+  return [
+    "Default agents:",
+    ...defaultDescs,
+    ...(customDescs.length > 0 ? ["", "Custom agents:", ...customDescs] : []),
+    "",
+    `Custom agents can be defined in .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) — they are picked up automatically. Project-level agents override global ones. Creating a .md file with the same name as a default agent overrides it.`,
+  ].join("\n");
+}
+
 /** Derive a short model label from a model string. */
 export function getModelLabelFromConfig(model: string): string {
   // Strip provider prefix (e.g. "anthropic/claude-sonnet-4-6" → "claude-sonnet-4-6")

package/src/ui/agent-menu.ts

@@ -32,15 +32,22 @@ export interface AgentMenuSettings {
   applyGraceTurns(n: number): { message: string; level: "info" | "warning" };
 }
 
+/**
+ * Read-only interface for the agent-menu's agentActivity access.
+ * Only the conversation viewer needs to read a tracker by agent ID.
+ */
+export interface AgentActivityReader {
+  get(id: string): AgentActivityTracker | undefined;
+}
+
 export interface AgentMenuDeps {
   manager: AgentMenuManager;
   registry: AgentTypeRegistry;
-  agentActivity: Map<string, AgentActivityTracker>;
+  agentActivity: AgentActivityReader;
   /** Resolve model label for a given agent type + registry. */
   getModelLabel: (type: string, registry?: ModelRegistry) => string;
   /** Settings manager — owns in-memory values and persistence. */
   settings: AgentMenuSettings;
-  emitEvent: (name: string, data: unknown) => void;
   personalAgentsDir: string;
   projectAgentsDir: string;
 }