@gotgenes/pi-subagents 6.16.1 → 6.16.3

package/CHANGELOG.md

@@ -5,6 +5,23 @@ 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.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.16.2...pi-subagents-v6.16.3) (2026-05-23)
+
+
+### Documentation
+
+* **retro:** add retro notes for issue [#146](https://github.com/gotgenes/pi-packages/issues/146) ([720fcb0](https://github.com/gotgenes/pi-packages/commit/720fcb07937fc62a1811e59448343d3dfbc1ab14))
+
+## [6.16.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.16.1...pi-subagents-v6.16.2) (2026-05-23)
+
+
+### Documentation
+
+* fix plan for narrow UI context ([#146](https://github.com/gotgenes/pi-packages/issues/146)) ([3d5b591](https://github.com/gotgenes/pi-packages/commit/3d5b591c0668ffcd9f66a6fc9a2c5d57236865af))
+* mark Step N complete in architecture doc ([#146](https://github.com/gotgenes/pi-packages/issues/146)) ([9948869](https://github.com/gotgenes/pi-packages/commit/9948869b849817dac6f221f1e90db5e47fd12d31))
+* plan narrow UI context for menu handlers ([#146](https://github.com/gotgenes/pi-packages/issues/146)) ([88318b4](https://github.com/gotgenes/pi-packages/commit/88318b4550fe95fc70b1a9ee1e904c608a2189a3))
+* **retro:** add retro notes for issue [#148](https://github.com/gotgenes/pi-packages/issues/148) ([982fe51](https://github.com/gotgenes/pi-packages/commit/982fe51d7e27b7a127605710ced709bbd6291a0f))
+
 ## [6.16.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.16.0...pi-subagents-v6.16.1) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -616,20 +616,20 @@ Phase 9 targets the next layer: observation model consolidation, `ExtensionConte
 
 ### Current smells
 
-| Smell                                            | Location                                                              | Evidence                                                                                                                                       | Severity |
-| ------------------------------------------------ | --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | -------- |
-| `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   |
-| 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)~~                                     | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                                         | Done     |
-| `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      |
+| Smell                                            | Location                                                                  | Evidence                                                                                                                       | Severity |
+| ------------------------------------------------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------- |
+| `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`~~ | Resolved by #146: `MenuUI` interface introduced; 42 `ctx as any` casts eliminated across 5 test files                          | Done     |
+| 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)~~                                         | Resolved by #148: rendering extracted to `widget-renderer.ts`; widget is now 198 lines                                         | Done     |
+| `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
 
 Applied incrementally as each step touches a module:
 
-- **≤4 fields** — accept as plain parameters; drop the interface.
-- **≥5 fields** — keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
+- **≤4 fields** - accept as plain parameters; drop the interface.
+- **≥5 fields** - keep a named interface but destructure in the function signature (`{ manager, widget }: ForegroundDeps`) so the function body uses bare names, not `deps.foo`.
 
 This eliminates the `deps.` prefix noise across ~124 callsites in 12 modules.
 
@@ -665,19 +665,23 @@ After this step, `ExtensionContext` appears only in:
 
 Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
 
-### Step N: Narrow UI context for menu handlers (#146)
+### Step N: Narrow UI context for menu handlers (#146) ✓
 
-Define a `MenuUI` interface with `select`, `confirm`, `input`, `notify`, and `editor` methods.
-Menu handler functions (`showAgentsMenu`, `showAgentDetail`, `showCreateWizard`, etc.) accept `MenuUI` instead of `ExtensionContext`.
-`index.ts` passes `ctx.ui` at the call site.
+Defined `MenuUI` interface (exported from `agent-menu.ts`) with `select`, `confirm`, `input`, `notify`, `editor`, and `custom` methods — the exact subset `ctx.ui` methods used by menu handlers.
+All inner functions in `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts` now accept `(ui: MenuUI)` instead of `(ctx: ExtensionContext)`.
+`index.ts` passes `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)` to the handler.
 
-Creation wizard’s `spawnAndWait` call changes: the narrow `AgentMenuManager.spawnAndWait` accepts `ParentSnapshot` (enabled by Step M) instead of `ExtensionContext`.
+`AgentMenuManager.spawnAndWait` and `WizardManager.spawnAndWait` both accept `ParentSnapshot` (enabled by Step M).
+Creation wizard threads `parentSnapshot` from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)` → `manager.spawnAndWait(parentSnapshot, ...)`.
 
-Apply the dependency bag convention to touched modules: `AgentConfigEditorDeps` (4 fields), `SteerToolDeps` (4 fields), and `GetResultDeps` (4 fields) become plain parameters; `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) are destructured in the signature.
+Applied the dependency bag convention:
 
-After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures, `service-adapter.ts` (cross-extension bridge), and `index.ts` (extension entry point).
+- `AgentConfigEditorDeps` (4 fields), `GetResultDeps` (4 fields), `SteerToolDeps` (4 fields) dissolved into plain parameters.
+- `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) kept as interfaces, destructured in the function signature.
 
-Impact: eliminates ~43 `ctx as any` casts across menu, editor, and wizard test files; tests construct a plain object satisfying `MenuUI` with no cast.
+After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures and `service-adapter.ts` (cross-extension bridge).
+
+Impact: eliminated 42 `ctx as any` casts across 5 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14); tests construct plain `MenuUI`-shaped objects with no cast.
 
 ### Step O: Inject text wrapping into ConversationViewer (#147)
 
@@ -693,7 +697,7 @@ Impact: eliminates the hoisted `vi.mock("@earendil-works/pi-tui")` in `conversat
 
 Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
 The widget is now a thin lifecycle/polling wrapper (198 lines, down from 374) that delegates to pure render functions.
-Rendering functions receive data (agent list, activity map, registry) and return formatted strings — testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
+Rendering functions receive data (agent list, activity map, registry) and return formatted strings - testable without widget lifecycle. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
 
 ### Step dependencies
 

package/docs/plans/0146-narrow-ui-context.md

@@ -0,0 +1,319 @@
+---
+issue: 146
+issue_title: "Narrow UI context for menu handlers (Phase 9, Step N)"
+---
+
+# Narrow UI context for menu handlers
+
+## Problem Statement
+
+Menu handler functions (`showAgentsMenu`, `showAgentDetail`, `showCreateWizard`, etc.) declare `ctx: ExtensionContext` but only call `ctx.ui.select/confirm/input/notify/editor/custom` and `ctx.modelRegistry`.
+This forces 42 `ctx as any` casts across 3 test files (`agent-menu.test.ts`: 8, `agent-config-editor.test.ts`: 20, `agent-creation-wizard.test.ts`: 14) because tests cannot construct a full `ExtensionContext`.
+
+## Goals
+
+- Define a `MenuUI` interface with the subset of `ctx.ui` methods that menu handlers actually use (`select`, `confirm`, `input`, `notify`, `editor`, `custom`).
+- Menu handler functions accept `MenuUI` (plus `modelRegistry` passed separately) instead of `ExtensionContext`.
+- `index.ts` handler registration extracts `ctx.ui` and `ctx.modelRegistry` from the SDK `ExtensionContext`.
+- Change `WizardManager.spawnAndWait` to accept `ParentSnapshot` (introduced by #145) instead of `ExtensionContext`.
+- Apply dependency bag convention: dissolve ≤4-field deps into plain parameters; keep ≥5-field interfaces but destructure in signature.
+- Eliminate all 42 `ctx as any` casts from menu, editor, and wizard test files.
+
+## Non-Goals
+
+- Changing the behavior of `ctx.ui.custom` — pass-through only.
+- Narrowing `ExtensionContext` usage in `index.ts` closures (the `as any` casts for `runtime.currentCtx?.ctx` are addressed separately).
+- Injecting `modelRegistry` further (already a narrow interface from `model-resolver.ts`).
+
+## Background
+
+### Dependency: #145 (Step M) — Decompose execute
+
+Issue #145 is **closed/implemented**.
+`buildParentSnapshot(ctx)` converts `ExtensionContext` → `ParentSnapshot` at the call site.
+This enables `WizardManager.spawnAndWait` to accept `ParentSnapshot` instead of `ExtensionContext`.
+
+### Existing modules
+
+- `agent-menu.ts` (296 lines) — menu handler factory, 8-field `AgentMenuDeps`, all inner functions take `ctx: ExtensionContext`
+- `agent-config-editor.ts` (202 lines) — `AgentConfigEditorDeps` (4 fields), `showAgentDetail` takes `ctx: ExtensionContext`
+- `agent-creation-wizard.ts` (246 lines) — `AgentCreationWizardDeps` (5 fields), `WizardManager.spawnAndWait` takes `ctx: ExtensionContext`
+- `tools/get-result-tool.ts` — `GetResultDeps` (4 fields)
+- `tools/steer-tool.ts` — `SteerToolDeps` (4 fields)
+- `index.ts` — wires everything, handler registration extracts `ctx.ui` and passes `ExtensionContext`
+
+### ExtensionContext usage in menu handlers
+
+Every `ctx` reference in the three menu UI modules maps to exactly one of:
+
+- `ctx.ui.select(...)` — 9 call sites
+- `ctx.ui.confirm(...)` — 5 call sites
+- `ctx.ui.input(...)` — 7 call sites
+- `ctx.ui.notify(...)` — 15 call sites
+- `ctx.ui.editor(...)` — 2 call sites
+- `ctx.ui.custom(...)` — 1 call site (conversation viewer overlay)
+- `ctx.modelRegistry` — 1 call site (model label resolution in `showAllAgentsList`)
+
+No other `ExtensionContext` properties (session, tools, hooks, etc.) are accessed.
+
+## Design Overview
+
+### MenuUI interface
+
+A narrow interface capturing only the `ctx.ui` methods used by menu handlers:
+
+```typescript
+export interface MenuUI {
+  select(title: string, options: string[]): Promise<string | undefined>;
+  confirm(title: string, message: string): Promise<boolean>;
+  input(title: string, defaultValue?: string): Promise<string | undefined>;
+  notify(message: string, level: "info" | "warning" | "error"): void;
+  editor(title: string, content: string): Promise<string | undefined>;
+  custom<R>(component: any, options?: any): Promise<R>;
+}
+```
+
+`select` uses a plain `string` return (not a generic `<T extends string>`) to match the SDK's structural signature.
+
+`modelRegistry` is not included in `MenuUI` — it is not a UI concern.
+Instead, the handler registration in `index.ts` passes it separately.
+
+### Handler signature change
+
+The menu handler currently receives `ExtensionContext` directly:
+
+```typescript
+// index.ts — before
+handler: async (_args, ctx) => { await agentsMenuHandler(ctx); },
+```
+
+After this change, `index.ts` destructures what each handler needs:
+
+```typescript
+// index.ts — after
+handler: async (_args, ctx) => {
+  await agentsMenuHandler({
+    ui: ctx.ui,
+    modelRegistry: ctx.modelRegistry,
+    parentSnapshot: buildParentSnapshot(ctx),
+  });
+},
+```
+
+In `agent-menu.ts`, the return type changes from `(ctx: ExtensionContext) => Promise<void>` to a function that accepts `{ ui: MenuUI; modelRegistry: ModelRegistry; parentSnapshot: ParentSnapshot }`.
+The `ExtensionContext` import is removed from `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts`.
+
+`modelRegistry` is threaded from the handler through `showAgentsMenu` → `showAllAgentsList` (the only consumer).
+`parentSnapshot` is threaded from the handler through `showAgentsMenu` → `wizard.showCreateWizard` → `showGenerateWizard` (the only consumer).
+
+### Wizard spawnAndWait — drop ctx parameter
+
+`WizardManager.spawnAndWait` currently takes `ctx: ExtensionContext` as its first parameter and passes it to `deps.manager.spawnAndWait(ctx, ...)`.
+Once the menu handler no longer receives `ExtensionContext`, the wizard has no `ctx` to pass.
+
+Thread `parentSnapshot` as a parameter from the handler through the wizard, keeping `AgentMenuManager.spawnAndWait` accepting `ParentSnapshot` as its first parameter (consistent with `AgentManager.spawnAndWait`).
+The wizard's `showGenerateWizard` receives `parentSnapshot` and passes it to `deps.manager.spawnAndWait(parentSnapshot, ...)`.
+
+```typescript
+// agent-creation-wizard.ts — after
+async function showGenerateWizard(
+  ui: MenuUI,
+  parentSnapshot: ParentSnapshot,
+  targetDir: string,
+) {
+  // ...
+  const record = await deps.manager.spawnAndWait(
+    parentSnapshot, "general-purpose", generatePrompt, { ... },
+  );
+}
+```
+
+The creation wizard no longer imports `ExtensionContext`.
+
+### Dependency bag convention
+
+Per `docs/architecture/architecture.md` § Dependency bag convention:
+
+- **≤4 fields** → dissolve the interface, accept as plain parameters.
+- **≥5 fields** → keep the interface but destructure in the function signature.
+
+#### Dissolve (≤4 fields)
+
+`AgentConfigEditorDeps` (4 fields: `fileOps`, `registry`, `personalAgentsDir`, `projectAgentsDir`) → plain parameters on `createAgentConfigEditor`.
+
+`GetResultDeps` (4 fields: `getRecord`, `cancelNudge`, `getConversation`, `registry`) → plain parameters on `createGetResultTool`.
+
+`SteerToolDeps` (4 fields: `getRecord`, `emitEvent`, `steerAgent`, `queueSteer`) → plain parameters on `createSteerTool`.
+
+#### Keep + destructure (≥5 fields)
+
+`AgentMenuDeps` (8 fields) — keep the interface, destructure in `createAgentsMenuHandler({ manager, registry, ... })`.
+
+`AgentCreationWizardDeps` (5 fields) — keep the interface, destructure in `createAgentCreationWizard({ fileOps, manager, ... })`.
+
+### Consumer call-site sketch (menu handler registration)
+
+```typescript
+// index.ts
+pi.registerCommand('agents', {
+  description: 'Manage agents',
+  handler: async (_args, ctx) => {
+    await agentsMenuHandler({
+      ui: ctx.ui,
+      modelRegistry: ctx.modelRegistry,
+      parentSnapshot: buildParentSnapshot(ctx),
+    });
+  },
+});
+```
+
+### Extracted module interaction sketch (agent-config-editor)
+
+```typescript
+// agent-config-editor.ts — after dissolving deps
+export function createAgentConfigEditor(
+  fileOps: AgentFileOps,
+  registry: AgentTypeRegistry,
+  personalAgentsDir: string,
+  projectAgentsDir: string,
+) {
+  // ... closures capture these directly; no deps.foo indirection
+}
+```
+
+No Tell-Don't-Ask violations — each parameter is a primitive or injectable collaborator.
+No output-argument mutations — pure closure capture.
+
+## Module-Level Changes
+
+### New file: none
+
+All changes are modifications to existing files.
+
+### Modified: `src/ui/agent-menu.ts`
+
+- Add `MenuUI` interface export (the new narrow type).
+- Import `ModelRegistry` from `model-resolver.js`.
+- Remove `ExtensionContext` import.
+- Change all inner function signatures from `(ctx: ExtensionContext)` to `(ui: MenuUI)`.
+- Replace `ctx.ui.xxx(...)` → `ui.xxx(...)`.
+- Replace `ctx.modelRegistry` → parameter `modelRegistry` threaded to `showAllAgentsList`.
+- Change `AgentMenuDeps` usage: destructure in `createAgentsMenuHandler` signature.
+- Change return type from `(ctx: ExtensionContext) => Promise<void>` to `(params: { ui: MenuUI; modelRegistry: ModelRegistry; parentSnapshot: ParentSnapshot }) => Promise<void>`.
+- Thread `modelRegistry` from handler through `showAgentsMenu` → `showAllAgentsList`.
+- Thread `parentSnapshot` from handler through `showAgentsMenu` → `wizard.showCreateWizard` → `showGenerateWizard`.
+- Update `AgentMenuManager.spawnAndWait` to accept `ParentSnapshot` instead of `ExtensionContext`.
+- Remove `Omit<AgentSpawnConfig, "isBackground">` in favor of plain inline type.
+
+### Modified: `src/ui/agent-config-editor.ts`
+
+- Remove `ExtensionContext` import.
+- Add `MenuUI` import from `agent-menu.js`.
+- Change all inner function signatures from `(ctx: ExtensionContext)` to `(ui: MenuUI)`.
+- Replace `ctx.ui.xxx(...)` → `ui.xxx(...)`.
+- Dissolve `AgentConfigEditorDeps`: replace single deps parameter with 4 plain parameters.
+
+### Modified: `src/ui/agent-creation-wizard.ts`
+
+- Remove `ExtensionContext` import.
+- Add `MenuUI` import from `agent-menu.js`.
+- Add `ParentSnapshot` import from `parent-snapshot.js`.
+- Change all inner function signatures from `(ctx: ExtensionContext)` to `(ui: MenuUI)`.
+- Replace `ctx.ui.xxx(...)` → `ui.xxx(...)`.
+- Change `WizardManager.spawnAndWait` to accept `ParentSnapshot` instead of `ExtensionContext`.
+- Thread `parentSnapshot` as a parameter from `showCreateWizard(ui, parentSnapshot)` → `showGenerateWizard(ui, parentSnapshot, targetDir)`.
+- Destructure `AgentCreationWizardDeps` in signature.
+
+### Modified: `src/tools/get-result-tool.ts`
+
+- Dissolve `GetResultDeps`: replace single deps parameter with 4 plain parameters.
+
+### Modified: `src/tools/steer-tool.ts`
+
+- Dissolve `SteerToolDeps`: replace single deps parameter with 4 plain parameters.
+
+### Modified: `src/index.ts`
+
+- Update `createAgentConfigEditor` call: pass 4 plain args instead of `AgentConfigEditorDeps`.
+- Update `createAgentCreationWizard` call: pass 4 plain args instead of `AgentCreationWizardDeps` (registry is the `WizardRegistry`, not the full `AgentTypeRegistry` — pass `{ reload: () => registry.reload() }`).
+- Update `createGetResultTool` call: pass 4 plain args instead of `GetResultDeps`.
+- Update `createSteerTool` call: pass 4 plain args instead of `SteerToolDeps`.
+- Update `spawnAndWait` in menu handler deps: keep `ParentSnapshot` as first parameter.
+- Update `/agents` command handler to destructure `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)`.
+
+### Modified: test files
+
+- `test/ui/agent-menu.test.ts` — remove `ctx as any` casts; pass `{ ui: { ... }, modelRegistry: {}, parentSnapshot: {} }`.
+- `test/ui/agent-config-editor.test.ts` — remove `ctx as any` casts; pass `MenuUI` objects directly.
+- `test/ui/agent-creation-wizard.test.ts` — remove `ctx as any` casts; pass `MenuUI` and stub `ParentSnapshot`.
+- `test/tools/get-result-tool.test.ts` — update `makeDeps` and `execute` helpers for dissolved parameters.
+- `test/tools/steer-tool.test.ts` — update `makeDeps` and `execute` helpers for dissolved parameters.
+
+### Unchanged
+
+- `src/ui/conversation-viewer.ts` — unrelated; uses its own deps.
+- `src/ui/agent-widget.ts` — already narrow (no `ExtensionContext`).
+- `src/agent-manager.ts` — already accepts `ParentSnapshot` from #145.
+- `src/parent-snapshot.ts` — unchanged.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:** None — this is a signature change, not an extraction.
+   The existing test coverage already exercises menu navigation, editing, creation, and tool operations.
+
+2. **Existing tests that simplify:** All 42 `ctx as any` casts are removed from the three test files.
+   `makeCtx()` returns a plain `MenuUI`-shaped object (already structurally compatible).
+   The `makeCtx` helper in `agent-menu.test.ts` already returns the right shape — it just needs the cast removed and the handler-call interface updated.
+
+3. **Tests that must stay:** All existing test assertions stay — only the method of constructing the handler input changes.
+   `get-result-tool.test.ts` and `steer-tool.test.ts` may need minor updates if the deps dissolve changes the factory call signature, but no assertion changes.
+
+## TDD Order
+
+Each step must leave `pnpm run check` green.
+When a step changes a factory signature, it must also update the corresponding `index.ts` call site in the same commit.
+
+1. **Refactor:** Define and export `MenuUI` interface in `agent-menu.ts`.
+   No other changes — just add the interface alongside the existing code.
+   Commit: `refactor: add MenuUI interface (#146)`
+
+2. **Refactor:** Update `agent-config-editor.ts` — dissolve `AgentConfigEditorDeps` into 4 plain parameters; change `showAgentDetail(ctx)` to `showAgentDetail(ui: MenuUI)`; replace `ctx.ui.xxx` → `ui.xxx`.
+   Update `agent-config-editor.test.ts` — remove `ctx as any` casts, pass `MenuUI` objects directly.
+   Update `index.ts` — update `createAgentConfigEditor` call to pass 4 plain args.
+   Commit: `refactor: dissolve AgentConfigEditorDeps and narrow to MenuUI (#146)`
+
+3. **Refactor:** Update `agent-creation-wizard.ts` — destructure `AgentCreationWizardDeps`; change `showCreateWizard(ctx)` to `showCreateWizard(ui: MenuUI, parentSnapshot: ParentSnapshot)`; thread `parentSnapshot` to `showGenerateWizard`; change `WizardManager.spawnAndWait` to accept `ParentSnapshot`; replace `ctx.ui.xxx` → `ui.xxx`.
+   Update `agent-creation-wizard.test.ts` — remove `ctx as any` casts, pass `MenuUI` and stub `ParentSnapshot`.
+   Update `index.ts` — update `createAgentCreationWizard` call for destructured params.
+   Commit: `refactor: narrow creation wizard to MenuUI and ParentSnapshot (#146)`
+
+4. **Refactor:** Update `agent-menu.ts` — destructure `AgentMenuDeps`; change handler return type to accept `{ ui: MenuUI; modelRegistry: ModelRegistry; parentSnapshot: ParentSnapshot }`; thread `modelRegistry` to `showAllAgentsList`; thread `parentSnapshot` to `wizard.showCreateWizard`; update `AgentMenuManager.spawnAndWait` to accept `ParentSnapshot`; replace `ctx.ui.xxx` → `ui.xxx`.
+   Update `agent-menu.test.ts` — remove `ctx as any` casts, pass `{ ui, modelRegistry, parentSnapshot }`.
+   Update `index.ts` — update `/agents` handler to destructure `ctx.ui`, `ctx.modelRegistry`, and `buildParentSnapshot(ctx)`.
+   Commit: `refactor: narrow agent menu to MenuUI interface (#146)`
+
+5. **Refactor:** Update `get-result-tool.ts` — dissolve `GetResultDeps` into 4 plain parameters.
+   Update `test/tools/get-result-tool.test.ts` — update `makeDeps` and `execute` helpers.
+   Update `index.ts` — update `createGetResultTool` call to pass 4 plain args.
+   Commit: `refactor: dissolve GetResultDeps into plain parameters (#146)`
+
+6. **Refactor:** Update `steer-tool.ts` — dissolve `SteerToolDeps` into 4 plain parameters.
+   Update `test/tools/steer-tool.test.ts` — update `makeDeps` and `execute` helpers.
+   Update `index.ts` — update `createSteerTool` call to pass 4 plain args.
+   Commit: `refactor: dissolve SteerToolDeps into plain parameters (#146)`
+
+7. **Verify:** Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
+   Confirm zero `ctx as any` in the three menu test files.
+   Commit: none (verification only).
+
+## Risks and Mitigations
+
+| Risk                                                                               | Mitigation                                                                                                                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ctx.ui.custom` signature mismatch between `MenuUI` and real `ExtensionContext.ui` | `MenuUI.custom` uses `any` for the component and options parameters since these are opaque TUI types internal to the SDK. This matches the existing usage where `ctx.ui.custom<undefined>(...)` passes a TUI component constructor.                                                                                          |
+| `ParentSnapshot` threading through menu → wizard call chain                        | The handler receives `parentSnapshot` from `index.ts` and threads it through `showAgentsMenu` → `showCreateWizard` → `showGenerateWizard`. Only `showGenerateWizard` uses it; the other functions relay it. This is acceptable since the parameter follows the existing `targetDir` threading pattern already in the wizard. |
+| Deps dissolution breaks `index.ts` type check mid-sequence                         | Each TDD step updates the factory, its test file, AND the `index.ts` call site together, keeping `pnpm run check` green after every commit.                                                                                                                                                                                  |
+
+## Open Questions
+
+- None — the design follows the architecture doc's Step N specification and the dependency (#145) is already implemented.

package/docs/retro/0146-narrow-ui-context.md

@@ -0,0 +1,70 @@
+---
+issue: 146
+issue_title: "Narrow UI context for menu handlers (Phase 9, Step N)"
+---
+
+# Retro: #146 — Narrow UI context for menu handlers
+
+## Final Retrospective (2026-05-23T10:00:00Z)
+
+### Session summary
+
+Introduced a `MenuUI` interface in `agent-menu.ts` capturing the 6 `ctx.ui` methods used by menu handlers.
+Replaced `ExtensionContext` with `MenuUI` (plus explicit `ModelRegistry` and `ParentSnapshot`) in all inner functions across `agent-menu.ts`, `agent-config-editor.ts`, and `agent-creation-wizard.ts`.
+Dissolved three ≤4-field dependency bags (`AgentConfigEditorDeps`, `GetResultDeps`, `SteerToolDeps`) into plain parameters; destructured `AgentMenuDeps` and `AgentCreationWizardDeps` in their factory signatures.
+Eliminated 42 `ctx as any` casts across 5 test files.
+Released as `pi-subagents-v6.16.2`.
+
+### Observations
+
+#### What went well
+
+- **User-initiated plan review caught three ordering bugs before implementation.**
+  The user asked the agent to "review the plan and judge its quality and clarity" after the initial commit.
+  The review identified three execution-blocking problems in the TDD order: `MenuUI` not defined before consumers, `ParentSnapshot` not threaded through the handler return type, and `index.ts` call sites not updated alongside their factories.
+  All three were fixed before TDD execution began, saving significant implementation friction.
+- The plan's TDD order (after fixes) worked well for a pure-refactoring change — all 806 tests stayed green throughout every step.
+- The type checker served as an effective safety net: every call-site mismatch was caught immediately by `pnpm run check`, preventing runtime surprises.
+
+#### What caused friction (agent side)
+
+##### Planning session
+
+- `missing-context` — The initial plan had three TDD ordering bugs: (1) `MenuUI` used before defined, (2) `ParentSnapshot` not threaded through handler return type, (3) `index.ts` call sites not updated alongside factory signature changes.
+  These were caught by a user-prompted plan review, not by the planning agent itself.
+  Impact: would have caused type-check failures during TDD execution; fixed before implementation started.
+
+- `wrong-abstraction` — After fixing the plan, the agent ran `git commit --amend --no-edit` to update the plan commit, but it landed on the wrong commit (a stacked prompt-changes commit from a different session).
+  This caused divergent history with origin.
+  Recovery required `git reset --hard origin/main` and re-applying the plan fixes as a new commit (`3d5b591`).
+  Impact: ~5 minutes of git recovery and re-application of edits.
+
+##### Implementation session
+
+- `missing-context` — In Step 3, the plan listed the `WizardManager.spawnAndWait` signature change (to accept `ParentSnapshot`) and the `AgentMenuManager.spawnAndWait` change as separate steps (3 and 4).
+  But `agent-menu.ts` passes `deps.manager` (typed as `AgentMenuManager`) to `createAgentCreationWizard`, which expects `WizardManager`.
+  Changing `WizardManager` without also changing `AgentMenuManager` broke the type checker.
+  I had to pull the `AgentMenuManager` change forward from Step 4 into Step 3.
+  Impact: minor — a few minutes of diagnosis and one extra edit, no rework.
+
+- `missing-context` — In Step 2, after dissolving `AgentConfigEditorDeps` and changing `showAgentDetail(ctx)` to `showAgentDetail(ui: MenuUI)`, I forgot to update the call site in `agent-menu.ts` from `editor.showAgentDetail(ctx, agentName)` to `editor.showAgentDetail(ctx.ui, agentName)`.
+  The type checker caught it immediately.
+  Impact: added friction but no rework — one extra `pnpm run check` cycle.
+
+- `missing-context` — In Step 4, the `makeUI()` test helper used `modelRegistry: {}` which didn't satisfy the `ModelRegistry` interface (requires `find` and `getAll`).
+  Impact: one extra `pnpm run check` cycle and a one-line fix.
+
+- `missing-context` — In Step 5, two tests called `createGetResultTool(makeDeps())` directly (not via the `execute()` helper).
+  After dissolving deps, the factory signature changed but I only updated `execute()`.
+  The type checker caught the two direct calls.
+  Impact: one extra `pnpm run check` cycle.
+
+#### What caused friction (user side)
+
+- None observed — the session ran autonomously with no user corrections needed.
+
+#### What caused friction (user side — planning)
+
+- The user had to explicitly ask for a plan review (“I'd like you to review the plan and judge its quality and clarity”) to surface three ordering bugs.
+  The planning agent should have caught these during plan authoring — the testing skill already contains rules about TDD step ordering and shared interface changes.
+  The user's intervention prevented significant implementation friction.

package/docs/retro/0148-split-agent-widget-rendering.md

@@ -0,0 +1,39 @@
+---
+issue: 148
+issue_title: "Split AgentWidget rendering from lifecycle (Phase 9, Step P)"
+---
+
+# Retro: #148 — Split AgentWidget rendering from lifecycle
+
+## Final Retrospective (2026-05-23T06:20:00Z)
+
+### Session summary
+
+Extracted pure rendering functions (`renderWidgetLines`, `renderFinishedLine`, `renderRunningLines`) from `AgentWidget` into `ui/widget-renderer.ts`.
+The widget shrank from 374 to 198 lines — now a thin lifecycle wrapper. 23 new unit tests cover all status variants, overflow, tree connectors, and empty states.
+Released as `pi-subagents-v6.16.1`.
+
+### Observations
+
+#### What went well
+
+- TDD cycles were fast and clean: 9 commits, all tests green on first or second try, zero test regressions across the full 806-test suite.
+- The `WidgetAgent` / `WidgetActivity` interfaces worked well as structural subsets — `AgentRecord` and `AgentActivityTracker` satisfy them without mapping code.
+- The stub `Theme` pattern from `test/renderer.test.ts` (`fg: (c, t) => \`[\${c}:\${t}]\``) transferred cleanly to the new test file, keeping assertions readable.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's `renderWidgetLines` API spec omitted `theme` from its parameters, even though the heading, tree connectors, and per-agent render calls all require it.
+  Caught immediately at step 4 (first `renderWidgetLines` test) and fixed by adding `theme` to the params.
+  Impact: deviation note in commit body; no rework.
+
+- `missing-context` — Step 3 (`renderRunningLines` implementation) initially missed importing `SPINNER` from `display.ts`.
+  The test caught it as a runtime `ReferenceError`, fixed in the same Red→Green cycle.
+  Impact: added friction but no rework.
+
+- `wrong-abstraction` — Step 8 ("Extract into `widget-renderer.ts`") was a no-op because the module was created incrementally during steps 1–7 (tests must import from the new module to run).
+  Impact: step skipped; noted in summary.
+
+#### What caused friction (user side)
+
+- None observed — the session ran autonomously from plan through ship with no user corrections needed.

package/package.json

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

package/src/index.ts

@@ -227,21 +227,21 @@ export default function (pi: ExtensionAPI) {
 
   // ---- get_subagent_result tool ----
 
-  pi.registerTool(defineTool(createGetResultTool({
-    getRecord: (id) => manager.getRecord(id),
-    cancelNudge: (key) => notifications.cancelNudge(key),
-    getConversation: (session) => getAgentConversation(session),
+  pi.registerTool(defineTool(createGetResultTool(
+    (id) => manager.getRecord(id),
+    (key) => notifications.cancelNudge(key),
+    (session) => getAgentConversation(session),
     registry,
-  })));
+  )));
 
   // ---- steer_subagent tool ----
 
-  pi.registerTool(defineTool(createSteerTool({
-    getRecord: (id) => manager.getRecord(id),
-    emitEvent: (name, data) => pi.events.emit(name, data),
-    steerAgent: (session, message) => steerAgent(session, message),
-    queueSteer: (id, message) => manager.queueSteer(id, message),
-  })));
+  pi.registerTool(defineTool(createSteerTool(
+    (id) => manager.getRecord(id),
+    (name, data) => pi.events.emit(name, data),
+    (session, message) => steerAgent(session, message),
+    (id, message) => manager.queueSteer(id, message),
+  )));
 
   // ---- /agents interactive menu ----
 
@@ -249,7 +249,7 @@ export default function (pi: ExtensionAPI) {
     manager: {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(buildParentSnapshot(ctx), type, prompt, opts),
+      spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
     },
     registry,
     agentActivity: runtime.agentActivity,
@@ -270,6 +270,12 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerCommand('agents', {
     description: 'Manage agents',
-    handler: async (_args, ctx) => { await agentsMenuHandler(ctx); },
+    handler: async (_args, ctx) => {
+      await agentsMenuHandler({
+        ui: ctx.ui,
+        modelRegistry: ctx.modelRegistry,
+        parentSnapshot: buildParentSnapshot(ctx),
+      });
+    },
   });
 }