@gotgenes/pi-subagents 18.0.1 → 18.0.3

package/docs/plans/0052-remove-scheduled-subagents.md

@@ -1,133 +0,0 @@
----
-issue: 52
-issue_title: "feat: remove in-process scheduled subagents"
----
-
-# Remove in-process scheduled subagents
-
-## Problem Statement
-
-The scheduling subsystem reimplements OS-level cron inside a process that is not designed to be a long-lived daemon.
-System cron (or launchd) invoking `pi` directly is strictly superior: it survives crashes and reboots, is inspectable via `crontab -l`, and adds zero lines of code to this extension.
-The current implementation weighs ~610 source lines plus ~820 test lines, a `croner` dependency, PID-locked file persistence, and scheduler lifecycle wiring scattered across `index.ts`.
-
-## Goals
-
-- Delete the three scheduling source files (`schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts`).
-- Delete the three scheduling test files (`schedule.test.ts`, `schedule-store.test.ts`, `schedule-e2e.test.ts`).
-- Remove all scheduler wiring from `index.ts` (~200 lines of imports, lifecycle hooks, tool-schema gates, and menu routing).
-- Remove `ScheduledSubagent` and `ScheduleStoreData` interfaces from `types.ts`.
-- Remove `schedulingEnabled` from `SubagentsSettings`, `SettingsAppliers`, and related sanitize/apply logic in `settings.ts`.
-- Remove the `croner` dependency from `package.json`.
-- Update `README.md` (remove "Scheduling" section and events-table rows) and package `AGENTS.md` (remove scheduling modules from architecture diagram and tables).
-- This is a **breaking change** (`feat!:`) — the `schedule` parameter is removed from the `Agent` tool, and the `subagents:scheduled` / `subagents:scheduler_ready` events are no longer emitted.
-
-## Non-Goals
-
-- Removing `bypassQueue` from `SpawnOptions` in `agent-manager.ts` — it remains useful for cross-extension RPC callers.
-- Removing other subsystems slated for removal in the architecture doc (output-file, cross-extension-rpc, group-join) — those are separate issues.
-- Providing a migration path or compatibility shim — no known consumers depend on the scheduling events.
-
-## Background
-
-The architecture doc (`docs/architecture/architecture.md`) already marks `schedule.ts`, `schedule-store.ts`, and `ui/schedule-menu.ts` as `← removing`.
-This issue executes that plan.
-
-The scheduling code touches `index.ts` in several distinct regions:
-
-1. Imports (lines 27–28, 46)
-2. Scheduler instance creation and `startScheduler()` helper (lines 445–462)
-3. Lifecycle hooks: `session_start`, `session_before_switch`, `session_shutdown` (lines 470–496)
-4. The `schedule` tool-schema param shape, conditional inclusion, and guideline string (lines 621–640, 666, 719)
-5. Schedule execution path in the Agent tool handler (lines 880–918)
-6. `/agents` menu: "Scheduled jobs" entry and routing (lines 1297–1327)
-7. `/agents → Settings → Scheduling` toggle (lines 1855–1867)
-
-The `settings.ts` module has `schedulingEnabled` woven into `SubagentsSettings`, `SettingsAppliers`, `sanitize()`, and `applySettings()`.
-
-`types.ts` carries `ScheduledSubagent` (30 lines) and `ScheduleStoreData` (5 lines) — both are only consumed by the scheduling subsystem.
-
-## Design Overview
-
-This is a pure deletion change with no new abstractions.
-The approach is inside-out: delete leaf modules first (no dependents), then remove references from the wiring layer (`index.ts`, `settings.ts`, `types.ts`), then clean up docs.
-
-The `bypassQueue` option on `SpawnOptions` stays — its JSDoc comment mentioning "scheduler" should be updated to a generic description since the scheduler is the only current user but the option is architecturally useful for any caller that needs to skip the concurrency queue.
-
-## Module-Level Changes
-
-### Delete
-
-| File                          | Lines |
-| ----------------------------- | ----- |
-| `src/schedule.ts`             | 365   |
-| `src/schedule-store.ts`       | 143   |
-| `src/ui/schedule-menu.ts`     | 104   |
-| `test/schedule.test.ts`       | 429   |
-| `test/schedule-store.test.ts` | 154   |
-| `test/schedule-e2e.test.ts`   | 237   |
-
-### Modify
-
-| File                                       | Change                                                                                                                                                                                                                                                                       |
-| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/index.ts`                             | Remove scheduler imports, instance creation, `startScheduler()`, lifecycle hooks, `scheduleParamShape`/`scheduleParam`/`scheduleGuideline`, schedule execution path in Agent handler, "Scheduled jobs" menu entry + routing, "Scheduling" settings toggle.                   |
-| `src/types.ts`                             | Remove `ScheduledSubagent` interface and `ScheduleStoreData` interface.                                                                                                                                                                                                      |
-| `src/settings.ts`                          | Remove `schedulingEnabled` from `SubagentsSettings` and `SettingsAppliers`. Remove sanitize clause and `applySettings` clause for `schedulingEnabled`.                                                                                                                       |
-| `src/agent-manager.ts`                     | Update `bypassQueue` JSDoc to remove scheduler-specific language.                                                                                                                                                                                                            |
-| `package.json`                             | Remove `"croner": "^10.0.1"` from dependencies.                                                                                                                                                                                                                              |
-| `README.md`                                | Remove "Scheduling" feature bullet, "Scheduling" subsection (lines 66–96), and `subagents:scheduled` / `subagents:scheduler_ready` rows from the events table.                                                                                                               |
-| `.pi/skills/package-pi-subagents/SKILL.md` | Remove `schedule.ts`, `schedule-store.ts`, `ui/schedule-menu.ts` from the architecture diagram and module tables. Update `index.ts` description to drop scheduler mention. (`packages/pi-subagents/AGENTS.md` is a stub — the architecture content lives in the skill file.) |
-
-## Test Impact Analysis
-
-1. No new unit tests are needed — this is pure deletion.
-2. All three scheduling test files (`schedule.test.ts`, `schedule-store.test.ts`, `schedule-e2e.test.ts`) become entirely redundant and are deleted.
-3. Existing tests for `agent-manager`, `agent-runner`, `settings`, and other modules stay as-is.
-   The `settings.test.ts` file (if it exists) may need minor updates to remove `schedulingEnabled` from fixture data.
-
-## TDD Order
-
-Since this is a removal (not a feature), the order is deletion-first with a single validation pass.
-
-1. **Delete scheduling source files.**
-   Delete `src/schedule.ts`, `src/schedule-store.ts`, `src/ui/schedule-menu.ts`.
-   Delete `test/schedule.test.ts`, `test/schedule-store.test.ts`, `test/schedule-e2e.test.ts`.
-   Commit: `feat!: remove scheduled subagents source and tests`
-
-2. **Remove scheduler wiring from `index.ts`.**
-   Remove imports, scheduler instance, `startScheduler()`, lifecycle hooks, schedule-related tool schema params and guideline, schedule execution path in Agent handler, "Scheduled jobs" menu entry/routing, and "Scheduling" settings toggle.
-   Commit: `feat!: remove scheduler wiring from index.ts`
-
-3. **Clean up types and settings.**
-   Remove `ScheduledSubagent` and `ScheduleStoreData` from `types.ts`.
-   Remove `schedulingEnabled` from `SubagentsSettings`, `SettingsAppliers`, `sanitize()`, and `applySettings()` in `settings.ts`.
-   Update `bypassQueue` JSDoc in `agent-manager.ts`.
-   Commit: `feat!: remove scheduling types and settings`
-
-4. **Remove `croner` dependency.**
-   Remove from `package.json`, run `pnpm install` to update lockfile.
-   Commit: `build: remove croner dependency`
-
-5. **Verify all tests pass.**
-   Run `pnpm vitest run` in the package.
-   Fix any test fixtures that reference `schedulingEnabled` or scheduling types.
-   Commit (if fixes needed): `test: remove scheduling references from test fixtures`
-
-6. **Update documentation.**
-   Update `README.md`: remove scheduling feature bullet, "Scheduling" subsection, and event-table rows.
-   Update package `AGENTS.md`: remove scheduling modules from architecture diagram and module tables, update `index.ts` description.
-   Commit: `docs: remove scheduling from README and AGENTS`
-
-## Risks and Mitigations
-
-| Risk                                             | Mitigation                                                                                                                         |
-| ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
-| Missed scheduling reference causes compile error | `grep -rn 'schedule\|Schedule\|croner' src/` after each step to catch stragglers. TypeScript `noEmit` check catches import errors. |
-| Test fixtures reference `schedulingEnabled`      | Step 5 explicitly scans for and fixes these.                                                                                       |
-| `bypassQueue` removal mistakenly included        | Explicitly excluded in Non-Goals; plan preserves the option and only updates its JSDoc.                                            |
-| Breaking change not communicated                 | `feat!:` commit prefix triggers a major version bump via release-please.                                                           |
-
-## Open Questions
-
-None — the issue scope is fully specified and the architecture doc already ratified this removal.

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

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

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