@gotgenes/pi-subagents 5.7.0 → 5.8.1

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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).
 
+## [5.8.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.8.0...pi-subagents-v5.8.1) (2026-05-20)
+
+
+### Documentation
+
+* plan replace as-any casts with SDK types ([#66](https://github.com/gotgenes/pi-packages/issues/66)) ([a8728bf](https://github.com/gotgenes/pi-packages/commit/a8728bf695a11f649fb908a6a31a55842b76ce32))
+* **retro:** add retro notes for issue [#70](https://github.com/gotgenes/pi-packages/issues/70) ([0668956](https://github.com/gotgenes/pi-packages/commit/0668956e99383df7a62fddde57dd4182bf491a5e))
+* **retro:** record architecture update for [#70](https://github.com/gotgenes/pi-packages/issues/70) ([49d4fae](https://github.com/gotgenes/pi-packages/commit/49d4faee4ee711e385dbf59334b0b737897d26a6))
+* update architecture roadmap with [#87](https://github.com/gotgenes/pi-packages/issues/87), [#70](https://github.com/gotgenes/pi-packages/issues/70) status ([97a2da1](https://github.com/gotgenes/pi-packages/commit/97a2da11cbd73c9f84eb2158e2437cbe8c749208))
+
+## [5.8.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.7.0...pi-subagents-v5.8.0) (2026-05-20)
+
+
+### Features
+
+* add SessionLifecycleHandler ([d8d95fa](https://github.com/gotgenes/pi-packages/commit/d8d95fa92561e0068444c3c925f21b50825a741c))
+* add ToolStartHandler ([c293e41](https://github.com/gotgenes/pi-packages/commit/c293e41e25d9742f807f85d0efe0a0e5605b29a6))
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#87](https://github.com/gotgenes/pi-packages/issues/87) ([1701fe4](https://github.com/gotgenes/pi-packages/commit/1701fe41d582d7180b2622c2e03db954e8d2c2af))
+
 ## [5.7.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.6.0...pi-subagents-v5.7.0) (2026-05-20)
 
 

package/docs/architecture/architecture.md

@@ -374,14 +374,13 @@ These build on Phase 1 and should land after it.
    - Removed all runtime imports of `agent-runner.ts` and `worktree.ts` from `agent-manager.ts` (only `import type` remains).
    - Migrated all tests from `vi.mock()` module stubs to `vi.fn()` interface stubs.
 
-3. **gotgenes/pi-packages#87** — Evolve `SubagentRuntime` from data bag to object with methods
-   - Add session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
+3. **gotgenes/pi-packages#87** ✓ — Evolve `SubagentRuntime` from data bag to object with methods
+   - Added session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
    - Prerequisite for #70 — without runtime methods, extracted handlers would move LoD violations and output-argument smells into handler classes.
 
-4. **gotgenes/pi-packages#70** — Extract event handlers into `src/handlers/`
-   - Move the four inline lambdas (`session_start`, `session_before_switch`, `session_shutdown`, `tool_execution_start`) into named handler modules.
-   - Requires Issues #69 and #87 because handlers need the `SubagentRuntime` with methods as their deps.
-   - Target: `src/index.ts` ≤150 lines.
+4. **gotgenes/pi-packages#70** ✓ — Extract event handlers into `src/handlers/`
+   - Moved the four inline lambdas (`session_start`, `session_before_switch`, `session_shutdown`, `tool_execution_start`) into `SessionLifecycleHandler` and `ToolStartHandler` classes.
+   - Handlers call methods on narrow runtime interfaces — no raw field writes, no `widget!` reach-throughs.
 
 ### Phase 3: Interface polish
 
@@ -407,7 +406,7 @@ Small cleanups that are safest after the structural changes settle.
 ### Dependency graph
 
 ```text
-#69 (SubagentRuntime) ✓ ──► #87 (runtime methods) ─┬─► #70 (handler extraction)
+#69 (SubagentRuntime) ✓ ──► #87 (runtime methods) ✓ ─┬─► #70 (handler extraction) ✓
                                                    │
 #71 (pure assembler) ✓                              │
 #80 (config lookup) ✓                               │
@@ -427,11 +426,11 @@ Small cleanups that are safest after the structural changes settle.
 The recommended sequence is:
 
 ```text
-#69 ✓ → #71 ✓ → #80 ✓ → #76 ✓ → #84 ✓ → #72 ✓ → #87 → #70 → #66 → #77 → #61
+#69 ✓ → #71 ✓ → #80 ✓ → #76 ✓ → #84 ✓ → #72 ✓ → #87 ✓ → #70 ✓ → #66 → #77 → #61
 ```
 
-Phase 1 is complete; Phase 2 is in progress.
-The next issue is #87 (runtime methods), which unblocks #70 (handler extraction).
+Phase 1 is complete; Phase 2 is complete.
+The next issue is #66 (replace `as any` casts with proper SDK types).
 Issue #22 is a parallel cross-extension track and does not gate the structural work.
 
 ## Relationship with upstream

package/docs/plans/0066-replace-as-any-with-sdk-types.md

@@ -0,0 +1,215 @@
+---
+issue: 66
+issue_title: "refactor: replace `as any` casts in extracted tool/menu factories with proper SDK types"
+---
+
+# Replace `as any` casts in factory dep interfaces with proper SDK types
+
+## Problem Statement
+
+The decomposition in #54 introduced 14 `as any` casts at the wiring boundary in `src/index.ts`.
+These exist because the factory dep interfaces (`AgentToolManager`, `GetResultDeps`, `SteerToolDeps`, `AgentMenuDeps`, `NotificationDeps`) declare `unknown` or `object` for parameters that are actually well-typed SDK exports.
+Every cast papers over a real type that the SDK already exports.
+For comparison, `pi-permission-system` imports SDK types directly in its internal interfaces and has zero `as any` casts.
+
+## Goals
+
+- Replace every `as any` cast in `src/index.ts` by typing the corresponding dep interface parameter with the actual SDK type.
+- Keep factory modules decoupled from `AgentManager` where possible — use shared types (`types.ts`) or SDK imports.
+- No runtime behavior change — this is purely a type-safety improvement.
+- Existing tests continue to pass without modification (factory `execute` methods use `ctx: any` or `ctx: unknown`, so test mocks are unaffected).
+
+## Non-Goals
+
+- Fixing `as any` casts in `agent-runner.ts`, `conversation-viewer.ts`, `tools/helpers.ts`, or `tools/agent-tool.ts:550` — those access untyped SDK message internals, a different concern.
+- Removing the `ctx as UICtx` cast (line 196) — that is a named cast, not `as any`.
+- Removing `as any` from test files (e.g., `agent-menu.test.ts`'s `ctx as any`) — test mocks are intentionally narrow.
+
+## Background
+
+### Current cast inventory (`src/index.ts`)
+
+| Line | Cast                                            | Root cause                                                                  |
+| ---- | ----------------------------------------------- | --------------------------------------------------------------------------- |
+| 59   | `msg as any, opts as any`                       | `NotificationDeps.sendMessage(msg: unknown, opts: unknown)`                 |
+| 188  | `ctx as any, opts as any`                       | `AgentToolManager.spawn(ctx: unknown, …, opts: object)`                     |
+| 189  | `ctx as any, opts as any`                       | `AgentToolManager.spawnAndWait(ctx: unknown, …, opts: object)`              |
+| 208  | `}) as any`                                     | Cascading from above — `createAgentTool` return doesn't match `defineTool`  |
+| 215  | `session as any`                                | `GetResultDeps.getConversation(session: unknown)`                           |
+| 223  | `session as any`                                | `SteerToolDeps.steerAgent(session: unknown, …)`                             |
+| 232  | `(piArg ?? pi) as any, ctx as any, opts as any` | `AgentMenuManager.spawnAndWait(pi: unknown, ctx: unknown, …, opts: object)` |
+| 242  | `registry as any`                               | `AgentMenuDeps.getModelLabel(…, registry?: unknown)`                        |
+| 271  | `ctx as any`                                    | `MenuContext` not structurally compatible with `ExtensionCommandContext`    |
+
+### SDK types available
+
+All are exported from `@earendil-works/pi-coding-agent`:
+
+- `ExtensionContext` — tool execute context (has `ui`, `modelRegistry`, `cwd`, etc.)
+- `ExtensionCommandContext` — command handler context (extends `ExtensionContext`)
+- `ExtensionAPI` — the `pi` object passed to extensions
+- `AgentSession` — session handle (has `steer()`, `messages`, etc.)
+
+`ModelRegistry` is already defined locally in `src/model-resolver.ts` and matches the SDK shape.
+`SpawnOptions` is defined locally in `src/agent-manager.ts` (not currently exported).
+
+### Relevant AGENTS.md constraints
+
+- "Avoid `any` unless absolutely necessary."
+- "Keep Pi SDK imports out of business-logic modules."
+  Tool definitions, event handlers, and command handlers are SDK consumers — they may import SDK types directly.
+  The restriction targets pure helpers, utilities, and domain modules.
+- "When writing event handlers that consume Pi SDK types, prefer lean local payload interfaces over full SDK event types."
+
+The factory modules (`tools/agent-tool.ts`, `tools/get-result-tool.ts`, `tools/steer-tool.ts`, `ui/agent-menu.ts`) are SDK consumers (they define tools and command handlers), so importing SDK types is acceptable.
+The notification module (`notification.ts`) is a pure helper — it should use narrow local types rather than SDK imports.
+
+## Design Overview
+
+### Strategy per interface
+
+1. **`NotificationDeps.sendMessage`** — define narrow inline parameter types matching `ExtensionAPI.sendMessage`'s shape.
+   No SDK import needed; the notification module stays SDK-independent.
+
+2. **`AgentToolManager`** — import `ExtensionContext` for `ctx`, export + import `SpawnOptions` from `agent-manager.ts` for `opts`.
+   The tool module is an SDK consumer, so SDK imports are acceptable.
+
+3. **`AgentToolWidget.setUICtx`** — stays `ctx: unknown` (not `as any`; currently `ctx as UICtx`).
+   Out of scope.
+
+4. **`GetResultDeps.getConversation`** — import `AgentSession` for `session`.
+
+5. **`SteerToolDeps.steerAgent`** — import `AgentSession` for `session`.
+
+6. **`AgentMenuManager.spawnAndWait`** — import `ExtensionAPI` for `pi`, `ExtensionContext` for `ctx`, export + import `SpawnOptions` for `opts`.
+
+7. **`AgentMenuDeps.getModelLabel`** — import `ModelRegistry` from `../model-resolver.js` for `registry`.
+
+8. **`MenuContext` structural compatibility** — switch `MenuUI` from property syntax (strict function types) to method syntax (bivariant), and type `modelRegistry` as `ModelRegistry`.
+   This makes `ExtensionCommandContext` structurally assignable to `MenuContext`, removing the cast without broadening the handler's dependency on the full SDK type.
+   Tests continue using narrow mocks because the handler's parameter is still the narrow `MenuContext`.
+
+### `SpawnOptions` export
+
+`SpawnOptions` in `agent-manager.ts` is currently a private interface.
+Exporting it as a named `type` export adds no runtime cost and avoids duplicating the 15-field type in each factory.
+Both `tools/agent-tool.ts` and `ui/agent-menu.ts` already import `AgentRecord` from `types.ts`, so an intra-package `import type` from `agent-manager.ts` follows the same pattern.
+
+### Cascading cast resolution
+
+The `createAgentTool({…}) as any` cast on line 208 exists because TypeScript cannot verify the returned object satisfies `ToolDefinition` when inner types are `unknown`/`object`.
+Once the inner types are correct, the factory return type matches `ToolDefinition` naturally, and the outer `as any` cast resolves without further changes.
+
+## Module-Level Changes
+
+### `src/agent-manager.ts`
+
+- Export the existing `SpawnOptions` interface (add `export` keyword).
+
+### `src/notification.ts`
+
+- Replace `sendMessage: (msg: unknown, opts: unknown) => void` with narrow inline types:
+
+```typescript
+sendMessage: (
+  msg: { customType: string; content: string; display?: boolean; details?: unknown },
+  opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+) => void;
+```
+
+### `src/tools/agent-tool.ts`
+
+- Add `import type { ExtensionContext } from "@earendil-works/pi-coding-agent";`
+- Add `import type { SpawnOptions } from "../agent-manager.js";`
+- `AgentToolManager.spawn`: `ctx: unknown` → `ctx: ExtensionContext`, `opts: object` → `opts: SpawnOptions`
+- `AgentToolManager.spawnAndWait`: same changes, opts as `Omit<SpawnOptions, "isBackground">`
+
+### `src/tools/get-result-tool.ts`
+
+- Add `import type { AgentSession } from "@earendil-works/pi-coding-agent";`
+- `GetResultDeps.getConversation`: `session: unknown` → `session: AgentSession`
+
+### `src/tools/steer-tool.ts`
+
+- Add `import type { AgentSession } from "@earendil-works/pi-coding-agent";`
+- `SteerToolDeps.steerAgent`: `session: unknown` → `session: AgentSession`
+
+### `src/ui/agent-menu.ts`
+
+- Add `import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";`
+- Add `import type { SpawnOptions } from "../agent-manager.js";`
+- Add `import type { ModelRegistry } from "../model-resolver.js";`
+- `AgentMenuManager.spawnAndWait`: `pi: unknown` → `pi: ExtensionAPI | null`, `ctx: unknown` → `ctx: ExtensionContext`, `opts: object` → `opts: Omit<SpawnOptions, "isBackground">`
+- `AgentMenuDeps.getModelLabel`: `registry?: unknown` → `registry?: ModelRegistry`
+- `MenuUI`: switch from property syntax to method syntax for structural compatibility with `ExtensionUIContext`.
+  Update `notify` second parameter from `level: string` to `type?: string` to match SDK.
+- `MenuContext.modelRegistry`: `unknown` → `ModelRegistry`
+
+### `src/index.ts`
+
+- Remove all 14 `as any` casts.
+- No new imports needed (types already used transitively).
+
+## Test Impact Analysis
+
+1. **No new unit tests needed** — this is a type-only refactoring with no behavioral change.
+2. **No existing tests become redundant** — the tests exercise tool execution and menu behavior, not type signatures.
+3. **Existing tests must stay as-is** — factory `execute` methods use `ctx: any` or `ctx: unknown`, so `makeCtx()` test helpers remain compatible.
+   Test-side `as any` casts (e.g., `handler(ctx as any)` in `agent-menu.test.ts`) are out of scope.
+
+## TDD Order
+
+Since this is a type-only change, each step is verified by `pnpm run check` (tsc) rather than new vitest tests.
+The full test suite (`pnpm vitest run`) is run at the end as a regression check.
+
+1. **Export `SpawnOptions`** — add `export` to the existing `interface SpawnOptions` in `agent-manager.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: export SpawnOptions from agent-manager`
+
+2. **Type `NotificationDeps`** — replace `(msg: unknown, opts: unknown)` with narrow inline types in `notification.ts`.
+   Remove `msg as any, opts as any` casts (line 59) in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: type NotificationDeps.sendMessage parameters (#66)`
+
+3. **Type `AgentToolManager`** — import `ExtensionContext` and `SpawnOptions`, update `spawn` and `spawnAndWait` signatures in `agent-tool.ts`.
+   Remove `ctx as any, opts as any` casts (lines 188–189) and the cascading `}) as any` cast (line 208) in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: type AgentToolManager with ExtensionContext and SpawnOptions (#66)`
+
+4. **Type `GetResultDeps`** — import `AgentSession`, update `getConversation` in `get-result-tool.ts`.
+   Remove `session as any` cast (line 215) in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: type GetResultDeps.getConversation with AgentSession (#66)`
+
+5. **Type `SteerToolDeps`** — import `AgentSession`, update `steerAgent` in `steer-tool.ts`.
+   Remove `session as any` cast (line 223) in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: type SteerToolDeps.steerAgent with AgentSession (#66)`
+
+6. **Type `AgentMenuManager` + `AgentMenuDeps`** — import `ExtensionAPI`, `ExtensionContext`, `SpawnOptions`, `ModelRegistry`.
+   Update `spawnAndWait` and `getModelLabel` signatures in `agent-menu.ts`.
+   Remove `(piArg ?? pi) as any, ctx as any, opts as any` (line 232) and `registry as any` (line 242) casts in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: type AgentMenu interfaces with SDK types (#66)`
+
+7. **Align `MenuContext` with `ExtensionCommandContext`** — switch `MenuUI` to method syntax, fix `notify` parameter, type `modelRegistry` as `ModelRegistry`.
+   Remove `ctx as any` cast (line 271) in `index.ts`.
+   Verify: `pnpm run check`.
+   Commit: `refactor: align MenuContext for structural ExtensionCommandContext compat (#66)`
+
+8. **Final verification** — run `pnpm vitest run` for the full test suite.
+   Grep `src/index.ts` for remaining `as any` — expect zero.
+   Commit: none (verification only).
+
+## Risks and Mitigations
+
+| Risk                                                                                           | Mitigation                                                                                                                                                                              |
+| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Exporting `SpawnOptions` from `agent-manager.ts` couples factory modules to the manager's type | The coupling is type-only (`import type`), adds no runtime dependency, and follows the existing pattern (`AgentRecord` in `types.ts` is already shared).                                |
+| `MenuUI` method-syntax change could break structural compatibility with test mocks             | Test mocks use `vi.fn()` which is bivariant; method syntax on the `MenuUI` interface only affects how TypeScript checks assignability from `ExtensionUIContext`, not from mock objects. |
+| SDK type exports could change in a future Pi release                                           | The SDK types used (`ExtensionContext`, `AgentSession`, `ExtensionAPI`) are stable public API. `ModelRegistry` is a local interface.                                                    |
+| Cascading `as any` on `createAgentTool` may not resolve automatically                          | If TypeScript still cannot infer the return type, add explicit `satisfies ToolDefinition<…>` or a return type annotation. Verified in step 3.                                           |
+
+## Open Questions
+
+- None — the issue's "Proposed change" section is unambiguous and all SDK types are confirmed available.

package/docs/retro/0070-extract-event-handlers.md

@@ -0,0 +1,49 @@
+---
+issue: 70
+issue_title: "refactor: extract event handlers from pi-subagents index.ts into src/handlers/"
+---
+
+# Retro: #70 — extract event handlers from index.ts
+
+## Final Retrospective (2026-05-20T19:30:00Z)
+
+### Session summary
+
+Planned and implemented #70 — extracting four inline event handler lambdas from `src/index.ts` into `src/handlers/lifecycle.ts` (`SessionLifecycleHandler` class) and `src/handlers/tool-start.ts` (`ToolStartHandler` class).
+During planning, the user identified that the initial plain-function design missed shared collaborators and structural smells, prompting a redesign to class-based handlers and a predecessor issue (#87) to evolve `SubagentRuntime` from a data bag to an object with methods.
+Released as `pi-subagents-v5.8.0` with 8 new handler tests (520 total).
+
+### Observations
+
+#### What went well
+
+- The user's progressive questioning during planning ("Are you confident?", "Keep digging", Kent Beck quote) surfaced two concrete structural smells — output arguments on `runtime.currentCtx` writes and 8 LoD violations via `runtime.widget!` reach-throughs — that the initial design would have just relocated rather than fixed.
+- Filing predecessor #87 was the right sequencing call.
+  By the time #70 executed, the runtime had proper methods and the handler extraction was purely mechanical.
+- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
+  The only issue was a `tsc` type error (`vi.fn()` return type not assignable to `() => void`) caught during the post-TDD type check and fixed in-place before the final commit.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — The initial plan used plain functions with per-call `LifecycleDeps`/`ToolStartDeps` interfaces, the first viable approach, without analyzing whether handlers shared collaborators.
+  The user had to prompt three times before I switched to class-based handlers with constructor-injected shared deps.
+  Impact: three rounds of plan revision before the design was correct; no rework commits, but significant planning churn.
+
+- `instruction-violation` (user-caught) — The `/plan-issue` prompt says "load the `design-review` skill and run its checklist on the affected modules."
+  I loaded the skill but did not actually run the checklist (grep for access patterns, check LoD, check output arguments) until the user explicitly told me to "keep digging."
+  Had I run the checklist proactively, the output-argument and LoD findings would have surfaced on the first pass, and the predecessor issue (#87) would have been identified without user escalation.
+  Impact: user had to escalate three times; planning took ~3× longer than necessary.
+
+- `wrong-abstraction` — I initially reasoned at the mechanical level ("handlers are small, 1–5 lines, so plain functions are fine") instead of the structural level ("do these handlers share collaborators that a class captures naturally?").
+  The code-style skill explicitly says "Do not pass a shared dependency bag to functions that only use a subset" — but I applied it backwards (splitting into per-function deps) rather than recognizing the shared deps as a class cohesion signal.
+  Impact: same as premature-convergence above; folded into the same rework cycle.
+
+#### What caused friction (user side)
+
+- The progressive escalation approach (question → directive → quote) was effective pedagogically but required three turns of user attention on what a proactive design-review checklist run would have caught automatically.
+  Earlier intervention with a specific redirect (e.g., "Run the design-review checklist before writing the plan") could have resolved it in one turn.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0070-extract-event-handlers.md`.
+2. Updated `packages/pi-subagents/docs/architecture/architecture.md` — marked #87 and #70 as done (✓), updated Phase 2 status to complete, updated next-issue pointer to #66.

package/docs/retro/0087-evolve-subagent-runtime-methods.md

@@ -0,0 +1,42 @@
+---
+issue: 87
+issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
+---
+
+# Retro: #87 — evolve SubagentRuntime from data bag to object with methods
+
+## Final Retrospective (2026-05-20T18:00:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped #87 — converting `SubagentRuntime` from a plain interface + factory into a class with session-context methods (`setSessionContext`, `clearSessionContext`) and widget delegation methods (`setUICtx`, `onTurnStart`, `markFinished`, `updateWidget`, `ensureTimer`).
+All 10 call sites in `index.ts` were migrated, eliminating raw `currentCtx` field writes and `runtime.widget!` reach-throughs.
+Released as `pi-subagents-v5.7.0`.
+
+### Observations
+
+#### What went well
+
+- The 3-step TDD cycle executed cleanly with zero rework or deviations from the plan.
+  Test count went from 5 → 16 in `runtime.test.ts`; all 512 package tests stayed green throughout.
+- The user identified a missing architecture update and a pre-existing hallucination (`@earendil-works/pi-subagents` → `@gotgenes/pi-subagents`) after the plan commit.
+  The fix was a single well-scoped commit (`ddee1a0`) that corrected 10 scope references, updated the dependency graph to include #87 as a precursor to #70, and fixed list numbering per phase heading.
+- The plan's "Call sites to migrate" tables with exact line numbers and before/after code made step 3 (the refactoring commit) purely mechanical — no design decisions at implementation time.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In TDD step 2, the new `describe` block used `vi.fn()` but the test file's import was `{ describe, expect, it }` without `vi`.
+  The first red run surfaced this immediately (`ReferenceError: vi is not defined`) and it was fixed before the green step.
+  Impact: one extra test run, no rework commits.
+- `scope-drift` — The `/plan-issue` prompt does not instruct updating `architecture.md`, but the user noticed #87 was missing from the roadmap's dependency graph.
+  The agent hadn't checked `architecture.md` during planning even though #87 is explicitly listed as a precursor to #70 in the #70 plan.
+  Impact: user-caught; required a follow-up edit pass after the plan commit.
+
+#### What caused friction (user side)
+
+No friction observed.
+The user's correction about `architecture.md` was well-targeted and caught a real gap.
+
+### Changes made
+
+1. Retro file created at `packages/pi-subagents/docs/retro/0087-evolve-subagent-runtime-methods.md`.

package/package.json

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

package/src/agent-manager.ts

@@ -42,7 +42,7 @@ interface SpawnArgs {
   options: SpawnOptions;
 }
 
-interface SpawnOptions {
+export interface SpawnOptions {
   description: string;
   model?: Model<any>;
   maxTurns?: number;

package/src/handlers/index.ts

@@ -0,0 +1,6 @@
+export {
+  type LifecycleManager,
+  type LifecycleRuntime,
+  SessionLifecycleHandler,
+} from "./lifecycle.js";
+export { ToolStartHandler, type ToolStartRuntime } from "./tool-start.js";

package/src/handlers/lifecycle.ts

@@ -0,0 +1,62 @@
+/**
+ * Session lifecycle event handlers: session_start, session_before_switch, session_shutdown.
+ *
+ * Extracted from index.ts so each handler can be tested in isolation
+ * with mocked narrow interfaces.
+ */
+
+/** Narrow manager interface — only the methods lifecycle handlers call. */
+export interface LifecycleManager {
+  clearCompleted(): void;
+  abortAll(): void;
+  dispose(): void;
+}
+
+/** Narrow runtime interface — only the methods lifecycle handlers call. */
+export interface LifecycleRuntime {
+  setSessionContext(pi: unknown, ctx: unknown): void;
+  clearSessionContext(): void;
+}
+
+/**
+ * Handles session lifecycle events.
+ *
+ * Constructor deps:
+ * - `pi` — the ExtensionAPI instance, stored in runtime on session_start
+ * - `runtime` — owns session context state
+ * - `manager` — manages agent lifecycle (clear, abort, dispose)
+ * - `disposeNotifications` — tears down the notification system on shutdown
+ * - `unpublishService` — unpublishes the SubagentsService symbol on shutdown
+ */
+export class SessionLifecycleHandler {
+  constructor(
+    private readonly pi: unknown,
+    private readonly runtime: LifecycleRuntime,
+    private readonly manager: LifecycleManager,
+    private readonly disposeNotifications: () => void,
+    private readonly unpublishService: () => void,
+  ) {}
+
+  handleSessionStart(_event: unknown, ctx: unknown): void {
+    this.runtime.setSessionContext(this.pi, ctx);
+    this.manager.clearCompleted();
+  }
+
+  handleSessionBeforeSwitch(): void {
+    this.manager.clearCompleted();
+  }
+
+  // Cleanup order matters:
+  // 1. Unpublish service — prevent new cross-extension calls
+  // 2. Clear session context — no more session state
+  // 3. Abort all agents — stop running work
+  // 4. Dispose notifications — cancel pending nudges/timers
+  // 5. Dispose manager — final cleanup
+  async handleSessionShutdown(): Promise<void> {
+    this.unpublishService();
+    this.runtime.clearSessionContext();
+    this.manager.abortAll();
+    this.disposeNotifications();
+    this.manager.dispose();
+  }
+}

package/src/handlers/tool-start.ts

@@ -0,0 +1,32 @@
+/**
+ * tool_execution_start event handler.
+ *
+ * Extracted from index.ts so the handler can be tested in isolation
+ * with a mocked narrow runtime interface.
+ */
+
+/** Narrow runtime interface — only the widget-delegation methods the handler calls. */
+export interface ToolStartRuntime {
+  setUICtx(ctx: unknown): void;
+  onTurnStart(): void;
+}
+
+/** Minimal context shape for tool_execution_start — only the field the handler reads. */
+interface ToolStartCtx {
+  ui: unknown;
+}
+
+/**
+ * Handles tool_execution_start events.
+ *
+ * Grabs UI context from the first tool execution of each turn
+ * and signals the widget to clear lingering state.
+ */
+export class ToolStartHandler {
+  constructor(private readonly runtime: ToolStartRuntime) {}
+
+  handleToolExecutionStart(_event: unknown, ctx: ToolStartCtx): void {
+    this.runtime.setUICtx(ctx.ui);
+    this.runtime.onTurnStart();
+  }
+}

package/src/index.ts

@@ -16,6 +16,7 @@ import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, normalizeMaxTurns, resumeAgent, runAgent, steerAgent } from "./agent-runner.js";
 import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
+import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, createNotificationSystem } from "./notification.js";
 import { createNotificationRenderer } from "./renderer.js";
@@ -55,7 +56,7 @@ export default function (pi: ExtensionAPI) {
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
   const notifications = createNotificationSystem({
-    sendMessage: (msg, opts) => pi.sendMessage(msg as any, opts as any),
+    sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
     agentActivity: runtime.agentActivity,
     markFinished: (id) => runtime.markFinished(id),
     updateWidget: () => runtime.updateWidget(),
@@ -122,33 +123,24 @@ export default function (pi: ExtensionAPI) {
   });
   publishSubagentsService(service);
 
-  pi.on("session_start", async (_event, ctx) => {
-    runtime.setSessionContext(pi, ctx);
-    manager.clearCompleted();
-  });
-
-  pi.on("session_before_switch", () => {
-    manager.clearCompleted();
-  });
+  const lifecycle = new SessionLifecycleHandler(
+    pi,
+    runtime,
+    manager,
+    () => notifications.dispose(),
+    unpublishSubagentsService,
+  );
 
-  // On shutdown, abort all agents immediately and clean up.
-  // If the session is going down, there's nothing left to consume agent results.
-  pi.on("session_shutdown", async () => {
-    unpublishSubagentsService();
-    runtime.clearSessionContext();
-    manager.abortAll();
-    notifications.dispose();
-    manager.dispose();
-  });
+  pi.on("session_start", (event, ctx) => lifecycle.handleSessionStart(event, ctx));
+  pi.on("session_before_switch", () => lifecycle.handleSessionBeforeSwitch());
+  pi.on("session_shutdown", () => lifecycle.handleSessionShutdown());
 
   // Live widget: show running agents above editor
   runtime.widget = new AgentWidget(manager, runtime.agentActivity);
 
   // Grab UI context from first tool execution + clear lingering widget on new turn
-  pi.on("tool_execution_start", async (_event, ctx) => {
-    runtime.setUICtx(ctx.ui as UICtx);
-    runtime.onTurnStart();
-  });
+  const toolStart = new ToolStartHandler(runtime);
+  pi.on("tool_execution_start", (event, ctx) => toolStart.handleToolExecutionStart(event, ctx));
 
   /** Build the full type list text dynamically from the unified registry. */
   const buildTypeListText = () => {
@@ -193,8 +185,8 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerTool(defineTool(createAgentTool({
     manager: {
-      spawn: (ctx, type, prompt, opts) => manager.spawn(pi, ctx as any, type, prompt, opts as any),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(pi, ctx as any, type, prompt, opts as any),
+      spawn: (ctx, type, prompt, opts) => manager.spawn(pi, ctx, type, prompt, opts),
+      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(pi, ctx, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
       getMaxConcurrent: () => manager.getMaxConcurrent(),
@@ -213,14 +205,14 @@ export default function (pi: ExtensionAPI) {
     availableTypesText: getAvailableTypes().join(", "),
     agentDir: getAgentDir(),
     getDefaultMaxTurns: () => runtime.defaultMaxTurns,
-  }) as any));
+  })));
 
   // ---- get_subagent_result tool ----
 
   pi.registerTool(defineTool(createGetResultTool({
     getRecord: (id) => manager.getRecord(id),
     cancelNudge: (key) => notifications.cancelNudge(key),
-    getConversation: (session) => getAgentConversation(session as any),
+    getConversation: (session) => getAgentConversation(session),
   })));
 
   // ---- steer_subagent tool ----
@@ -228,7 +220,7 @@ export default function (pi: ExtensionAPI) {
   pi.registerTool(defineTool(createSteerTool({
     getRecord: (id) => manager.getRecord(id),
     emitEvent: (name, data) => pi.events.emit(name, data),
-    steerAgent: (session, message) => steerAgent(session as any, message),
+    steerAgent: (session, message) => steerAgent(session, message),
   })));
 
   // ---- /agents interactive menu ----
@@ -237,7 +229,7 @@ export default function (pi: ExtensionAPI) {
     manager: {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (piArg, ctx, type, prompt, opts) => manager.spawnAndWait((piArg ?? pi) as any, ctx as any, type, prompt, opts as any),
+      spawnAndWait: (piArg, ctx, type, prompt, opts) => manager.spawnAndWait(piArg ?? pi, ctx, type, prompt, opts),
       getMaxConcurrent: () => manager.getMaxConcurrent(),
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
     },
@@ -247,7 +239,7 @@ export default function (pi: ExtensionAPI) {
       const cfg = resolveAgentConfig(type);
       if (!cfg.model) return 'inherit';
       if (registry) {
-        const resolved = resolveModel(cfg.model, registry as any);
+        const resolved = resolveModel(cfg.model, registry);
         if (typeof resolved === 'string') return 'inherit';
       }
       return getModelLabelFromConfig(cfg.model);
@@ -276,6 +268,6 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand('agents', {
     description: 'Manage agents',
-    handler: async (_args, ctx) => { await agentsMenuHandler(ctx as any); },
+    handler: async (_args, ctx) => { await agentsMenuHandler(ctx); },
   });
 }

package/src/notification.ts

@@ -109,7 +109,10 @@ export function buildEventData(record: AgentRecord) {
 
 /** Narrow deps for the notification system — only the methods it actually calls. */
 export interface NotificationDeps {
-  sendMessage: (msg: unknown, opts: unknown) => void;
+  sendMessage: (
+    msg: { customType: string; content: string; display: boolean; details?: unknown },
+    opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+  ) => void;
   agentActivity: Map<string, AgentActivity>;
   markFinished: (id: string) => void;
   updateWidget: () => void;

package/src/tools/agent-tool.ts

@@ -1,5 +1,7 @@
+import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
+import type { SpawnOptions } from "../agent-manager.js";
 import { normalizeMaxTurns } from "../agent-runner.js";
 import { resolveAgentConfig, resolveType } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
@@ -121,8 +123,8 @@ export function buildDetails(
 
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
-  spawn: (ctx: unknown, type: string, prompt: string, opts: object) => string;
-  spawnAndWait: (ctx: unknown, type: string, prompt: string, opts: object) => Promise<AgentRecord>;
+  spawn: (ctx: ExtensionContext, type: string, prompt: string, opts: SpawnOptions) => string;
+  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;
@@ -353,8 +355,8 @@ Guidelines:
     execute: async (
       toolCallId: string,
       params: Record<string, unknown>,
-      signal: AbortSignal,
-      onUpdate: ((update: unknown) => void) | undefined,
+      signal: AbortSignal | undefined,
+      onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
       ctx: any,
     ) => {
       // Ensure we have UI context for widget rendering
@@ -436,7 +438,7 @@ Guidelines:
         const record = await deps.manager.resume(
           params.resume as string,
           params.prompt as string,
-          signal,
+          signal ?? new AbortController().signal,
         );
         if (!record) {
           return textResult(`Failed to resume agent "${params.resume}".`);
@@ -465,7 +467,7 @@ Guidelines:
 
         try {
           id = deps.manager.spawn(ctx, subagentType, params.prompt as string, {
-            description: params.description,
+            description: params.description as string,
             model,
             maxTurns: effectiveMaxTurns,
             isolated,
@@ -585,7 +587,7 @@ Guidelines:
           subagentType,
           params.prompt as string,
           {
-            description: params.description,
+            description: params.description as string,
             model,
             maxTurns: effectiveMaxTurns,
             isolated,

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

@@ -1,3 +1,4 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentRecord } from "../types.js";
 import { formatDuration, getDisplayName } from "../ui/agent-widget.js";
@@ -8,7 +9,7 @@ import { formatLifetimeTokens, textResult } from "./helpers.js";
 export interface GetResultDeps {
   getRecord: (id: string) => AgentRecord | undefined;
   cancelNudge: (key: string) => void;
-  getConversation: (session: unknown) => string | undefined;
+  getConversation: (session: AgentSession) => string | undefined;
 }
 
 /** Create the get_subagent_result tool definition (without Pi SDK wrapper). */

package/src/tools/steer-tool.ts

@@ -1,3 +1,4 @@
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import type { AgentRecord } from "../types.js";
 import { getSessionContextPercent } from "../usage.js";
@@ -7,7 +8,7 @@ import { formatLifetimeTokens, textResult } from "./helpers.js";
 export interface SteerToolDeps {
   getRecord: (id: string) => AgentRecord | undefined;
   emitEvent: (name: string, data: unknown) => void;
-  steerAgent: (session: unknown, message: string) => Promise<void>;
+  steerAgent: (session: AgentSession, message: string) => Promise<void>;
 }
 
 /** Create the steer_subagent tool definition (without Pi SDK wrapper). */

package/src/ui/agent-menu.ts

@@ -1,12 +1,15 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SpawnOptions } from "../agent-manager.js";
 import {
   BUILTIN_TOOL_NAMES,
   getAllTypes,
   resolveAgentConfig,
   resolveType,
 } from "../agent-types.js";
+import type { ModelRegistry } from "../model-resolver.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
 import type { AgentActivity } from "./agent-widget.js";
 import { formatDuration, getDisplayName } from "./agent-widget.js";
@@ -18,7 +21,7 @@ export interface AgentMenuManager {
   listAgents: () => AgentRecord[];
   getRecord: (id: string) => AgentRecord | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
-  spawnAndWait: (pi: unknown, ctx: unknown, type: string, prompt: string, opts: object) => Promise<AgentRecord>;
+  spawnAndWait: (pi: ExtensionAPI | null, ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
   getMaxConcurrent: () => number;
   setMaxConcurrent: (n: number) => void;
 }
@@ -28,7 +31,7 @@ export interface AgentMenuDeps {
   reloadCustomAgents: () => void;
   agentActivity: Map<string, AgentActivity>;
   /** Resolve model label for a given agent type + registry. */
-  getModelLabel: (type: string, registry?: unknown) => string;
+  getModelLabel: (type: string, registry?: ModelRegistry) => string;
   /** Snapshot current settings for persistence. */
   snapshotSettings: () => { maxConcurrent: number; defaultMaxTurns: number; graceTurns: number };
   /** Save settings and return a notification result. */
@@ -50,20 +53,6 @@ export interface AgentMenuDeps {
 
 // ---- Narrow UI context types ----
 
-interface MenuUI {
-  select: (title: string, options: string[]) => Promise<string | undefined>;
-  input: (prompt: string, defaultValue?: string) => Promise<string | undefined>;
-  confirm: (title: string, message: string) => Promise<boolean>;
-  editor: (title: string, content: string) => Promise<string | undefined>;
-  notify: (message: string, level: string) => void;
-  custom: <T>(factory: any, options: any) => Promise<T>;
-}
-
-interface MenuContext {
-  ui: MenuUI;
-  modelRegistry?: unknown;
-}
-
 // ---- Factory ----
 
 /**
@@ -83,7 +72,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     return undefined;
   }
 
-  async function showAgentsMenu(ctx: MenuContext) {
+  async function showAgentsMenu(ctx: ExtensionContext) {
     deps.reloadCustomAgents();
     const allNames = getAllTypes();
 
@@ -137,7 +126,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     }
   }
 
-  async function showAllAgentsList(ctx: MenuContext) {
+  async function showAllAgentsList(ctx: ExtensionContext) {
     const allNames = getAllTypes();
     if (allNames.length === 0) {
       ctx.ui.notify("No agents.", "info");
@@ -191,7 +180,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     }
   }
 
-  async function showRunningAgents(ctx: MenuContext) {
+  async function showRunningAgents(ctx: ExtensionContext) {
     const agents = deps.manager.listAgents();
     if (agents.length === 0) {
       ctx.ui.notify("No agents.", "info");
@@ -215,7 +204,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     await showRunningAgents(ctx);
   }
 
-  async function viewAgentConversation(ctx: MenuContext, record: AgentRecord) {
+  async function viewAgentConversation(ctx: ExtensionContext, record: AgentRecord) {
     if (!record.session) {
       ctx.ui.notify(
         `Agent is ${record.status === "queued" ? "queued" : "expired"} — no session available.`,
@@ -245,7 +234,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     );
   }
 
-  async function showAgentDetail(ctx: MenuContext, name: string) {
+  async function showAgentDetail(ctx: ExtensionContext, name: string) {
     if (resolveType(name) == null) {
       ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
       return;
@@ -312,7 +301,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     }
   }
 
-  async function ejectAgent(ctx: MenuContext, name: string, cfg: AgentConfig) {
+  async function ejectAgent(ctx: ExtensionContext, name: string, cfg: AgentConfig) {
     const location = await ctx.ui.select("Choose location", [
       "Project (.pi/agents/)",
       `Personal (${deps.personalAgentsDir})`,
@@ -363,7 +352,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     ctx.ui.notify(`Ejected ${name} to ${targetPath}`, "info");
   }
 
-  async function disableAgent(ctx: MenuContext, name: string) {
+  async function disableAgent(ctx: ExtensionContext, name: string) {
     const file = findAgentFile(name);
     if (file) {
       const content = readFileSync(file.path, "utf-8");
@@ -397,7 +386,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     ctx.ui.notify(`Disabled ${name} (${targetPath})`, "info");
   }
 
-  async function enableAgent(ctx: MenuContext, name: string) {
+  async function enableAgent(ctx: ExtensionContext, name: string) {
     const file = findAgentFile(name);
     if (!file) return;
 
@@ -416,7 +405,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     }
   }
 
-  async function showCreateWizard(ctx: MenuContext) {
+  async function showCreateWizard(ctx: ExtensionContext) {
     const location = await ctx.ui.select("Choose location", [
       "Project (.pi/agents/)",
       `Personal (${deps.personalAgentsDir})`,
@@ -440,7 +429,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     }
   }
 
-  async function showGenerateWizard(ctx: MenuContext, targetDir: string) {
+  async function showGenerateWizard(ctx: ExtensionContext, targetDir: string) {
     const description = await ctx.ui.input("Describe what this agent should do");
     if (!description) return;
 
@@ -526,7 +515,7 @@ Write the file using the write tool. Only write the file, nothing else.`;
     }
   }
 
-  async function showManualWizard(ctx: MenuContext, targetDir: string) {
+  async function showManualWizard(ctx: ExtensionContext, targetDir: string) {
     const name = await ctx.ui.input("Agent name (filename, no spaces)");
     if (!name) return;
 
@@ -621,7 +610,7 @@ ${systemPrompt}
     ctx.ui.notify(`Created ${targetPath}`, "info");
   }
 
-  async function showSettings(ctx: MenuContext) {
+  async function showSettings(ctx: ExtensionContext) {
     const choice = await ctx.ui.select("Settings", [
       `Max concurrency (current: ${deps.manager.getMaxConcurrent()})`,
       `Default max turns (current: ${deps.getDefaultMaxTurns() ?? "unlimited"})`,
@@ -677,13 +666,13 @@ ${systemPrompt}
     }
   }
 
-  function notifyApplied(ctx: MenuContext, successMsg: string) {
+  function notifyApplied(ctx: ExtensionContext, successMsg: string) {
     const { message, level } = deps.saveSettings(deps.snapshotSettings(), successMsg);
-    ctx.ui.notify(message, level);
+    ctx.ui.notify(message, level as "info" | "warning" | "error");
   }
 
   // Return the handler function
-  return async (ctx: MenuContext) => {
+  return async (ctx: ExtensionContext) => {
     await showAgentsMenu(ctx);
   };
 }