@gotgenes/pi-subagents 6.6.0 → 6.8.0

package/CHANGELOG.md

@@ -5,6 +5,36 @@ 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.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.7.0...pi-subagents-v6.8.0) (2026-05-21)
+
+
+### Features
+
+* add ExecutionState interface ([#111](https://github.com/gotgenes/pi-packages/issues/111)) ([4f33e09](https://github.com/gotgenes/pi-packages/commit/4f33e09b8578509985308b225111cfdfce22bb06))
+* add NotificationState class ([#111](https://github.com/gotgenes/pi-packages/issues/111)) ([cbee34d](https://github.com/gotgenes/pi-packages/commit/cbee34d1944e411dd8593ac0cfbaa3fa66982d00))
+* add WorktreeState class ([#111](https://github.com/gotgenes/pi-packages/issues/111)) ([eddb0c8](https://github.com/gotgenes/pi-packages/commit/eddb0c84311d420f3b50c2861f7585cfd8d1037f))
+
+
+### Documentation
+
+* plan AgentRecord lifecycle state split ([#111](https://github.com/gotgenes/pi-packages/issues/111)) ([c271d89](https://github.com/gotgenes/pi-packages/commit/c271d8931729e620e46f05e82cdca8276dbd0a6d))
+* **retro:** add retro notes for issue [#110](https://github.com/gotgenes/pi-packages/issues/110) ([4a48c65](https://github.com/gotgenes/pi-packages/commit/4a48c655752902f86b864f224e209831f73e241d))
+* update architecture doc for AgentRecord lifecycle split ([#111](https://github.com/gotgenes/pi-packages/issues/111)) ([b0d8967](https://github.com/gotgenes/pi-packages/commit/b0d8967601eb7aca41cf59ce7f40f399ccc51fec))
+
+## [6.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.6.0...pi-subagents-v6.7.0) (2026-05-21)
+
+
+### Features
+
+* add AgentActivityTracker class ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([151308a](https://github.com/gotgenes/pi-packages/commit/151308ad3da569d72e40495bece502281dc302a8))
+
+
+### Documentation
+
+* plan AgentActivityTracker class ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([8f5e56b](https://github.com/gotgenes/pi-packages/commit/8f5e56ba0a29730e060bac4658bb4953ce36d4a9))
+* **retro:** add retro notes for issue [#118](https://github.com/gotgenes/pi-packages/issues/118) ([1959e52](https://github.com/gotgenes/pi-packages/commit/1959e52d8b150bbc90da72edd93dc6f2ec315e22))
+* update architecture doc — mark A3 done, fix Map type ([#110](https://github.com/gotgenes/pi-packages/issues/110)) ([463e997](https://github.com/gotgenes/pi-packages/commit/463e9974db21df17f4b2578825f3c67bc1e90b29))
+
 ## [6.6.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.5.0...pi-subagents-v6.6.0) (2026-05-21)
 
 

package/docs/architecture/architecture.md

@@ -82,7 +82,7 @@ Record statistics (tool uses, token usage, compaction counts) are updated by `re
 UI streaming (active tools, response text, turn counts) is handled by `ui/ui-observer.ts`, which subscribes to the same session events independently.
 Neither observer wraps or forwards the other — both subscribe directly to the session.
 
-The widget reads agent state by polling a shared `Map<string, AgentActivity>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
+The widget reads agent state by polling a shared `Map<string, AgentActivityTracker>` on `SubagentRuntime` every 80 ms. The conversation viewer subscribes directly to `AgentSession` objects.
 
 Cross-extension consumers use the typed `SubagentsService` API published via `Symbol.for("@gotgenes/pi-subagents:service")` on `globalThis`.
 
@@ -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)               | Written by `ui-observer.ts`, read by widget, notification, agent-tool                                                                                                     |
-| ~~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       | `session`, `outputFile`, `worktree`, `promise` written by external code after construction                                                                                |
-| Fire-and-forget callbacks  | `AgentManagerOptions`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
-| 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                                                                                     |
+| 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`                    | `onStart`, `onComplete`, `onCompact` wired as closures in `index.ts`                                                                                                      |
+| 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                                                                                     |
 
 ### Step A: Extract state into classes (foundation, parallel)
 
@@ -422,23 +422,25 @@ Each owns the full consequence chain: normalize → set in memory → notify cal
 
 Impact: eliminates LoD / Tell-Don't-Ask violation in `showSettings`; menu no longer coordinates between settings and manager.
 
-#### A3. `AgentActivityTracker` class (#110)
+#### ~~A3. `AgentActivityTracker` class (#110)~~ — **Done**
 
-Wrap the 7-field mutable `AgentActivity` interface with transition methods (`onToolStart()`, `onToolEnd()`, `onMessageUpdate()`, `onTurnEnd()`).
-`ui-observer.ts` calls tracker methods instead of writing raw fields.
-The notification system, widget, and agent-tool receive a proper collaborator instead of reaching into a shared `Map<string, AgentActivity>`.
+Wrapped the 7-field mutable `AgentActivity` interface in an `AgentActivityTracker` class (`src/ui/agent-activity-tracker.ts`).
+`ui-observer.ts` calls transition methods (`onToolStart`, `onToolEnd`, `onMessageStart`, `onMessageUpdate`, `onTurnEnd`, `onUsageUpdate`, `setSession`).
+The notification system, widget, conversation viewer, and agent-tool use read-only accessors.
+The shared map on `SubagentRuntime` is now `Map<string, AgentActivityTracker>`.
 
 Impact: eliminates output-argument writes in `ui-observer.ts`, makes the mutation contract explicit.
 
-### Step B: Split `AgentRecord` lifecycle state (#111)
+### ~~Step B: Split `AgentRecord` lifecycle state (#111)~~ — **Done**
 
-`AgentRecord` is currently constructed in `spawn()` before most of its state exists, then mutated across 4 files as information trickles in.
-The fix is not setter methods — it's splitting along lifecycle boundaries so each object is born complete.
+Split post-construction mutation into phase-specific collaborators, each born complete:
 
-- **`AgentRecord`** stays as identity + status state machine (what we know at spawn time).
-- **Execution state** (`session`, `promise`, `outputFile`) → a new object constructed when the runner creates the session, injected as a complete collaborator.
-- **Worktree state** (`worktree` info, cleanup result) → a new object constructed when isolation is set up, only exists for worktree agents.
-- **`pendingSteers`** moves to a queue on the manager (where they're buffered), not a field on the record.
+- **`ExecutionState`** (`session`, `outputFile`) — constructed in `onSessionCreated`, attached as `record.execution`.
+- **`WorktreeState`** (`path`, `branch`, `cleanupResult`) — constructed at worktree setup, attached as `record.worktreeState`.
+- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by agent-tool after spawn, attached as `record.notification`.
+- **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`; steer-tool and service-adapter call `manager.queueSteer()`.
+- Stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods (`incrementToolUses`, `addUsage`, `incrementCompactions`) with read-only getters.
+- `AgentRecordInit` trimmed from 19 optional fields to 4 construction-time fields.
 
 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.
@@ -485,17 +487,17 @@ The 654-line file splits along a natural seam.
 
 ### Expected impact
 
-| Metric                                     | Before                                                                       | After   |
-| ------------------------------------------ | ---------------------------------------------------------------------------- | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                 | **0** ✓ |
-| Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**) | 0       |
-| Externally-mutated state bags              | 2 (`AgentActivity`, `AgentRecord` non-transition fields)                     | 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 ✓    |
-| `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       |
+| Metric                                     | Before                                                                           | After   |
+| ------------------------------------------ | -------------------------------------------------------------------------------- | ------- |
+| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                     | **0** ✓ |
+| 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 ✓    |
+| `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       |
 
 ### Dependency graph
 

package/docs/plans/0110-agent-activity-tracker.md

@@ -0,0 +1,297 @@
+---
+issue: 110
+issue_title: "refactor(pi-subagents): wrap AgentActivity in AgentActivityTracker class"
+---
+
+# Wrap AgentActivity in AgentActivityTracker class
+
+## Problem Statement
+
+`AgentActivity` is a 7-field mutable interface (`activeTools`, `toolUses`, `responseText`, `session`, `turnCount`, `maxTurns`, `lifetimeUsage`) shared across 4 modules.
+`ui-observer.ts` writes raw fields on it (output arguments), the widget and conversation viewer read them, and the agent-tool creates empty instances and stuffs them into a shared `Map`.
+The mutation contract is implicit — callers know which fields to set by convention, not by API.
+
+This is Phase 7, Step A3 in the architecture doc.
+
+## Goals
+
+- Wrap `AgentActivity` in an `AgentActivityTracker` class with explicit transition methods.
+- Replace the output-argument writes in `ui-observer.ts` with tracker method calls.
+- Expose read-only accessors for the state the widget, notification system, conversation viewer, and agent-tool need.
+- Change the shared `Map<string, AgentActivity>` on `SubagentRuntime` to `Map<string, AgentActivityTracker>`.
+- Preserve all existing behavior — this is a pure encapsulation refactor.
+
+## Non-Goals
+
+- Splitting `AgentRecord` lifecycle state (#111) — deferred to Step B.
+- Replacing `AgentManager` callbacks with an observer (#112) — deferred to Step C.
+- Narrowing `AgentToolDeps` or `AgentMenuDeps` further (#114) — deferred to Step D2.
+- Changing `createNotificationSystem` from closure to class (#116) — deferred to Step E2.
+
+## Background
+
+### Who writes AgentActivity today
+
+`ui-observer.ts` (`subscribeUIObserver`) is the sole writer.
+It subscribes to session events and mutates the state object directly:
+
+- `state.activeTools.set(...)` / `state.activeTools.delete(...)` on tool start/end
+- `state.toolUses++` on tool end
+- `state.responseText = ""` on message start, `state.responseText += delta` on message update
+- `state.turnCount++` on turn end
+- `addUsage(state.lifetimeUsage, ...)` on message end with assistant usage
+
+The agent-tool also writes `session` after session creation (`fgState.session = session`, `bgState.session = session`).
+
+### Who reads AgentActivity today
+
+| Consumer                                       | Fields read                                                                                    |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| `agent-widget.ts` (widget render)              | `activeTools`, `responseText`, `toolUses`, `turnCount`, `maxTurns`, `lifetimeUsage`, `session` |
+| `conversation-viewer.ts`                       | `toolUses`, `lifetimeUsage`, `session`, `activeTools`, `responseText`                          |
+| `notification.ts` (`buildNotificationDetails`) | `turnCount`, `maxTurns`                                                                        |
+| `agent-tool.ts` (foreground streaming)         | `toolUses`, `turnCount`, `maxTurns`, `activeTools`, `responseText`, `lifetimeUsage`            |
+| `agent-menu.ts` (conversation viewer launch)   | passes to `ConversationViewer`                                                                 |
+
+### Who creates AgentActivity today
+
+`createAgentActivity()` in `agent-tool.ts` — a factory function that returns a plain object with defaults.
+
+### AGENTS.md constraints
+
+- One concern per file: the tracker gets its own module.
+- Avoid `any`: use typed accessors.
+- Output arguments: this refactor eliminates them from `ui-observer.ts`.
+- Keep modules focused: the tracker owns its mutable state; consumers use read-only accessors.
+
+## Design Overview
+
+### AgentActivityTracker class
+
+New file: `src/ui/agent-activity-tracker.ts`.
+
+The class owns the 7 mutable fields and exposes:
+
+1. Transition methods (the write surface — called by `ui-observer.ts` and agent-tool):
+
+   ```typescript
+   onToolStart(toolName: string): void    // adds to activeTools map
+   onToolEnd(toolName: string): void      // removes from activeTools, increments toolUses
+   onMessageStart(): void                  // resets responseText
+   onMessageUpdate(delta: string): void    // appends to responseText
+   onTurnEnd(): void                       // increments turnCount
+   onUsageUpdate(usage: UsageDelta): void  // accumulates into lifetimeUsage
+   setSession(session: SessionLike): void  // one-time session binding
+   ```
+
+2. Read-only accessors (the read surface — used by widget, notification, conversation viewer, agent-tool streaming):
+
+   ```typescript
+   get activeTools(): ReadonlyMap<string, string>
+   get toolUses(): number
+   get responseText(): string
+   get session(): SessionLike | undefined
+   get turnCount(): number
+   get maxTurns(): number | undefined
+   get lifetimeUsage(): Readonly<LifetimeUsage>
+   ```
+
+The constructor accepts `maxTurns?: number` (set at creation time, immutable).
+
+### UsageDelta type
+
+A narrow type for the usage values passed to `onUsageUpdate`:
+
+```typescript
+interface UsageDelta { input: number; output: number; cacheWrite: number }
+```
+
+This matches the shape `addUsage` already expects and avoids coupling to the full `LifetimeUsage` type name for what is logically a delta.
+
+### activeTools key strategy
+
+The current `activeTools` Map uses `toolName + "_" + Date.now()` as a key to allow multiple concurrent tools with the same name.
+`onToolStart` returns `void` and generates the key internally (same `Date.now()` strategy).
+`onToolEnd(toolName)` finds and removes the first matching entry (same logic as today).
+
+### subscribeUIObserver changes
+
+`subscribeUIObserver` changes its second parameter from `state: AgentActivity` to `tracker: AgentActivityTracker`.
+Instead of writing fields, it calls tracker methods:
+
+```typescript
+// Before:
+state.activeTools.set(event.toolName + "_" + Date.now(), event.toolName);
+// After:
+tracker.onToolStart(event.toolName);
+```
+
+### Consumer interface
+
+Readers continue to access the same properties but through getters.
+Since the tracker exposes matching property names, consumer code like `bg.turnCount` and `bg.toolUses` remains syntactically identical — only the type annotation changes from `AgentActivity` to `AgentActivityTracker`.
+
+The `AgentActivity` interface is removed entirely.
+All references migrate to `AgentActivityTracker`.
+
+### Map type change
+
+`SubagentRuntime.agentActivity` changes from `Map<string, AgentActivity>` to `Map<string, AgentActivityTracker>`.
+All dependency bags that pass this map (`AgentToolDeps`, `AgentMenuDeps`, `NotificationDeps`, `AgentWidget` constructor) update their type annotations.
+
+### createAgentActivity replacement
+
+The factory function in `agent-tool.ts` is replaced by `new AgentActivityTracker(maxTurns)`.
+
+## Module-Level Changes
+
+### New file
+
+| File                               | What                                                                         |
+| ---------------------------------- | ---------------------------------------------------------------------------- |
+| `src/ui/agent-activity-tracker.ts` | `AgentActivityTracker` class with transition methods and read-only accessors |
+
+### New test file
+
+| File                                     | What                                                          |
+| ---------------------------------------- | ------------------------------------------------------------- |
+| `test/ui/agent-activity-tracker.test.ts` | Unit tests for all transition methods and read-only accessors |
+
+### Modified files
+
+| File                            | What changes                                                                                                                                                                                                   |
+| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/ui/ui-observer.ts`         | Accept `AgentActivityTracker` instead of `AgentActivity`; call transition methods instead of writing fields                                                                                                    |
+| `src/ui/agent-widget.ts`        | Remove `AgentActivity` interface; import `AgentActivityTracker`; update `Map` type and read sites (property names stay the same)                                                                               |
+| `src/ui/conversation-viewer.ts` | Import `AgentActivityTracker` instead of `AgentActivity`; update parameter type                                                                                                                                |
+| `src/ui/agent-menu.ts`          | Import `AgentActivityTracker` instead of `AgentActivity`; update `Map` type                                                                                                                                    |
+| `src/tools/agent-tool.ts`       | Import `AgentActivityTracker`; replace `createAgentActivity()` with `new AgentActivityTracker()`; replace `fgState.session = session` with `fgState.setSession(session)`; update `Map` type in `AgentToolDeps` |
+| `src/notification.ts`           | Import `AgentActivityTracker` instead of `AgentActivity`; update `buildNotificationDetails` parameter and `NotificationDeps.agentActivity` Map type                                                            |
+| `src/runtime.ts`                | Import `AgentActivityTracker`; change `agentActivity` Map type; update `AgentWidget` import (type only change since `AgentActivity` moves)                                                                     |
+| `src/index.ts`                  | No changes (already references `runtime.agentActivity` by reference, the type flows through)                                                                                                                   |
+
+### Modified test files
+
+| File                            | What changes                                                                                                                                               |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `test/ui/ui-observer.test.ts`   | Replace `makeActivity()` factory with `new AgentActivityTracker()`; access state through getters; assertions on accessor values instead of raw field reads |
+| `test/notification.test.ts`     | Replace `as AgentActivity` casts with `new AgentActivityTracker()`; set up tracker state via transition methods                                            |
+| `test/tools/agent-tool.test.ts` | Update `Map<string, AgentActivity>` type to `Map<string, AgentActivityTracker>`                                                                            |
+
+### Removed exports
+
+| Symbol                             | Was in                    | Replaced by                                                        |
+| ---------------------------------- | ------------------------- | ------------------------------------------------------------------ |
+| `AgentActivity` (interface)        | `src/ui/agent-widget.ts`  | `AgentActivityTracker` class in `src/ui/agent-activity-tracker.ts` |
+| `createAgentActivity()` (function) | `src/tools/agent-tool.ts` | `new AgentActivityTracker(maxTurns)`                               |
+
+Grep verification: `AgentActivity` is referenced in 7 source files and 3 test files (listed above) — all accounted for in the modified files list.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+The `AgentActivityTracker` class enables focused unit tests for each transition method in isolation:
+
+- `onToolStart` / `onToolEnd` — concurrent tool tracking, correct toolUses increment
+- `onMessageStart` / `onMessageUpdate` — response text lifecycle
+- `onTurnEnd` — turn counting from initial value
+- `onUsageUpdate` — accumulation semantics
+- `setSession` — one-time binding
+- Read-only accessors — verify consumers cannot mutate internal state
+
+These were previously impossible to test without going through `subscribeUIObserver` and a mock session.
+
+### Existing tests that simplify
+
+`test/ui/ui-observer.test.ts` — currently constructs a plain `AgentActivity` object and asserts on raw field mutations.
+After the change, it constructs an `AgentActivityTracker` and the assertions read the same properties through accessors.
+The `makeActivity()` helper is replaced by `new AgentActivityTracker()`.
+The test logic stays the same (event → tracker state check) but the assertions use getter-backed properties.
+
+### Existing tests that stay as-is
+
+`test/notification.test.ts` — the pure helper tests (`escapeXml`, `getStatusLabel`, `formatTaskNotification`, `buildNotificationDetails`) only need their `AgentActivity` type references updated to `AgentActivityTracker`.
+The notification system integration tests that cast `{} as AgentActivity` need minimal updates to construct a real tracker instead.
+
+`test/tools/agent-tool.test.ts` — only the `Map` type annotation changes.
+
+## TDD Order
+
+### 1. Red/green: AgentActivityTracker class — transition methods and read-only accessors
+
+Test file: `test/ui/agent-activity-tracker.test.ts`
+
+Tests:
+
+- Constructor sets initial state (`turnCount: 1`, empty `activeTools`, `toolUses: 0`, empty `responseText`, zero `lifetimeUsage`, `maxTurns` from constructor arg, `session` undefined)
+- `onToolStart` adds entry to `activeTools`
+- `onToolEnd` removes entry and increments `toolUses`
+- `onToolEnd` with no matching tool is a no-op (defensive)
+- Multiple concurrent tools with same name tracked independently
+- `onMessageStart` resets `responseText` to empty
+- `onMessageUpdate` appends delta to `responseText`
+- `onTurnEnd` increments `turnCount`
+- `onUsageUpdate` accumulates into `lifetimeUsage`
+- `setSession` stores the session reference
+- Read-only: `activeTools` returns `ReadonlyMap`
+- Read-only: `lifetimeUsage` returns `Readonly<LifetimeUsage>`
+
+Commit: `feat: add AgentActivityTracker class (#110)`
+
+### 2. Red/green: migrate ui-observer to use AgentActivityTracker
+
+Update `src/ui/ui-observer.ts` to accept `AgentActivityTracker` and call transition methods.
+Update `test/ui/ui-observer.test.ts`: replace `makeActivity()` with `new AgentActivityTracker()`, read state through accessors.
+
+All existing test scenarios must pass unchanged (same events → same observable state).
+
+Commit: `refactor: migrate ui-observer to AgentActivityTracker (#110)`
+
+### 3. Migrate agent-widget and conversation-viewer
+
+Update `src/ui/agent-widget.ts`: remove `AgentActivity` interface, import `AgentActivityTracker`, update `Map` type and constructor parameter.
+Update `src/ui/conversation-viewer.ts`: import `AgentActivityTracker`, update parameter type.
+
+No test changes needed — widget and conversation viewer are not unit-tested (they render UI).
+
+Commit: `refactor: migrate widget and conversation-viewer to AgentActivityTracker (#110)`
+
+### 4. Migrate agent-tool
+
+Update `src/tools/agent-tool.ts`: import `AgentActivityTracker`, replace `createAgentActivity()` with `new AgentActivityTracker()`, replace `fgState.session = session` with `fgState.setSession(session)`, update `AgentToolDeps` Map type.
+Update `test/tools/agent-tool.test.ts`: update Map type.
+
+Commit: `refactor: migrate agent-tool to AgentActivityTracker (#110)`
+
+### 5. Migrate notification and agent-menu
+
+Update `src/notification.ts`: import `AgentActivityTracker`, update `buildNotificationDetails` parameter and `NotificationDeps` Map type.
+Update `src/ui/agent-menu.ts`: import `AgentActivityTracker`, update Map type in `AgentMenuDeps`.
+Update `test/notification.test.ts`: replace `as AgentActivity` casts with real `AgentActivityTracker` instances.
+
+Commit: `refactor: migrate notification and agent-menu to AgentActivityTracker (#110)`
+
+### 6. Migrate runtime and clean up
+
+Update `src/runtime.ts`: import `AgentActivityTracker`, change `agentActivity` Map type.
+Remove any remaining `AgentActivity` references.
+Run `pnpm run check` to verify no type errors remain.
+
+Commit: `refactor: complete AgentActivityTracker migration, remove AgentActivity interface (#110)`
+
+## Risks and Mitigations
+
+| Risk                                                                              | Mitigation                                                                                                                                                                                                                        |
+| --------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Read-only getters change identity semantics for `activeTools` and `lifetimeUsage` | The `ReadonlyMap` and `Readonly<LifetimeUsage>` types restrict writes at compile time. Consumers already only read these values, so no runtime change. Return the internal mutable reference cast to readonly (no copy overhead). |
+| Spreading a class instance loses methods                                          | Grep for `{ ...activity` or `{ ...bg` patterns — none found in current code. The `buildDetails` function spreads `detailBase` (a plain object), not the activity.                                                                 |
+| `onToolEnd` matching logic fragility                                              | Port the exact same `for...of` + `break` pattern from `ui-observer.ts`. New unit tests cover this independently.                                                                                                                  |
+| `turnCount` initial value of 1 (not 0)                                            | The current `createAgentActivity` sets `turnCount: 1`. The tracker constructor preserves this. A dedicated test asserts the initial value.                                                                                        |
+| Test files casting `{} as AgentActivity`                                          | Replace with real `AgentActivityTracker` instances. Where tests only need `turnCount` and `maxTurns` (e.g., `buildNotificationDetails`), construct a tracker and call `onTurnEnd` to set up the desired state.                    |
+
+## Open Questions
+
+- None — the issue and architecture doc are prescriptive about the approach.
+  The only design latitude is whether `onToolStart` returns a key (for symmetric `onToolEnd(key)`) or whether `onToolEnd(toolName)` does a lookup.
+  The plan uses `onToolEnd(toolName)` with lookup to match the existing pattern and avoid threading a key through the session event handler.