@gotgenes/pi-subagents 18.0.0 → 18.0.2

package/docs/plans/0192-define-session-context-interface.md

@@ -1,107 +0,0 @@
----
-issue: 192
-issue_title: "Define SessionContext narrow interface"
----
-
-# Define `SessionContext` narrow interface
-
-## Problem Statement
-
-`SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }`.
-Every consumer must cast through `as any` to read fields from the SDK context.
-This forces context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) to live as closures in `index.ts` with repeated `as any` casts, rather than as typed methods on the state holder.
-
-The SDK exports `ExtensionContext` — the `unknown` typing is a historical choice, not a constraint.
-
-## Goals
-
-- Define a narrow `SessionContext` interface in `src/types.ts` capturing the 5 fields `SubagentRuntime` actually reads.
-- Pure additive — no consumers change in this step.
-- Provide the typed foundation for Layer 1 (#193) and subsequent closure-to-class conversion issues.
-
-## Non-Goals
-
-- Changing `SubagentRuntime.currentCtx` type (that's #193).
-- Converting closure factories to classes (#195, #196).
-- Removing any `as any` casts from `index.ts` (that's #193).
-
-## Background
-
-Phase 11, Layer 0 in `docs/architecture/architecture.md`.
-This is the first step in a 5-issue sequence (issues #192–#196) that converts closure factories to classes, eliminating 44 adapter closures in `index.ts`.
-
-The SDK's `ExtensionContext` interface (in `@earendil-works/pi-coding-agent`) is broad — it exposes `ui`, `abort()`, `shutdown()`, `compact()`, etc.
-ISP (Interface Segregation Principle) from `code-design` mandates a narrow interface capturing only what `SubagentRuntime` needs.
-
-The 5 fields consumed by runtime (traced from `index.ts` lines 214–223 and `lifecycle/parent-snapshot.ts`):
-
-1. `cwd` — working directory for agent sessions.
-2. `model` — parent model instance for fallback resolution.
-3. `modelRegistry` — resolving config model strings.
-4. `getSystemPrompt()` — system prompt for append-mode agents.
-5. `sessionManager.getSessionFile()` / `.getSessionId()` / `.getBranch()` — session identification and context inheritance.
-
-The local `ModelRegistry` interface (in `src/session/model-resolver.ts`) already exists as a narrow ISP interface.
-`SessionContext` will reference it rather than redeclaring model-registry methods inline.
-
-## Design Overview
-
-```typescript
-import type { ModelRegistry } from "#src/session/model-resolver";
-
-/**
- * Narrow interface capturing the 5 ExtensionContext fields SubagentRuntime needs.
- * Avoids coupling runtime to the full SDK ExtensionContext surface.
- */
-export interface SessionContext {
-  readonly cwd: string;
-  readonly model: unknown;
-  readonly modelRegistry: ModelRegistry | undefined;
-  getSystemPrompt(): string;
-  readonly sessionManager: {
-    getSessionFile(): string | undefined;
-    getSessionId(): string;
-    getBranch(): unknown[];
-  };
-}
-```
-
-Design decisions:
-
-1. `model` stays `unknown` — the runtime only passes it through to `resolveModel`; narrowing it gains nothing and would couple to `@earendil-works/pi-ai`'s `Model<Api>` generic.
-2. `modelRegistry` is `ModelRegistry | undefined` — the SDK type says `ModelRegistry` (non-optional), but `SubagentRuntime.currentCtx` can be undefined, and the architecture doc specifies this signature.
-   The `| undefined` reflects reality at the cast boundary (pre-bind, the registry may not exist).
-3. `sessionManager` uses an inline structural type rather than importing `ReadonlySessionManager` — we only need 3 of its 13 methods; a separate named type would be over-engineering for a nested structural slice.
-4. `getBranch()` returns `unknown[]` — the runtime passes entries through to `buildParentContext()` which already type-narrows internally.
-
-## Module-Level Changes
-
-| File           | Change                                                                                                         |
-| -------------- | -------------------------------------------------------------------------------------------------------------- |
-| `src/types.ts` | Add `SessionContext` interface export. Add `import type { ModelRegistry }` from `#src/session/model-resolver`. |
-
-No other files change — this is pure additive.
-
-## Test Impact Analysis
-
-1. No new unit tests are needed — `SessionContext` is a pure type definition with no runtime behavior.
-2. No existing tests become redundant.
-3. A compile-time check (`pnpm run check`) verifies the interface is well-formed and the import resolves.
-
-## TDD Order
-
-1. **Add `SessionContext` interface to `src/types.ts`** — add the interface with its import.
-   Verify with `pnpm run check` (type-check passes).
-   Commit: `feat(pi-subagents): define SessionContext narrow interface (#192)`
-
-## Risks and Mitigations
-
-| Risk                                                             | Mitigation                                                                                                                 |
-| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Interface shape doesn't match real `ExtensionContext` at runtime | Traced all 5 fields against SDK `.d.ts` declarations; shapes align exactly.                                                |
-| Circular import from `types.ts` → `session/model-resolver.ts`    | `model-resolver.ts` does not import from `types.ts`; no cycle.                                                             |
-| Future SDK changes break the narrow interface                    | The cast boundary (Layer 1, #193) will be the single enforcement point — structural typing ensures compile-time detection. |
-
-## Open Questions
-
-None — the issue's "Proposed change" section fully specifies the interface shape.

package/docs/plans/0193-runtime-owns-context-queries.md

@@ -1,245 +0,0 @@
----
-issue: 193
-issue_title: "SubagentRuntime owns context queries"
----
-
-# SubagentRuntime owns context queries
-
-## Problem Statement
-
-Three closure queries in `index.ts` reach into `runtime.currentCtx?.ctx` with `as any` casts to extract model, modelRegistry, and sessionManager values.
-These closures exist because `SubagentRuntime` stores `unknown` and doesn't provide typed accessors.
-The queries belong on the state holder — `SubagentRuntime` owns `currentCtx`, so it should own the queries on that state.
-
-## Goals
-
-- Type `SubagentRuntime.currentCtx` as `SessionContext | undefined` (eliminating the `{ pi: unknown; ctx: unknown }` shape).
-- Move the `as SessionContext` cast into `handleSessionStart` — the single SDK boundary.
-- Add typed methods on `SubagentRuntime`: `buildSnapshot()`, `getModelInfo()`, `getSessionInfo()`.
-- Remove 4 `as any` casts from `index.ts`.
-- Remove 3 closure queries from the composition root.
-- Update `service-adapter.ts` to delegate to `SubagentRuntime` instead of holding its own `as ExtensionContext` cast.
-
-## Non-Goals
-
-- Converting closure factories to classes (Layer 3, #195/#196).
-- Aligning interface names so real objects satisfy tool deps (Layer 2, #194).
-- Changing `buildParentContext` in `session/context.ts` (it will continue to accept `ExtensionContext`; `SessionContext` is structurally compatible).
-
-## Background
-
-Issue #192 (closed, shipped as v7.1.0) added the `SessionContext` interface to `src/types.ts`.
-This plan builds on that foundation.
-
-The architecture doc (Phase 11, Layer 1) specifies this exact change: "Change `currentCtx` from `{ pi: unknown; ctx: unknown }` to `SessionContext | undefined`."
-
-Key modules:
-
-- `src/runtime.ts` — `SubagentRuntime` class with `currentCtx`, `setSessionContext()`, `clearSessionContext()`
-- `src/handlers/lifecycle.ts` — `SessionLifecycleHandler.handleSessionStart()` receives raw SDK `ctx`
-- `src/index.ts` — composition root with inline `buildSnapshot`, `getModelInfo`, `getSessionInfo` closures
-- `src/service/service-adapter.ts` — `createSubagentsService()` with `getCtx()` and `getModelRegistry()` closures
-- `src/lifecycle/parent-snapshot.ts` — `buildParentSnapshot(ctx: ExtensionContext, inheritContext?)` function
-- `src/session/context.ts` — `buildParentContext(ctx: ExtensionContext)` function
-
-AGENTS.md constraint: keep modules focused and composable.
-The queries belong on the state owner per Law of Demeter (code-design skill).
-
-## Design Overview
-
-### Type change
-
-`SubagentRuntime.currentCtx` becomes `SessionContext | undefined` (previously `{ pi: unknown; ctx: unknown } | undefined`).
-The `pi` field is dropped from the stored context — it is only used in `SessionLifecycleHandler` which already stores it as a constructor param.
-
-### Cast boundary
-
-`handleSessionStart` receives `ctx: unknown` from the SDK event.
-The single `as SessionContext` cast lives here:
-
-```typescript
-handleSessionStart(_event: unknown, ctx: unknown): void {
-  this.runtime.setSessionContext(ctx as SessionContext);
-  this.manager.clearCompleted();
-}
-```
-
-### New methods on `SubagentRuntime`
-
-```typescript
-import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import type { ModelInfo } from "#src/tools/spawn-config";
-import type { SessionContext } from "#src/types";
-
-class SubagentRuntime {
-  currentCtx: SessionContext | undefined = undefined;
-
-  setSessionContext(ctx: SessionContext): void {
-    this.currentCtx = ctx;
-  }
-
-  clearSessionContext(): void {
-    this.currentCtx = undefined;
-  }
-
-  buildSnapshot(inheritContext: boolean): ParentSnapshot {
-    return buildParentSnapshot(this.currentCtx!, inheritContext);
-  }
-
-  getModelInfo(): ModelInfo {
-    return {
-      parentModel: this.currentCtx?.model as ModelInfo["parentModel"],
-      modelRegistry: this.currentCtx?.modelRegistry,
-    };
-  }
-
-  getSessionInfo(): { parentSessionFile: string; parentSessionId: string } {
-    return {
-      parentSessionFile: this.currentCtx?.sessionManager?.getSessionFile() ?? "",
-      parentSessionId: this.currentCtx?.sessionManager?.getSessionId() ?? "",
-    };
-  }
-}
-```
-
-### `buildParentSnapshot` signature change
-
-Change the parameter type from `ExtensionContext` to `SessionContext`:
-
-```typescript
-export function buildParentSnapshot(
-  ctx: SessionContext,
-  inheritContext?: boolean,
-): ParentSnapshot { ... }
-```
-
-`ExtensionContext` structurally satisfies `SessionContext` (all 5 fields match), so existing callers (the `/agents` command handler) continue to work without change.
-
-Similarly, `buildParentContext` changes from `ExtensionContext` to `SessionContext`.
-The `sessionManager.getBranch()` returns `unknown[]` in `SessionContext`, which is what `buildParentContext` already treats the entries as (it accesses `.type`, `.message`, `.summary` via runtime checks without type narrowing).
-
-### `service-adapter.ts` change
-
-The adapter currently receives `getCtx: () => { pi: unknown; ctx: unknown } | undefined`.
-After this change, it receives the runtime directly and calls `runtime.buildSnapshot()`:
-
-```typescript
-export function createSubagentsService(
-  manager: AgentManagerLike,
-  resolveModel: (input: string, registry: ModelRegistry) => unknown,
-  runtime: ServiceRuntimeLike,
-): SubagentsService { ... }
-```
-
-Where `ServiceRuntimeLike` is a narrow interface:
-
-```typescript
-export interface ServiceRuntimeLike {
-  readonly currentCtx: SessionContext | undefined;
-  buildSnapshot(inheritContext: boolean): ParentSnapshot;
-  getModelInfo(): { modelRegistry: unknown };
-}
-```
-
-### Impact on `LifecycleRuntime` interface
-
-The narrow interface in `handlers/lifecycle.ts` changes from:
-
-```typescript
-interface LifecycleRuntime {
-  setSessionContext(pi: unknown, ctx: unknown): void;
-  clearSessionContext(): void;
-}
-```
-
-to:
-
-```typescript
-interface LifecycleRuntime {
-  setSessionContext(ctx: SessionContext): void;
-  clearSessionContext(): void;
-}
-```
-
-## Module-Level Changes
-
-1. `src/runtime.ts` — Change `currentCtx` type, update `setSessionContext()` signature (drop `pi` param), add `buildSnapshot()`, `getModelInfo()`, `getSessionInfo()` methods.
-   Add imports for `SessionContext`, `ParentSnapshot`, `ModelInfo`, `buildParentSnapshot`.
-2. `src/handlers/lifecycle.ts` — Update `LifecycleRuntime` interface (single `ctx: SessionContext` param).
-   Cast `ctx as SessionContext` in `handleSessionStart`.
-   Remove `pi` from `setSessionContext` call.
-   Import `SessionContext`.
-3. `src/lifecycle/parent-snapshot.ts` — Change `buildParentSnapshot` param from `ExtensionContext` to `SessionContext`.
-   Update import.
-4. `src/session/context.ts` — Change `buildParentContext` param from `ExtensionContext` to `SessionContext`.
-   Update import.
-5. `src/service/service-adapter.ts` — Replace `getCtx`/`getModelRegistry` closures with a `ServiceRuntimeLike` interface.
-   Use `runtime.buildSnapshot()` and `runtime.currentCtx?.modelRegistry`.
-   Remove `ExtensionContext` import.
-6. `src/index.ts` — Remove inline `buildSnapshot`, `getModelInfo`, `getSessionInfo` closures from `createAgentTool` deps.
-   Pass `runtime.buildSnapshot.bind(runtime)`, `runtime.getModelInfo.bind(runtime)`, `runtime.getSessionInfo.bind(runtime)`.
-   Update `createSubagentsService` call to pass `runtime` instead of two closures.
-   Update `lifecycle.handleSessionStart` call (drop `pi` from `setSessionContext`).
-   Remove `as any` eslint-disable for the eliminated casts.
-7. `test/runtime.test.ts` — Update session-context method tests (single param).
-   Add tests for `buildSnapshot()`, `getModelInfo()`, `getSessionInfo()`.
-8. `test/handlers/lifecycle.test.ts` — Update `setSessionContext` mock expectations (single param).
-9. `test/service/service-adapter.test.ts` — Update `createSubagentsService` calls to pass a runtime-like mock instead of two closures.
-10. `test/helpers/stub-ctx.ts` (or equivalent) — Verify the stub ctx satisfies `SessionContext`.
-
-## Test Impact Analysis
-
-1. **New unit tests enabled:** `SubagentRuntime.buildSnapshot()`, `.getModelInfo()`, `.getSessionInfo()` — previously untestable as anonymous closures.
-2. **Existing tests that simplify:** `service-adapter.test.ts` no longer needs to wire `getCtx`/`getModelRegistry` closures; a simple runtime stub replaces them.
-3. **Tests that stay as-is:** `agent-tool.test.ts` (via `make-deps.ts`) — the tool deps interface still has `buildSnapshot`, `getModelInfo`, `getSessionInfo` fields; only the wiring in `index.ts` changes.
-   The tool tests use mocks and are unaffected.
-
-## TDD Order
-
-1. **Red → Green:** Add `buildSnapshot()`, `getModelInfo()`, `getSessionInfo()` method tests to `runtime.test.ts`.
-   Update `setSessionContext` tests to use single param.
-   Tests fail because the methods don't exist yet.
-   Commit: `test: add SubagentRuntime context-query method tests (#193)`
-
-2. **Green:** Change `SubagentRuntime.currentCtx` type to `SessionContext | undefined`.
-   Update `setSessionContext` to single param.
-   Add three query methods.
-   Update imports.
-   Run `pnpm run check` to verify type coherence.
-   Commit: `feat: SubagentRuntime stores typed SessionContext and owns context queries (#193)`
-
-3. **Green:** Change `buildParentSnapshot` and `buildParentContext` to accept `SessionContext` instead of `ExtensionContext`.
-   Update imports.
-   Run `pnpm run check`.
-   Commit: `refactor: narrow buildParentSnapshot param to SessionContext (#193)`
-
-4. **Green:** Update `handlers/lifecycle.ts` — change `LifecycleRuntime` interface, cast `ctx as SessionContext` in handler.
-   Update lifecycle test expectations.
-   Commit: `refactor: move SessionContext cast to handleSessionStart boundary (#193)`
-
-5. **Green:** Update `service-adapter.ts` — introduce `ServiceRuntimeLike`, replace closure params with runtime.
-   Update service-adapter tests.
-   Commit: `refactor: service-adapter delegates to SubagentRuntime for context (#193)`
-
-6. **Green:** Update `index.ts` — wire `runtime.buildSnapshot.bind(runtime)` etc. into agent tool deps.
-   Update `createSubagentsService` call.
-   Remove `as any` casts and corresponding eslint-disable comment.
-   Clean up unused imports.
-   Commit: `refactor: index.ts delegates context queries to SubagentRuntime (#193)`
-
-7. **Verify:** Run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
-   Fix any remaining lint issues.
-   Commit: `chore: cleanup lint after SubagentRuntime context migration (#193)` (if needed)
-
-## Risks and Mitigations
-
-| Risk                                                                                                                    | Mitigation                                                                                                                                                                                            |
-| ----------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `buildParentSnapshot` callers outside this package break when param changes from `ExtensionContext` to `SessionContext` | `ExtensionContext` structurally satisfies `SessionContext` — no source-level changes needed at call sites. The `/agents` command handler passes `ctx` which is still `ExtensionContext` from the SDK. |
-| `runtime.currentCtx` is `undefined` when `buildSnapshot()` is called                                                    | Same risk exists today — the closure reads `runtime.currentCtx?.ctx` which may be undefined. The `!` assertion documents the invariant: methods are only called during an active session.             |
-| Dropping `pi` from `currentCtx` breaks something that reads it                                                          | Grep confirms `pi` is only stored and never read back from `currentCtx`. `SessionLifecycleHandler` already stores `pi` as its own constructor param.                                                  |
-| Test fixture `make-deps.ts` still mocks `buildSnapshot`/`getModelInfo`/`getSessionInfo` on `AgentToolDeps`              | Correct — the tool interface doesn't change in this issue. The closures in `index.ts` are replaced with bound methods, but the deps shape stays the same.                                             |
-
-## Open Questions
-
-- None — the issue's proposed change and the architecture doc's Layer 1 spec are fully aligned.

package/docs/plans/0194-align-tool-interfaces-for-structural-typing.md

@@ -1,139 +0,0 @@
----
-issue: 194
-issue_title: "Align tool interfaces for structural typing"
----
-
-# Align tool interfaces for structural typing
-
-## Problem Statement
-
-The narrow interfaces that tool factories accept don't structurally match the real objects (`AgentManager`, `SubagentRuntime`, `SettingsManager`).
-This forces `index.ts` to build adapter closures bridging the gap — each a one-liner that exists only because names or ownership don't align.
-Three specific mismatches prevent structural typing from connecting real objects to tool interfaces directly.
-
-## Goals
-
-- Remove `getMaxConcurrent()` from `AgentToolManager` — it belongs on the settings accessor.
-- Rename `SubagentRuntime.updateWidget()` → `update()` so `SubagentRuntime` structurally satisfies `AgentToolWidget`.
-- Remove the dead `getToolCallName` re-export from `ui/message-formatters.ts`.
-- After these changes, `AgentManager` structurally satisfies `AgentToolManager` and `SubagentRuntime` structurally satisfies `AgentToolWidget` — no adapter closures needed in `index.ts`.
-
-## Non-Goals
-
-- Converting tool factories to classes (that's #195).
-- Simplifying `index.ts` wiring (that's #195/#196, after this layer).
-- Changing `NotificationManager`'s constructor parameter name (`updateWidget` callback) — it's a positional callback, not a structural interface member.
-
-## Background
-
-This is Phase 11, Layer 2 in `docs/architecture/architecture.md`.
-Layer 0 (#192, done) and Layer 1 (#193, done) established the typed `SessionContext` and moved context queries onto `SubagentRuntime`.
-Layer 2 (this issue) aligns the remaining structural mismatches.
-Layer 3 (#195) depends on this layer.
-
-Relevant modules:
-
-- `src/tools/agent-tool.ts` — defines `AgentToolManager` and `AgentToolWidget` interfaces.
-- `src/tools/background-spawner.ts` — defines `BackgroundManagerDeps` with `getMaxConcurrent()`.
-- `src/runtime.ts` — defines `SubagentRuntime` class with `updateWidget()` delegation method.
-- `src/ui/message-formatters.ts` — has the dead `getToolCallName` re-export.
-- `src/index.ts` — composition root that builds adapter closures.
-- `src/settings.ts` — `SettingsManager` owns `maxConcurrent`.
-
-## Design Overview
-
-### 1. Move `getMaxConcurrent` off manager interfaces → settings
-
-The `BackgroundManagerDeps` and `AgentToolManager` interfaces both declare `getMaxConcurrent(): number`.
-In reality, the value comes from `SettingsManager.maxConcurrent`.
-The fix:
-
-- Remove `getMaxConcurrent` from `AgentToolManager`.
-- Remove `getMaxConcurrent` from `BackgroundManagerDeps`.
-- Widen `AgentToolDeps.settings` from `{ readonly defaultMaxTurns: number | undefined }` to also include `readonly maxConcurrent: number`.
-- Pass `settings` (or a narrow settings interface) to `spawnBackground` so it can read `maxConcurrent` directly.
-- `SettingsManager` already exposes a `get maxConcurrent(): number` property, so it structurally satisfies the widened interface.
-
-After this, `AgentManager` (which has `spawn`, `spawnAndWait`, `resume`, `getRecord` but NOT `getMaxConcurrent`) structurally satisfies `AgentToolManager`.
-
-### 2. Rename `SubagentRuntime.updateWidget()` → `update()`
-
-The `AgentToolWidget` interface declares `update(): void`.
-`SubagentRuntime` has `updateWidget(): void` which delegates to `this.widget?.update()`.
-Renaming the delegation method to `update()` makes `SubagentRuntime` structurally satisfy `AgentToolWidget` (it already has `setUICtx`, `ensureTimer`, and `markFinished`).
-
-Callers of `runtime.updateWidget()`:
-
-- `src/index.ts` line 70: `() => runtime.updateWidget()` → `() => runtime.update()`
-- `src/index.ts` line 199: `update: () => runtime.updateWidget()` → can now pass `runtime` directly (but that's a #195 concern — for now just rename the call).
-
-The `WidgetLike` interface in `runtime.ts` already uses `update()` — no conflict.
-
-### 3. Remove dead re-export
-
-`src/ui/message-formatters.ts` line 24 exports `getToolCallName` from `#src/session/content-items`.
-No consumer imports `getToolCallName` from `message-formatters` — all uses go directly to `content-items.ts`.
-Delete the re-export line.
-
-### After all three changes
-
-```typescript
-// AgentToolManager (after removing getMaxConcurrent):
-interface AgentToolManager {
-  spawn(...): string;
-  spawnAndWait(...): Promise<AgentRecord>;
-  resume(...): Promise<AgentRecord | undefined>;
-  getRecord(id: string): AgentRecord | undefined;
-}
-// AgentManager has all four methods → structural match ✓
-
-// AgentToolWidget (unchanged):
-interface AgentToolWidget {
-  setUICtx(ctx: unknown): void;
-  ensureTimer(): void;
-  update(): void;
-  markFinished(id: string): void;
-}
-// SubagentRuntime has all four methods (after rename) → structural match ✓
-```
-
-## Module-Level Changes
-
-| File                                    | Change                                                                                                                                                                                                                            |
-| --------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/tools/agent-tool.ts`               | Remove `getMaxConcurrent` from `AgentToolManager`. Widen `settings` type in `AgentToolDeps` to include `readonly maxConcurrent: number`.                                                                                          |
-| `src/tools/background-spawner.ts`       | Remove `getMaxConcurrent` from `BackgroundManagerDeps`. Add a `settings: { readonly maxConcurrent: number }` parameter (or add to `BackgroundParams`). Read `settings.maxConcurrent` instead of `manager.getMaxConcurrent()`.     |
-| `src/runtime.ts`                        | Rename `updateWidget()` → `update()`.                                                                                                                                                                                             |
-| `src/ui/message-formatters.ts`          | Remove the `export { getToolCallName } from ...` line.                                                                                                                                                                            |
-| `src/index.ts`                          | Update `runtime.updateWidget()` → `runtime.update()` at both call sites. Remove `getMaxConcurrent` from the `manager` adapter object passed to `createAgentTool`. Pass `settings` through to `spawnBackground` via the tool deps. |
-| `test/tools/background-spawner.test.ts` | Remove `getMaxConcurrent` from mock manager objects. Add `settings` mock with `maxConcurrent`.                                                                                                                                    |
-| `test/runtime.test.ts`                  | Rename `updateWidget` → `update` in test descriptions and call sites.                                                                                                                                                             |
-| `docs/architecture/architecture.md`     | Update Layer 2 status and health metrics (adapter closures count, dead exports count).                                                                                                                                            |
-
-## Test Impact Analysis
-
-1. No new unit tests are strictly needed — this is interface alignment, not new behavior.
-2. `test/tools/background-spawner.test.ts` needs mock shape updates (remove `getMaxConcurrent` from manager mock, add settings mock).
-3. `test/runtime.test.ts` needs the method name updated from `updateWidget` to `update`.
-4. Existing tests for `agent-tool`, `notification`, and `message-formatters` remain as-is (no behavior change).
-
-## TDD Order
-
-1. `refactor:` Rename `SubagentRuntime.updateWidget()` → `update()` — update `runtime.ts`, `test/runtime.test.ts`, and both call sites in `index.ts`.
-   Run `pnpm run check` to verify no type errors remain.
-2. `refactor:` Move `getMaxConcurrent` off manager interfaces — remove from `AgentToolManager` and `BackgroundManagerDeps`, widen `AgentToolDeps.settings`, add settings parameter to `spawnBackground`, update `index.ts` call site and `test/tools/background-spawner.test.ts`.
-   Run `pnpm run check`.
-3. `refactor:` Remove dead `getToolCallName` re-export from `ui/message-formatters.ts`.
-4. `docs:` Update architecture doc — mark Layer 2 as done, update health metrics (dead exports: 0, adapter closures reduced).
-
-## Risks and Mitigations
-
-| Risk                                                                                                 | Mitigation                                                                                                                                                     |
-| ---------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `update()` is a generic name on `SubagentRuntime` — could confuse readers about what's being updated | The method is a documented widget delegation like its siblings (`markFinished`, `ensureTimer`); the JSDoc comment clarifies it delegates to `widget.update()`. |
-| `background-spawner` signature change could break other callers                                      | Grep confirms only `agent-tool.ts` calls `spawnBackground` — no other consumers.                                                                               |
-| Renaming method in runtime could miss a call site                                                    | Grep and `pnpm run check` after each step catch all references.                                                                                                |
-
-## Open Questions
-
-None — the issue's proposed direction is unambiguous and the architecture doc confirms the design.