@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0080-consolidate-agent-config-lookup.md

@@ -1,247 +0,0 @@
----
-issue: 80
-issue_title: "refactor: consolidate getConfig / getAgentConfig into a single resolution path"
----
-
-# Consolidate agent config lookup into resolveAgentConfig
-
-## Problem Statement
-
-`agent-types.ts` exports two overlapping lookup functions:
-
-- `getConfig(type)` — returns a narrow shape (`displayName`, `description`, `builtinToolNames`, `extensions`, `skills`, `promptMode`) with a guaranteed-non-null fallback chain (unknown → general-purpose → absolute fallback).
-- `getAgentConfig(type)` — returns the full `AgentConfig | undefined`.
-
-Every field `getConfig()` returns also exists on `AgentConfig`.
-Callers that need both must call both and keep them in sync:
-
-```typescript
-const config = getConfig(type);
-const agentConfig = getAgentConfig(type);
-```
-
-This showed up concretely in `session-config.ts` (extracted in #71), where the assembler calls both, then handles the `agentConfig === undefined` fallback separately — duplicating the same fallback chain that `getConfig()` already handles internally.
-Test mocks must also set up both `mockGetConfig` and `mockGetAgentConfig` with compatible values, which is error-prone.
-
-## Goals
-
-- Add a single `resolveAgentConfig(type): AgentConfig` function that returns a guaranteed-non-null `AgentConfig`, handling the fallback chain internally (unknown → general-purpose → absolute fallback).
-- Migrate all callers of `getConfig()` and `getAgentConfig()` to `resolveAgentConfig()`.
-- Remove `getConfig()` and `getAgentConfig()`.
-- Simplify test mocks from two compatible stubs to one.
-
-This is a pure internal refactor — no behavior change, no public API impact (the package's `exports` only expose `service.ts`).
-
-## Non-Goals
-
-- Changing the `AgentConfig` type shape.
-- Refactoring `getToolNamesForType()` (it has its own lookup logic and is a separate concern).
-- Modifying the public API surface (`service.ts`).
-- Changing the fallback semantics (the chain stays: type → general-purpose → absolute fallback).
-
-## Background
-
-### Relevant modules
-
-| Module                | Role                                                                                                                  |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `agent-types.ts`      | Unified agent type registry — owns `getConfig`, `getAgentConfig`, `resolveType`, `getToolNamesForType`, `isValidType` |
-| `session-config.ts`   | Pure configuration assembler — calls both `getConfig` + `getAgentConfig`                                              |
-| `ui/agent-widget.ts`  | Widget rendering — calls `getConfig` via `getDisplayName()` and `getPromptModeLabel()` helpers                        |
-| `index.ts`            | Extension entry point — calls `getAgentConfig` (3 sites) for type listing and model label                             |
-| `tools/agent-tool.ts` | Agent tool handler — calls `getAgentConfig` (1 site) after `resolveType()`                                            |
-| `ui/agent-menu.ts`    | Agent menu UI — calls `getAgentConfig` (5 sites) for listing, detail, and existence checks                            |
-
-### Current caller inventory
-
-Source files that import `getConfig` or `getAgentConfig`:
-
-| File                  | `getConfig` calls | `getAgentConfig` calls | Notes                                         |
-| --------------------- | ----------------- | ---------------------- | --------------------------------------------- |
-| `session-config.ts`   | 1                 | 1                      | Primary motivation; dual-call pattern         |
-| `ui/agent-widget.ts`  | 2 (via helpers)   | 0                      | `getDisplayName()`, `getPromptModeLabel()`    |
-| `index.ts`            | 0                 | 3                      | Iterates known names; `?.` is defensive       |
-| `tools/agent-tool.ts` | 0                 | 1                      | After `resolveType()` — guaranteed to exist   |
-| `ui/agent-menu.ts`    | 0                 | 5                      | 3 iterate known names; 2 are existence guards |
-
-Test files that mock `agent-types.js` with both functions:
-
-| Test file                              | Mocks `getConfig` | Mocks `getAgentConfig` |
-| -------------------------------------- | ----------------- | ---------------------- |
-| `session-config.test.ts`               | ✓                 | ✓                      |
-| `agent-runner.test.ts`                 | ✓                 | ✓                      |
-| `agent-runner-extension-tools.test.ts` | ✓                 | ✓                      |
-
-### Caller migration notes
-
-- **`session-config.ts`**: Replace both calls with one `resolveAgentConfig(type)`.
-  Read `extensions` and `skills` directly from the returned `AgentConfig` instead of the narrow shape.
-  The prompt-building fallback (`agentConfig` null → use `DEFAULT_AGENTS.get("general-purpose")`) collapses into the single call since `resolveAgentConfig` already handles the fallback.
-- **`ui/agent-widget.ts`**: `getDisplayName()` becomes `resolveAgentConfig(type).displayName ?? resolveAgentConfig(type).name` (or cache the result).
-  `getPromptModeLabel()` reads `.promptMode` from the resolved config.
-- **`index.ts`**: All 3 call sites iterate names from `getDefaultAgentNames()` or `getUserAgentNames()` — configs are guaranteed to exist.
-  Direct replacement with `resolveAgentConfig()`.
-- **`tools/agent-tool.ts`**: Called after `resolveType()` — config guaranteed.
-  Direct replacement.
-- **`ui/agent-menu.ts`**: 3 of 5 calls iterate `getAllTypes()` — configs guaranteed.
-  The 2 defensive existence guards (lines 187, 248) switch to `resolveType(name) != null` checks, then use `resolveAgentConfig()` for the config.
-
-### Constraints from AGENTS.md
-
-- Keep modules focused and composable (one concern per file).
-- Prefer explicit configuration over hidden behavior.
-- Use `vi.hoisted()` for module-level mocks, `.mockClear()` when the factory provides a default.
-- Run `pnpm run check` after interface changes.
-
-## Design Overview
-
-### `resolveAgentConfig` semantics
-
-```typescript
-export function resolveAgentConfig(type: string): AgentConfig
-```
-
-1. Case-insensitive key lookup via `resolveKey(type)`.
-2. If found and `enabled !== false`, return the `AgentConfig`.
-3. Fallback to `general-purpose` (if present and enabled).
-4. Absolute fallback: a synthetic `AgentConfig` with safe defaults (same values as today's `getConfig` absolute fallback, plus the missing `AgentConfig` fields like `name`, `systemPrompt`).
-
-The function is pure (reads from the module-level `agents` map) and deterministic.
-
-### Absolute fallback shape
-
-The absolute fallback is a complete `AgentConfig` synthesized inline, matching the current `getConfig` absolute fallback values plus required `AgentConfig` fields:
-
-```typescript
-{
-  name: type,
-  displayName: "Agent",
-  description: "General-purpose agent for complex, multi-step tasks",
-  builtinToolNames: BUILTIN_TOOL_NAMES,
-  extensions: true,
-  skills: true,
-  systemPrompt: "",
-  promptMode: "append",
-}
-```
-
-### session-config.ts simplification
-
-Before (two calls, two variables, null-check branching):
-
-```typescript
-const config = getConfig(type);
-const agentConfig = getAgentConfig(type);
-// ...
-const extensions = options.isolated ? false : config.extensions;
-const skills = options.isolated ? false : config.skills;
-// ...
-if (agentConfig) {
-  systemPrompt = buildAgentPrompt(agentConfig, ...);
-} else {
-  const fallback = DEFAULT_AGENTS.get("general-purpose");
-  systemPrompt = buildAgentPrompt({ ...fallback, name: type }, ...);
-}
-```
-
-After (one call, no null checks):
-
-```typescript
-const agentConfig = resolveAgentConfig(type);
-// ...
-const extensions = options.isolated ? false : agentConfig.extensions;
-const skills = options.isolated ? false : agentConfig.skills;
-// ...
-systemPrompt = buildAgentPrompt(agentConfig, ...);
-```
-
-The `DEFAULT_AGENTS` import in `session-config.ts` becomes unnecessary.
-
-## Module-Level Changes
-
-### `src/agent-types.ts`
-
-- **Add** `resolveAgentConfig(type: string): AgentConfig` — guaranteed-non-null lookup with fallback chain.
-- **Remove** `getConfig(type)` — replaced by `resolveAgentConfig`.
-- **Remove** `getAgentConfig(type)` — replaced by `resolveAgentConfig`.
-
-### `src/session-config.ts`
-
-- **Change** imports: replace `getConfig`, `getAgentConfig` with `resolveAgentConfig`.
-- **Remove** `DEFAULT_AGENTS` import (no longer needed for the unknown-type fallback prompt path).
-- **Simplify** `assembleSessionConfig()`: one `resolveAgentConfig(type)` call replaces two; remove the `if (agentConfig)` / `else` branch for prompt building.
-
-### `src/ui/agent-widget.ts`
-
-- **Change** import: replace `getConfig` with `resolveAgentConfig`.
-- **Update** `getDisplayName()`: `const config = resolveAgentConfig(type); return config.displayName ?? config.name;`.
-- **Update** `getPromptModeLabel()`: read `promptMode` from resolved config.
-
-### `src/index.ts`
-
-- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`.
-- **Update** 3 call sites: direct replacement (all iterate known names).
-
-### `src/tools/agent-tool.ts`
-
-- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`.
-- **Update** 1 call site: direct replacement (type already resolved via `resolveType()`).
-
-### `src/ui/agent-menu.ts`
-
-- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`, add `resolveType` if not already imported.
-- **Update** 5 call sites: 3 are direct replacements; 2 existence guards switch to `resolveType(name) != null` before calling `resolveAgentConfig()`.
-
-### Test files
-
-- **`test/agent-types.test.ts`**: Add tests for `resolveAgentConfig`; remove tests for `getConfig` and `getAgentConfig`.
-- **`test/session-config.test.ts`**: Replace `mockGetConfig` + `mockGetAgentConfig` with a single `mockResolveAgentConfig`; remove all `mockGetConfig` usages.
-- **`test/agent-runner.test.ts`**: Update `vi.mock("../src/agent-types.js")` factory: replace `getConfig` + `getAgentConfig` with `resolveAgentConfig`.
-- **`test/agent-runner-extension-tools.test.ts`**: Same mock update as above.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled**: `resolveAgentConfig` gets focused tests for the fallback chain (unknown → general-purpose → absolute fallback), case-insensitive lookup, and disabled-type fallback.
-   These replace the scattered `getConfig` fallback tests in `agent-types.test.ts`.
-2. **Redundant tests**: `getConfig`-specific tests (return shape, fallback, extension allowlist) become redundant since `resolveAgentConfig` returns the full `AgentConfig` directly.
-   Remove them.
-3. **Tests that must stay**: `agent-types.test.ts` tests for `registerAgents`, `resolveType`, `isValidType`, `getAvailableTypes`, `getAllTypes`, `getToolNamesForType`, `getMemoryToolNames`, `getReadOnlyMemoryToolNames` are unaffected.
-   `session-config.test.ts` tests all stay — they test assembler behavior, just with a simpler mock setup.
-
-## TDD Order
-
-1. **Add `resolveAgentConfig` with tests** — add the function to `agent-types.ts` alongside existing functions.
-   Tests: known type returns config; unknown type falls back to general-purpose; disabled type falls back; absolute fallback when general-purpose is missing; case-insensitive lookup.
-   Commit: `feat: add resolveAgentConfig with guaranteed-non-null fallback chain`.
-
-2. **Migrate `session-config.ts` and its tests** — replace `getConfig` + `getAgentConfig` imports with `resolveAgentConfig`; remove `DEFAULT_AGENTS` import; simplify the assembler body (one call, no null-check branch).
-   Update `session-config.test.ts`: replace `mockGetConfig` + `mockGetAgentConfig` with single `mockResolveAgentConfig`; update all test setups.
-   Commit: `refactor: migrate session-config to resolveAgentConfig`.
-
-3. **Migrate `agent-widget.ts`** — update `getDisplayName()` and `getPromptModeLabel()` to use `resolveAgentConfig`.
-   Commit: `refactor: migrate agent-widget to resolveAgentConfig`.
-
-4. **Migrate remaining source callers** — update `index.ts` (3 sites), `tools/agent-tool.ts` (1 site), `ui/agent-menu.ts` (5 sites, including 2 existence-guard rewrites).
-   Commit: `refactor: migrate remaining callers to resolveAgentConfig`.
-
-5. **Update transitive test mocks** — update `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` mock factories to export `resolveAgentConfig` instead of `getConfig` + `getAgentConfig`.
-   Commit: `test: update agent-runner test mocks for resolveAgentConfig`.
-
-6. **Remove `getConfig` and `getAgentConfig`** — delete both functions from `agent-types.ts`; remove their tests from `agent-types.test.ts`.
-   Run `pnpm run check` to verify no remaining references.
-   Commit: `refactor: remove getConfig and getAgentConfig`.
-
-## Risks and Mitigations
-
-| Risk                                                                     | Mitigation                                                                                                                                      |
-| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| Overlooked caller of removed functions                                   | Grep all `src/` and `test/` files for `getConfig` and `getAgentConfig` before the removal step; `pnpm run check` catches any remaining imports. |
-| `agent-menu.ts` existence guards behave differently with `resolveType()` | `resolveType()` is already the canonical existence check used by `agent-tool.ts`; the guard semantics are identical.                            |
-| Absolute fallback `AgentConfig` shape drift                              | The absolute fallback is a single inline literal — any future `AgentConfig` field additions will cause a type error at the definition site.     |
-| Test mock compatibility during migration                                 | Lift-and-shift: `resolveAgentConfig` coexists with old functions until all callers are migrated; each step leaves tests green.                  |
-
-## Open Questions
-
-- `getToolNamesForType()` does its own lookup with similar fallback logic.
-  It could be simplified to delegate to `resolveAgentConfig()`, but that is out of scope for this issue.
-  Consider a follow-up if the duplication becomes a maintenance concern.

package/docs/plans/0084-extract-git-worktree-manager.md

@@ -1,142 +0,0 @@
----
-issue: 84
-issue_title: "refactor: extract GitWorktreeManager class from worktree.ts free functions"
----
-
-# Extract GitWorktreeManager class
-
-## Problem Statement
-
-`worktree.ts` exports three free functions — `createWorktree(cwd, id)`, `cleanupWorktree(cwd, wt, desc)`, and `pruneWorktrees(cwd)` — that all operate on git worktrees relative to a repository root.
-Every caller threads `cwd` as the first argument.
-These functions form a cohesive unit with natural shared state (the repo root), but today there is no object to capture it.
-
-Issue #72 (dependency-inject `AgentManager`'s collaborators) needs a `WorktreeManager` interface to inject.
-Extracting the class first keeps #72 a clean DI + constructor refactor instead of mixing object extraction with dependency injection.
-
-## Goals
-
-- Define a `WorktreeManager` interface in `worktree.ts` with three methods: `create(id)`, `cleanup(wt, desc)`, `prune()` — no `cwd` parameter.
-- Add a `GitWorktreeManager` class that captures `cwd` at construction and delegates to the existing free functions.
-- Export both the interface and the class.
-- Existing free functions stay exported and unchanged.
-- No behavior change.
-
-## Non-Goals
-
-- Changing `AgentManager` to use the new class (that is #72).
-- Refactoring the internal implementation of `createWorktree`, `cleanupWorktree`, or `pruneWorktrees`.
-- Publishing `WorktreeManager` as a cross-extension API via `Symbol.for()` — it is internal to this package.
-
-## Background
-
-### Prerequisites
-
-None — this is the first step in the #72 dependency chain.
-
-### Relevant modules
-
-| Module                  | Role                                                       |
-| ----------------------- | ---------------------------------------------------------- |
-| `src/worktree.ts`       | Free functions for git worktree create/cleanup/prune       |
-| `test/worktree.test.ts` | Integration tests that create real git repos and worktrees |
-| `src/agent-manager.ts`  | Only consumer of the three free functions (6 call sites)   |
-
-### Constraints from AGENTS.md / code-style
-
-- Keep modules focused and composable (one concern per file).
-- When a shared interface references a collaborator, use a narrow interface type — not the concrete class.
-- Business logic should be pure functions wherever possible — keep IO at the edges.
-
-The free functions are IO (they shell out to `git`), so wrapping them in a class that captures `cwd` is the right level of abstraction — the class is a thin adapter, not business logic.
-
-## Design Overview
-
-### Interface and class
-
-Added at the bottom of `worktree.ts`, after the existing free functions:
-
-```typescript
-export interface WorktreeManager {
-  create(id: string): WorktreeInfo | undefined;
-  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult;
-  prune(): void;
-}
-
-export class GitWorktreeManager implements WorktreeManager {
-  constructor(private readonly cwd: string) {}
-
-  create(id: string): WorktreeInfo | undefined {
-    return createWorktree(this.cwd, id);
-  }
-
-  cleanup(wt: WorktreeInfo, description: string): WorktreeCleanupResult {
-    return cleanupWorktree(this.cwd, wt, description);
-  }
-
-  prune(): void {
-    pruneWorktrees(this.cwd);
-  }
-}
-```
-
-### Why the interface lives in `worktree.ts`
-
-The `WorktreeManager` interface references `WorktreeInfo` and `WorktreeCleanupResult`, which are already defined in `worktree.ts`.
-Co-locating avoids a separate file for a 5-line interface.
-This matches the #72 plan's expectation: `import type { WorktreeManager } from "./worktree.js"`.
-
-### No changes to callers
-
-`agent-manager.ts` continues importing and calling the free functions directly.
-Issue #72 handles the migration to the injected `WorktreeManager`.
-
-## Module-Level Changes
-
-### `src/worktree.ts` (modified)
-
-- Add `WorktreeManager` interface (3 methods).
-- Add `GitWorktreeManager` class implementing the interface.
-- Existing free functions, types, and imports unchanged.
-
-### `test/worktree.test.ts` (modified)
-
-- Add a new `describe("GitWorktreeManager")` block with tests for the class.
-- Existing free-function tests stay as-is.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-1. `GitWorktreeManager.create` — delegates to `createWorktree` with the captured `cwd`.
-2. `GitWorktreeManager.cleanup` — delegates to `cleanupWorktree` with the captured `cwd`.
-3. `GitWorktreeManager.prune` — delegates to `pruneWorktrees` with the captured `cwd`.
-
-These are thin delegation tests that verify the class wires `cwd` correctly.
-They reuse the same real-git-repo test infrastructure already in `worktree.test.ts`.
-
-### Existing tests
-
-All existing tests in `worktree.test.ts` stay unchanged — they test the free functions directly.
-
-## TDD Order
-
-1. **RED:** Add `describe("GitWorktreeManager")` with tests for `create`, `cleanup`, and `prune`.
-   Tests import `GitWorktreeManager` which does not exist yet — compilation fails.
-   Commit: `test: add GitWorktreeManager tests`
-
-2. **GREEN:** Add `WorktreeManager` interface and `GitWorktreeManager` class to `worktree.ts`.
-   All tests pass.
-   Run `pnpm run check` to verify types.
-   Commit: `feat: extract WorktreeManager interface and GitWorktreeManager class (#84)`
-
-## Risks and Mitigations
-
-| Risk                                                                      | Mitigation                                                                                                                                     |
-| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
-| Class delegation tests are slow because they create real git repos        | The existing test suite already does this; the new tests reuse the same `initGitRepo()` helper and add ~3 test cases to an already-fast suite. |
-| Future callers bypass the interface and use `GitWorktreeManager` directly | The #72 plan types `AgentManager`'s constructor parameter as `WorktreeManager` (the interface), not the class. Code review enforces this.      |
-
-## Open Questions
-
-None — the interface shape is specified by the issue and matches the #72 plan exactly.

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

@@ -1,240 +0,0 @@
----
-issue: 87
-issue_title: "refactor: evolve SubagentRuntime from data bag to object with methods"
----
-
-# Evolve SubagentRuntime from data bag to object with methods
-
-## Problem Statement
-
-`SubagentRuntime` (introduced in #69) consolidates all mutable extension state into one object, but it remains a plain data bag — an interface with public mutable fields and no methods.
-This causes two structural smells in `index.ts`:
-
-1. **Output arguments** — handlers write raw fields on the runtime instead of calling methods:
-   `runtime.currentCtx = { pi, ctx }` and `runtime.currentCtx = undefined`.
-2. **Law of Demeter violations** — 8 occurrences of `runtime.widget!.method()` across 4 call sites in `index.ts`, where callers reach through the runtime to talk to the widget with unsafe `!` non-null assertions.
-
-Issue #70 (extract event handlers) explicitly lists this issue as a prerequisite.
-Without these methods, extracted handlers would just move the output-argument and LoD smells from `index.ts` into handler classes.
-
-## Goals
-
-- Convert `SubagentRuntime` from an interface + factory to a class with methods.
-- Add session-context methods: `setSessionContext(pi, ctx)` and `clearSessionContext()`.
-- Add widget delegation methods that absorb the `runtime.widget!` reach-throughs: `setUICtx()`, `onTurnStart()`, `markFinished()`, `updateWidget()`, `ensureTimer()`.
-- Update all 10 call sites in `index.ts` to use the new methods — eliminate raw `currentCtx` field writes and `widget!` assertions.
-- No behavior change; pure structural refactor.
-
-## Non-Goals
-
-- Extracting event handlers into separate files (that is #70).
-- Adding methods for `defaultMaxTurns` / `graceTurns` writes — those field writes remain as-is; the issue scope covers `currentCtx` and `widget!` only.
-- Changing the `SubagentsService` interface.
-- Making `widget` private — `index.ts` still assigns `runtime.widget = new AgentWidget(...)` after construction.
-- Adding new features.
-
-## Background
-
-### Prior art
-
-`pi-permission-system`'s `PermissionSession` is a class with lifecycle methods (`refreshConfig`, `resetForNewSession`, `shutdown`).
-Lifecycle handlers in `src/handlers/lifecycle.ts` call those methods instead of writing fields.
-This issue brings `SubagentRuntime` to the same level.
-
-### Current runtime shape
-
-`src/runtime.ts` exports a `SubagentRuntime` interface and a `createSubagentRuntime()` factory:
-
-```typescript
-export interface SubagentRuntime {
-  defaultMaxTurns: number | undefined;
-  graceTurns: number;
-  currentCtx: { pi: unknown; ctx: unknown } | undefined;
-  readonly agentActivity: Map<string, AgentActivity>;
-  widget: AgentWidget | null;
-}
-```
-
-### Call sites to migrate
-
-Two `currentCtx` writes (output arguments):
-
-| Line | Current                            | After                                |
-| ---- | ---------------------------------- | ------------------------------------ |
-| 126  | `runtime.currentCtx = { pi, ctx }` | `runtime.setSessionContext(pi, ctx)` |
-| 138  | `runtime.currentCtx = undefined`   | `runtime.clearSessionContext()`      |
-
-Eight `widget!` reach-throughs (LoD violations):
-
-| Line | Current                                     | After                               |
-| ---- | ------------------------------------------- | ----------------------------------- |
-| 60   | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
-| 61   | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
-| 149  | `runtime.widget!.setUICtx(ctx.ui as UICtx)` | `runtime.setUICtx(ctx.ui as UICtx)` |
-| 150  | `runtime.widget!.onTurnStart()`             | `runtime.onTurnStart()`             |
-| 204  | `runtime.widget!.setUICtx(ctx as UICtx)`    | `runtime.setUICtx(ctx as UICtx)`    |
-| 205  | `runtime.widget!.ensureTimer()`             | `runtime.ensureTimer()`             |
-| 206  | `runtime.widget!.update()`                  | `runtime.updateWidget()`            |
-| 207  | `runtime.widget!.markFinished(id)`          | `runtime.markFinished(id)`          |
-
-### Dependency chain
-
-Issue #69 (SubagentRuntime) is closed/implemented.
-This issue (#87) is a prerequisite for #70 (extract event handlers).
-The #70 plan defines narrow handler interfaces (`LifecycleRuntime`, `ToolStartRuntime`) that the runtime class satisfies structurally.
-
-### Relevant constraints from AGENTS.md / code-style skill
-
-- Keep modules focused and composable (one concern per file).
-- Do not pass a shared dependency bag to functions that only use a subset — define narrow interfaces per consumer.
-- Do not write back into a received dependency bag (output arguments).
-- Do not reach through an injected collaborator to talk to a stranger (Law of Demeter).
-- When multiple callers perform the same reach-through, the missing abstraction is a method on the intermediate object that delegates internally.
-
-## Design Overview
-
-### Class conversion
-
-Convert `SubagentRuntime` from an interface to a class.
-Public fields stay as-is — callers that read `runtime.defaultMaxTurns`, `runtime.currentCtx`, `runtime.agentActivity`, etc. continue to work.
-The `createSubagentRuntime()` factory becomes a thin alias returning `new SubagentRuntime()`, preserving backward compatibility for `index.ts` and existing tests during the transition.
-
-```typescript
-export class SubagentRuntime {
-  defaultMaxTurns: number | undefined = undefined;
-  graceTurns: number = 5;
-  currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;
-  readonly agentActivity: Map<string, AgentActivity> = new Map();
-  widget: AgentWidget | null = null;
-
-  setSessionContext(pi: unknown, ctx: unknown): void {
-    this.currentCtx = { pi, ctx };
-  }
-
-  clearSessionContext(): void {
-    this.currentCtx = undefined;
-  }
-
-  setUICtx(ctx: UICtx): void {
-    this.widget?.setUICtx(ctx);
-  }
-
-  onTurnStart(): void {
-    this.widget?.onTurnStart();
-  }
-
-  markFinished(id: string): void {
-    this.widget?.markFinished(id);
-  }
-
-  updateWidget(): void {
-    this.widget?.update();
-  }
-
-  ensureTimer(): void {
-    this.widget?.ensureTimer();
-  }
-}
-```
-
-### Widget delegation null safety
-
-Current code uses `runtime.widget!.method()` — an unsafe non-null assertion that would throw if widget were null.
-The delegation methods use optional chaining (`this.widget?.method()`), which silently no-ops when widget is null.
-This is safe and intentional: widget is always assigned before any agent can complete, so the null path is unreachable in practice, but the delegation removes the assertion smell.
-The #70 plan explicitly expects this behavior: "Widget null safety: after #87, the runtime's delegation methods handle null internally."
-
-### UICtx type import
-
-`runtime.ts` already imports `AgentActivity` and `AgentWidget` from `ui/agent-widget.ts`.
-Adding `UICtx` to the same type import is consistent with the existing dependency.
-`UICtx` is a lean local interface (two method signatures), not a Pi SDK type.
-
-### What stays unchanged
-
-- `RunConfig` interface — remains as-is.
-- `defaultMaxTurns` / `graceTurns` field writes from settings appliers — out of scope per non-goals.
-- `runtime.currentCtx` reads via getter callbacks (`getCtx: () => runtime.currentCtx`) — reads are not output arguments.
-- `runtime.widget = new AgentWidget(...)` assignment — `widget` stays public.
-- `agentActivity` map usage across notification, tool, and menu deps — unchanged.
-
-## Module-Level Changes
-
-### `src/runtime.ts` (modified)
-
-- Convert `SubagentRuntime` from `export interface` to `export class` with field initializers.
-- Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
-- Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` delegation methods.
-- Add `UICtx` to the existing type import from `./ui/agent-widget.js`.
-- Keep `createSubagentRuntime()` as `() => new SubagentRuntime()` for backward compat.
-- Keep `RunConfig` interface unchanged.
-
-### `src/index.ts` (modified)
-
-- Replace `runtime.currentCtx = { pi, ctx }` with `runtime.setSessionContext(pi, ctx)` (line 126).
-- Replace `runtime.currentCtx = undefined` with `runtime.clearSessionContext()` (line 138).
-- Replace all 8 `runtime.widget!.method()` reach-throughs with `runtime.method()` delegation calls (lines 60, 61, 149, 150, 204–207).
-- No import changes needed — `runtime` is already imported via the factory.
-
-### `test/runtime.test.ts` (modified)
-
-- Add tests for `setSessionContext` / `clearSessionContext` methods.
-- Add tests for each widget delegation method using duck-typed widget stubs.
-- Add test verifying delegation methods no-op when widget is null.
-- Existing tests remain — factory defaults, field mutability, instance isolation, and widget assignment all still apply.
-
-## Test Impact Analysis
-
-### New unit tests enabled
-
-1. `test/runtime.test.ts` additions — `setSessionContext` sets `currentCtx` correctly; `clearSessionContext` resets it to `undefined`.
-2. `test/runtime.test.ts` additions — Each widget delegation method forwards to the widget's corresponding method; all delegation methods silently no-op when widget is null.
-
-### Existing tests that become redundant
-
-None.
-The existing `runtime.test.ts` tests cover factory defaults, field mutability, and instance isolation — all still valid with the class conversion.
-The "fields are independently mutable" test exercises direct field writes, which remain supported.
-
-### Existing tests that stay as-is
-
-- `test/runtime.test.ts` — All 5 existing tests pass unchanged (the class satisfies the same structural contract as the previous interface-based object).
-- `test/print-mode.test.ts` — Calls `session_shutdown` via the extension's handler map; transparent to runtime internals.
-- All other test files — No dependency on `SubagentRuntime` fields or methods.
-
-## TDD Order
-
-1. **Convert `SubagentRuntime` to a class; add session-context methods.**
-   Convert the interface to a class with field initializers matching current defaults.
-   Add `setSessionContext(pi, ctx)` and `clearSessionContext()` methods.
-   Update `createSubagentRuntime()` to return `new SubagentRuntime()`.
-   Add tests in `runtime.test.ts`: `setSessionContext` sets `currentCtx`; `clearSessionContext` resets to `undefined`; round-trip set→clear.
-   Run existing tests to verify no regressions.
-   Commit: `feat: add session-context methods to SubagentRuntime`
-
-2. **Add widget delegation methods; add tests.**
-   Add `setUICtx(ctx)`, `onTurnStart()`, `markFinished(id)`, `updateWidget()`, `ensureTimer()` methods to the class.
-   Add `UICtx` to the type import from `./ui/agent-widget.js`.
-   Add tests in `runtime.test.ts`: each delegation method forwards to the widget stub; all methods no-op when widget is null.
-   Commit: `feat: add widget delegation methods to SubagentRuntime`
-
-3. **Migrate all call sites in `index.ts` to use the new methods.**
-   Replace the 2 `currentCtx` writes with `setSessionContext` / `clearSessionContext`.
-   Replace the 8 `widget!` reach-throughs with delegation methods.
-   Run full test suite and `pnpm run check`.
-   Commit: `refactor: use SubagentRuntime methods in extension factory (#87)`
-
-## Risks and Mitigations
-
-| Risk                                                                                                  | Mitigation                                                                                                                                                                                                  |
-| ----------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Class conversion breaks code that constructs `SubagentRuntime` as a plain object                      | Only `createSubagentRuntime()` constructs runtime instances (in `index.ts` and tests). The factory is updated to return `new SubagentRuntime()`. No code constructs a `{ ... } as SubagentRuntime` literal. |
-| Widget delegation silently swallows errors when widget is null (changes behavior from throw to no-op) | The null path is unreachable in practice — widget is always assigned before any agent completes. The silent no-op is strictly safer than the `!` assertion. The #70 plan explicitly expects this behavior.  |
-| Adding `UICtx` import to `runtime.ts` increases coupling to the widget module                         | `runtime.ts` already imports `AgentActivity` and `AgentWidget` from the same module. `UICtx` is a lean 2-method interface, not a Pi SDK type. Coupling is minimal and consistent.                           |
-| Remaining output-argument writes (`defaultMaxTurns`, `graceTurns`) are left unaddressed               | Explicitly out of scope per the issue's acceptance criteria. Can be addressed in a follow-up if the pattern becomes painful.                                                                                |
-
-## Open Questions
-
-- Should `createSubagentRuntime()` be removed in favor of `new SubagentRuntime()` directly?
-  The factory adds no value over a no-arg constructor, but removing it widens the blast radius without benefit.
-  Defer — remove it as part of #70 or a future cleanup if it feels redundant.