@gotgenes/pi-subagents 18.0.1 → 18.0.2

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

@@ -1,290 +0,0 @@
----
-issue: 145
-issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
----
-
-# Decompose execute and push ctx to the boundary
-
-## Problem Statement
-
-`agent-tool.ts` `execute` is ~140 lines mixing three concerns: boundary extraction (~5 lines reading `ctx`), config resolution (~60 lines unpacking `resolvedConfig` field by field), and dispatch (~80 lines building 14–16 field parameter bags for `spawnBackground` and `runForeground`).
-The large parameter bags exist because config resolution happens inline instead of in a dedicated function.
-Meanwhile, `ExtensionContext` is threaded from `execute` through `ForegroundParams.ctx` / `BackgroundParams.ctx` into `foreground-runner` and `background-spawner`, where the only thing consumed is `sessionManager.getSessionFile()` and `sessionManager.getSessionId()`.
-`AgentManager.spawn()` and `spawnAndWait()` accept `ExtensionContext` directly and call `buildParentSnapshot(ctx)` internally — but this is already a pure boundary concern that belongs at the call site.
-Additionally, `execute` reaches into `ctx` for model info and session identity — these are session-scoped values that `index.ts` already captures and could inject as collaborators, removing `execute`'s need to read `ctx` beyond the UI context it already delegates to `widget.setUICtx()`.
-
-## Goals
-
-- Extract config resolution into a pure function (`resolveSpawnConfig`) so `execute` becomes: resolve config → dispatch.
-- Inject three missing collaborators into `createAgentTool` so `execute` no longer extracts values from `ctx`:
-  - `buildSnapshot: (inheritContext: boolean) => ParentSnapshot` — closure over `ctx`, wired in `index.ts`.
-  - `getModelInfo: () => ModelInfo` — provides `parentModel` and `modelRegistry` for `resolveSpawnConfig`.
-  - `getSessionInfo: () => { parentSessionFile: string; parentSessionId: string }` — parent session identity.
-- Replace `ForegroundParams.ctx` and `BackgroundParams.ctx` with plain domain values (`parentSessionFile`, `parentSessionId`, `snapshot`).
-- Change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot` instead of `ExtensionContext`.
-- Move `buildParentSnapshot(ctx)` calls to the two boundaries: `index.ts` (via closure) and `service-adapter.ts`.
-- Eliminate the `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`.
-- Apply the dependency bag convention: dissolve `ForegroundDeps`, `BackgroundDeps`, `AdapterDeps` (each ≤3 fields) into plain parameters.
-- This is a breaking internal refactor — no public API changes.
-
-## Non-Goals
-
-- Narrowing menu handler ctx (Step N, #146) — deferred.
-- Injecting text wrapping into ConversationViewer (Step O, #147) — unrelated track.
-- Observation model consolidation (Step L, #144) — independent track.
-- Changing the `SubagentsService` public API in `service.ts`.
-
-## Background
-
-### Relevant modules
-
-| Module                        | Current role                                                                                     |
-| ----------------------------- | ------------------------------------------------------------------------------------------------ |
-| `tools/agent-tool.ts`         | `execute` callback — 140 lines, mixes boundary extraction, config resolution, dispatch           |
-| `tools/foreground-runner.ts`  | `runForeground()` — receives 14-field `ForegroundParams` including `ctx` with `sessionManager`   |
-| `tools/background-spawner.ts` | `spawnBackground()` — receives 14-field `BackgroundParams` including `ctx` with `sessionManager` |
-| `agent-manager.ts`            | `spawn()` / `spawnAndWait()` accept `ExtensionContext`, call `buildParentSnapshot()` internally  |
-| `parent-snapshot.ts`          | `buildParentSnapshot(ctx)` — pure function capturing `ParentSnapshot` from ctx                   |
-| `service-adapter.ts`          | Cross-extension boundary — calls `manager.spawn(session.ctx, ...)`                               |
-| `invocation-config.ts`        | `resolveAgentInvocationConfig()` — merges agent config with tool params                          |
-| `model-resolver.ts`           | `resolveInvocationModel()` — resolves model strings to model instances                           |
-| `index.ts`                    | Extension entry point — wires `createAgentTool` deps, captures `runtime.currentCtx`              |
-| `runtime.ts`                  | `SubagentRuntime` — holds session-scoped mutable state including `currentCtx`                    |
-
-### Constraints from AGENTS.md
-
-- Keep modules focused and composable (one concern per file).
-- Prefer explicit configuration over hidden behavior.
-- Keep Pi SDK imports out of business-logic modules.
-- Business logic should be pure functions — keep IO at the edges.
-
-### Phase 9 context
-
-This is Step M of Phase 9.
-It has no blockers and blocks Step N (#146), which narrows menu handler ctx.
-After this step, `ExtensionContext` appears only at true SDK/extension boundaries: `index.ts` closures, `service-adapter.ts`, and menu handlers.
-
-## Design Overview
-
-### Part 1: Extract config resolution (done)
-
-A new pure function `resolveSpawnConfig` in `spawn-config.ts` encapsulates all config resolution logic previously inline in `execute`.
-`execute` calls `resolveSpawnConfig(params, registry, modelInfo, settings)` and dispatches on the result.
-This is already committed.
-
-### Part 2: Inject collaborators and push ctx out of execute
-
-`execute` currently reads `ctx.model`, `ctx.modelRegistry`, `ctx.sessionManager`, and passes `ctx` to `buildParentSnapshot`.
-These are all session-scoped values that `index.ts` captures at session start.
-Three collaborators replace the `ctx` reads:
-
-```typescript
-// Injected as plain parameters into createAgentTool:
-buildSnapshot: (inheritContext: boolean) => ParentSnapshot,
-getModelInfo: () => ModelInfo,
-getSessionInfo: () => { parentSessionFile: string; parentSessionId: string },
-```
-
-`index.ts` wires them as closures over `runtime.currentCtx`:
-
-```typescript
-createAgentTool({
-  // ... existing params ...
-  buildSnapshot: (inheritContext) => buildParentSnapshot(ctx, inheritContext),
-  getModelInfo: () => ({
-    parentModel: ctx.model,
-    modelRegistry: ctx.modelRegistry,
-  }),
-  getSessionInfo: () => ({
-    parentSessionFile: ctx.sessionManager.getSessionFile(),
-    parentSessionId: ctx.sessionManager.getSessionId(),
-  }),
-})
-```
-
-After this, `execute` touches `ctx` only for `ctx.ui` — which is already delegated via `widget.setUICtx()`.
-The `ExtensionContext` import in `agent-tool.ts` is removed entirely.
-
-### Part 3: Push ctx out of AgentManager
-
-`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
-The internal `buildParentSnapshot(ctx, ...)` call is removed — `snapshot` arrives pre-built from the call sites.
-`service-adapter.ts` calls `buildParentSnapshot(session.ctx, ...)` at its boundary before delegating.
-
-### Part 4: Push ctx out of foreground-runner and background-spawner
-
-`ForegroundParams.ctx` and `BackgroundParams.ctx` are replaced by `snapshot: ParentSnapshot`, `parentSessionFile: string`, `parentSessionId: string`.
-The narrow manager interfaces change from `ctx: any` to `snapshot: ParentSnapshot`.
-
-### Part 5: Shrink params bags with ResolvedSpawnConfig
-
-`ForegroundParams` and `BackgroundParams` carry `ResolvedSpawnConfig` instead of 10+ individual fields that were computed during config resolution.
-Only dispatch-specific fields (`rawType`, `fellBack`, `toolCallId`, `displayName`) remain as separate params fields.
-
-### Part 6: Dissolve small dependency bags
-
-Per the dependency bag convention:
-
-- `ForegroundDeps` (3 fields) → plain parameters on `runForeground`.
-- `BackgroundDeps` (3 fields) → plain parameters on `spawnBackground`.
-- `AdapterDeps` (4 fields) → plain parameters on `createSubagentsService`.
-- `AgentToolDeps` → destructured in the `createAgentTool` signature; the interface stays as a named type for the test factory.
-
-The narrow `*ManagerDeps` and `*WidgetDeps` interfaces stay — they define the contract each function needs from its collaborators.
-
-## Module-Level Changes
-
-### New file: `src/tools/spawn-config.ts` (done)
-
-- `ResolvedSpawnConfig` interface.
-- `ModelInfo` interface.
-- `resolveSpawnConfig()` pure function.
-
-### Modified: `src/tools/agent-tool.ts`
-
-- `execute` shrinks from ~140 to ~20 lines.
-- `ExtensionContext` import removed — `execute` no longer reads `ctx` directly (beyond `ctx.ui` via widget).
-- Three new collaborator parameters: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
-- Calls `resolveSpawnConfig(params, registry, getModelInfo(), settings)`.
-- Calls `buildSnapshot(config.inheritContext)` for the snapshot.
-- Calls `getSessionInfo()` for parent session identity.
-- Passes domain values (not `ctx`) to `runForeground` / `spawnBackground`.
-- `AgentToolManager.spawn` and `spawnAndWait` signatures change to accept `ParentSnapshot`.
-- `AgentToolDeps` stays as a named type (used by test factory) but its fields are destructured in `createAgentTool`.
-
-### Modified: `src/tools/foreground-runner.ts`
-
-- `ForegroundDeps` interface removed — `runForeground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
-- `ForegroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
-- `ForegroundManagerDeps.spawnAndWait` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
-- Individual config fields move into `ResolvedSpawnConfig`.
-
-### Modified: `src/tools/background-spawner.ts`
-
-- `BackgroundDeps` interface removed — `spawnBackground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
-- `BackgroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
-- `BackgroundManagerDeps.spawn` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
-- Individual config fields move into `ResolvedSpawnConfig`.
-
-### Modified: `src/agent-manager.ts`
-
-- `spawn()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
-- `spawnAndWait()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
-- Internal `buildParentSnapshot(ctx, ...)` call removed.
-- Imports of `ExtensionContext` and `buildParentSnapshot` removed.
-
-### Modified: `src/service-adapter.ts`
-
-- `AdapterDeps` interface removed — `createSubagentsService` accepts plain parameters.
-- `AgentManagerLike.spawn` signature changes from `ctx: unknown` to `snapshot: ParentSnapshot`.
-- `spawn()` method calls `buildParentSnapshot(session.ctx, options?.inheritContext)` before delegating.
-- Adds imports of `buildParentSnapshot` and `ParentSnapshot`.
-
-### Modified: `src/index.ts`
-
-- Wiring for `createAgentTool` adds three collaborator closures: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
-- `manager.spawn` / `spawnAndWait` wiring adapters removed (closures no longer need to relay `ctx`).
-- Wiring for `createSubagentsService` changes from bag to plain arguments.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-- `spawn-config.test.ts` (done) — pure-function tests for `resolveSpawnConfig`.
-
-### Existing tests that simplify
-
-- `agent-manager.test.ts` — the `vi.mock("../src/parent-snapshot.js")` block is removed.
-  All tests pass a plain `ParentSnapshot` object directly instead of `mockCtx`.
-- `foreground-runner.test.ts` — `makeCtx()` helper removed; plain strings for session identity.
-- `background-spawner.test.ts` — same as foreground.
-- `agent-tool.test.ts` — `makeCtx()` simplified; collaborator stubs replace `ctx.model` / `ctx.modelRegistry` reads.
-- `service-adapter.test.ts` — adapter test setup changes from bag to plain parameters.
-
-### Existing tests that stay
-
-- `parent-snapshot.test.ts` — unchanged; `buildParentSnapshot` is still a standalone pure function.
-
-## TDD Order
-
-### Step 1: Extract resolveSpawnConfig (done)
-
-1. ~~Write `spawn-config.test.ts`, implement `spawn-config.ts`.~~
-   Commit: `feat: extract resolveSpawnConfig pure function (#145)` ✓
-
-2. ~~Rewire `execute` to call `resolveSpawnConfig`.~~
-   Commit: `refactor: use resolveSpawnConfig in execute (#145)` ✓
-
-### Step 2: Push ctx out of AgentManager
-
-3. Red: update `agent-manager.test.ts` — replace `mockCtx` with a plain `ParentSnapshot` object, remove `vi.mock("../src/parent-snapshot.js")`.
-   Green: change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot`.
-   Update `agent-tool.ts` manager interface, `service-adapter.ts` to call `buildParentSnapshot` at its boundary, and `index.ts` wiring.
-   Commit: `refactor: AgentManager accepts ParentSnapshot instead of ExtensionContext (#145)`
-
-### Step 3: Inject collaborators into createAgentTool
-
-4. Red: update `agent-tool.test.ts` — add `buildSnapshot`, `getModelInfo`, `getSessionInfo` stubs to `createToolDeps`; simplify `makeCtx()`.
-   Green: add three collaborator parameters to `createAgentTool`; rewrite `execute` to use them instead of `ctx.model` / `ctx.modelRegistry` / `ctx.sessionManager`.
-   Remove `ExtensionContext` import from `agent-tool.ts`.
-   Update `index.ts` wiring to provide closures.
-   Commit: `refactor: inject collaborators into createAgentTool, eliminate ctx reads (#145)`
-
-### Step 4: Push ctx out of foreground-runner and background-spawner
-
-5. Red: update `foreground-runner.test.ts` — remove `makeCtx()`, replace `ForegroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
-   Green: change `ForegroundParams` to use plain domain values, update `runForeground` accordingly.
-   Commit: `refactor: foreground-runner receives domain values instead of ctx (#145)`
-
-6. Red: update `background-spawner.test.ts` — remove `makeCtx()`, replace `BackgroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
-   Green: change `BackgroundParams` to use plain domain values, update `spawnBackground` accordingly.
-   Commit: `refactor: background-spawner receives domain values instead of ctx (#145)`
-
-### Step 5: Shrink params bags with ResolvedSpawnConfig
-
-7. Red: update `foreground-runner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
-   Green: change `ForegroundParams` to carry `ResolvedSpawnConfig`.
-   Update `agent-tool.ts` dispatch to pass the config through.
-   Commit: `refactor: ForegroundParams carries ResolvedSpawnConfig (#145)`
-
-8. Red: update `background-spawner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
-   Green: change `BackgroundParams` to carry `ResolvedSpawnConfig`.
-   Update `agent-tool.ts` dispatch to pass the config through.
-   Commit: `refactor: BackgroundParams carries ResolvedSpawnConfig (#145)`
-
-### Step 6: Dissolve small dependency bags
-
-9. Red: update `foreground-runner.test.ts` calls to pass `manager`, `widget`, `agentActivity` as plain args.
-   Green: remove `ForegroundDeps` interface, change `runForeground` signature.
-   Commit: `refactor: dissolve ForegroundDeps into plain parameters (#145)`
-
-10. Red: update `background-spawner.test.ts` calls to pass plain args.
-    Green: remove `BackgroundDeps` interface, change `spawnBackground` signature.
-    Commit: `refactor: dissolve BackgroundDeps into plain parameters (#145)`
-
-11. Red: update `service-adapter.test.ts` to pass plain parameters instead of `AdapterDeps` bag.
-    Green: remove `AdapterDeps` interface, change `createSubagentsService` signature.
-    Update `index.ts` wiring call site.
-    Commit: `refactor: dissolve AdapterDeps into plain parameters (#145)`
-
-12. Refactor: destructure `AgentToolDeps` in `createAgentTool` signature (keep the named type for test factory).
-    Commit: `refactor: destructure AgentToolDeps in createAgentTool (#145)`
-
-### Step 7: Final verification
-
-13. Run full test suite and type check.
-
-## Risks and Mitigations
-
-| Risk                                                                  | Mitigation                                                                                                                                                                      |
-| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Wide blast radius — touches 7+ source files and 5+ test files         | Incremental TDD steps; each commit leaves the repo green                                                                                                                        |
-| `service-adapter.ts` now imports `buildParentSnapshot` — new coupling | Acceptable: the adapter is already a boundary module that bridges `ExtensionContext` to domain types                                                                            |
-| `ResolvedSpawnConfig` could become a new "god object"                 | It is a pure data return from a single function; consumers destructure what they need                                                                                           |
-| Three new collaborators grow `AgentToolDeps` from 6 to 9 fields       | The deps bag is destructured at the signature; the named type exists only for the test factory. The real dependency count stays the same — previously hidden behind `ctx` reads |
-| `index.ts` closures capture `ctx` — stale reference risk              | Same pattern `service-adapter.ts` already uses via `runtime.currentCtx`; session lifecycle clears on shutdown                                                                   |
-
-## Open Questions
-
-- The exact boundary between fields that stay in `ForegroundParams` / `BackgroundParams` vs. fields that move into `ResolvedSpawnConfig` may shift during implementation.
-  The guiding principle: if the field is computed during config resolution, it belongs in `ResolvedSpawnConfig`; if it is dispatch-specific (e.g., `toolCallId`, `signal`, `onUpdate`), it stays in the params type.

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

@@ -1,319 +0,0 @@
----
-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.