@gotgenes/pi-subagents 7.2.0 → 7.2.2

package/CHANGELOG.md

@@ -5,6 +5,33 @@ 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).
 
+## [7.2.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.1...pi-subagents-v7.2.2) (2026-05-25)
+
+
+### Bug Fixes
+
+* remove unused AgentSession import and over-annotated mock return type in get-result-tool ([c3bc590](https://github.com/gotgenes/pi-packages/commit/c3bc59015e766d961422f4a7ecd23643c4cabefd))
+
+
+### Documentation
+
+* mark [#195](https://github.com/gotgenes/pi-packages/issues/195) tool factory conversions complete in architecture roadmap ([cb5562b](https://github.com/gotgenes/pi-packages/commit/cb5562b57ef613ab0c1e136c9d9712c71e831bcd))
+* plan convert tool factories to classes ([#195](https://github.com/gotgenes/pi-packages/issues/195)) ([ec916c2](https://github.com/gotgenes/pi-packages/commit/ec916c22a9d5f3453fba5784e3d2f5ecdc68740d))
+* **retro:** add planning stage notes for issue [#195](https://github.com/gotgenes/pi-packages/issues/195) ([2ca0c96](https://github.com/gotgenes/pi-packages/commit/2ca0c964f8e73b0b0247daf9834986a9344be060))
+* **retro:** add retro notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([d7d973f](https://github.com/gotgenes/pi-packages/commit/d7d973f88ca48cf1a19b24bd396ef15a606a98bc))
+* **retro:** add TDD stage notes for issue [#195](https://github.com/gotgenes/pi-packages/issues/195) ([921b1f8](https://github.com/gotgenes/pi-packages/commit/921b1f8e500baf9b2fffeb140336d4561bdaebf1))
+
+## [7.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.0...pi-subagents-v7.2.1) (2026-05-25)
+
+
+### Documentation
+
+* mark Layer 2 done and update health metrics in architecture doc ([ad00426](https://github.com/gotgenes/pi-packages/commit/ad00426f0f29ceff0915033419fdc2f1b53755b0))
+* plan align tool interfaces for structural typing ([#194](https://github.com/gotgenes/pi-packages/issues/194)) ([36e56b0](https://github.com/gotgenes/pi-packages/commit/36e56b08351893e3c2d63569e7cfa140c172e20b))
+* **retro:** add planning stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([63a5763](https://github.com/gotgenes/pi-packages/commit/63a5763ed2bf4c2a6e2e9a19fdcdce71a2a9905a))
+* **retro:** add retro notes for issue [#193](https://github.com/gotgenes/pi-packages/issues/193) ([8987f90](https://github.com/gotgenes/pi-packages/commit/8987f907e00bb70429782c947a2afbdb1db5faa9))
+* **retro:** add TDD stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([f692323](https://github.com/gotgenes/pi-packages/commit/f69232395882c07d6d95273e08021b94800f0e43))
+
 ## [7.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.1.0...pi-subagents-v7.2.0) (2026-05-25)
 
 

package/docs/architecture/architecture.md

@@ -457,7 +457,7 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
 | `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
 | `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                                      | agent-tool                                        | Low      |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | ✓ done   |
 | `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
 | `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
 | `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
@@ -608,16 +608,16 @@ The approach is layered: each step makes the next step trivial.
 
 ### Findings
 
-| Metric                    | Value                                   |
-| ------------------------- | --------------------------------------- |
-| Health score              | 75/100 (B)                              |
-| #1 hotspot                | `index.ts` (128 commits, accelerating)  |
-| Dead exports              | 1 (`getToolCallName` re-export)         |
-| Production duplication    | 0                                       |
-| Test duplication          | 1,396 lines (69 clone groups, 22 files) |
-| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)     |
-| Adapter closures in index | 41 (down from 44; Layer 1 resolved 3)   |
-| Index fan-out             | 25 imports                              |
+| Metric                    | Value                                      |
+| ------------------------- | ------------------------------------------ |
+| Health score              | 75/100 (B)                                 |
+| #1 hotspot                | `index.ts` (128 commits, accelerating)     |
+| Dead exports              | 0 (down from 1; Layer 2 removed re-export) |
+| Production duplication    | 0                                          |
+| Test duplication          | 1,396 lines (69 clone groups, 22 files)    |
+| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)        |
+| Adapter closures in index | 40 (down from 44; Layers 1–2 resolved 4)   |
+| Index fan-out             | 25 imports                                 |
 
 ### Root cause
 
@@ -628,8 +628,10 @@ The real objects can't satisfy the interfaces because:
    Resolved by Layer 0 (#192) + Layer 1 (#193).
 2. ~~Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.~~
    Resolved by Layer 1 (#193).
-3. `AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).
-4. `AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).
+3. ~~`AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).~~
+   Resolved by Layer 2 (#194).
+4. ~~`AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).~~
+   Resolved by Layer 2 (#194).
 
 Fix these structural misalignments and the class conversions become mechanical.
 
@@ -668,7 +670,7 @@ Add typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessio
 - Outcome: 3 closure queries in index.ts → 0; `SubagentRuntime` is self-sufficient for tool deps
 - Enables: Layer 3 (tools accept `SubagentRuntime` directly)
 
-### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194])
+### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194]) ✓ done
 
 Three alignment changes:
 
@@ -681,18 +683,18 @@ After this step, `AgentManager` structurally satisfies `AgentToolManager` and `S
 
 - Target: `src/tools/agent-tool.ts` (interface), `src/runtime.ts` (method names), `src/ui/message-formatters.ts`
 - Smell: Category C (source mismatch, name mismatch) + Category A (dead export)
-- Outcome: structural typing connects real objects to tool interfaces without adapters
+- Outcome: structural typing connects real objects to tool interfaces without adapters; 0 dead exports (fallow clean)
 - Enables: Layer 3 (class constructors accept real objects directly)
 
 ### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])
 
-With Layers 0–2 complete, each factory is a mechanical conversion:
+With Layers 0–2 complete, each factory is a mechanical conversion. ✓ Tool factories converted in [#195][195]:
 
 | Factory                          | Class                          | Constructor params                                  |
 | -------------------------------- | ------------------------------ | --------------------------------------------------- |
-| `createAgentTool({...})`         | `AgentTool`                    | `manager`, `runtime`, `settings`, `registry`        |
-| `createGetResultTool(...)`       | `GetResultTool`                | `manager`, `notifications`, `registry`              |
-| `createSteerTool(...)`           | `SteerTool`                    | `manager`, `events`                                 |
+| `createAgentTool({...})`         | `AgentTool` ✓                  | `manager`, `runtime`, `settings`, `registry`        |
+| `createGetResultTool(...)`       | `GetResultTool` ✓              | `manager`, `notifications`, `registry`              |
+| `createSteerTool(...)`           | `SteerTool` ✓                  | `manager`, `events`                                 |
 | `createAgentRunner(runnerIO)`    | `AgentRunner` (concrete class) | `io: RunnerIO`                                      |
 | `createAgentsMenuHandler({...})` | `AgentsMenuHandler`            | `manager`, `registry`, `settings`, `fileOps`, paths |
 

package/docs/plans/0194-align-tool-interfaces-for-structural-typing.md

@@ -0,0 +1,139 @@
+---
+issue: 194
+issue_title: "Align tool interfaces for structural typing"
+---
+
+# Align tool interfaces for structural typing
+
+## Problem Statement
+
+The narrow interfaces that tool factories accept don't structurally match the real objects (`AgentManager`, `SubagentRuntime`, `SettingsManager`).
+This forces `index.ts` to build adapter closures bridging the gap — each a one-liner that exists only because names or ownership don't align.
+Three specific mismatches prevent structural typing from connecting real objects to tool interfaces directly.
+
+## Goals
+
+- Remove `getMaxConcurrent()` from `AgentToolManager` — it belongs on the settings accessor.
+- Rename `SubagentRuntime.updateWidget()` → `update()` so `SubagentRuntime` structurally satisfies `AgentToolWidget`.
+- Remove the dead `getToolCallName` re-export from `ui/message-formatters.ts`.
+- After these changes, `AgentManager` structurally satisfies `AgentToolManager` and `SubagentRuntime` structurally satisfies `AgentToolWidget` — no adapter closures needed in `index.ts`.
+
+## Non-Goals
+
+- Converting tool factories to classes (that's #195).
+- Simplifying `index.ts` wiring (that's #195/#196, after this layer).
+- Changing `NotificationManager`'s constructor parameter name (`updateWidget` callback) — it's a positional callback, not a structural interface member.
+
+## Background
+
+This is Phase 11, Layer 2 in `docs/architecture/architecture.md`.
+Layer 0 (#192, done) and Layer 1 (#193, done) established the typed `SessionContext` and moved context queries onto `SubagentRuntime`.
+Layer 2 (this issue) aligns the remaining structural mismatches.
+Layer 3 (#195) depends on this layer.
+
+Relevant modules:
+
+- `src/tools/agent-tool.ts` — defines `AgentToolManager` and `AgentToolWidget` interfaces.
+- `src/tools/background-spawner.ts` — defines `BackgroundManagerDeps` with `getMaxConcurrent()`.
+- `src/runtime.ts` — defines `SubagentRuntime` class with `updateWidget()` delegation method.
+- `src/ui/message-formatters.ts` — has the dead `getToolCallName` re-export.
+- `src/index.ts` — composition root that builds adapter closures.
+- `src/settings.ts` — `SettingsManager` owns `maxConcurrent`.
+
+## Design Overview
+
+### 1. Move `getMaxConcurrent` off manager interfaces → settings
+
+The `BackgroundManagerDeps` and `AgentToolManager` interfaces both declare `getMaxConcurrent(): number`.
+In reality, the value comes from `SettingsManager.maxConcurrent`.
+The fix:
+
+- Remove `getMaxConcurrent` from `AgentToolManager`.
+- Remove `getMaxConcurrent` from `BackgroundManagerDeps`.
+- Widen `AgentToolDeps.settings` from `{ readonly defaultMaxTurns: number | undefined }` to also include `readonly maxConcurrent: number`.
+- Pass `settings` (or a narrow settings interface) to `spawnBackground` so it can read `maxConcurrent` directly.
+- `SettingsManager` already exposes a `get maxConcurrent(): number` property, so it structurally satisfies the widened interface.
+
+After this, `AgentManager` (which has `spawn`, `spawnAndWait`, `resume`, `getRecord` but NOT `getMaxConcurrent`) structurally satisfies `AgentToolManager`.
+
+### 2. Rename `SubagentRuntime.updateWidget()` → `update()`
+
+The `AgentToolWidget` interface declares `update(): void`.
+`SubagentRuntime` has `updateWidget(): void` which delegates to `this.widget?.update()`.
+Renaming the delegation method to `update()` makes `SubagentRuntime` structurally satisfy `AgentToolWidget` (it already has `setUICtx`, `ensureTimer`, and `markFinished`).
+
+Callers of `runtime.updateWidget()`:
+
+- `src/index.ts` line 70: `() => runtime.updateWidget()` → `() => runtime.update()`
+- `src/index.ts` line 199: `update: () => runtime.updateWidget()` → can now pass `runtime` directly (but that's a #195 concern — for now just rename the call).
+
+The `WidgetLike` interface in `runtime.ts` already uses `update()` — no conflict.
+
+### 3. Remove dead re-export
+
+`src/ui/message-formatters.ts` line 24 exports `getToolCallName` from `#src/session/content-items`.
+No consumer imports `getToolCallName` from `message-formatters` — all uses go directly to `content-items.ts`.
+Delete the re-export line.
+
+### After all three changes
+
+```typescript
+// AgentToolManager (after removing getMaxConcurrent):
+interface AgentToolManager {
+  spawn(...): string;
+  spawnAndWait(...): Promise<AgentRecord>;
+  resume(...): Promise<AgentRecord | undefined>;
+  getRecord(id: string): AgentRecord | undefined;
+}
+// AgentManager has all four methods → structural match ✓
+
+// AgentToolWidget (unchanged):
+interface AgentToolWidget {
+  setUICtx(ctx: unknown): void;
+  ensureTimer(): void;
+  update(): void;
+  markFinished(id: string): void;
+}
+// SubagentRuntime has all four methods (after rename) → structural match ✓
+```
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                                                                                                            |
+| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/agent-tool.ts`               | Remove `getMaxConcurrent` from `AgentToolManager`. Widen `settings` type in `AgentToolDeps` to include `readonly maxConcurrent: number`.                                                                                          |
+| `src/tools/background-spawner.ts`       | Remove `getMaxConcurrent` from `BackgroundManagerDeps`. Add a `settings: { readonly maxConcurrent: number }` parameter (or add to `BackgroundParams`). Read `settings.maxConcurrent` instead of `manager.getMaxConcurrent()`.     |
+| `src/runtime.ts`                        | Rename `updateWidget()` → `update()`.                                                                                                                                                                                             |
+| `src/ui/message-formatters.ts`          | Remove the `export { getToolCallName } from ...` line.                                                                                                                                                                            |
+| `src/index.ts`                          | Update `runtime.updateWidget()` → `runtime.update()` at both call sites. Remove `getMaxConcurrent` from the `manager` adapter object passed to `createAgentTool`. Pass `settings` through to `spawnBackground` via the tool deps. |
+| `test/tools/background-spawner.test.ts` | Remove `getMaxConcurrent` from mock manager objects. Add `settings` mock with `maxConcurrent`.                                                                                                                                    |
+| `test/runtime.test.ts`                  | Rename `updateWidget` → `update` in test descriptions and call sites.                                                                                                                                                             |
+| `docs/architecture/architecture.md`     | Update Layer 2 status and health metrics (adapter closures count, dead exports count).                                                                                                                                            |
+
+## Test Impact Analysis
+
+1. No new unit tests are strictly needed — this is interface alignment, not new behavior.
+2. `test/tools/background-spawner.test.ts` needs mock shape updates (remove `getMaxConcurrent` from manager mock, add settings mock).
+3. `test/runtime.test.ts` needs the method name updated from `updateWidget` to `update`.
+4. Existing tests for `agent-tool`, `notification`, and `message-formatters` remain as-is (no behavior change).
+
+## TDD Order
+
+1. `refactor:` Rename `SubagentRuntime.updateWidget()` → `update()` — update `runtime.ts`, `test/runtime.test.ts`, and both call sites in `index.ts`.
+   Run `pnpm run check` to verify no type errors remain.
+2. `refactor:` Move `getMaxConcurrent` off manager interfaces — remove from `AgentToolManager` and `BackgroundManagerDeps`, widen `AgentToolDeps.settings`, add settings parameter to `spawnBackground`, update `index.ts` call site and `test/tools/background-spawner.test.ts`.
+   Run `pnpm run check`.
+3. `refactor:` Remove dead `getToolCallName` re-export from `ui/message-formatters.ts`.
+4. `docs:` Update architecture doc — mark Layer 2 as done, update health metrics (dead exports: 0, adapter closures reduced).
+
+## Risks and Mitigations
+
+| Risk                                                                                                 | Mitigation                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `update()` is a generic name on `SubagentRuntime` — could confuse readers about what's being updated | The method is a documented widget delegation like its siblings (`markFinished`, `ensureTimer`); the JSDoc comment clarifies it delegates to `widget.update()`. |
+| `background-spawner` signature change could break other callers                                      | Grep confirms only `agent-tool.ts` calls `spawnBackground` — no other consumers.                                                                               |
+| Renaming method in runtime could miss a call site                                                    | Grep and `pnpm run check` after each step catch all references.                                                                                                |
+
+## Open Questions
+
+None — the issue's proposed direction is unambiguous and the architecture doc confirms the design.

package/docs/plans/0195-convert-tool-factories-to-classes.md

@@ -0,0 +1,264 @@
+---
+issue: 195
+issue_title: "Convert tool factories to classes"
+---
+
+# Convert tool factories to classes
+
+## Problem Statement
+
+`createAgentTool`, `createGetResultTool`, and `createSteerTool` are closure factories that capture dependencies and return tool definitions.
+This pattern hides dependencies in closures, forces `index.ts` to build narrow adapter objects at each call site, and prevents direct structural typing between real objects and tool interfaces.
+With #193 (runtime owns queries) and #194 (interfaces aligned) both complete, the conversions are mechanical.
+
+## Goals
+
+- Convert all three tool factories to classes with constructor-injected dependencies.
+- Each class exposes a `toToolDefinition()` method that wraps the tool with `defineTool()`.
+- `index.ts` passes real objects directly — no adapter closures for tool wiring.
+- Eliminate 16+ adapter closures from `index.ts`.
+
+## Non-Goals
+
+- Converting `createAgentRunner` or `createAgentsMenuHandler` — those belong to #196.
+- Simplifying `index.ts` beyond tool wiring — that's #196 Layer 4.
+- Changing tool behavior or parameters — this is a purely structural refactoring.
+
+## Background
+
+### Dependencies (both closed)
+
+- Issue #193 moved context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) onto `SubagentRuntime`.
+- Issue #194 aligned tool interfaces so `AgentManager` and `SubagentRuntime` structurally satisfy the narrow tool interfaces without adapters.
+
+### Existing module layout
+
+The three factory functions live in:
+
+- `src/tools/agent-tool.ts` — `createAgentTool(deps: AgentToolDeps)`
+- `src/tools/get-result-tool.ts` — `createGetResultTool(getRecord, cancelNudge, getConversation, registry)`
+- `src/tools/steer-tool.ts` — `createSteerTool(getRecord, emitEvent, steerAgent, queueSteer)`
+
+Each returns a plain object with `name`, `label`, `description`, `parameters`, `execute`, and optional render methods.
+`index.ts` wraps each in `defineTool()` at registration time.
+
+### Architecture doc reference
+
+Phase 11, Layer 3 in `docs/architecture/architecture.md` (lines 689–709).
+
+## Design Overview
+
+### Class structure
+
+Each class stores constructor-injected dependencies as instance fields and exposes:
+
+1. A `toToolDefinition()` method that calls `defineTool(this.buildToolSpec())` (or similar) — returning the Pi SDK tool registration object.
+2. Private methods that correspond to the existing function body sections.
+
+### Constructor signatures
+
+| Class           | Constructor params                                                                                                                         |
+| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
+| `AgentTool`     | `manager: AgentToolManager`, `runtime: AgentToolRuntime`, `settings: AgentToolSettings`, `registry: AgentTypeRegistry`, `agentDir: string` |
+| `GetResultTool` | `manager: GetResultToolManager`, `notifications: GetResultToolNotifications`, `registry: AgentConfigLookup`                                |
+| `SteerTool`     | `manager: SteerToolManager`, `events: SteerToolEvents`                                                                                     |
+
+### Narrow interfaces
+
+Each class defines its own narrow interface for the collaborators it uses.
+These already exist (e.g., `AgentToolManager`, `BackgroundManagerDeps`) — they stay as-is; the class uses them directly.
+
+#### `AgentTool`
+
+The existing `AgentToolDeps` interface (8 fields) collapses into 5 constructor params.
+The `widget`, `agentActivity`, `buildSnapshot`, `getModelInfo`, and `getSessionInfo` fields merge into a single `runtime` param because `SubagentRuntime` structurally satisfies all of them after #193/#194.
+
+New narrow interface for the runtime slice:
+
+```typescript
+export interface AgentToolRuntime {
+  readonly agentActivity: AgentActivityAccess;
+  setUICtx(ctx: UICtx): void;
+  ensureTimer(): void;
+  update(): void;
+  markFinished(id: string): void;
+  buildSnapshot(inheritContext: boolean): ParentSnapshot;
+  getModelInfo(): ModelInfo;
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+}
+```
+
+`SubagentRuntime` satisfies this structurally — no adapter needed in `index.ts`.
+
+#### `GetResultTool`
+
+New narrow interfaces:
+
+```typescript
+export interface GetResultToolManager {
+  getRecord(id: string): AgentRecord | undefined;
+}
+
+export interface GetResultToolNotifications {
+  cancelNudge(key: string): void;
+}
+```
+
+`getAgentConversation` is a pure function — imported directly by the class, not injected.
+
+#### `SteerTool`
+
+New narrow interfaces:
+
+```typescript
+export interface SteerToolManager {
+  getRecord(id: string): AgentRecord | undefined;
+  queueSteer(id: string, message: string): boolean;
+}
+
+export interface SteerToolEvents {
+  emit(name: string, data: unknown): void;
+}
+```
+
+`steerAgent` is a pure function — imported directly by the class, not injected.
+
+### Call site after conversion
+
+```typescript
+const agentTool = new AgentTool(manager, runtime, settings, registry, getAgentDir());
+const getResultTool = new GetResultTool(manager, notifications, registry);
+const steerTool = new SteerTool(manager, pi.events);
+pi.registerTool(agentTool.toToolDefinition());
+pi.registerTool(getResultTool.toToolDefinition());
+pi.registerTool(steerTool.toToolDefinition());
+```
+
+### Design decisions
+
+1. **`toToolDefinition()` on each class** — encapsulates the `defineTool()` call so `index.ts` doesn't import `defineTool` for each tool.
+2. **Pure functions imported directly** — `steerAgent` and `getAgentConversation` are pure utilities with no state; injecting them adds indirection without testability benefit.
+3. **`agentDir` stays a constructor param** — it's a static string computed once at startup; putting it on the registry would add scope responsibility the registry doesn't need.
+4. **Keep existing `AgentToolDeps` temporarily** — remove it in the same PR once the class replaces all usage.
+
+## Module-Level Changes
+
+### `src/tools/agent-tool.ts`
+
+- Add `AgentToolRuntime` interface (narrow runtime slice).
+- Add `AgentToolSettings` type alias (existing inline type, extracted for clarity).
+- Add `AgentTool` class with constructor storing `manager`, `runtime`, `settings`, `registry`, `agentDir`.
+- Move the existing factory body into class methods: `toToolDefinition()`, private `execute()`.
+- Remove `createAgentTool` function and `AgentToolDeps` interface.
+- Keep `AgentToolManager`, `AgentToolWidget`, `AgentActivityAccess` interfaces (still used by `background-spawner` and `foreground-runner` — though `AgentToolWidget` may be replaceable by `AgentToolRuntime`).
+
+### `src/tools/get-result-tool.ts`
+
+- Add `GetResultToolManager` and `GetResultToolNotifications` interfaces.
+- Add `GetResultTool` class with constructor.
+- Import `getAgentConversation` directly.
+- Move factory body into class method.
+- Remove `createGetResultTool` function.
+
+### `src/tools/steer-tool.ts`
+
+- Add `SteerToolManager` and `SteerToolEvents` interfaces.
+- Add `SteerTool` class with constructor.
+- Import `steerAgent` directly.
+- Move factory body into class method.
+- Remove `createSteerTool` function.
+
+### `src/tools/background-spawner.ts`
+
+- Update `BackgroundWidgetDeps` to reference `AgentToolRuntime` instead (or keep as-is since `AgentToolRuntime` is a superset).
+  Actually no change needed — `spawnBackground` already accepts narrow interfaces; the `AgentTool` class passes `this.runtime` which satisfies `BackgroundWidgetDeps` structurally.
+
+### `src/tools/foreground-runner.ts`
+
+- Same as above — no change needed.
+  The `AgentTool` class passes `this.runtime` which satisfies `ForegroundWidgetDeps` structurally.
+
+### `src/index.ts`
+
+- Remove adapter closures for all three tool registrations.
+- Replace with class construction + `toToolDefinition()` calls.
+- Remove `defineTool` import (moves into tool classes).
+- Remove unused imports that were only needed for adapter closures.
+
+### `test/tools/agent-tool.test.ts`
+
+- Replace `createToolDeps()` with class construction in test helpers.
+- Update `execute()` helper to instantiate `AgentTool` and call its execute.
+- Keep all existing test cases — behavior is unchanged.
+
+### `test/tools/get-result-tool.test.ts`
+
+- Replace positional args with class construction.
+- Update `makeDeps` and `execute` helpers.
+- Keep all existing test cases.
+
+### `test/tools/steer-tool.test.ts`
+
+- Replace positional args with class construction.
+- Update `makeDeps` and `execute` helpers.
+- Keep all existing test cases.
+
+### `test/helpers/make-deps.ts`
+
+- Update `createToolDeps` to construct `AgentTool`-compatible deps (or remove if no longer needed).
+  Likely transforms into a factory that builds mock `AgentToolRuntime`, `AgentToolManager`, etc.
+
+### `docs/architecture/architecture.md`
+
+- Update the Layer 3 table to mark #195 as done.
+- Update the file listing for `src/tools/` to reflect class names (if the listing is that detailed).
+
+## Test Impact Analysis
+
+1. **No new test surfaces** — this is a structural refactoring with identical behavior.
+   Existing tests already cover all tool paths.
+2. **Test helper changes** — `createToolDeps()` and per-tool `makeDeps()` functions need updating to use class construction instead of function calls, but the mock shapes remain the same.
+3. **All existing tests stay** — they exercise the tool execution logic which doesn't change.
+
+## TDD Order
+
+1. **Convert `SteerTool` to class** — smallest tool (fewest deps, no render methods).
+   - Update `steer-tool.ts`: add interfaces, add class, remove factory.
+   - Update `test/tools/steer-tool.test.ts`: use class construction.
+   - Verify: `pnpm vitest run test/tools/steer-tool.test.ts`
+   - Commit: `refactor: convert createSteerTool to SteerTool class (#195)`
+
+2. **Convert `GetResultTool` to class** — medium complexity (3 deps, no render methods).
+   - Update `get-result-tool.ts`: add interfaces, add class, import `getAgentConversation`, remove factory.
+   - Update `test/tools/get-result-tool.test.ts`: use class construction.
+   - Verify: `pnpm vitest run test/tools/get-result-tool.test.ts`
+   - Commit: `refactor: convert createGetResultTool to GetResultTool class (#195)`
+
+3. **Convert `AgentTool` to class** — largest (5 deps, render methods, delegates to spawner/runner).
+   - Add `AgentToolRuntime` and `AgentToolSettings` interfaces.
+   - Add `AgentTool` class.
+   - Remove `createAgentTool` and `AgentToolDeps`.
+   - Update `test/tools/agent-tool.test.ts` and `test/helpers/make-deps.ts`.
+   - Verify: `pnpm vitest run test/tools/agent-tool.test.ts`
+   - Commit: `refactor: convert createAgentTool to AgentTool class (#195)`
+
+4. **Update `index.ts`** — wire class constructors, remove adapter closures and `defineTool` import.
+   - Verify: `pnpm vitest run` (full suite) + `pnpm run check` (type-check).
+   - Commit: `refactor: wire tool classes in index.ts, remove adapter closures (#195)`
+
+5. **Update architecture doc** — mark Layer 3 (partial) as complete.
+   - Commit: `docs: mark #195 complete in architecture roadmap`
+
+## Risks and Mitigations
+
+| Risk                                                                                                      | Mitigation                                                                                    |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `background-spawner` and `foreground-runner` accept narrow interfaces that differ from `AgentToolRuntime` | `AgentToolRuntime` is a superset — pass `this.runtime` and structural typing handles it.      |
+| Test factories import `AgentToolDeps` which will be removed                                               | Step 3 updates all test imports in the same commit.                                           |
+| `defineTool` import removed from `index.ts` — must live somewhere                                         | Each class's `toToolDefinition()` imports it internally.                                      |
+| Spreading class instances in tests breaks method access                                                   | Tests will construct the class, not spread it. Step 3 uses lift-and-shift for `make-deps.ts`. |
+
+## Open Questions
+
+- Should `AgentToolWidget` interface be removed entirely (replaced by `AgentToolRuntime`)?
+  Defer to implementation — if `background-spawner` and `foreground-runner` can accept `AgentToolRuntime` directly, remove it; otherwise keep the narrow subset interfaces.

package/docs/retro/0193-runtime-owns-context-queries.md

@@ -41,3 +41,35 @@ This is cleaner than the plan's `getModelInfo(): { modelRegistry: unknown }` app
 - Biome's `noUnusedPrivateClassMembers` warning caught the leftover `private readonly pi: unknown` in `SessionLifecycleHandler`.
 Removed `pi` from the constructor entirely (rather than adding `_` prefix), which also cleaned up `index.ts`.
 - The `eslint-disable` directive at the top of `index.ts` had two now-unused entries (`no-unsafe-member-access`, `no-unsafe-call`) removed by `eslint --fix`.
+
+## Stage: Final Retrospective (2026-05-24T20:45:00Z)
+
+### Session summary
+
+All three stages (plan, TDD, ship) completed in a single session.
+Released as `pi-subagents-v7.2.0`.
+One plan contradiction required a judgment call during implementation; otherwise clean mechanical execution.
+
+### Observations
+
+#### What went well
+
+- The architecture doc's Phase 11 Layer 1 spec was precise enough that no `ask_user` was needed at any stage — the issue body, architecture doc, and #192 retro were fully aligned.
+- `ServiceRuntimeLike` ended up simpler than planned (only `currentCtx` + `buildSnapshot` instead of also requiring `getModelInfo()`) — the implementation found a cleaner design than the plan specified.
+- Test count increase (+6) validates the design: methods that were previously untestable as anonymous closures now have dedicated unit tests.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's Non-Goals section claimed `buildParentContext` would not change, contradicting Module-Level Changes item #4 which explicitly listed the file.
+  The planning stage didn't cross-check these sections before committing.
+  Impact: brief confusion during step 3 about which section to trust (resolved by following Module-Level Changes); no rework, added ~30s of deliberation.
+- `missing-context` — TypeScript's discriminated union narrowing limitation with a `{ type: string }` catch-all arm was not anticipated.
+  Impact: required adding a local `BranchEntry` union type and explicit casts in `context.ts`; no rework but ~2 min of debugging the type error.
+
+#### What caused friction (user side)
+
+- None — no user intervention was needed at any point across all three stages.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added a Non-Goals vs Module-Level Changes cross-check instruction under the Module-Level Changes bullet.

package/docs/retro/0194-align-tool-interfaces-for-structural-typing.md

@@ -0,0 +1,62 @@
+---
+issue: 194
+issue_title: "Align tool interfaces for structural typing"
+---
+
+# Retro: #194 — Align tool interfaces for structural typing
+
+## Stage: Planning (2026-05-24T12:00:00Z)
+
+### Session summary
+
+Produced an implementation plan for three targeted alignment changes: moving `getMaxConcurrent` off manager interfaces to the settings accessor, renaming `SubagentRuntime.updateWidget()` → `update()`, and removing the dead `getToolCallName` re-export.
+The plan includes a 4-step TDD order with type-check gates after each refactoring step.
+
+### Observations
+
+- Issue #193 (Layer 1) is already closed/implemented, confirming this layer can proceed immediately.
+
+## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps: renamed `SubagentRuntime.updateWidget()` → `update()`, moved `getMaxConcurrent` from manager interfaces to the `settings` narrow type, removed the dead `getToolCallName` re-export, and updated the architecture doc.
+Test count stayed flat at 854 (53 files) — all green.
+The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-deps.test.ts` that also validated `getMaxConcurrent` and the old `settings` shape; this file was updated as part of step 2.
+
+### Observations
+
+- An unexpected file `test/helpers/make-deps.test.ts` had three type errors after removing `getMaxConcurrent` (one test asserting `manager.getMaxConcurrent()`, one structural compatibility check referencing it, and one settings override that only passed `defaultMaxTurns`).
+  All three were fixed in the same commit as step 2 — no deviation from the plan.
+- Adding `settings` to `BackgroundParams` (instead of as a 5th function parameter) was the right call: it keeps `spawnBackground` at 4 arguments and groups all spawn-context values together.
+- The health metric update: dead exports 1 → 0, adapter closures 41 → 40 (only `getMaxConcurrent` was removed in this layer; the remaining 8 widget/manager adapter closures need #195 class conversion to collapse).
+- The `background-spawner.ts` module is the only consumer of `getMaxConcurrent` — grep confirms no other call sites beyond `agent-tool.ts`'s interface definition.
+- The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
+- The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
+- All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.
+
+## Stage: Final Retrospective (2026-05-24T21:15:00Z)
+
+### Session summary
+
+Planning, TDD implementation, and shipping completed in one continuous session.
+Released as `pi-subagents-v7.2.1` with zero rework or deviations from the plan.
+
+### Observations
+
+#### What went well
+
+- Clean execution end-to-end: 3 refactor commits + 1 docs commit, all planned in advance.
+- The `pnpm run check` gate after step 2 caught `test/helpers/make-deps.test.ts` — a file the plan didn't list — preventing a broken intermediate state.
+  This validates the "run type-check after each step" pattern for interface-alignment work.
+- Phased architecture approach paid off: Layers 0 and 1 being done made Layer 2 entirely mechanical.
+
+#### What caused friction (agent side)
+
+- None identified.
+  The issue scope was tight, the plan was unambiguous, and no rabbit-holes arose.
+
+#### What caused friction (user side)
+
+- None identified.
+  The issue body and architecture doc provided complete context with no ambiguity.