@gotgenes/pi-subagents 6.2.0 → 6.3.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.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.2.0...pi-subagents-v6.3.0) (2026-05-21)
+
+
+### Features
+
+* add record observer for direct session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([3776345](https://github.com/gotgenes/pi-packages/commit/37763454609d38d55c85f89bb051b8c592d425bf))
+* add UI observer for direct session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([5b35e80](https://github.com/gotgenes/pi-packages/commit/5b35e80e784d96883ee44bf5e890284efa1047ef))
+
+
+### Documentation
+
+* plan callback-threading replacement with session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([7a8e262](https://github.com/gotgenes/pi-packages/commit/7a8e262ebaf99cba017aac00691cc3614ef8c80a))
+* **retro:** add retro notes for issue [#99](https://github.com/gotgenes/pi-packages/issues/99) ([b596d0c](https://github.com/gotgenes/pi-packages/commit/b596d0c34862542d0ebb9fae67dd90e9fc660a8b))
+
 ## [6.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.1.0...pi-subagents-v6.2.0) (2026-05-21)
 
 

package/docs/plans/0100-replace-callback-threading-with-session-subscription.md

@@ -0,0 +1,454 @@
+---
+issue: 100
+issue_title: "Replace callback threading with direct session-event subscription"
+---
+
+# Replace callback threading with direct session-event subscription
+
+## Problem Statement
+
+`SpawnOptions` carries 6 `on*` callback fields that thread through three layers: `agent-tool.ts` creates activity-tracking callbacks → `AgentManager.startAgent()` wraps each to update the record, then forwards → `runner.run()` subscribes to session events and translates them into callback invocations.
+The session already emits all of these events via `session.subscribe()`.
+Three layers reimplement what two independent subscriptions could provide.
+
+The same pattern repeats in `resume()`, which hand-rolls 3 of the 4 callback wrappers.
+
+## Goals
+
+- Replace the 3-layer callback chain with two direct session subscribers: a **record observer** (AgentManager, updates record stats) and a **UI observer** (agent-tool, streams widget state).
+- Drop 5 `on*` callback fields from `SpawnOptions` (keep `onSessionCreated` as the session-delivery mechanism).
+- Drop 5 `on*` callback fields from `RunOptions`.
+- Drop 3 `on*` callback fields from `ResumeOptions`.
+- Simplify `startAgent()` from ~80 lines of callback wiring to ~20 lines of observer setup.
+- Eliminate duplicated callback wiring between `startAgent()` and `resume()`.
+
+## Non-Goals
+
+- Extracting turn-limit enforcement from the runner — it stays as the runner's own subscription, just simplified.
+  A follow-up could extract it into a `turn-limiter.ts` module.
+- Changing the public `SubagentsService` API in `service.ts` — the public `SpawnOptions` type is unaffected.
+- Removing `onSessionCreated` — it remains as the session-delivery bridge between the runner and external subscribers.
+- Changing `collectResponseText` or `forwardAbortSignal` in the runner — those are the runner's own concerns.
+
+## Background
+
+### Prerequisite status
+
+- Issue #98 (AgentRecord state machine) — **done**.
+  `AgentRecord` is a class with encapsulated transition methods (`markRunning`, `markCompleted`, `markError`, etc.).
+  The record observer uses public mutable fields (`toolUses`, `lifetimeUsage`, `compactionCount`) and the `addUsage` helper.
+- Issue #99 (ParentSnapshot) — **done**.
+  `runner.run()` accepts `ParentSnapshot`, `SpawnArgs` stores a snapshot, `AgentManager` has `exec: ShellExec` injected.
+
+### Current callback threading
+
+In `startAgent()`, AgentManager wraps 4 of the 6 callbacks to interleave record mutations:
+
+| Callback           | Record mutation                                               | Forwarding                            |
+| ------------------ | ------------------------------------------------------------- | ------------------------------------- |
+| `onToolActivity`   | `record.toolUses++` on end                                    | Forward to `options.onToolActivity`   |
+| `onAssistantUsage` | `addUsage(record.lifetimeUsage, …)`                           | Forward to `options.onAssistantUsage` |
+| `onCompaction`     | `record.compactionCount++` + `this.onCompact?.(record, info)` | Forward to `options.onCompaction`     |
+| `onSessionCreated` | Store session, capture file, flush steers                     | Forward to `options.onSessionCreated` |
+| `onTextDelta`      | None                                                          | Pass-through                          |
+| `onTurnEnd`        | None                                                          | Pass-through                          |
+
+In `resume()`, 3 callbacks are wired manually (onToolActivity, onAssistantUsage, onCompaction) with no forwarding — only record mutations.
+
+The runner's big `session.subscribe()` block (lines 323–370 of `agent-runner.ts`) mixes turn-limit enforcement with event→callback translation for all 6 callback types.
+
+### Code-design constraints
+
+- **Parameter relay** (code-design skill): the 5 UI callbacks thread through `SpawnOptions` → `startAgent()` wrapping → `RunOptions` → runner subscription.
+  The intermediary (`startAgent`) only uses them to interleave record mutations.
+- **Scattered resets** (design-review): `resume()` hand-rolls 3 of the same 4 callback wrappers from `startAgent()`.
+
+### Relevant modules
+
+| Module                    | Role in this change                                                  |
+| ------------------------- | -------------------------------------------------------------------- |
+| `src/agent-manager.ts`    | Owns `SpawnOptions`, `startAgent()`, `resume()` — primary target     |
+| `src/agent-runner.ts`     | Owns `RunOptions`, `ResumeOptions`, runner subscription — simplifies |
+| `src/tools/agent-tool.ts` | Owns `createActivityTracker()` — replaced by UI observer             |
+| `src/ui/agent-widget.ts`  | Defines `AgentActivity` interface — unchanged                        |
+| `src/agent-record.ts`     | `AgentRecord` class — unchanged (observer writes to public fields)   |
+| `src/usage.ts`            | `addUsage` helper — unchanged, used by record observer               |
+
+## Design Overview
+
+### Two independent observers
+
+```text
+                     session.subscribe()
+                            │
+              ┌─────────────┼─────────────┐
+              │                           │
+       Record observer              UI observer
+  (accumulates stats on record)   (updates widget state)
+  managed by AgentManager         managed by agent-tool
+  subscribes in onSessionCreated  subscribes in onSessionCreated
+  unsubscribes in .then/.catch    unsubscribes on completion
+```
+
+Both subscribe to the same session but update independent state.
+Neither wraps or forwards the other's events.
+
+### Record observer
+
+New module `src/record-observer.ts`:
+
+```typescript
+export interface RecordObserverOptions {
+  onCompact?: (record: AgentRecord, info: CompactionInfo) => void;
+}
+
+export function subscribeRecordObserver(
+  session: AgentSession,
+  record: AgentRecord,
+  options?: RecordObserverOptions,
+): () => void;
+```
+
+Handles three event types:
+
+| Session event                               | Record mutation                                      |
+| ------------------------------------------- | ---------------------------------------------------- |
+| `tool_execution_end`                        | `record.toolUses++`                                  |
+| `message_end` (assistant, with usage)       | `addUsage(record.lifetimeUsage, usage)`              |
+| `compaction_end` (not aborted, with result) | `record.compactionCount++`, call `options.onCompact` |
+
+These are the exact mutations currently scattered across `startAgent()` and `resume()` callback wrappers.
+
+The returned function unsubscribes from the session.
+
+### UI observer
+
+New module `src/ui/ui-observer.ts`:
+
+```typescript
+export function subscribeUIObserver(
+  session: AgentSession,
+  state: AgentActivity,
+  onUpdate?: () => void,
+): () => void;
+```
+
+Handles six event types — the same events currently translated by `createActivityTracker`'s callbacks:
+
+| Session event                         | State mutation                                      |
+| ------------------------------------- | --------------------------------------------------- |
+| `tool_execution_start`                | Add to `state.activeTools`                          |
+| `tool_execution_end`                  | Remove from `state.activeTools`, `state.toolUses++` |
+| `message_start`                       | Reset `state.responseText`                          |
+| `message_update` (text_delta)         | Append to `state.responseText`                      |
+| `turn_end`                            | `state.turnCount++`                                 |
+| `message_end` (assistant, with usage) | `addUsage(state.lifetimeUsage, usage)`              |
+
+Calls `onUpdate?.()` after each mutation (matching current `onStreamUpdate` behavior for foreground rendering).
+
+The returned function unsubscribes from the session.
+
+### SpawnOptions after the change
+
+```typescript
+export interface SpawnOptions {
+  description: string;
+  model?: Model<any>;
+  maxTurns?: number;
+  isolated?: boolean;
+  inheritContext?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  isBackground?: boolean;
+  bypassQueue?: boolean;
+  isolation?: IsolationMode;
+  invocation?: AgentInvocation;
+  signal?: AbortSignal;
+  parentSessionFile?: string;
+  parentSessionId?: string;
+  /** Called when the session is created — the one remaining callback. */
+  onSessionCreated?: (session: AgentSession) => void;
+}
+```
+
+Drops: `onToolActivity`, `onTextDelta`, `onTurnEnd`, `onAssistantUsage`, `onCompaction`.
+
+### RunOptions after the change
+
+```typescript
+export interface RunOptions {
+  exec: ShellExec;
+  model?: Model<any>;
+  maxTurns?: number;
+  signal?: AbortSignal;
+  isolated?: boolean;
+  thinkingLevel?: ThinkingLevel;
+  cwd?: string;
+  parentSessionFile?: string;
+  parentSessionId?: string;
+  defaultMaxTurns?: number;
+  graceTurns?: number;
+  /** Called once after session creation — session delivery mechanism. */
+  onSessionCreated?: (session: AgentSession) => void;
+}
+```
+
+Drops: `onToolActivity`, `onTextDelta`, `onTurnEnd`, `onAssistantUsage`, `onCompaction`.
+
+### ResumeOptions after the change
+
+```typescript
+export interface ResumeOptions {
+  signal?: AbortSignal;
+}
+```
+
+Drops: `onToolActivity`, `onAssistantUsage`, `onCompaction`.
+
+### Runner simplification
+
+The runner's big `session.subscribe()` block in `runAgent()` (currently ~50 lines mixing turn-limit enforcement with callback forwarding) simplifies to turn-limit enforcement only (~15 lines):
+
+```typescript
+const unsubTurns = session.subscribe((event) => {
+  if (event.type === "turn_end") {
+    turnCount++;
+    if (maxTurns != null) {
+      if (!softLimitReached && turnCount >= maxTurns) {
+        softLimitReached = true;
+        session.steer("...");
+      } else if (softLimitReached && turnCount >= maxTurns + grace) {
+        aborted = true;
+        session.abort();
+      }
+    }
+  }
+});
+```
+
+`collectResponseText(session)` and `forwardAbortSignal(session, signal)` remain unchanged — they are the runner's own concerns.
+
+`resumeAgent()` drops its conditional event subscription entirely — only `collectResponseText` and `forwardAbortSignal` remain.
+
+### Unsubscription strategy
+
+| Observer            | Subscribe point            | Unsubscribe point            |
+| ------------------- | -------------------------- | ---------------------------- |
+| Record (startAgent) | `onSessionCreated` handler | `.then()` and `.catch()`     |
+| Record (resume)     | Before `runner.resume()`   | `finally` block              |
+| UI (foreground)     | `onSessionCreated` handler | After `spawnAndWait` returns |
+| UI (background)     | `onSessionCreated` handler | Session disposal on cleanup  |
+
+### createActivityTracker replacement
+
+`createActivityTracker()` in `agent-tool.ts` is replaced by:
+
+1. Inline `AgentActivity` state construction (the state object is simple enough).
+2. In the `onSessionCreated` callback: `subscribeUIObserver(session, state, onStreamUpdate)`.
+
+The `callbacks` spread pattern (`...bgCallbacks` / `...fgCallbacks`) disappears entirely.
+
+## Module-Level Changes
+
+### New files
+
+1. `src/record-observer.ts` — `subscribeRecordObserver()` function.
+2. `test/record-observer.test.ts` — unit tests with mock session.
+3. `src/ui/ui-observer.ts` — `subscribeUIObserver()` function.
+4. `test/ui/ui-observer.test.ts` — unit tests with mock session.
+
+### Changed files (source)
+
+1. `src/agent-manager.ts` — Wire record observer in `onSessionCreated`; simplify callback wrappers to pass-through (cycle 3); drop 5 `on*` fields from `SpawnOptions` (cycle 4).
+2. `src/tools/agent-tool.ts` — Replace `createActivityTracker` with inline state + `subscribeUIObserver`; drop callback spread from spawn calls (cycle 4).
+3. `src/agent-runner.ts` — Drop 5 `on*` fields from `RunOptions`; drop 3 `on*` fields from `ResumeOptions`; simplify `runAgent()` subscription to turn-limit only; remove conditional subscription from `resumeAgent()` (cycle 5).
+
+### Changed files (tests)
+
+1. `test/agent-manager.test.ts` — Upgrade `mockSession()` to support `subscribe()`; update 3 stat-verification tests to emit events through mock session instead of calling callbacks on `RunOptions` (cycle 3).
+2. `test/agent-runner.test.ts` — Drop tests for callback forwarding (`onAssistantUsage` wiring, `onCompaction` forwarding); runner tests focus on turn-limit enforcement and session creation (cycle 5).
+3. `test/agent-runner-extension-tools.test.ts` — Drop callback-related fields from `RunOptions` mock construction (cycle 5).
+
+### Unchanged files
+
+- `src/service.ts` — public API unchanged (its `SpawnOptions` is a separate type).
+- `src/agent-record.ts` — public mutable fields used by observer, no changes needed.
+- `src/usage.ts` — `addUsage` helper used by observer, unchanged.
+- `src/ui/agent-widget.ts` — `AgentActivity` interface unchanged; widget reads state as before.
+- `src/session-config.ts`, `src/context.ts`, `src/env.ts` — unrelated.
+- `src/service-adapter.ts` — `AgentManagerLike.spawn` signature unchanged (onSessionCreated is already optional on SpawnOptions).
+- `test/tools/agent-tool.test.ts` — tests use mocked `deps.manager` and don't exercise callback wiring; spawn mock shape doesn't change.
+- `test/service-adapter.test.ts` — tests mock `AgentManagerLike`, unaffected by internal SpawnOptions changes.
+
+## Test Impact Analysis
+
+### New tests enabled by the extraction
+
+1. `subscribeRecordObserver` tested in isolation with a mock session and real `AgentRecord`.
+   Previously impossible — record stat updates were interleaved with callback wrapping inside `startAgent()`.
+2. `subscribeUIObserver` tested in isolation with a mock session and `AgentActivity` state object.
+   Previously impossible — UI state updates were buried in `createActivityTracker` closures that required a full spawn flow to exercise.
+
+### Existing tests that simplify
+
+1. `agent-manager.test.ts` stat tests — currently simulate callbacks by having the mock runner call `opts.onAssistantUsage?.(...)`.
+   After the change, mock runners call `opts.onSessionCreated?.(session)` and tests emit events through the mock session.
+   The pattern is more realistic (events drive state, not callbacks).
+2. `agent-runner.test.ts` — callback forwarding tests (`onAssistantUsage wiring`, `onCompaction forwarding`) become unnecessary since the runner no longer translates events to callbacks.
+   Turn-limit tests remain and simplify (no callback interleaving).
+
+### Existing tests that stay as-is
+
+1. All `agent-manager.test.ts` lifecycle tests (spawn, abort, queue drain, worktree, resume flow) — they verify AgentManager behavior and don't depend on callback wiring.
+   Only the mock construction (`mockSession`) gains a `subscribe` method.
+2. `agent-record.test.ts` — state-machine transitions are unrelated.
+3. `agent-runner-extension-tools.test.ts` — tool filtering tests are unrelated to callbacks.
+4. `test/tools/agent-tool.test.ts` — tests mock the manager; spawn/spawnAndWait call shapes don't change from the test's perspective.
+
+## TDD Order
+
+### Phase 1: Extract observers (additive, no breaking changes)
+
+#### Cycle 1: Record observer module
+
+Test surface: `test/record-observer.test.ts` (new).
+
+Tests:
+
+- `tool_execution_end` event increments `record.toolUses`.
+- `message_end` (assistant, with usage) accumulates into `record.lifetimeUsage`.
+- `compaction_end` (not aborted) increments `record.compactionCount` and calls `onCompact`.
+- `compaction_end` with `aborted: true` is ignored.
+- Returned function unsubscribes from session.
+
+Source changes:
+
+- `src/record-observer.ts`: `subscribeRecordObserver()` function.
+
+Commit: `feat: add record observer for direct session subscription (#100)`
+
+#### Cycle 2: UI observer module
+
+Test surface: `test/ui/ui-observer.test.ts` (new).
+
+Tests:
+
+- `tool_execution_start` adds to `state.activeTools`, calls `onUpdate`.
+- `tool_execution_end` removes from `state.activeTools`, increments `state.toolUses`, calls `onUpdate`.
+- `message_start` resets `state.responseText`.
+- `message_update` (text_delta) appends to `state.responseText`, calls `onUpdate`.
+- `turn_end` increments `state.turnCount`, calls `onUpdate`.
+- `message_end` (assistant, with usage) accumulates into `state.lifetimeUsage`, calls `onUpdate`.
+- Returned function unsubscribes from session.
+
+Source changes:
+
+- `src/ui/ui-observer.ts`: `subscribeUIObserver()` function.
+
+Commit: `feat: add UI observer for direct session subscription (#100)`
+
+### Phase 2: AgentManager uses record observer
+
+#### Cycle 3: Wire record observer into startAgent and resume
+
+Test surface: `test/agent-manager.test.ts` (updated).
+
+This cycle replaces the record-mutation logic in `startAgent()` and `resume()` callback wrappers with `subscribeRecordObserver`.
+The 5 UI callbacks (`onToolActivity` through `onCompaction`) are still accepted on `SpawnOptions` and forwarded to `RunOptions` as pass-through (no wrapping).
+They are removed in cycle 4.
+
+Source changes:
+
+- `src/agent-manager.ts`:
+  - Import `subscribeRecordObserver`.
+  - In `startAgent()`: subscribe record observer inside `onSessionCreated` handler; remove `record.toolUses++` from `onToolActivity` wrapper (pass through `options.onToolActivity`); remove `addUsage` from `onAssistantUsage` wrapper (pass through); remove `record.compactionCount++` from `onCompaction` wrapper (pass through, `this.onCompact` moves to observer's `onCompact` option); capture unsubscribe function, call in `.then()` and `.catch()`.
+  - In `resume()`: subscribe record observer to `record.session` before calling `runner.resume()`; drop `onToolActivity`, `onAssistantUsage`, `onCompaction` args from `runner.resume()` call; unsubscribe in `finally` block.
+
+Test changes:
+
+- `test/agent-manager.test.ts`:
+  - Upgrade `mockSession()` to support `subscribe()` and provide a test helper `emit()` method.
+  - Update the `onAssistantUsage` test: mock runner calls `opts.onSessionCreated?.(session)`, then emits `message_end` events through the mock session.
+  - Update the `onCompaction` test: same pattern — emit `compaction_end` events through mock session.
+  - Update the `resume()` accumulation test: mock session emits events during `runner.resume()`.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: AgentManager subscribes record observer directly (#100)`
+
+### Phase 3: Agent-tool uses UI observer
+
+#### Cycle 4: Replace createActivityTracker with UI observer, drop SpawnOptions callbacks
+
+Test surface: `test/tools/agent-tool.test.ts` (verified unchanged), `test/agent-manager.test.ts` (verified compatible).
+
+This cycle replaces `createActivityTracker` with inline `AgentActivity` state construction and `subscribeUIObserver` subscription via `onSessionCreated`.
+`SpawnOptions` drops 5 `on*` fields.
+
+Source changes:
+
+- `src/tools/agent-tool.ts`:
+  - Import `subscribeUIObserver` from `../ui/ui-observer.js`.
+  - Remove `createActivityTracker` function.
+  - Background path: construct `AgentActivity` state inline; pass `onSessionCreated` callback that subscribes UI observer; remove `...bgCallbacks` spread.
+  - Foreground path: construct `AgentActivity` state inline; pass `onSessionCreated` callback that subscribes UI observer, registers activity in widget, and captures unsubscribe; remove `...fgCallbacks` spread; call UI unsubscribe after `spawnAndWait` returns.
+- `src/agent-manager.ts`:
+  - `SpawnOptions`: remove `onToolActivity`, `onTextDelta`, `onTurnEnd`, `onAssistantUsage`, `onCompaction` fields.
+  - `startAgent()`: remove pass-through forwarding of the 5 dropped callbacks to `RunOptions`.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: agent-tool subscribes UI observer, drop SpawnOptions callbacks (#100)`
+
+### Phase 4: Runner drops callback forwarding
+
+#### Cycle 5: RunOptions and ResumeOptions drop callback fields, runner simplifies
+
+Test surface: `test/agent-runner.test.ts` (updated), `test/agent-runner-extension-tools.test.ts` (updated).
+
+Source changes:
+
+- `src/agent-runner.ts`:
+  - `RunOptions`: remove `onToolActivity`, `onTextDelta`, `onTurnEnd`, `onAssistantUsage`, `onCompaction` fields.
+  - `ResumeOptions`: remove `onToolActivity`, `onAssistantUsage`, `onCompaction` fields (keep `signal`).
+  - `runAgent()`: simplify the big `session.subscribe()` block to turn-limit enforcement only (turn_end → count, steer, abort).
+    Remove message_start/message_update/tool_execution_start/tool_execution_end/message_end/compaction_end handling.
+  - `resumeAgent()`: remove the conditional `session.subscribe()` block entirely (no callbacks to forward).
+    Keep `collectResponseText` and `forwardAbortSignal`.
+  - Remove `ToolActivity` export if no longer needed externally (check consumers).
+
+Test changes:
+
+- `test/agent-runner.test.ts`:
+  - Remove or simplify callback forwarding tests (onAssistantUsage wiring, onCompaction forwarding, tool activity forwarding).
+  - Turn-limit tests remain, with simplified setup (no callback expectations).
+  - `runAgent()` call sites drop the 5 callback fields.
+- `test/agent-runner-extension-tools.test.ts`:
+  - Drop callback-related fields from `runAgent()` call construction.
+
+Run: full test suite + `pnpm run check`.
+
+Commit: `refactor: RunOptions and ResumeOptions drop callback fields (#100)`
+
+## Risks and Mitigations
+
+| Risk                                                                                | Mitigation                                                                                                                |
+| ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| Double-counting during transition (old callbacks + new observer both update record) | Cycle 3 replaces record mutations atomically — old wrappers become pass-through in the same commit that adds the observer |
+| Mock session complexity increases (need `subscribe` + `emit` helper)                | One-time investment; upgrade `mockSession()` once, reused across all tests; more realistic than simulating callbacks      |
+| Event ordering between record observer and UI observer                              | Observers update independent state (record vs AgentActivity); no cross-dependency, ordering irrelevant                    |
+| `ToolActivity` type used outside this package                                       | Grep before removing; if used, keep the export and add a deprecation note                                                 |
+| `createActivityTracker` exported but unused externally                              | Verified: only used within `agent-tool.ts`; safe to remove                                                                |
+| Turn-limit enforcement mixed with callback subscription in runner                   | Cycle 5 extracts turn-limit into its own subscription cleanly; `collectResponseText` stays separate                       |
+| Unsubscription missed on error paths                                                | Record observer unsubscribe captured in closure, called in both `.then()` and `.catch()`; resume uses `finally`           |
+
+## Open Questions
+
+- Whether to extract turn-limit enforcement from the runner into a separate `turn-limiter.ts` module.
+  This would improve testability but is orthogonal to callback elimination.
+  Deferred — the runner's subscription simplifies enough in cycle 5.
+- Whether `ResumeOptions` should be renamed or inlined since it reduces to `{ signal?: AbortSignal }`.
+  Keeping it as a named type is fine for extensibility.
+  Deferred — cosmetic, can be done anytime.
+- Whether to introduce a `SessionLike` interface for the mock session pattern used in `record-observer.test.ts` and `ui-observer.test.ts`.
+  Both tests need a minimal session with `subscribe()`.
+  If the pattern proves reusable, extract it; otherwise keep the inline mock.

package/docs/retro/0099-replace-ctx-with-parent-snapshot.md

@@ -0,0 +1,37 @@
+---
+issue: 99
+issue_title: "Replace live `ctx` capture with ParentSnapshot in AgentManager"
+---
+
+# Retro: #99 — Replace live ctx capture with ParentSnapshot
+
+## Final Retrospective (2026-05-20T20:30:00-04:00)
+
+### Session summary
+
+Implemented the `ParentSnapshot` extraction — Step 2 of the AgentManager internal decomposition.
+The user prompted a mid-planning restructure using Kent Beck's "make the change that makes the change easy" principle, which split the work into two clean phases: pi-elimination prep (cycles 1–2), then snapshot introduction (cycles 3–5).
+All 5 cycles landed first-try with no rework, releasing as `pi-subagents-v6.2.0`.
+
+### Observations
+
+#### What went well
+
+- The two-phase plan structure (prep then payload) kept each cycle focused on one concern.
+  Cycle 5 was particularly clean — only 2 files changed because `buildParentSnapshot` was mocked in agent-manager tests.
+- `sed` for mechanical bulk replacements (27 `spawn(mockPi,` → `spawn(mockCtx,`) was the right tool — faster and less error-prone than 27 individual edits.
+- The `pnpm run check` after cycle 4 caught exactly the expected type error in `agent-manager.ts`, confirming the incremental approach was working as designed.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Initial plan (before user intervention) interleaved pi-elimination and snapshot concerns across all 5 cycles.
+  The user had to invoke Kent Beck's principle to trigger the restructure.
+  Impact: one plan rewrite (amend commit), but no implementation rework since it happened before coding started.
+
+- `missing-context` — Used `Parameters<typeof createAgentSession>[0]["modelRegistry"]` as a type cast without checking that the SDK's `createAgentSession` parameter type is a union including `undefined`.
+  Impact: minimal — caught immediately by `pnpm run check`, fixed with a simple `as any` in the same cycle.
+
+#### What caused friction (user side)
+
+- The user's "make the change easy" prompt was well-timed — after the plan was written but before implementation.
+  No suggestions for improvement here; the intervention was strategic and well-placed.

package/package.json

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

package/src/agent-manager.ts

@@ -10,12 +10,12 @@ import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSession, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { AgentRecord } from "./agent-record.js";
-import type { AgentRunner, ToolActivity } from "./agent-runner.js";
+import type { AgentRunner } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
+import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
-import { addUsage } from "./usage.js";
 import type { WorktreeManager } from "./worktree.js";
 
 export type OnAgentComplete = (record: AgentRecord) => void;
@@ -64,18 +64,8 @@ export interface SpawnOptions {
   invocation?: AgentInvocation;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Called on tool start/end with activity info (for streaming progress to UI). */
-  onToolActivity?: (activity: ToolActivity) => void;
-  /** Called on streaming text deltas from the assistant response. */
-  onTextDelta?: (delta: string, fullText: string) => void;
-  /** Called when the agent session is created (for accessing session stats). */
+  /** Called when the agent session is created — the one remaining callback. */
   onSessionCreated?: (session: AgentSession) => void;
-  /** Called at the end of each agentic turn with the cumulative count. */
-  onTurnEnd?: (turnCount: number) => void;
-  /** Called once per assistant message_end with that message's usage delta. */
-  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
-  /** Called when the session successfully compacts. */
-  onCompaction?: (info: CompactionInfo) => void;
   /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
   parentSessionFile?: string;
   /** Session ID of the parent agent (stored in the child session's parentSession header). */
@@ -198,6 +188,8 @@ export class AgentManager {
     }
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
+    let unsubRecordObserver: (() => void) | undefined;
+
     const runConfig = this.getRunConfig?.();
     const promise = this.runner.run(snapshot, type, prompt, {
       exec: this.exec,
@@ -211,21 +203,6 @@ export class AgentManager {
       parentSessionFile: options.parentSessionFile,
       parentSessionId: options.parentSessionId,
       signal: record.abortController!.signal,
-      onToolActivity: (activity) => {
-        if (activity.type === "end") record.toolUses++;
-        options.onToolActivity?.(activity);
-      },
-      onTurnEnd: options.onTurnEnd,
-      onTextDelta: options.onTextDelta,
-      onAssistantUsage: (usage) => {
-        addUsage(record.lifetimeUsage, usage);
-        options.onAssistantUsage?.(usage);
-      },
-      onCompaction: (info) => {
-        record.compactionCount++;
-        this.onCompact?.(record, info);
-        options.onCompaction?.(info);
-      },
       onSessionCreated: (session) => {
         record.session = session;
         // Capture the session file path early so it's available for display
@@ -239,10 +216,15 @@ export class AgentManager {
           }
           record.pendingSteers = undefined;
         }
+        // Subscribe record observer for stats accumulation
+        unsubRecordObserver = subscribeRecordObserver(session, record, {
+          onCompact: (r, info) => this.onCompact?.(r, info),
+        });
         options.onSessionCreated?.(session);
       },
     })
       .then(({ responseText, session, aborted, steered, sessionFile }) => {
+        unsubRecordObserver?.();
         detach();
 
         // Clean up worktree before transition so the final result includes branch text
@@ -273,6 +255,7 @@ export class AgentManager {
       .catch((err) => {
         record.markError(err);
 
+        unsubRecordObserver?.();
         detach();
 
         // Best-effort worktree cleanup on error
@@ -340,23 +323,19 @@ export class AgentManager {
 
     record.resetForResume(Date.now());
 
+    const unsubResume = subscribeRecordObserver(record.session, record, {
+      onCompact: (r, info) => this.onCompact?.(r, info),
+    });
+
     try {
       const responseText = await this.runner.resume(record.session, prompt, {
-        onToolActivity: (activity) => {
-          if (activity.type === "end") record.toolUses++;
-        },
-        onAssistantUsage: (usage) => {
-          addUsage(record.lifetimeUsage, usage);
-        },
-        onCompaction: (info) => {
-          record.compactionCount++;
-          this.onCompact?.(record, info);
-        },
         signal,
       });
       record.markCompleted(responseText);
     } catch (err) {
       record.markError(err);
+    } finally {
+      unsubResume();
     }
 
     return record;

package/src/agent-runner.ts

@@ -64,12 +64,6 @@ export function normalizeMaxTurns(n: number | undefined): number | undefined {
 }
 
 
-/** Info about a tool event in the subagent. */
-export interface ToolActivity {
-  type: "start" | "end";
-  toolName: string;
-}
-
 export interface RunOptions {
   /** Shell-exec callback for detectEnv — injected from pi.exec(). */
   exec: ShellExec;
@@ -84,31 +78,8 @@ export interface RunOptions {
   parentSessionFile?: string;
   /** Session ID of the parent agent (stored in the child session's parentSession header). */
   parentSessionId?: string;
-  /** Called on tool start/end with activity info. */
-  onToolActivity?: (activity: ToolActivity) => void;
-  /** Called on streaming text deltas from the assistant response. */
-  onTextDelta?: (delta: string, fullText: string) => void;
+  /** Called once after session creation — session delivery mechanism. */
   onSessionCreated?: (session: AgentSession) => void;
-  /** Called at the end of each agentic turn with the cumulative count. */
-  onTurnEnd?: (turnCount: number) => void;
-  /**
-   * Called once per assistant message_end with that message's usage delta.
-   * Lets callers maintain a lifetime accumulator that survives compaction
-   * (which replaces session.state.messages and resets stats-derived sums).
-   */
-  onAssistantUsage?: (usage: {
-    input: number;
-    output: number;
-    cacheWrite: number;
-  }) => void;
-  /**
-   * Called when the session successfully compacts. `tokensBefore` is upstream's
-   * pre-compaction context size estimate. Aborted compactions don't fire.
-   */
-  onCompaction?: (info: {
-    reason: "manual" | "threshold" | "overflow";
-    tokensBefore: number;
-  }) => void;
   /**
    * Default max turns from runtime config. Falls back to the module-scope
    * `defaultMaxTurns` during the lift-and-shift migration; superseded by
@@ -135,9 +106,6 @@ export interface RunResult {
 
 /** Options for resuming an existing agent session. */
 export interface ResumeOptions {
-  onToolActivity?: (activity: ToolActivity) => void;
-  onAssistantUsage?: (usage: { input: number; output: number; cacheWrite: number }) => void;
-  onCompaction?: (info: { reason: "manual" | "threshold" | "overflow"; tokensBefore: number }) => void;
   signal?: AbortSignal;
 }
 
@@ -284,14 +252,7 @@ export async function runAgent(
   // (e.g. loading credentials, setting up state). Placed after tool filtering
   // so extension-provided skills/prompts from extendResourcesFromExtensions()
   // respect the active tool set. All ExtensionBindings fields are optional.
-  await session.bindExtensions({
-    onError: (err) => {
-      options.onToolActivity?.({
-        type: "end",
-        toolName: `extension-error:${err.extensionPath}`,
-      });
-    },
-  });
+  await session.bindExtensions({});
 
   // Patch 2 (RepOne #443): re-filter active tools after bindExtensions.
   // Extension-registered tools (added during bindExtensions) are not in the
@@ -319,11 +280,9 @@ export async function runAgent(
   let softLimitReached = false;
   let aborted = false;
 
-  let currentMessageText = "";
   const unsubTurns = session.subscribe((event: AgentSessionEvent) => {
     if (event.type === "turn_end") {
       turnCount++;
-      options.onTurnEnd?.(turnCount);
       if (maxTurns != null) {
         if (!softLimitReached && turnCount >= maxTurns) {
           softLimitReached = true;
@@ -336,40 +295,6 @@ export async function runAgent(
         }
       }
     }
-    if (event.type === "message_start") {
-      currentMessageText = "";
-    }
-    if (
-      event.type === "message_update" &&
-      event.assistantMessageEvent.type === "text_delta"
-    ) {
-      currentMessageText += event.assistantMessageEvent.delta;
-      options.onTextDelta?.(
-        event.assistantMessageEvent.delta,
-        currentMessageText,
-      );
-    }
-    if (event.type === "tool_execution_start") {
-      options.onToolActivity?.({ type: "start", toolName: event.toolName });
-    }
-    if (event.type === "tool_execution_end") {
-      options.onToolActivity?.({ type: "end", toolName: event.toolName });
-    }
-    if (event.type === "message_end" && event.message.role === "assistant") {
-      const u = (event.message as any).usage;
-      if (u)
-        options.onAssistantUsage?.({
-          input: u.input ?? 0,
-          output: u.output ?? 0,
-          cacheWrite: u.cacheWrite ?? 0,
-        });
-    }
-    if (event.type === "compaction_end" && !event.aborted && event.result) {
-      options.onCompaction?.({
-        reason: event.reason,
-        tokensBefore: event.result.tokensBefore,
-      });
-    }
   });
 
   const collector = collectResponseText(session);
@@ -411,46 +336,10 @@ export async function resumeAgent(
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);
 
-  const unsubEvents =
-    options.onToolActivity || options.onAssistantUsage || options.onCompaction
-      ? session.subscribe((event: AgentSessionEvent) => {
-          if (event.type === "tool_execution_start")
-            options.onToolActivity?.({
-              type: "start",
-              toolName: event.toolName,
-            });
-          if (event.type === "tool_execution_end")
-            options.onToolActivity?.({ type: "end", toolName: event.toolName });
-          if (
-            event.type === "message_end" &&
-            event.message.role === "assistant"
-          ) {
-            const u = (event.message as any).usage;
-            if (u)
-              options.onAssistantUsage?.({
-                input: u.input ?? 0,
-                output: u.output ?? 0,
-                cacheWrite: u.cacheWrite ?? 0,
-              });
-          }
-          if (
-            event.type === "compaction_end" &&
-            !event.aborted &&
-            event.result
-          ) {
-            options.onCompaction?.({
-              reason: event.reason,
-              tokensBefore: event.result.tokensBefore,
-            });
-          }
-        })
-      : () => {};
-
   try {
     await session.prompt(prompt);
   } finally {
     collector.unsubscribe();
-    unsubEvents();
     cleanupAbort();
   }
 

package/src/record-observer.ts

@@ -0,0 +1,60 @@
+/**
+ * record-observer.ts — Subscribes to session events and updates AgentRecord stats.
+ *
+ * Replaces the scattered callback-wrapping logic in AgentManager's startAgent()
+ * and resume() with a single direct subscription.
+ */
+
+import type { CompactionInfo } from "./agent-manager.js";
+import type { AgentRecord } from "./agent-record.js";
+import { addUsage } from "./usage.js";
+
+/** Narrow session interface — only the subscribe method needed by the observer. */
+interface SubscribableSession {
+  subscribe(fn: (event: any) => void): () => void;
+}
+
+export interface RecordObserverOptions {
+  onCompact?: (record: AgentRecord, info: CompactionInfo) => void;
+}
+
+/**
+ * Subscribe to session events and accumulate stats on the agent record.
+ *
+ * Handles:
+ * - `tool_execution_end` → `record.toolUses++`
+ * - `message_end` (assistant, with usage) → `addUsage(record.lifetimeUsage, …)`
+ * - `compaction_end` (not aborted) → `record.compactionCount++`, call `onCompact`
+ *
+ * @returns An unsubscribe function.
+ */
+export function subscribeRecordObserver(
+  session: SubscribableSession,
+  record: AgentRecord,
+  options?: RecordObserverOptions,
+): () => void {
+  return session.subscribe((event: any) => {
+    if (event.type === "tool_execution_end") {
+      record.toolUses++;
+    }
+
+    if (event.type === "message_end" && event.message?.role === "assistant") {
+      const u = event.message.usage;
+      if (u) {
+        addUsage(record.lifetimeUsage, {
+          input: u.input ?? 0,
+          output: u.output ?? 0,
+          cacheWrite: u.cacheWrite ?? 0,
+        });
+      }
+    }
+
+    if (event.type === "compaction_end" && !event.aborted && event.result) {
+      record.compactionCount++;
+      options?.onCompact?.(record, {
+        reason: event.reason,
+        tokensBefore: event.result.tokensBefore,
+      });
+    }
+  });
+}

package/src/tools/agent-tool.ts

@@ -20,17 +20,15 @@ import {
   SPINNER,
   type UICtx,
 } from "../ui/agent-widget.js";
-import { addUsage, type LifetimeUsage } from "../usage.js";
+import { subscribeUIObserver } from "../ui/ui-observer.js";
+import type { LifetimeUsage } from "../usage.js";
 import { formatLifetimeTokens, textResult } from "./helpers.js";
 
 // ---- Agent-tool-specific helpers ----
 
-/**
- * Create an AgentActivity state and spawn callbacks for tracking tool usage.
- * Used by both foreground and background paths to avoid duplication.
- */
-export function createActivityTracker(maxTurns?: number, onStreamUpdate?: () => void) {
-  const state: AgentActivity = {
+/** Create a fresh AgentActivity state for tracking UI progress. */
+function createAgentActivity(maxTurns?: number): AgentActivity {
+  return {
     activeTools: new Map(),
     toolUses: 0,
     turnCount: 1,
@@ -39,40 +37,6 @@ export function createActivityTracker(maxTurns?: number, onStreamUpdate?: () =>
     session: undefined,
     lifetimeUsage: { input: 0, output: 0, cacheWrite: 0 },
   };
-
-  const callbacks = {
-    onToolActivity: (activity: { type: "start" | "end"; toolName: string }) => {
-      if (activity.type === "start") {
-        state.activeTools.set(activity.toolName + "_" + Date.now(), activity.toolName);
-      } else {
-        for (const [key, name] of state.activeTools) {
-          if (name === activity.toolName) {
-            state.activeTools.delete(key);
-            break;
-          }
-        }
-        state.toolUses++;
-      }
-      onStreamUpdate?.();
-    },
-    onTextDelta: (_delta: string, fullText: string) => {
-      state.responseText = fullText;
-      onStreamUpdate?.();
-    },
-    onTurnEnd: (turnCount: number) => {
-      state.turnCount = turnCount;
-      onStreamUpdate?.();
-    },
-    onSessionCreated: (session: any) => {
-      state.session = session;
-    },
-    onAssistantUsage: (usage: { input: number; output: number; cacheWrite: number }) => {
-      addUsage(state.lifetimeUsage, usage);
-      onStreamUpdate?.();
-    },
-  };
-
-  return { state, callbacks };
 }
 
 /** Parenthetical status note for completed agent result text. */
@@ -451,8 +415,7 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const { state: bgState, callbacks: bgCallbacks } =
-          createActivityTracker(effectiveMaxTurns);
+        const bgState = createAgentActivity(effectiveMaxTurns);
 
         let id: string;
 
@@ -469,7 +432,10 @@ Guidelines:
             isBackground: true,
             isolation,
             invocation: agentInvocation,
-            ...bgCallbacks,
+            onSessionCreated: (session: any) => {
+              bgState.session = session;
+              subscribeUIObserver(session, bgState);
+            },
           });
         } catch (err) {
           return textResult(err instanceof Error ? err.message : String(err));
@@ -521,6 +487,9 @@ Guidelines:
       const startedAt = Date.now();
       let fgId: string | undefined;
 
+      const fgState = createAgentActivity(effectiveMaxTurns);
+      let unsubUI: (() => void) | undefined;
+
       const streamUpdate = () => {
         const details: AgentDetails = {
           ...detailBase,
@@ -539,25 +508,6 @@ Guidelines:
         });
       };
 
-      const { state: fgState, callbacks: fgCallbacks } = createActivityTracker(
-        effectiveMaxTurns,
-        streamUpdate,
-      );
-
-      // Wire session creation to register in widget
-      const origOnSession = fgCallbacks.onSessionCreated;
-      fgCallbacks.onSessionCreated = (session: any) => {
-        origOnSession(session);
-        for (const a of deps.manager.listAgents()) {
-          if (a.session === session) {
-            fgId = a.id;
-            deps.agentActivity.set(a.id, fgState);
-            deps.widget.ensureTimer();
-            break;
-          }
-        }
-      };
-
       // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
       const spinnerInterval = setInterval(() => {
         spinnerFrame++;
@@ -584,15 +534,28 @@ Guidelines:
             signal,
             parentSessionFile: ctx.sessionManager.getSessionFile(),
             parentSessionId: ctx.sessionManager.getSessionId(),
-            ...fgCallbacks,
+            onSessionCreated: (session: any) => {
+              fgState.session = session;
+              unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+              for (const a of deps.manager.listAgents()) {
+                if (a.session === session) {
+                  fgId = a.id;
+                  deps.agentActivity.set(a.id, fgState);
+                  deps.widget.ensureTimer();
+                  break;
+                }
+              }
+            },
           },
         );
       } catch (err) {
         clearInterval(spinnerInterval);
+        unsubUI?.();
         return textResult(err instanceof Error ? err.message : String(err));
       }
 
       clearInterval(spinnerInterval);
+      unsubUI?.();
 
       // Clean up foreground agent from widget
       if (fgId) {

package/src/ui/ui-observer.ts

@@ -0,0 +1,83 @@
+/**
+ * ui-observer.ts — Subscribes to session events and updates AgentActivity state.
+ *
+ * Replaces the callback-based createActivityTracker pattern with a direct
+ * session subscription for streaming UI state (active tools, response text,
+ * turn count, lifetime usage).
+ */
+
+import { addUsage } from "../usage.js";
+import type { AgentActivity } from "./agent-widget.js";
+
+/** Narrow session interface — only the subscribe method needed by the observer. */
+interface SubscribableSession {
+	subscribe(fn: (event: any) => void): () => void;
+}
+
+/**
+ * Subscribe to session events and stream UI state into an AgentActivity object.
+ *
+ * Handles:
+ * - `tool_execution_start` → add to `state.activeTools`
+ * - `tool_execution_end` → remove from `state.activeTools`, `state.toolUses++`
+ * - `message_start` → reset `state.responseText`
+ * - `message_update` (text_delta) → append to `state.responseText`
+ * - `turn_end` → `state.turnCount++`
+ * - `message_end` (assistant, with usage) → `addUsage(state.lifetimeUsage, …)`
+ *
+ * Calls `onUpdate?.()` after each state mutation to trigger re-renders.
+ *
+ * @returns An unsubscribe function.
+ */
+export function subscribeUIObserver(
+	session: SubscribableSession,
+	state: AgentActivity,
+	onUpdate?: () => void,
+): () => void {
+	return session.subscribe((event: any) => {
+		if (event.type === "tool_execution_start") {
+			state.activeTools.set(event.toolName + "_" + Date.now(), event.toolName);
+			onUpdate?.();
+		}
+
+		if (event.type === "tool_execution_end") {
+			for (const [key, name] of state.activeTools) {
+				if (name === event.toolName) {
+					state.activeTools.delete(key);
+					break;
+				}
+			}
+			state.toolUses++;
+			onUpdate?.();
+		}
+
+		if (event.type === "message_start") {
+			state.responseText = "";
+		}
+
+		if (
+			event.type === "message_update" &&
+			event.assistantMessageEvent?.type === "text_delta"
+		) {
+			state.responseText += event.assistantMessageEvent.delta;
+			onUpdate?.();
+		}
+
+		if (event.type === "turn_end") {
+			state.turnCount++;
+			onUpdate?.();
+		}
+
+		if (event.type === "message_end" && event.message?.role === "assistant") {
+			const u = event.message.usage;
+			if (u) {
+				addUsage(state.lifetimeUsage, {
+					input: u.input ?? 0,
+					output: u.output ?? 0,
+					cacheWrite: u.cacheWrite ?? 0,
+				});
+				onUpdate?.();
+			}
+		}
+	});
+}