@gotgenes/pi-subagents 4.0.0 → 4.1.1

package/CHANGELOG.md

@@ -5,6 +5,32 @@ 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).
 
+## [4.1.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v4.1.0...pi-subagents-v4.1.1) (2026-05-18)
+
+
+### Documentation
+
+* plan decompose index.ts into tool + menu modules ([#54](https://github.com/gotgenes/pi-packages/issues/54)) ([7adf954](https://github.com/gotgenes/pi-packages/commit/7adf954f37800ace0bcc9d5eb65045e2e133e4f2))
+* **retro:** add retro notes for issue [#53](https://github.com/gotgenes/pi-packages/issues/53) ([f8ca910](https://github.com/gotgenes/pi-packages/commit/f8ca9101576eaad8639d1bb2579f0e631a075038))
+
+## [4.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v4.0.0...pi-subagents-v4.1.0) (2026-05-18)
+
+
+### Features
+
+* add resolveInvocationModel to model-resolver ([462b519](https://github.com/gotgenes/pi-packages/commit/462b5194fdfdf86d8d2d166a99472c651e00b76b))
+
+
+### Bug Fixes
+
+* remove quotes from rumdl glob patterns in lint:md script ([a8a0c62](https://github.com/gotgenes/pi-packages/commit/a8a0c62feb2fc45cf68cd7d777259dc159de671b))
+
+
+### Documentation
+
+* plan extract model resolution from Agent.execute ([#53](https://github.com/gotgenes/pi-packages/issues/53)) ([4c07a47](https://github.com/gotgenes/pi-packages/commit/4c07a474f9f25043a2fa3a4f2829e97eb9bb7666))
+* **retro:** add retro notes for issue [#48](https://github.com/gotgenes/pi-packages/issues/48) ([f244c04](https://github.com/gotgenes/pi-packages/commit/f244c04c64f768e724e89d77962f2fb63715b998))
+
 ## [4.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v3.0.0...pi-subagents-v4.0.0) (2026-05-17)
 
 

package/docs/plans/0053-extract-model-resolution-from-execute.md

@@ -0,0 +1,181 @@
+---
+issue: 53
+issue_title: "refactor: extract model resolution from Agent.execute"
+---
+
+# Extract model resolution from Agent.execute
+
+## Problem Statement
+
+The `Agent` tool's `execute` callback in `index.ts` contains inline model-resolution logic (~lines 660–670) that determines which model an agent runs with.
+This block checks `resolvedConfig.modelInput`, calls `resolveModel()`, distinguishes error strings from resolved model instances, and silently falls back to the parent model for config-specified models that fail resolution.
+The logic is not independently testable — it is only exercised through integration-level agent spawning.
+
+A second, simpler call site in `getModelLabel()` (~line 1043) also calls `resolveModel()` inline but only checks whether the model resolves; it does not need the same fallback semantics.
+
+## Goals
+
+- Extract the inline model-resolution block from `Agent.execute` into a named, unit-testable function in `model-resolver.ts`.
+- Keep the existing `resolveModel()` function unchanged — the new function composes it.
+- No behavior change: model-resolution priority and fallback semantics remain identical.
+
+## Non-Goals
+
+- Changing the `resolveModel()` fuzzy-matching algorithm.
+- Refactoring the `getModelLabel()` call site (~line 1043) — it has different semantics (display-only, no fallback) and does not benefit from the same extraction.
+- Refactoring `service-adapter.ts` model resolution — it already uses a clean injected-dependency pattern.
+- Changing any public API surface.
+
+## Background
+
+### Existing modules
+
+| Module                 | Role                                                                                                                                                                                                                                    |
+| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `model-resolver.ts`    | Exports `resolveModel(input, registry)` — returns a `Model` on success or an error string on failure.                                                                                                                                   |
+| `invocation-config.ts` | Exports `resolveAgentInvocationConfig()` — merges tool params with agent config. Returns `modelInput` (the raw string) and `modelFromParams` (whether the string came from tool params vs. agent config).                               |
+| `service-adapter.ts`   | Already receives `resolveModel` as a dependency via `AdapterDeps`. Its model resolution is simpler (always throw on failure).                                                                                                           |
+| `index.ts`             | `Agent.execute` contains the inline block. Uses both `modelInput` and `modelFromParams` to decide: (a) return error to user if params-specified model fails, or (b) silently fall back to parent model if config-specified model fails. |
+
+### Relevant constraint from AGENTS.md
+
+> Keep modules focused and composable (one concern per file).
+
+The new function belongs in `model-resolver.ts` alongside `resolveModel()` since it composes the latter with invocation-level fallback policy.
+
+## Design Overview
+
+### New function signature
+
+```typescript
+interface ModelResolutionResult {
+  model: unknown;
+  error?: undefined;
+}
+
+interface ModelResolutionError {
+  model?: undefined;
+  error: string;
+}
+
+type ModelResolution = ModelResolutionResult | ModelResolutionError;
+
+function resolveInvocationModel(
+  parentModel: unknown,
+  modelInput: string | undefined,
+  modelFromParams: boolean,
+  registry: ModelRegistry,
+): ModelResolution;
+```
+
+### Decision model
+
+The function encapsulates the existing three-branch logic:
+
+1. **No `modelInput`** → return `{ model: parentModel }` (inherit parent).
+2. **`modelInput` resolves** → return `{ model: resolved }`.
+3. **`modelInput` fails to resolve**:
+   - If `modelFromParams` (user typed it) → return `{ error: errorMessage }` so the caller can surface it.
+   - If `!modelFromParams` (agent config specified it) → return `{ model: parentModel }` (silent fallback).
+
+### Result shape rationale
+
+A discriminated union (`ModelResolution`) with `model` and `error` fields avoids the existing `typeof resolved === "string"` type-narrowing smell.
+The caller in `index.ts` becomes:
+
+```typescript
+const resolution = resolveInvocationModel(
+  ctx.model,
+  resolvedConfig.modelInput,
+  resolvedConfig.modelFromParams,
+  ctx.modelRegistry,
+);
+if (resolution.error) return textResult(resolution.error);
+const model = resolution.model;
+```
+
+### Edge cases
+
+- `modelInput` is `undefined` → short-circuit, return parent model.
+- `modelInput` is an empty string → delegates to `resolveModel()`, which currently matches vacuously (documented in existing tests); no change in behavior.
+
+## Module-Level Changes
+
+### `src/model-resolver.ts`
+
+- Add `ModelResolutionResult`, `ModelResolutionError`, and `ModelResolution` type exports.
+- Add `resolveInvocationModel()` export.
+- No changes to existing `resolveModel()`, `ModelEntry`, or `ModelRegistry`.
+
+### `src/index.ts`
+
+- Update import to include `resolveInvocationModel`.
+- Replace the inline model-resolution block in `Agent.execute` (~lines 660–670) with a call to `resolveInvocationModel()` and a check on the result.
+- Remove the now-unused destructuring of `modelFromParams` from `resolvedConfig` at the call site (it is consumed internally by `resolveInvocationModel` via the parameter).
+
+### `test/model-resolver.test.ts`
+
+- Add a new `describe("resolveInvocationModel")` block with tests covering all three branches plus edge cases.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+The extraction enables direct testing of the three-branch fallback logic (inherit, resolve, fallback-on-config-failure) that was previously only exercisable through full agent spawning.
+Specifically:
+
+- Parent model inheritance when no `modelInput` is provided.
+- Successful resolution returns the resolved model.
+- User-specified model failure returns an error.
+- Config-specified model failure silently falls back to parent.
+
+### Existing tests that stay as-is
+
+- All existing `resolveModel` tests in `test/model-resolver.test.ts` — they test the lower-level function which is unchanged.
+- Integration-level tests in `test/agent-runner.test.ts` and `test/agent-manager.test.ts` — they exercise model usage through the full agent lifecycle.
+- `test/invocation-config.test.ts` — unchanged module.
+- `test/service-adapter.test.ts` — uses its own injected `resolveModel` dependency, unaffected.
+
+### Tests that become redundant
+
+None.
+The inline block was not directly tested anywhere — it was only reached through integration paths that test much more than model resolution.
+
+## TDD Order
+
+1. **Red → Green: parent model inheritance.**
+   Test: `resolveInvocationModel` returns `{ model: parentModel }` when `modelInput` is `undefined`.
+   Commit: `test: add resolveInvocationModel tests for parent model inheritance`
+
+2. **Red → Green: successful model resolution.**
+   Test: returns `{ model: resolvedModel }` when `resolveModel` succeeds (both params-specified and config-specified).
+   Commit: `test: add resolveInvocationModel tests for successful resolution`
+
+3. **Red → Green: user-specified model failure.**
+   Test: returns `{ error: message }` when `modelFromParams` is `true` and `resolveModel` returns an error string.
+   Commit: `test: add resolveInvocationModel tests for param model failure`
+
+4. **Red → Green: config-specified model silent fallback.**
+   Test: returns `{ model: parentModel }` when `modelFromParams` is `false` and `resolveModel` returns an error string.
+   Commit: `test: add resolveInvocationModel tests for config model fallback`
+
+5. **Green: implement `resolveInvocationModel` in `model-resolver.ts`.**
+   All four test cases go green.
+   Commit: `feat: add resolveInvocationModel to model-resolver`
+
+6. **Refactor: replace inline block in `index.ts`.**
+   Replace the inline model-resolution block in `Agent.execute` with a call to `resolveInvocationModel`.
+   Run full test suite to confirm no regressions.
+   Commit: `refactor: use resolveInvocationModel in Agent.execute (#53)`
+
+## Risks and Mitigations
+
+| Risk                                                                                   | Mitigation                                                                                                                                                                                         |
+| -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Subtle behavior difference in the extracted function vs. the inline block              | TDD steps 1–4 encode the exact current semantics; step 6 is a pure mechanical substitution.                                                                                                        |
+| `resolveModel` return type is `any \| string` — fragile narrowing                      | The new function encapsulates the `typeof` check behind a discriminated union, reducing but not eliminating the `any`. Fixing the `any` is out of scope (would require Pi SDK model type changes). |
+| Second call site (`getModelLabel`) might seem like it should also use the new function | Explicitly listed as a non-goal — it has display-only semantics with no fallback behavior.                                                                                                         |
+
+## Open Questions
+
+None — the extraction is mechanical and the issue's acceptance criteria are unambiguous.

package/docs/plans/0054-decompose-index-into-modules.md

@@ -0,0 +1,302 @@
+---
+issue: 54
+issue_title: "refactor: decompose src/index.ts into tool + menu modules"
+---
+
+# Decompose index.ts into tool and menu modules
+
+## Problem Statement
+
+`src/index.ts` is 1,619 lines — the single largest file in the codebase.
+It currently holds the extension entrypoint, all three tool definitions (with full execute callbacks and render functions), the custom message renderer, the entire `/agents` interactive menu with all sub-menus, the notification/nudge system, widget and lifecycle wiring, and ~130 lines of helper functions.
+None of this code is independently testable — it is all nested inside a single default export closure.
+
+## Goals
+
+- Extract each tool definition into its own module under `src/tools/`.
+- Extract the `/agents` menu and all sub-handlers into `src/ui/agent-menu.ts`.
+- Extract the notification message renderer into `src/renderer.ts`.
+- Extract the completion notification system into `src/notification.ts`.
+- Extract shared pure helpers into `src/tools/helpers.ts`.
+- Reduce `index.ts` to a thin wire-up (~120–150 lines) that imports and assembles pieces.
+- Enable unit testing of each extracted module via narrow dependency interfaces.
+- No behavior change — pure extraction refactoring.
+
+## Non-Goals
+
+- Refactoring `agent-manager.ts`, `agent-runner.ts`, or other already-separate modules.
+- Adding new features or changing tool behavior.
+- Writing exhaustive test suites for every extracted module — establish foundational coverage, not completeness.
+- Changing any public API surface (`service.ts` exports, `SubagentsService` interface).
+
+## Background
+
+### Current structure
+
+Everything lives inside one `export default function (pi: ExtensionAPI)` closure.
+State (`agentActivity`, `pendingNudges`, `widget`, `manager`, `currentCtx`) is declared as closure variables.
+Helper functions, tool definitions, menu handlers, and lifecycle hooks are all defined in the same scope.
+The only existing test files cover modules that were already separate (`agent-manager.test.ts`, `agent-runner.test.ts`, etc.) — there is no `index.test.ts`.
+
+### Architecture reference
+
+The SKILL's module dependency graph already shows `tools` and `ui/` as conceptual sub-trees under `index.ts`:
+
+```text
+index.ts ──wires──> agent-manager.ts
+    ├── tools (Agent, get_subagent_result, steer_subagent)
+    ├── ui/
+    │   ├── agent-widget.ts
+    │   └── conversation-viewer.ts
+    └── ...
+```
+
+This plan makes that conceptual structure physical.
+
+### Relevant constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Prefer small, reversible changes.
+- Keep Pi SDK imports out of business-logic modules — tool modules are at the SDK boundary and may import SDK types; pure helpers must not.
+- Narrow interfaces per consumer — do not pass a shared dependency bag when a function only uses a subset.
+
+### Helper usage trace
+
+Traced every helper function in `index.ts` to determine where it belongs:
+
+| Helper                     | Used by                                                   | Destination           |
+| -------------------------- | --------------------------------------------------------- | --------------------- |
+| `textResult`               | All three tools                                           | `tools/helpers.ts`    |
+| `formatLifetimeTokens`     | All three tools + completion callback                     | `tools/helpers.ts`    |
+| `getModelLabelFromConfig`  | `buildTypeListText` (agent tool) + `getModelLabel` (menu) | `tools/helpers.ts`    |
+| `createActivityTracker`    | Agent tool execute (foreground + background)              | `tools/agent-tool.ts` |
+| `buildDetails`             | Agent tool execute                                        | `tools/agent-tool.ts` |
+| `getStatusNote`            | Agent tool execute                                        | `tools/agent-tool.ts` |
+| `escapeXml`                | `formatTaskNotification`                                  | `notification.ts`     |
+| `getStatusLabel`           | `formatTaskNotification`                                  | `notification.ts`     |
+| `formatTaskNotification`   | `emitIndividualNudge`                                     | `notification.ts`     |
+| `buildNotificationDetails` | `emitIndividualNudge`                                     | `notification.ts`     |
+| `buildEventData`           | Completion callback                                       | `notification.ts`     |
+
+## Design Overview
+
+### Extraction strategy
+
+Each module exports a **factory function** that receives narrow dependencies and returns the tool definition, handler, or system object.
+This follows the established pattern in the codebase (`createSubagentsService` in `service-adapter.ts` already uses this approach).
+Factory functions keep state scoped to the instance (matching the current closure scope) and make dependencies explicit for testing.
+
+### New module tree
+
+```text
+src/
+├── index.ts               ← thin wire-up (~120-150 lines)
+├── renderer.ts            ← notification message renderer
+├── notification.ts        ← completion notification system
+├── tools/
+│   ├── helpers.ts         ← shared pure helpers (textResult, formatLifetimeTokens, etc.)
+│   ├── agent-tool.ts      ← Agent tool definition + agent-specific helpers
+│   ├── get-result-tool.ts ← get_subagent_result tool definition
+│   └── steer-tool.ts      ← steer_subagent tool definition
+├── ui/
+│   ├── agent-menu.ts      ← /agents menu + all sub-handlers (NEW)
+│   ├── agent-widget.ts    (existing, unchanged)
+│   └── conversation-viewer.ts  (existing, unchanged)
+└── ... (other existing modules unchanged)
+```
+
+### Dependency design
+
+Each factory receives only the methods it calls — not the full `AgentManager`, `AgentWidget`, or `ExtensionAPI`.
+Example narrow interface for the get-result tool:
+
+```typescript
+interface GetResultDeps {
+  getRecord: (id: string) => AgentRecord | undefined;
+  cancelNudge: (key: string) => void;
+  agentActivity: ReadonlyMap<string, AgentActivity>;
+}
+```
+
+The Agent tool has more dependencies but they remain enumerable — each one maps to a specific method or value the execute callback calls.
+
+### Notification system
+
+The nudge/notification helpers (`scheduleNudge`, `cancelNudge`, `emitIndividualNudge`, `sendIndividualNudge`) and their associated formatters (`formatTaskNotification`, `buildNotificationDetails`, `buildEventData`, `escapeXml`, `getStatusLabel`) form a cohesive unit.
+They move to `notification.ts` as a factory:
+
+```typescript
+export function createNotificationSystem(deps: NotificationDeps): NotificationSystem;
+
+interface NotificationSystem {
+  cancelNudge: (key: string) => void;
+  sendCompletion: (record: AgentRecord) => void;
+  cleanupCompleted: (id: string) => void;
+  buildEventData: (record: AgentRecord) => object;
+  dispose: () => void;
+}
+```
+
+The completion callback in `index.ts` becomes a thin orchestrator (~15 lines) that calls `notifications.buildEventData()`, emits lifecycle events, persists the record, and delegates to `notifications.sendCompletion()`.
+
+### What remains in index.ts
+
+After all extractions, `index.ts` retains only:
+
+1. Imports and default export declaration.
+2. `reloadCustomAgents` helper and initial load call.
+3. `agentActivity` map creation.
+4. `createNotificationSystem()` call.
+5. `AgentManager` construction with completion/started/compacted callbacks (~20 lines).
+6. Service creation and publishing.
+7. Lifecycle hooks (`session_start`, `session_before_switch`, `session_shutdown`).
+8. Widget creation and `tool_execution_start` handler.
+9. `buildTypeListText` computation.
+10. Settings application.
+11. Three `pi.registerTool()` calls (importing factories).
+12. `pi.registerCommand("agents", ...)` call.
+
+## Module-Level Changes
+
+### `src/tools/helpers.ts` (new)
+
+- `textResult(msg, details?)` — tool execute return value builder.
+- `formatLifetimeTokens(record)` — format lifetime token total.
+- `getModelLabelFromConfig(model)` — strip provider prefix and date suffix from model string.
+
+### `src/renderer.ts` (new)
+
+- `registerNotificationRenderer(registerFn)` — accepts `pi.registerMessageRenderer` and registers the `"subagent-notification"` renderer.
+- Contains the full `renderOne` formatting logic currently inline in the `registerMessageRenderer` callback.
+
+### `src/notification.ts` (new)
+
+- `createNotificationSystem(deps)` factory — returns `NotificationSystem`.
+- Contains: `scheduleNudge`, `cancelNudge`, `emitIndividualNudge`, `sendIndividualNudge`, `formatTaskNotification`, `buildNotificationDetails`, `buildEventData`, `escapeXml`, `getStatusLabel`.
+- Deps interface: narrow accessors for `sendMessage`, `agentActivity`, `widget.markFinished`, `widget.update`.
+
+### `src/tools/agent-tool.ts` (new)
+
+- `createAgentTool(deps)` factory — returns the tool definition config object.
+- Contains: `renderCall`, `renderResult`, `execute`, plus agent-tool-specific helpers (`createActivityTracker`, `buildDetails`, `getStatusNote`).
+- Deps interface: narrow accessors for manager spawn/wait, widget lifecycle, activity map, event emission, output file wiring, type list text, and `reloadCustomAgents`.
+
+### `src/tools/get-result-tool.ts` (new)
+
+- `createGetResultTool(deps)` factory — returns the tool definition config object.
+- Deps: `getRecord`, `cancelNudge`, `agentActivity`.
+
+### `src/tools/steer-tool.ts` (new)
+
+- `createSteerTool(deps)` factory — returns the tool definition config object.
+- Deps: `getRecord`, `emitEvent`.
+
+### `src/ui/agent-menu.ts` (new)
+
+- `createAgentsMenuHandler(deps)` factory — returns the `/agents` command handler.
+- Contains all menu functions: `showAgentsMenu`, `showAllAgentsList`, `showRunningAgents`, `viewAgentConversation`, `showAgentDetail`, `ejectAgent`, `disableAgent`, `enableAgent`, `showCreateWizard`, `showGenerateWizard`, `showManualWizard`, `showSettings`, `notifyApplied`, `findAgentFile`, `getModelLabel`.
+- Deps: manager list/get methods, `reloadCustomAgents`, `agentActivity`, settings snapshot/save functions, event emission, and `pi` (for generate wizard spawning).
+
+### `src/index.ts` (modified — shrinks from ~1,619 to ~120–150 lines)
+
+- Remove all helper function definitions.
+- Remove all tool definitions.
+- Remove all menu handler functions.
+- Remove renderer registration logic.
+- Remove nudge/notification helpers.
+- Add imports from new modules.
+- Wire everything together: create deps, call factories, register tools/commands/lifecycle hooks.
+
+## Test Impact Analysis
+
+### New unit tests enabled by extraction
+
+The decomposition enables direct testing of code that was previously locked inside the closure:
+
+- `test/tools/helpers.test.ts` — `textResult`, `formatLifetimeTokens`, `getModelLabelFromConfig` with edge cases (zero tokens, empty model strings).
+- `test/renderer.test.ts` — notification renderer formatting for each status (completed, error, stopped, steered, aborted) in collapsed and expanded modes.
+- `test/notification.test.ts` — nudge scheduling/cancellation timing, `buildEventData` shape, `formatTaskNotification` XML output, `buildNotificationDetails` field mapping.
+- `test/tools/get-result-tool.test.ts` — execute paths: agent not found, wait-for-completion, result-consumed suppression, verbose conversation inclusion.
+- `test/tools/steer-tool.test.ts` — execute paths: agent not found, not running, session not ready (queued steer), successful steer.
+- `test/tools/agent-tool.test.ts` — execute paths: foreground completion, background launch, resume, unknown type fallback, model resolution error.
+- `test/ui/agent-menu.test.ts` — menu navigation, settings mutation, eject/disable/enable flows with mock UI context.
+
+### Existing tests that become redundant
+
+None.
+There are no existing tests for `index.ts` — the extraction creates test coverage where none existed.
+
+### Existing tests that stay as-is
+
+All 21 existing test files are unaffected.
+They test modules (`agent-manager`, `agent-runner`, `model-resolver`, `invocation-config`, `service-adapter`, etc.) that are not touched by this refactoring.
+
+## TDD Order
+
+Each step is a self-contained extraction + test cycle.
+The existing test suite (362+ tests) runs after each step as a regression safety net.
+
+1. **Extract `src/tools/helpers.ts` — shared pure helpers.**
+   Move `textResult`, `formatLifetimeTokens`, `getModelLabelFromConfig` to new module.
+   Update `index.ts` imports.
+   Write `test/tools/helpers.test.ts` covering each function.
+   Commit: `refactor: extract shared tool helpers to tools/helpers`
+
+2. **Extract `src/renderer.ts` — notification message renderer.**
+   Move renderer callback to `registerNotificationRenderer` export.
+   Update `index.ts` to call the new function.
+   Write `test/renderer.test.ts` covering status-dependent formatting.
+   Commit: `refactor: extract notification renderer to renderer module`
+
+3. **Extract `src/notification.ts` — completion notification system.**
+   Move nudge system + formatters to `createNotificationSystem` factory.
+   Update `index.ts` completion callback to use the notification system.
+   Write `test/notification.test.ts` covering nudge timing and event data.
+   Commit: `refactor: extract notification system to notification module`
+
+4. **Extract `src/tools/get-result-tool.ts` — get_subagent_result tool.**
+   Move tool definition to `createGetResultTool` factory with narrow deps.
+   Update `index.ts` to call factory and register.
+   Write `test/tools/get-result-tool.test.ts` covering execute paths.
+   Commit: `refactor: extract get_subagent_result tool`
+
+5. **Extract `src/tools/steer-tool.ts` — steer_subagent tool.**
+   Move tool definition to `createSteerTool` factory with narrow deps.
+   Update `index.ts`.
+   Write `test/tools/steer-tool.test.ts` covering execute paths.
+   Commit: `refactor: extract steer_subagent tool`
+
+6. **Extract `src/tools/agent-tool.ts` — Agent tool.**
+   Move tool definition + agent-specific helpers (`createActivityTracker`, `buildDetails`, `getStatusNote`) to `createAgentTool` factory.
+   Update `index.ts`.
+   Write `test/tools/agent-tool.test.ts` covering foreground, background, resume, and error paths.
+   Commit: `refactor: extract Agent tool`
+
+7. **Extract `src/ui/agent-menu.ts` — /agents menu handlers.**
+   Move all menu functions to `createAgentsMenuHandler` factory.
+   Update `index.ts` to register command with factory result.
+   Write `test/ui/agent-menu.test.ts` covering key menu navigation flows.
+   Commit: `refactor: extract /agents menu handlers`
+
+8. **Final index.ts cleanup.**
+   Remove any dead imports or vestigial code.
+   Verify index.ts is ~120–150 lines of pure wire-up.
+   Run `pnpm run check` (typecheck) and full test suite.
+   Commit: `refactor: slim index.ts to wire-up entrypoint (#54)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                          | Mitigation                                                                                                                                                                                                                                    |
+| ----------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Closure variable access breaks after extraction — helpers currently close over shared maps (`agentActivity`, `pendingNudges`) | Factory pattern replaces closure access with explicit dependency injection; each factory's deps interface enumerates exactly what it needs.                                                                                                   |
+| Narrow dep interfaces diverge from the real objects — test mocks pass but runtime breaks                                      | Run `pnpm run check` (typecheck) after each extraction step; the factory call sites in `index.ts` provide real objects whose types must satisfy the narrow interfaces.                                                                        |
+| Large number of extraction steps creates merge-conflict risk with parallel PRs                                                | Steps are ordered leaf-first so earlier commits don't touch files later steps modify. Each step is independently committable and revertable.                                                                                                  |
+| Agent tool factory has many deps (~8–10) — risks becoming a dependency bag                                                    | Deps are individual functions and values, not a monolithic object. Each dep maps to exactly one method call in execute. If the count feels excessive during implementation, group by concern (spawn, widget, events) into 2–3 sub-interfaces. |
+| `buildTypeListText` is called at init time and captures agent types — extraction might change when it runs                    | `buildTypeListText` stays in `index.ts` as wire-up code (called once, result passed to agent tool factory). Timing is unchanged.                                                                                                              |
+
+## Open Questions
+
+- Should the notification module also own the lifecycle event emission (`subagents:completed`, `subagents:failed`, `subagents:started`, `subagents:compacted`), or should those stay in the completion callback in `index.ts`?
+  Defer until step 3 — the answer depends on whether the completion callback shrinks enough to justify the move.
+- Should `buildTypeListText` move into `agent-tool.ts` or stay as wire-up in `index.ts`?
+  Defer until step 6 — evaluate once the agent tool factory interface is concrete.

package/docs/retro/0053-extract-model-resolution-from-execute.md

@@ -0,0 +1,30 @@
+---
+issue: 53
+issue_title: "refactor: extract model resolution from Agent.execute"
+---
+
+# Retro: #53 — extract model resolution from Agent.execute
+
+## Final Retrospective (2026-05-17T21:00:00Z)
+
+### Session summary
+
+Planned and executed the extraction of inline model-resolution logic from `Agent.execute` in `index.ts` into a new `resolveInvocationModel()` function in `model-resolver.ts`.
+Released as `pi-subagents-v4.1.0` with +10 new unit tests and no behavior change.
+Also fixed a pre-existing `rumdl` glob-quoting bug in `package.json` discovered during the lint step.
+
+### Observations
+
+#### What went well
+
+- Pre-existing lint bug surfaced and fixed: the `rumdl check '*.md' 'docs/**/*.md'` command in `package.json` used single-quoted globs that prevented shell expansion. Verified as pre-existing (reproduced on prior commit via `git stash`), cleanly isolated into its own `fix:` commit. This was a genuine find — the lint had been silently broken.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In step 6 (refactoring `index.ts`), replaced the `resolveModel` import with `resolveInvocationModel` without first checking whether `resolveModel` was still used elsewhere in the file. Two other call sites (`createSubagentsService` at line 386 and `getModelLabel` at line 1043) still needed it. The plan explicitly listed `getModelLabel` as a non-goal that continues using `resolveModel`, so the information was available. Caught immediately via `grep` after the edit and fixed in the same commit. Impact: one extra edit + grep cycle, no rework.
+
+- `missing-context` — The plan's type definitions specified `model: unknown` for `ModelResolutionResult`, but downstream code in `index.ts` accesses `.id` and `.name` on the model and passes it where `Model<any>` is expected. The plan's risk section flagged this ("reducing but not eliminating the `any`"), yet the implementation went with `unknown` first, requiring a correction after `pnpm run check` failed with 4 type errors. Changed to `model: any` to match the existing `resolveModel` return type. Impact: one extra edit cycle within the same commit, no rework.
+
+#### What caused friction (user side)
+
+- None observed. The issue was well-scoped with clear acceptance criteria, making planning and execution straightforward.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "4.0.0",
+  "version": "4.1.1",
   "exports": {
     ".": "./src/service.ts"
   },
@@ -59,7 +59,7 @@
     "check": "tsc --noEmit",
     "test": "vitest run",
     "test:watch": "vitest",
-    "lint:md": "rumdl check '*.md' 'docs/**/*.md'",
+    "lint:md": "rumdl check *.md docs/**/*.md",
     "lint": "biome check . && pnpm run lint:md"
   }
 }