@gotgenes/pi-subagents 6.8.1 → 6.8.2

package/CHANGELOG.md

@@ -5,6 +5,15 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.8.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.1...pi-subagents-v6.8.2) (2026-05-22)
+
+
+### Documentation
+
+* mark Step C complete in architecture.md ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([9f6e783](https://github.com/gotgenes/pi-packages/commit/9f6e783ab4ddcabdc24224e02aa631b93b0fb6d4))
+* plan replace AgentManager callbacks with observer interface ([#112](https://github.com/gotgenes/pi-packages/issues/112)) ([b32dde1](https://github.com/gotgenes/pi-packages/commit/b32dde1e473611b2734a287e88c8d155642405a7))
+* **retro:** add retro notes for issue [#123](https://github.com/gotgenes/pi-packages/issues/123) ([e9333ee](https://github.com/gotgenes/pi-packages/commit/e9333ee2af70e821ba1bace63bdbd7befa72ce84))
+
 ## [6.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.0...pi-subagents-v6.8.1) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -384,7 +384,7 @@ Each step is sequenced so it makes the next step easier.
 | ~~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`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
+| ~~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`        | Two incompatible shapes (JSON-friendly vs runtime types) with the same name                                                                                               |
 | 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                                                                                     |
@@ -445,12 +445,12 @@ Split post-construction mutation into phase-specific collaborators, each born co
 Each piece is born complete at the moment its information is available.
 The record doesn't accumulate half-baked state — it receives fully constructed collaborators.
 
-### Step C: Replace `AgentManager` callbacks with observer (#112)
+### Step C: Replace `AgentManager` callbacks with observer (#112) ✅
 
-Replace the `onStart`/`onComplete`/`onCompact` callback parameters with an `AgentManagerObserver` interface (or typed event emitter).
-The observer methods receive the same data the callbacks receive today.
-`index.ts` constructs the observer once instead of building 3 closure callbacks that capture `runtime`, `pi`, `notifications`, etc.
-`AgentManagerOptions` drops from 8 → 5 fields.
+**Done.**
+`AgentManagerObserver` interface replaces `onStart`/`onComplete`/`onCompact`.
+`index.ts` constructs one observer object instead of 3 closure lambdas.
+`AgentManagerOptions` drops from 9 → 7 fields.
 
 ### Step D: Disambiguate `SpawnOptions` and narrow dependency bags
 

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

@@ -0,0 +1,241 @@
+---
+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/retro/0123-remove-vi-fn-cast-smell.md

@@ -0,0 +1,49 @@
+---
+issue: 123
+issue_title: "refactor(pi-subagents): remove vi.fn() cast smell from test helpers"
+---
+
+# Retro: #123 — remove vi.fn() cast smell from test helpers
+
+## Final Retrospective (2026-05-22T00:00:00Z)
+
+### Session summary
+
+Planned and implemented removal of all 9 `as ReturnType<typeof vi.fn>` casts and 5 `vi.mocked()` calls across 3 test files, replacing them with named typed mock variables.
+Released as `pi-subagents-v6.8.1`.
+Pure test hygiene — no production code changes, no behavioral changes, 652 tests unchanged.
+
+### Observations
+
+#### What went well
+
+- **Three-file scope executed cleanly once the plan was right.**
+  Each file was an independent commit with no cross-file dependencies.
+  The named-variable pattern (`const mockGetRecord = vi.fn<AgentManagerLike["getRecord"]>()`) worked identically across all three test files despite different mock construction styles (factory function vs `beforeEach` assignment).
+
+#### What caused friction (agent side)
+
+- `scope-drift` — The initial plan scoped the fix to `service-adapter.test.ts` only, listing `lifecycle.test.ts` and `tool-start.test.ts` as explicit Non-Goals — despite the planning-phase grep showing all 9 cast sites across 3 files.
+  The user redirected with "let's eliminate this pattern of behavior."
+  Updated the GitHub issue body, rewrote the plan, and amended the commit.
+  Impact: plan rewrite (~2 minutes), no implementation rework.
+  User-caught.
+- `missing-context` — Imported `MockInstance` from `vitest` during step 1 (`service-adapter.test.ts`) but actually used `ReturnType<typeof vi.fn<...>>` — matching the pattern used in the other two files.
+  The unused import was caught by `pnpm run lint` at the post-implementation check, not proactively.
+  Impact: one extra edit + amend cycle.
+  Self-identified (via lint).
+- `other` — Ran `git commit --amend` to fix the unused import but HEAD was step 3's commit (`tool-start`), not step 1's (`service-adapter`).
+  The amend landed the `service-adapter.test.ts` change into the wrong commit with the wrong message.
+  Required `git reset --soft` back to the plan commit and recommitting all 3 files.
+  Impact: ~1 minute of git surgery, clean result.
+  Self-identified.
+
+#### What caused friction (user side)
+
+- The issue body scoped the fix to `service-adapter.test.ts` only, which the agent followed literally.
+  The broader intent ("eliminate this pattern") was implicit.
+  Flagging the desired scope as "all files with this pattern" in the issue body would have avoided the plan rewrite.
+
+### Changes made
+
+1. Wrote retro file at `packages/pi-subagents/docs/retro/0123-remove-vi-fn-cast-smell.md`.

package/package.json

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

package/src/agent-manager.ts

@@ -13,7 +13,6 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
-import type { ExecutionState } from "./execution-state.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
@@ -21,11 +20,15 @@ import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, Subagen
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 
-export type OnAgentComplete = (record: AgentRecord) => void;
-export type OnAgentStart = (record: AgentRecord) => void;
-export type OnAgentCompact = (record: AgentRecord, info: CompactionInfo) => void;
 export type CompactionInfo = { reason: "manual" | "threshold" | "overflow"; tokensBefore: number };
 
+/** Observer interface for agent lifecycle notifications. */
+export interface AgentManagerObserver {
+  onAgentStarted(record: AgentRecord): void;
+  onAgentCompleted(record: AgentRecord): void;
+  onAgentCompacted(record: AgentRecord, info: CompactionInfo): void;
+}
+
 /** Default max concurrent background agents. */
 const DEFAULT_MAX_CONCURRENT = 4;
 
@@ -37,9 +40,7 @@ export interface AgentManagerOptions {
   /** Injected getter for the concurrency limit — owned by SettingsManager. */
   getMaxConcurrent?: () => number;
   getRunConfig?: () => RunConfig;
-  onStart?: OnAgentStart;
-  onComplete?: OnAgentComplete;
-  onCompact?: OnAgentCompact;
+  observer?: AgentManagerObserver;
 }
 
 interface SpawnArgs {
@@ -80,9 +81,7 @@ export interface SpawnOptions {
 export class AgentManager {
   private agents = new Map<string, AgentRecord>();
   private cleanupInterval: ReturnType<typeof setInterval>;
-  private onComplete?: OnAgentComplete;
-  private onStart?: OnAgentStart;
-  private onCompact?: OnAgentCompact;
+  private readonly observer?: AgentManagerObserver;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
   private readonly exec: ShellExec;
@@ -102,9 +101,7 @@ export class AgentManager {
     this.worktrees = options.worktrees;
     this.exec = options.exec;
     this.registry = options.registry;
-    this.onComplete = options.onComplete;
-    this.onStart = options.onStart;
-    this.onCompact = options.onCompact;
+    this.observer = options.observer;
     this.getRunConfig = options.getRunConfig;
     this._getMaxConcurrent = options.getMaxConcurrent ?? (() => DEFAULT_MAX_CONCURRENT);
     // Cleanup completed agents after 10 minutes (but keep sessions for resume)
@@ -196,7 +193,7 @@ export class AgentManager {
 
     record.markRunning(Date.now());
     if (options.isBackground) this.runningBackground++;
-    this.onStart?.(record);
+    this.observer?.onAgentStarted(record);
 
     // Wire parent abort signal to stop the subagent when the parent is interrupted
     let detachParentSignal: (() => void) | undefined;
@@ -239,7 +236,7 @@ export class AgentManager {
         }
         // Subscribe record observer for stats accumulation
         unsubRecordObserver = subscribeRecordObserver(session, record, {
-          onCompact: (r, info) => this.onCompact?.(r, info),
+          onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
         });
         options.onSessionCreated?.(session);
       },
@@ -268,7 +265,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          try { this.onComplete?.(record); } catch (err) { debugLog("onComplete callback", err); }
+          try { this.observer?.onAgentCompleted(record); } catch (err) { debugLog("onAgentCompleted observer", err); }
           this.drainQueue();
         }
         return responseText;
@@ -290,7 +287,7 @@ export class AgentManager {
 
         if (options.isBackground) {
           this.runningBackground--;
-          this.onComplete?.(record);
+          this.observer?.onAgentCompleted(record);
           this.drainQueue();
         }
         return "";
@@ -311,7 +308,7 @@ export class AgentManager {
         // Late failure (e.g. strict worktree-isolation) — surface on the record
         // so the user/agent can see it via /agents, then keep draining.
         record.markError(err);
-        this.onComplete?.(record);
+        this.observer?.onAgentCompleted(record);
       }
     }
   }
@@ -347,7 +344,7 @@ export class AgentManager {
     record.resetForResume(Date.now());
 
     const unsubResume = subscribeRecordObserver(session, record, {
-      onCompact: (r, info) => this.onCompact?.(r, info),
+      onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
     });
 
     try {

package/src/index.ts

@@ -12,7 +12,7 @@
 
 import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
-import { AgentManager } from "./agent-manager.js";
+import { AgentManager, type AgentManagerObserver } from "./agent-manager.js";
 import { getAgentConversation, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -64,14 +64,18 @@ export default function (pi: ExtensionAPI) {
   });
   settings.load();
 
-  // Background completion: emit lifecycle event and delegate to notification system
-  const manager = new AgentManager({
-    runner: { run: runAgent, resume: resumeAgent },
-    worktrees: new GitWorktreeManager(process.cwd()),
-    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
-    registry,
-    onComplete: (record) => {
-      // Emit lifecycle event based on terminal status
+  // Observer: receives agent lifecycle notifications and dispatches events/notifications.
+  const observer: AgentManagerObserver = {
+    onAgentStarted(record) {
+      // Emit started event when agent transitions to running (including from queue).
+      pi.events.emit("subagents:started", {
+        id: record.id,
+        type: record.type,
+        description: record.description,
+      });
+    },
+    onAgentCompleted(record) {
+      // Emit lifecycle event based on terminal status.
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
       const eventData = buildEventData(record);
       if (isError) {
@@ -80,14 +84,14 @@ export default function (pi: ExtensionAPI) {
         pi.events.emit("subagents:completed", eventData);
       }
 
-      // Persist final record for cross-extension history reconstruction
+      // Persist final record for cross-extension history reconstruction.
       pi.appendEntry("subagents:record", {
         id: record.id, type: record.type, description: record.description,
         status: record.status, result: record.result, error: record.error,
         startedAt: record.startedAt, completedAt: record.completedAt,
       });
 
-      // Skip notification if result was already consumed via get_subagent_result
+      // Skip notification if result was already consumed via get_subagent_result.
       if (record.notification?.resultConsumed) {
         notifications.cleanupCompleted(record.id);
         return;
@@ -95,15 +99,7 @@ export default function (pi: ExtensionAPI) {
 
       notifications.sendCompletion(record);
     },
-    onStart: (record) => {
-      // Emit started event when agent transitions to running (including from queue)
-      pi.events.emit("subagents:started", {
-        id: record.id,
-        type: record.type,
-        description: record.description,
-      });
-    },
-    onCompact: (record, info) => {
+    onAgentCompacted(record, info) {
       // Emit compacted event when agent's session compacts (preserves count on record).
       pi.events.emit("subagents:compacted", {
         id: record.id,
@@ -114,6 +110,14 @@ export default function (pi: ExtensionAPI) {
         compactionCount: record.compactionCount,
       });
     },
+  };
+
+  const manager = new AgentManager({
+    runner: { run: runAgent, resume: resumeAgent },
+    worktrees: new GitWorktreeManager(process.cwd()),
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+    registry,
+    observer,
     getMaxConcurrent: () => settings.maxConcurrent,
     getRunConfig: () => settings,
   });