@gotgenes/pi-subagents 6.15.0 → 6.16.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.16.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.15.0...pi-subagents-v6.16.0) (2026-05-23)
+
+
+### Features
+
+* add session and outputFile convenience getters to AgentRecord ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([b451894](https://github.com/gotgenes/pi-packages/commit/b451894d101b43be9115dcf6d45725a09da81df8))
+
+
+### Documentation
+
+* mark Step L complete, remove resolved smells from architecture doc ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([36ab7a5](https://github.com/gotgenes/pi-packages/commit/36ab7a51d0320666b71d6c9e20c3bbf63b7c43c5))
+* plan consolidate observation model ([#144](https://github.com/gotgenes/pi-packages/issues/144)) ([9aa2c85](https://github.com/gotgenes/pi-packages/commit/9aa2c8508079c6ae847662631afd223e8966e12e))
+* **retro:** add retro notes for issue [#145](https://github.com/gotgenes/pi-packages/issues/145) ([2d23081](https://github.com/gotgenes/pi-packages/commit/2d230817d53357a62eb752b56f8b1c8ce4af718c))
+
 ## [6.15.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.1...pi-subagents-v6.15.0) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -617,13 +617,11 @@ Phase 9 targets the next layer: observation model consolidation, `ExtensionConte
 
 | Smell                                            | Location                                                              | Evidence                                                                                                                                                       | Severity |
 | ------------------------------------------------ | --------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| Dual observation                                 | `record-observer.ts`, `ui-observer.ts`                                | Both independently count tool uses and accumulate lifetime usage from the same session events; consumers use `activity?.toolUses ?? record.toolUses` fallbacks | High     |
 | `execute` does config resolution for its callees | `agent-tool.ts` (145-line `execute`)                                  | ~60 lines unpack config, resolve model, compute metadata, repack into 16-field bags for spawners; `ctx` threaded 4 layers deep                                 | Medium   |
 | Wide `ctx` in menu handlers                      | `agent-menu.ts`, `agent-config-editor.ts`, `agent-creation-wizard.ts` | Functions declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor`; 43 `ctx as any` casts across 3 test files                 | Medium   |
-| `record.execution?.session` traversal            | 15+ callsites across tools, notification, widget, menu                | Callers reach through `ExecutionState` to access session and outputFile - Law of Demeter violation                                                             | Medium   |
 | Direct SDK import in `conversation-viewer.ts`    | `conversation-viewer.test.ts`                                         | Hoisted `vi.mock("@earendil-works/pi-tui")` to intercept `wrapTextWithAnsi`                                                                                    | Low      |
 | Widget mixes rendering, lifecycle, and state     | `agent-widget.ts` (370 lines)                                         | `renderWidget` is ~109 lines mixing data collection, formatting, and overflow layout; constructor takes 3 concrete collaborators                               | Low      |
-| `deps.` prefix noise in function bodies          | 12 modules across tools, UI, notification, service-adapter            | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                                      | Low      |
+| `deps.` prefix noise in function bodies          | remaining modules across tools, UI, service-adapter                   | Functions accept a `deps` bag and access every field as `deps.foo`; hides real dependencies and lengthens every call line                                      | Low      |
 
 ### Dependency bag convention
 
@@ -634,9 +632,9 @@ Applied incrementally as each step touches a module:
 
 This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
 
-### Step L: Consolidate observation model (#144)
+### Step L: Consolidate observation model (#144) ✓
 
-Remove `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
+Removed `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker`.
 UI consumers read stats from `AgentRecord` instead of the tracker.
 The UI observer retains event subscriptions for re-render triggers but no longer accumulates stats independently.
 

package/docs/plans/0144-consolidate-observation-model.md

@@ -0,0 +1,263 @@
+---
+issue: 144
+issue_title: "Consolidate observation model (Phase 9, Step L)"
+---
+
+# Consolidate observation model
+
+## Problem Statement
+
+`record-observer.ts` and `ui-observer.ts` independently count tool uses and accumulate lifetime usage from the same session events.
+`AgentRecord` owns `_toolUses` and `_lifetimeUsage` (accumulated by the record observer), while `AgentActivityTracker` maintains its own `_toolUses` and `_lifetimeUsage` (accumulated by the UI observer).
+Consumers use `activity?.toolUses ?? record.toolUses` fallbacks to paper over the ambiguity.
+
+Separately, 15+ callsites navigate `record.execution?.session` and `record.execution?.outputFile`, leaking the `ExecutionState` structure to every consumer.
+
+Finally, `NotificationDeps` (4 fields) is a dependency bag on a class where every method uses every field — plain constructor parameters are simpler.
+
+## Goals
+
+- Remove `_toolUses` and `_lifetimeUsage` from `AgentActivityTracker` so stats have a single source of truth on `AgentRecord`.
+- Update UI consumers (widget, conversation viewer, notification, foreground runner) to read stats from `AgentRecord` instead of the tracker.
+- Remove the `onToolEnd` counter and `onUsageUpdate` accumulator from `AgentActivityTracker`, keeping only live UI state (active tools, response text, turn count).
+- Stop the UI observer from duplicating `tool_execution_end` counting and `message_end` usage accumulation.
+- Add `session` and `outputFile` convenience getters on `AgentRecord` to hide the `execution?.` traversal.
+- Replace `NotificationDeps` interface with plain parameters on `NotificationManager` constructor.
+
+## Non-Goals
+
+- Splitting `AgentWidget` rendering into pure functions (Step P / #148 — depends on this work).
+- Narrowing `ExtensionContext` for menu handlers (Step N / #146 — independent track).
+- Injecting text wrapping into `ConversationViewer` (Step O / #147 — independent track).
+
+## Background
+
+### Dual counting
+
+Both observers subscribe to the same session events:
+
+| Event                 | `record-observer.ts`         | `ui-observer.ts`                      |
+| --------------------- | ---------------------------- | ------------------------------------- |
+| `tool_execution_end`  | `record.incrementToolUses()` | `tracker.onToolEnd()` → `_toolUses++` |
+| `message_end` (usage) | `record.addUsage(delta)`     | `tracker.onUsageUpdate(delta)`        |
+
+The widget reads `bg?.toolUses ?? a.toolUses` and the conversation viewer reads `this.activity?.toolUses ?? this.record.toolUses`, preferring the tracker when alive and falling back to the record.
+After this change, there is one source: `AgentRecord`.
+
+### `execution?.` traversal
+
+`ExecutionState` holds `session` and `outputFile`.
+These are set once when the agent session is created (`agent-manager.ts` line 276).
+Consumers reach through `record.execution?.session` and `record.execution?.outputFile` in 12 distinct locations across 7 files.
+Convenience getters on `AgentRecord` eliminate the traversal and hide the `ExecutionState` structure.
+
+### `NotificationDeps` bag
+
+`NotificationManager` receives 4 fields via `NotificationDeps`: `sendMessage`, `agentActivity`, `markFinished`, `updateWidget`.
+Every method on the class uses every field.
+Per code-design convention (dependency width), a 4-field interface where every consumer uses every field is fine as a bag, but the architecture doc explicitly calls for plain parameters here.
+This is a mechanical change.
+
+## Design Overview
+
+### AgentActivityTracker changes
+
+Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, and `lifetimeUsage` getter.
+Retain: `_activeTools`, `_toolKeySeq`, `_responseText`, `_session`, `_turnCount`, `_maxTurns`, and their associated transition methods and getters.
+
+`onToolStart` stays (tracks active tools for the widget spinner).
+A new `onToolDone(toolName)` method replaces `onToolEnd` — it removes the tool from `_activeTools` without incrementing any counter.
+This rename clarifies that the method only manages the active-tool display set.
+
+### UI observer changes
+
+The UI observer stops calling counter/accumulator methods:
+
+- `tool_execution_end` handler: calls `tracker.onToolDone(name)` (active-tool tracking only).
+- `message_end` handler: removed entirely (no more usage accumulation).
+  The `onUpdate?.()` call for usage re-render moves to the record observer path via the existing widget update flow.
+
+### AgentRecord convenience getters
+
+```typescript
+get session(): AgentSession | undefined {
+  return this.execution?.session;
+}
+
+get outputFile(): string | undefined {
+  return this.execution?.outputFile;
+}
+```
+
+Callers change from `record.execution?.session` to `record.session`.
+The `execution` field remains writable (set by `AgentManager`), but consumers no longer need to know about `ExecutionState`.
+
+### Consumer migration
+
+| File                       | Before                                             | After                                            |
+| -------------------------- | -------------------------------------------------- | ------------------------------------------------ |
+| `agent-widget.ts`          | `bg?.toolUses ?? a.toolUses`                       | `a.toolUses`                                     |
+| `agent-widget.ts`          | `getLifetimeTotal(bg?.lifetimeUsage)`              | `getLifetimeTotal(a.lifetimeUsage)`              |
+| `agent-widget.ts`          | `getSessionContextPercent(bg?.session)`            | `getSessionContextPercent(a.session)`            |
+| `conversation-viewer.ts`   | `this.activity?.toolUses ?? this.record.toolUses`  | `this.record.toolUses`                           |
+| `conversation-viewer.ts`   | `getLifetimeTotal(this.activity?.lifetimeUsage)`   | `getLifetimeTotal(this.record.lifetimeUsage)`    |
+| `conversation-viewer.ts`   | `getSessionContextPercent(this.activity?.session)` | `getSessionContextPercent(this.record.session)`  |
+| `notification.ts`          | `record.execution?.session`                        | `record.session`                                 |
+| `notification.ts`          | `record.execution?.outputFile`                     | `record.outputFile`                              |
+| `tools/get-result-tool.ts` | `record.execution?.session`                        | `record.session`                                 |
+| `tools/steer-tool.ts`      | `record.execution?.session`                        | `record.session`                                 |
+| `agent-menu.ts`            | `record.execution?.session`                        | `record.session`                                 |
+| `service-adapter.ts`       | `record.execution?.session`                        | `record.session`                                 |
+| `agent-manager.ts`         | `record.execution?.session`                        | `record.session` (in dispose paths)              |
+| `foreground-runner.ts`     | `fgState.toolUses`                                 | `record.toolUses` (in final result)              |
+| `foreground-runner.ts`     | `formatLifetimeTokens(fgState)`                    | `formatLifetimeTokens(record)` (in final result) |
+
+### NotificationManager refactoring
+
+Replace:
+
+```typescript
+export interface NotificationDeps { … }
+constructor(private deps: NotificationDeps) {}
+```
+
+With:
+
+```typescript
+constructor(
+  private sendMessage: NotificationDeps["sendMessage"],
+  private agentActivity: Map<string, AgentActivityTracker>,
+  private markFinished: (id: string) => void,
+  private updateWidget: () => void,
+) {}
+```
+
+Internal references change from `this.deps.sendMessage(…)` to `this.sendMessage(…)`.
+The `NotificationDeps` interface is removed.
+
+### Foreground runner streaming
+
+During foreground execution, `streamUpdate` reads `fgState.toolUses` and `formatLifetimeTokens(fgState)` for live spinner updates.
+After removing these from the tracker, `streamUpdate` must read from the record instead.
+The record is available only after `spawnAndWait` returns the record reference via `onSessionCreated`.
+Before that callback fires, tool uses and usage are both zero — the tracker never had meaningful data at that point either.
+`streamUpdate` will capture a `let recordRef: AgentRecord | undefined` and read `recordRef?.toolUses ?? 0` during the spinner phase.
+After `onSessionCreated`, `recordRef` is set and subsequent spinner ticks read live values from the record.
+
+## Module-Level Changes
+
+### Modified files
+
+1. `src/ui/agent-activity-tracker.ts` — Remove `_toolUses`, `_lifetimeUsage`, `onToolEnd`, `onUsageUpdate`, `toolUses` getter, `lifetimeUsage` getter.
+   Rename remaining tool-end logic to `onToolDone`.
+   Remove `addUsage` and `UsageDelta` imports.
+2. `src/ui/ui-observer.ts` — Call `tracker.onToolDone` instead of `tracker.onToolEnd`.
+   Remove `message_end` usage accumulation block.
+3. `src/agent-record.ts` — Add `get session()` and `get outputFile()` convenience getters.
+   Import `AgentSession` type for the return type.
+4. `src/notification.ts` — Remove `NotificationDeps` interface.
+   Change `NotificationManager` constructor to plain parameters.
+   Replace `this.deps.*` with `this.*`.
+   Change `record.execution?.session` → `record.session`, `record.execution?.outputFile` → `record.outputFile`.
+5. `src/ui/agent-widget.ts` — Read `a.toolUses`, `a.lifetimeUsage`, `a.session` instead of `bg?.toolUses ?? a.toolUses` etc.
+6. `src/ui/conversation-viewer.ts` — Read `this.record.toolUses`, `this.record.lifetimeUsage`, `this.record.session` instead of fallback pattern.
+7. `src/tools/get-result-tool.ts` — `record.execution?.session` → `record.session`.
+8. `src/tools/steer-tool.ts` — `record.execution?.session` → `record.session`.
+9. `src/ui/agent-menu.ts` — `record.execution?.session` → `record.session`.
+10. `src/service-adapter.ts` — `record.execution?.session` → `record.session`.
+11. `src/agent-manager.ts` — `record.execution?.session` → `record.session` in dispose paths.
+    Keep the `record.execution = { session, outputFile }` assignment unchanged (that's the write path).
+12. `src/tools/foreground-runner.ts` — Read `record.toolUses` and `formatLifetimeTokens(record)` for final result.
+    Capture `recordRef` for streaming phase.
+13. `src/tools/helpers.ts` — `buildDetails`: read `record.toolUses` and `record.lifetimeUsage` (already does); remove optional `activity` parameter's usage of `toolUses`/`lifetimeUsage` if present (verify).
+14. `src/index.ts` — Update `NotificationManager` construction from bag to plain parameters.
+15. `src/tools/background-spawner.ts` — `record?.execution?.outputFile` → `record?.outputFile`.
+
+### Test files modified
+
+1. `test/ui/agent-activity-tracker.test.ts` — Remove tests for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate`.
+   Add tests for `onToolDone` (active-tool removal without counting).
+2. `test/ui/ui-observer.test.ts` — Update `tool_execution_end` expectations (calls `onToolDone` not `onToolEnd`).
+   Remove `message_end` usage accumulation tests.
+3. `test/notification.test.ts` — Update `makeDeps()` factory to use plain parameters.
+   Or update `NotificationManager` construction call to match new signature.
+4. `test/agent-record.test.ts` — Add tests for `session` and `outputFile` getters.
+5. `test/conversation-viewer.test.ts` — Remove mock activity tracker usage for stats; tests use record stats directly.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+1. `AgentRecord.session` and `AgentRecord.outputFile` getters — straightforward getter tests on the record class.
+2. `AgentActivityTracker.onToolDone` — verifies active-tool removal without side effects on a counter.
+
+### Existing tests that become simpler
+
+1. `agent-activity-tracker.test.ts` — 4 test blocks for `toolUses`, `lifetimeUsage`, `onToolEnd`, `onUsageUpdate` can be removed.
+   The `onToolDone` replacement needs fewer assertions (no counter check).
+2. `ui-observer.test.ts` — The `message_end` usage accumulation tests can be removed.
+   The `tool_execution_end` test simplifies (verifies active-tool removal only).
+3. `notification.test.ts` — The `makeDeps()` helper changes shape but stays the same size.
+4. `conversation-viewer.test.ts` — Tests that mock `activity.toolUses` and `activity.lifetimeUsage` can simplify to reading from the record.
+
+### Existing tests that must stay
+
+1. `record-observer.test.ts` — All tests remain as-is.
+   The record observer is the sole source of `incrementToolUses` and `addUsage` calls now.
+2. `agent-record.test.ts` — All existing tests for `incrementToolUses`, `addUsage`, `incrementCompactions` remain.
+3. `notification.test.ts` — Pure helper tests (`escapeXml`, `getStatusLabel`, `formatTaskNotification`, `buildNotificationDetails`, `buildEventData`) remain unchanged.
+
+## TDD Order
+
+1. **Red→Green: `AgentRecord` convenience getters.**
+   Add tests for `record.session` and `record.outputFile` (returns `undefined` when no execution, delegates when set).
+   Implement the getters.
+   Commit: `feat: add session and outputFile convenience getters to AgentRecord (#144)`
+
+2. **Green→Green: Migrate callsites from `execution?.` to convenience getters.**
+   Update all 12 callsites across 7 files (`notification.ts`, `agent-widget.ts`, `agent-menu.ts`, `get-result-tool.ts`, `steer-tool.ts`, `service-adapter.ts`, `agent-manager.ts`, `background-spawner.ts`).
+   No test changes needed — existing tests pass.
+   Run `pnpm run check` to verify.
+   Commit: `refactor: use AgentRecord.session and .outputFile convenience getters (#144)`
+
+3. **Red→Green: Rename `onToolEnd` to `onToolDone` and remove counter.**
+   Update `agent-activity-tracker.test.ts`: remove `onToolEnd` counter tests, add `onToolDone` tests (active-tool removal only, no `toolUses` assertion).
+   Implement: rename method, remove `_toolUses++`.
+   Update `ui-observer.ts` to call `onToolDone`.
+   Update `ui-observer.test.ts` expectations.
+   Commit: `refactor: rename AgentActivityTracker.onToolEnd to onToolDone (#144)`
+
+4. **Red→Green: Remove `_toolUses` and `_lifetimeUsage` from tracker.**
+   Update `agent-activity-tracker.test.ts`: remove `toolUses` getter, `lifetimeUsage` getter, and `onUsageUpdate` test blocks.
+   Implement: remove `_toolUses`, `_lifetimeUsage`, `toolUses` getter, `lifetimeUsage` getter, `onUsageUpdate` method, `UsageDelta` type, `addUsage` import.
+   Update `ui-observer.ts`: remove `message_end` usage accumulation block.
+   Update `ui-observer.test.ts`: remove `message_end` usage tests.
+   Run `pnpm run check` to catch any remaining references.
+   Commit: `refactor: remove duplicate stats from AgentActivityTracker (#144)`
+
+5. **Green→Green: Migrate UI consumers to read stats from `AgentRecord`.**
+   Update `agent-widget.ts`: replace `bg?.toolUses ?? a.toolUses` → `a.toolUses`, `bg?.lifetimeUsage` → `a.lifetimeUsage`, `bg?.session` → `a.session`.
+   Update `conversation-viewer.ts`: replace `activity?.toolUses ?? record.toolUses` → `record.toolUses`, `activity?.lifetimeUsage` → `record.lifetimeUsage`, `activity?.session` → `record.session`.
+   Update `foreground-runner.ts`: read stats from record instead of tracker for final result.
+   Capture `recordRef` for streaming phase.
+   Update `conversation-viewer.test.ts` if any tests mock activity stats.
+   Commit: `refactor: read stats from AgentRecord in UI consumers (#144)`
+
+6. **Red→Green: Replace `NotificationDeps` with plain parameters.**
+   Update `notification.test.ts`: change `makeDeps()` → individual parameters in `NotificationManager` constructor calls.
+   Implement: remove `NotificationDeps` interface, change constructor to plain parameters, replace `this.deps.*` with `this.*`.
+   Update `index.ts`: change `NotificationManager` construction to pass individual arguments.
+   Commit: `refactor: dissolve NotificationDeps into plain constructor parameters (#144)`
+
+## Risks and Mitigations
+
+| Risk                                                                                              | Mitigation                                                                                                                                                                                                                                                  |
+| ------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Foreground streaming reads stale `recordRef` before `onSessionCreated` fires                      | Before `onSessionCreated`, both tracker and record have zero stats — behavior is unchanged.  Capture `recordRef` as `undefined` initially and guard with `??`.                                                                                              |
+| Widget reads `a.toolUses` but `a` is the snapshot from `listAgents()` — might be stale            | `listAgents()` returns live `AgentRecord` references (not copies), so `a.toolUses` reflects the latest record-observer increment.                                                                                                                           |
+| Removing `lifetimeUsage` from tracker breaks `formatLifetimeTokens(fgState)` in foreground runner | Step 5 explicitly migrates this callsite to `formatLifetimeTokens(record)`.  The TDD order places the removal (step 4) before the migration (step 5), but step 4's `pnpm run check` will catch the type error and both steps can be merged if needed.       |
+| `buildDetails` in `helpers.ts` accepts an `activity` parameter for `turnCount`/`maxTurns`         | `turnCount` and `maxTurns` remain on the tracker — only `toolUses` and `lifetimeUsage` are removed.  `buildDetails` reads `record.toolUses` and `record.lifetimeUsage` already; it reads `activity?.turnCount` and `activity?.maxTurns` which remain valid. |
+
+## Open Questions
+
+- None — the architecture doc prescribes the exact changes and the design is straightforward.

package/docs/retro/0145-decompose-execute-push-ctx-to-boundary.md

@@ -0,0 +1,56 @@
+---
+issue: 145
+issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
+---
+
+# Retro: #145 — Decompose execute and push ExtensionContext to the boundary
+
+## Final Retrospective (2026-05-23)
+
+### Session summary
+
+Extracted config resolution into a pure `resolveSpawnConfig` function, injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` to eliminate `ctx` reads from `execute`, pushed `ParentSnapshot` to `AgentManager`'s public API, and dissolved three small dependency bags (`ForegroundDeps`, `BackgroundDeps`, `AdapterDeps`) into plain parameters.
+Released as `pi-subagents-v6.15.0`.
+
+### Observations
+
+#### What went well
+
+- User's two escalating questions ("Are there any other missing collaborators?"
+  → "Hiding dependencies in an object bag still counts as dependencies!") caught a `premature-convergence` before it landed as committed code.
+  The reverted partial step 3 attempt was ~4 files of changes that would have needed rework.
+  The resulting design (injected collaborators) is meaningfully better than the original plan's mechanical relocation.
+- Folding tightly-coupled TDD steps (ctx elimination + params shrinking + deps dissolution) into fewer commits avoided intermediate states with broken types.
+  The plan's 12-step sequence would have required lift-and-shift gymnastics; the actual 7-commit sequence was cleaner.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — the original plan relocated `buildParentSnapshot` calls to `execute` without questioning whether `execute` should read `ctx` at all.
+  The existing `code-design` skill has DIP and parameter-relay rules that should have flagged this.
+  The `service-adapter.ts` module already demonstrated the getter-injection pattern (`getCtx`, `getModelRegistry`), but I didn't search for it during plan writing.
+  Impact: one plan rewrite commit (76bb57b), one reverted partial implementation (~15 minutes of rework).
+  User-caught.
+
+- `missing-context` — didn't use `colgrep` during initial plan writing to discover the established getter-injection convention in `service-adapter.ts`.
+  Used `grep` exclusively for exact symbol matching.
+  When prompted by the user to use `colgrep`, the results were confirmatory rather than revelatory because I'd already read the relevant files by that point.
+  The miss was not using it *earlier* for intent-based exploration ("how do existing modules inject session-scoped state?").
+  Impact: added friction but no rework — the user's questions surfaced the pattern before code was committed.
+  User-caught.
+
+- `instruction-violation` — wrote an inline `import()` type assertion (`session.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext`) in `service-adapter.ts`.
+  AGENTS.md says "Use standard top-level imports only."
+  Impact: one extra edit round, caught before committing.
+  User-caught.
+
+#### What caused friction (user side)
+
+- The user's redirecting questions were well-timed and effective.
+  The escalation from "Are there any other missing collaborators?"
+  to the more pointed "Hiding dependencies in an object bag still counts as dependencies!"
+  was the right amount of pressure.
+  No friction observed on the user side.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added `colgrep` skill loading to the "Load skills" section for code-change plans, so convention discovery happens during exploration rather than after committing to a design.

package/package.json

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

package/src/agent-manager.ts

@@ -350,7 +350,7 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
-    const session = record?.execution?.session;
+    const session = record?.session;
     if (!session) return undefined;
 
     record.resetForResume(Date.now());
@@ -402,7 +402,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.execution?.session?.dispose?.();
+    record.session?.dispose?.();
     this.agents.delete(id);
     this.pendingSteers.delete(id);
   }
@@ -480,7 +480,7 @@ export class AgentManager {
     // Clear queue
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.execution?.session?.dispose();
+      record.session?.dispose();
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)

package/src/agent-record.ts

@@ -12,6 +12,7 @@
  * after construction as lifecycle information becomes available.
  */
 
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { ExecutionState } from "./execution-state.js";
 import type { NotificationState } from "./notification-state.js";
 import type { AgentInvocation, SubagentType } from "./types.js";
@@ -85,6 +86,16 @@ export class AgentRecord {
 	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
+	/** The active agent session, or undefined before the session is created. */
+	get session(): AgentSession | undefined {
+		return this.execution?.session;
+	}
+
+	/** Path to the agent's session JSONL file, or undefined if not yet available. */
+	get outputFile(): string | undefined {
+		return this.execution?.outputFile;
+	}
+
 	constructor(init: AgentRecordInit) {
 		this.id = init.id;
 		this.type = init.type;

package/src/index.ts

@@ -62,12 +62,12 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = new NotificationManager({
-    sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
-    agentActivity: runtime.agentActivity,
-    markFinished: (id) => runtime.markFinished(id),
-    updateWidget: () => runtime.updateWidget(),
-  });
+  const notifications = new NotificationManager(
+    (msg, opts) => pi.sendMessage(msg, opts),
+    runtime.agentActivity,
+    (id) => runtime.markFinished(id),
+    () => runtime.updateWidget(),
+  );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
   // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).

package/src/notification.ts

@@ -46,7 +46,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.execution?.session);
+  const contextPercent = getSessionContextPercent(record.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
@@ -57,7 +57,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
     : "No output.";
 
   const toolCallId = record.notification?.toolCallId;
-  const outputFile = record.execution?.outputFile;
+  const outputFile = record.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
@@ -90,7 +90,7 @@ export function buildNotificationDetails(
     maxTurns: activity?.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.execution?.outputFile,
+    outputFile: record.outputFile,
     error: record.error,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
@@ -124,17 +124,6 @@ export function buildEventData(record: AgentRecord) {
 
 // ---- Notification system factory ----
 
-/** Narrow deps for the notification system — only the methods it actually calls. */
-export interface NotificationDeps {
-  sendMessage: (
-    msg: { customType: string; content: string; display: boolean; details?: unknown },
-    opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
-  ) => void;
-  agentActivity: Map<string, AgentActivityTracker>;
-  markFinished: (id: string) => void;
-  updateWidget: () => void;
-}
-
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
   sendCompletion: (record: AgentRecord) => void;
@@ -147,7 +136,15 @@ const NUDGE_HOLD_MS = 200;
 export class NotificationManager implements NotificationSystem {
   private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  constructor(private deps: NotificationDeps) {}
+  constructor(
+    private sendMessage: (
+      msg: { customType: string; content: string; display: boolean; details?: unknown },
+      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => void,
+    private agentActivity: Map<string, AgentActivityTracker>,
+    private markFinished: (id: string) => void,
+    private updateWidget: () => void,
+  ) {}
 
   cancelNudge(key: string): void {
     const timer = this.pendingNudges.get(key);
@@ -158,16 +155,16 @@ export class NotificationManager implements NotificationSystem {
   }
 
   sendCompletion(record: AgentRecord): void {
-    this.deps.agentActivity.delete(record.id);
-    this.deps.markFinished(record.id);
+    this.agentActivity.delete(record.id);
+    this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
-    this.deps.updateWidget();
+    this.updateWidget();
   }
 
   cleanupCompleted(id: string): void {
-    this.deps.agentActivity.delete(id);
-    this.deps.markFinished(id);
-    this.deps.updateWidget();
+    this.agentActivity.delete(id);
+    this.markFinished(id);
+    this.updateWidget();
   }
 
   dispose(): void {
@@ -194,15 +191,15 @@ export class NotificationManager implements NotificationSystem {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
-    const outputFile = record.execution?.outputFile;
+    const outputFile = record.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    this.deps.sendMessage(
+    this.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );

package/src/service-adapter.ts

@@ -88,7 +88,7 @@ export function createSubagentsService(
       if (!record || record.status !== "running") {
         return false;
       }
-      const session = record.execution?.session;
+      const session = record.session;
       if (!session) {
         // Session not ready yet — queue via manager for delivery once initialized
         return manager.queueSteer(id, message);

package/src/tools/agent-tool.ts

@@ -312,7 +312,7 @@ Guidelines:
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
           );
         }
-        if (!existing.execution?.session) {
+        if (!existing.session) {
           return textResult(
             `Agent "${params.resume}" has no active session to resume.`,
           );

package/src/tools/background-spawner.ts

@@ -79,7 +79,7 @@ export function spawnBackground(
       `Agent ID: ${id}\n` +
       `Type: ${config.displayName}\n` +
       `Description: ${config.description}\n` +
-      (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
+      (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
         ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
         : "") +

package/src/tools/foreground-runner.ts

@@ -63,12 +63,14 @@ export async function runForeground(
 
   const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
+  let recordRef: AgentRecord | undefined;
 
   const streamUpdate = () => {
+    const toolUses = recordRef?.toolUses ?? 0;
     const details: AgentDetails = {
       ...config.detailBase,
-      toolUses: fgState.toolUses,
-      tokens: formatLifetimeTokens(fgState),
+      toolUses,
+      tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
       turnCount: fgState.turnCount,
       maxTurns: fgState.maxTurns,
       durationMs: Date.now() - startedAt,
@@ -77,7 +79,7 @@ export async function runForeground(
       spinnerFrame: spinnerFrame % SPINNER.length,
     };
     onUpdate?.({
-      content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
+      content: [{ type: "text", text: `${toolUses} tool uses...` }],
       details: details as any,
     });
   };
@@ -110,6 +112,7 @@ export async function runForeground(
         parentSessionId: params.parentSessionId,
         onSessionCreated: (session, record) => {
           fgState.setSession(session);
+          recordRef = record;
           unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
           fgId = record.id;
           agentActivity.set(record.id, fgState);
@@ -132,7 +135,7 @@ export async function runForeground(
     widget.markFinished(fgId);
   }
 
-  const tokenText = formatLifetimeTokens(fgState);
+  const tokenText = formatLifetimeTokens(record);
   const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
 
   const fallbackNote = config.fellBack

package/src/tools/get-result-tool.ts

@@ -65,7 +65,7 @@ export function createGetResultTool(deps: GetResultDeps) {
       const displayName = getDisplayName(record.type, deps.registry);
       const duration = formatDuration(record.startedAt, record.completedAt);
       const tokens = formatLifetimeTokens(record);
-      const contextPercent = getSessionContextPercent(record.execution?.session);
+      const contextPercent = getSessionContextPercent(record.session);
       const statsParts = [`Tool uses: ${record.toolUses}`];
       if (tokens) statsParts.push(tokens);
       if (contextPercent !== null) statsParts.push(`Context: ${Math.round(contextPercent)}%`);
@@ -92,8 +92,8 @@ export function createGetResultTool(deps: GetResultDeps) {
       }
 
       // Verbose: include full conversation
-      if (params.verbose && record.execution?.session) {
-        const conversation = deps.getConversation(record.execution.session);
+      if (params.verbose && record.session) {
+        const conversation = deps.getConversation(record.session);
         if (conversation) {
           output += `\n\n--- Agent Conversation ---\n${conversation}`;
         }

package/src/tools/steer-tool.ts

@@ -49,7 +49,7 @@ export function createSteerTool(deps: SteerToolDeps) {
           `Agent "${params.agent_id}" is not running (status: ${record.status}). Cannot steer a non-running agent.`,
         );
       }
-      const session = record.execution?.session;
+      const session = record.session;
       if (!session) {
         // Session not ready yet — queue via manager for delivery once initialized
         deps.queueSteer(record.id, params.message);

package/src/ui/agent-activity-tracker.ts

@@ -5,24 +5,15 @@
  * in `ui-observer.ts`. Callers use named transition methods; readers use read-only accessors.
  */
 
-import { addUsage, type LifetimeUsage, type SessionLike } from "../usage.js";
-
-/** Usage delta accepted by onUsageUpdate — matches the LifetimeUsage accumulator shape. */
-export interface UsageDelta {
-	input: number;
-	output: number;
-	cacheWrite: number;
-}
+import type { SessionLike } from "../usage.js";
 
 /** Per-agent live activity state with explicit transition methods and read-only accessors. */
 export class AgentActivityTracker {
 	private _activeTools = new Map<string, string>();
 	private _toolKeySeq = 0;
-	private _toolUses = 0;
 	private _responseText = "";
 	private _session: SessionLike | undefined = undefined;
 	private _turnCount = 1;
-	private _lifetimeUsage: LifetimeUsage = { input: 0, output: 0, cacheWrite: 0 };
 
 	constructor(private readonly _maxTurns?: number) {}
 
@@ -33,12 +24,11 @@ export class AgentActivityTracker {
 		this._activeTools.set(toolName + "_" + (++this._toolKeySeq), toolName);
 	}
 
-	/** Record that a tool has finished executing; increments toolUses. No-op when no matching tool is active. */
-	onToolEnd(toolName: string): void {
+	/** Remove a tool from active tools (called when tool execution ends). No-op when no matching tool is active. */
+	onToolDone(toolName: string): void {
 		for (const [key, name] of this._activeTools) {
 			if (name === toolName) {
 				this._activeTools.delete(key);
-				this._toolUses++;
 				break;
 			}
 		}
@@ -59,11 +49,6 @@ export class AgentActivityTracker {
 		this._turnCount++;
 	}
 
-	/** Accumulate a usage delta into the lifetime usage totals. */
-	onUsageUpdate(delta: UsageDelta): void {
-		addUsage(this._lifetimeUsage, delta);
-	}
-
 	/** Bind the session reference (called once when the agent session is created). */
 	setSession(session: SessionLike): void {
 		this._session = session;
@@ -76,11 +61,6 @@ export class AgentActivityTracker {
 		return this._activeTools;
 	}
 
-	/** Total completed tool invocations. */
-	get toolUses(): number {
-		return this._toolUses;
-	}
-
 	/** The agent's latest partial response text (reset at each message start). */
 	get responseText(): string {
 		return this._responseText;
@@ -101,8 +81,4 @@ export class AgentActivityTracker {
 		return this._maxTurns;
 	}
 
-	/** Accumulated lifetime token usage (survives compaction). */
-	get lifetimeUsage(): Readonly<LifetimeUsage> {
-		return this._lifetimeUsage;
-	}
 }

package/src/ui/agent-menu.ts

@@ -207,7 +207,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function viewAgentConversation(ctx: ExtensionContext, record: AgentRecord) {
-    const session = record.execution?.session;
+    const session = record.session;
     if (!session) {
       ctx.ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,

package/src/ui/agent-widget.ts

@@ -191,14 +191,13 @@ export class AgentWidget {
       const elapsed = formatMs(Date.now() - a.startedAt);
 
       const bg = this.agentActivity.get(a.id);
-      const toolUses = bg?.toolUses ?? a.toolUses;
-      const tokens = getLifetimeTotal(bg?.lifetimeUsage);
-      const contextPercent = getSessionContextPercent(bg?.session);
+      const tokens = getLifetimeTotal(a.lifetimeUsage);
+      const contextPercent = getSessionContextPercent(a.session);
       const tokenText = tokens > 0 ? formatSessionTokens(tokens, contextPercent, theme, a.compactionCount) : "";
 
       const parts: string[] = [];
       if (bg) parts.push(formatTurns(bg.turnCount, bg.maxTurns));
-      if (toolUses > 0) parts.push(`${toolUses} tool use${toolUses === 1 ? "" : "s"}`);
+      if (a.toolUses > 0) parts.push(`${a.toolUses} tool use${a.toolUses === 1 ? "" : "s"}`);
       if (tokenText) parts.push(tokenText);
       parts.push(elapsed);
       const statsText = parts.join(" · ");

package/src/ui/conversation-viewer.ts

@@ -155,11 +155,11 @@ export class ConversationViewer implements Component {
     const duration = formatDuration(this.record.startedAt, this.record.completedAt);
 
     const headerParts: string[] = [duration];
-    const toolUses = this.activity?.toolUses ?? this.record.toolUses;
+    const toolUses = this.record.toolUses;
     if (toolUses > 0) headerParts.unshift(`${toolUses} tool${toolUses === 1 ? "" : "s"}`);
-    const tokens = getLifetimeTotal(this.activity?.lifetimeUsage);
+    const tokens = getLifetimeTotal(this.record.lifetimeUsage);
     if (tokens > 0) {
-      const percent = getSessionContextPercent(this.activity?.session);
+      const percent = getSessionContextPercent(this.record.session);
       headerParts.push(formatSessionTokens(tokens, percent, th, this.record.compactionCount));
     }
 

package/src/ui/ui-observer.ts

@@ -40,7 +40,7 @@ export function subscribeUIObserver(
 		}
 
 		if (event.type === "tool_execution_end") {
-			tracker.onToolEnd(event.toolName);
+			tracker.onToolDone(event.toolName);
 			onUpdate?.();
 		}
 
@@ -61,16 +61,5 @@ export function subscribeUIObserver(
 			onUpdate?.();
 		}
 
-		if (event.type === "message_end" && event.message?.role === "assistant") {
-			const u = event.message.usage;
-			if (u) {
-				tracker.onUsageUpdate({
-					input: u.input ?? 0,
-					output: u.output ?? 0,
-					cacheWrite: u.cacheWrite ?? 0,
-				});
-				onUpdate?.();
-			}
-		}
 	});
 }