@gotgenes/pi-subagents 7.1.0 → 7.2.1

package/CHANGELOG.md

@@ -5,6 +5,33 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [7.2.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.2.0...pi-subagents-v7.2.1) (2026-05-25)
+
+
+### Documentation
+
+* mark Layer 2 done and update health metrics in architecture doc ([ad00426](https://github.com/gotgenes/pi-packages/commit/ad00426f0f29ceff0915033419fdc2f1b53755b0))
+* plan align tool interfaces for structural typing ([#194](https://github.com/gotgenes/pi-packages/issues/194)) ([36e56b0](https://github.com/gotgenes/pi-packages/commit/36e56b08351893e3c2d63569e7cfa140c172e20b))
+* **retro:** add planning stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([63a5763](https://github.com/gotgenes/pi-packages/commit/63a5763ed2bf4c2a6e2e9a19fdcdce71a2a9905a))
+* **retro:** add retro notes for issue [#193](https://github.com/gotgenes/pi-packages/issues/193) ([8987f90](https://github.com/gotgenes/pi-packages/commit/8987f907e00bb70429782c947a2afbdb1db5faa9))
+* **retro:** add TDD stage notes for issue [#194](https://github.com/gotgenes/pi-packages/issues/194) ([f692323](https://github.com/gotgenes/pi-packages/commit/f69232395882c07d6d95273e08021b94800f0e43))
+
+## [7.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.1.0...pi-subagents-v7.2.0) (2026-05-25)
+
+
+### Features
+
+* SubagentRuntime stores typed SessionContext and owns context queries ([#193](https://github.com/gotgenes/pi-packages/issues/193)) ([4ca5319](https://github.com/gotgenes/pi-packages/commit/4ca531934e36c37c7cbc8fef8314a483e7dec479))
+
+
+### Documentation
+
+* mark Phase 11 Layer 1 complete, update metrics ([#193](https://github.com/gotgenes/pi-packages/issues/193)) ([32233ed](https://github.com/gotgenes/pi-packages/commit/32233ed89f27dca854ce858978c3acc029b1e801))
+* plan SubagentRuntime owns context queries ([#193](https://github.com/gotgenes/pi-packages/issues/193)) ([6ea475a](https://github.com/gotgenes/pi-packages/commit/6ea475af94f8456c1d665adcd007dd2833ab7a4b))
+* **retro:** add planning stage notes for issue [#193](https://github.com/gotgenes/pi-packages/issues/193) ([7da6d5a](https://github.com/gotgenes/pi-packages/commit/7da6d5abac82bdea0cbdbc8677dda04d38a7887d))
+* **retro:** add retro notes for issue [#192](https://github.com/gotgenes/pi-packages/issues/192) ([1223de4](https://github.com/gotgenes/pi-packages/commit/1223de4a68d4514eb504c5c95d64fb35500d286b))
+* **retro:** add TDD stage notes for issue [#193](https://github.com/gotgenes/pi-packages/issues/193) ([3950b81](https://github.com/gotgenes/pi-packages/commit/3950b81228a3db57eb4c24236fa7d75c638a335a))
+
 ## [7.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v7.0.0...pi-subagents-v7.1.0) (2026-05-24)
 
 

package/docs/architecture/architecture.md

@@ -608,26 +608,30 @@ The approach is layered: each step makes the next step trivial.
 
 ### Findings
 
-| Metric                    | Value                                   |
-| ------------------------- | --------------------------------------- |
-| Health score              | 75/100 (B)                              |
-| #1 hotspot                | `index.ts` (128 commits, accelerating)  |
-| Dead exports              | 1 (`getToolCallName` re-export)         |
-| Production duplication    | 0                                       |
-| Test duplication          | 1,396 lines (69 clone groups, 22 files) |
-| `as any` casts in index   | 5                                       |
-| Adapter closures in index | 44                                      |
-| Index fan-out             | 25 imports                              |
+| Metric                    | Value                                      |
+| ------------------------- | ------------------------------------------ |
+| Health score              | 75/100 (B)                                 |
+| #1 hotspot                | `index.ts` (128 commits, accelerating)     |
+| Dead exports              | 0 (down from 1; Layer 2 removed re-export) |
+| Production duplication    | 0                                          |
+| Test duplication          | 1,396 lines (69 clone groups, 22 files)    |
+| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)        |
+| Adapter closures in index | 40 (down from 44; Layers 1–2 resolved 4)   |
+| Index fan-out             | 25 imports                                 |
 
 ### Root cause
 
 The 44 adapter closures in `index.ts` exist because the tool factories accept narrow interfaces that don't structurally match the real objects.
 The real objects can't satisfy the interfaces because:
 
-1. `SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }` — so every consumer must `as any` cast to read fields.
-2. Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.
-3. `AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).
-4. `AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).
+1. ~~`SubagentRuntime.currentCtx` is typed `{ pi: unknown; ctx: unknown }` — so every consumer must `as any` cast to read fields.~~
+   Resolved by Layer 0 (#192) + Layer 1 (#193).
+2. ~~Context queries (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) live as closures in index.ts instead of methods on the state holder.~~
+   Resolved by Layer 1 (#193).
+3. ~~`AgentToolManager` mixes fields from `AgentManager` and `SettingsManager` (source mismatch).~~
+   Resolved by Layer 2 (#194).
+4. ~~`AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).~~
+   Resolved by Layer 2 (#194).
 
 Fix these structural misalignments and the class conversions become mechanical.
 
@@ -655,18 +659,18 @@ export interface SessionContext {
 - Smell: Category C (platform type threading)
 - Outcome: typed foundation for Layers 1–4; no `as any` needed by consumers of `SubagentRuntime`
 
-### Layer 1: `SubagentRuntime` stores typed context, owns its queries ([#193][193])
+### Layer 1: `SubagentRuntime` stores typed context, owns its queries ([#193][193]) ✓ done
 
 Change `currentCtx` from `{ pi: unknown; ctx: unknown }` to `SessionContext | undefined`.
 The single `as SessionContext` cast moves into `handleSessionStart` — the boundary where the SDK hands us the value.
 Add typed methods: `buildSnapshot(inheritContext)`, `getModelInfo()`, `getSessionInfo()`.
 
-- Target: `src/runtime.ts`, `src/handlers/lifecycle.ts`
+- Target: `src/runtime.ts`, `src/handlers/lifecycle.ts`, `src/service/service-adapter.ts`, `src/index.ts`
 - Smell: Category C (closure queries on mutable field → methods on state owner)
 - Outcome: 3 closure queries in index.ts → 0; `SubagentRuntime` is self-sufficient for tool deps
 - Enables: Layer 3 (tools accept `SubagentRuntime` directly)
 
-### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194])
+### Layer 2: Align interfaces so real objects satisfy tool deps structurally ([#194][194]) ✓ done
 
 Three alignment changes:
 
@@ -679,7 +683,7 @@ After this step, `AgentManager` structurally satisfies `AgentToolManager` and `S
 
 - Target: `src/tools/agent-tool.ts` (interface), `src/runtime.ts` (method names), `src/ui/message-formatters.ts`
 - Smell: Category C (source mismatch, name mismatch) + Category A (dead export)
-- Outcome: structural typing connects real objects to tool interfaces without adapters
+- Outcome: structural typing connects real objects to tool interfaces without adapters; 0 dead exports (fallow clean)
 - Enables: Layer 3 (class constructors accept real objects directly)
 
 ### Layer 3: Convert closure factories to classes ([#195][195], [#196][196])

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

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

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

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

@@ -33,3 +33,27 @@ Baseline: 53 test files, 848 tests; final: unchanged.
 
 - Pre-existing lint failure in `docs/architecture/architecture.md` (5 unused MD053 link references for issues #164, #165, #170, #171, #172) was fixed as part of the baseline verification and included in the feat commit.
 - The interface landed exactly as planned — no deviations from the plan's Design Overview.
+
+## Stage: Final Retrospective (2026-05-24T20:00:00Z)
+
+### Session summary
+
+All three stages (plan, TDD, ship) completed in a single session.
+Released as `pi-subagents-v7.1.0`.
+No rework, no deviations from plan.
+
+### Observations
+
+#### What went well
+
+- The issue was fully specified — no ambiguity, no `ask_user` needed at any stage.
+- Trivial scope (one interface, no consumers) made the plan-to-ship pipeline fast and mechanical.
+- Pre-existing lint failures in `architecture.md` were caught during baseline verification and fixed without disrupting the flow.
+
+#### What caused friction (agent side)
+
+- None — clean execution with no rework or corrections.
+
+#### What caused friction (user side)
+
+- None — no intervention needed beyond invoking the three workflow commands.

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

@@ -0,0 +1,75 @@
+---
+issue: 193
+issue_title: "SubagentRuntime owns context queries"
+---
+
+# Retro: #193 — SubagentRuntime owns context queries
+
+## Stage: Planning (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Planned the Layer 1 change that types `SubagentRuntime.currentCtx` as `SessionContext`, adds three query methods (`buildSnapshot`, `getModelInfo`, `getSessionInfo`), and eliminates 4 `as any` casts from `index.ts`.
+The plan covers 7 TDD steps touching `runtime.ts`, `handlers/lifecycle.ts`, `parent-snapshot.ts`, `context.ts`, `service-adapter.ts`, and `index.ts`.
+
+### Observations
+
+- The `pi` field in `currentCtx` is never read back — only stored.
+  Dropping it is safe; `SessionLifecycleHandler` already holds `pi` as a constructor param.
+- `ExtensionContext` structurally satisfies `SessionContext`, so changing `buildParentSnapshot`'s param type is source-compatible with the `/agents` command handler that passes raw SDK `ctx`.
+- `service-adapter.ts` gets the biggest structural change: its two closure params (`getCtx`, `getModelRegistry`) collapse into a single `ServiceRuntimeLike` interface.
+- No design ambiguity — the architecture doc's Layer 1 spec and the issue body are fully aligned.
+- Test fixtures in `make-deps.ts` are unaffected because the `AgentToolDeps` interface shape doesn't change — only the wiring in `index.ts` that supplies the implementations changes.
+
+## Stage: Implementation — TDD (2026-05-24T20:30:00Z)
+
+### Session summary
+
+Completed all 6 implementation TDD steps plus an architecture doc update in one session.
+The `getSessionInfo` implementation needed `?.sessionManager.getSessionFile()` (not `?.sessionManager?.getSessionFile()`) since `sessionManager` is a required field of `SessionContext` — ESLint's `no-unnecessary-condition` caught this at the pre-commit hook.
+Final test count: 854 (up from 848 baseline, +6 new tests for `buildSnapshot`, `getModelInfo`, `getSessionInfo`).
+
+### Observations
+
+- The plan's Non-Goals section incorrectly said `buildParentContext` would NOT change.
+In practice it had to accept `SessionContext` instead of `ExtensionContext` — they are not substitutable in that direction.
+The Module-Level Changes list was correct; only the Non-Goals prose was wrong.
+- `context.ts` needed a local `BranchEntry` union type to handle `getBranch(): unknown[]`.
+TypeScript's discriminated union narrowing doesn't work when the union includes a catch-all `{ type: string }` arm — explicit casts within each `if` branch were required.
+- `service-adapter.ts` ended up using `runtime.currentCtx.modelRegistry` directly (no `getModelInfo()` call needed in the service adapter) — `ServiceRuntimeLike` only needs `currentCtx` and `buildSnapshot`.
+This is cleaner than the plan's `getModelInfo(): { modelRegistry: unknown }` approach.
+- Biome's `noUnusedPrivateClassMembers` warning caught the leftover `private readonly pi: unknown` in `SessionLifecycleHandler`.
+Removed `pi` from the constructor entirely (rather than adding `_` prefix), which also cleaned up `index.ts`.
+- The `eslint-disable` directive at the top of `index.ts` had two now-unused entries (`no-unsafe-member-access`, `no-unsafe-call`) removed by `eslint --fix`.
+
+## Stage: Final Retrospective (2026-05-24T20:45:00Z)
+
+### Session summary
+
+All three stages (plan, TDD, ship) completed in a single session.
+Released as `pi-subagents-v7.2.0`.
+One plan contradiction required a judgment call during implementation; otherwise clean mechanical execution.
+
+### Observations
+
+#### What went well
+
+- The architecture doc's Phase 11 Layer 1 spec was precise enough that no `ask_user` was needed at any stage — the issue body, architecture doc, and #192 retro were fully aligned.
+- `ServiceRuntimeLike` ended up simpler than planned (only `currentCtx` + `buildSnapshot` instead of also requiring `getModelInfo()`) — the implementation found a cleaner design than the plan specified.
+- Test count increase (+6) validates the design: methods that were previously untestable as anonymous closures now have dedicated unit tests.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's Non-Goals section claimed `buildParentContext` would not change, contradicting Module-Level Changes item #4 which explicitly listed the file.
+  The planning stage didn't cross-check these sections before committing.
+  Impact: brief confusion during step 3 about which section to trust (resolved by following Module-Level Changes); no rework, added ~30s of deliberation.
+- `missing-context` — TypeScript's discriminated union narrowing limitation with a `{ type: string }` catch-all arm was not anticipated.
+  Impact: required adding a local `BranchEntry` union type and explicit casts in `context.ts`; no rework but ~2 min of debugging the type error.
+
+#### What caused friction (user side)
+
+- None — no user intervention was needed at any point across all three stages.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added a Non-Goals vs Module-Level Changes cross-check instruction under the Module-Level Changes bullet.

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

@@ -0,0 +1,36 @@
+---
+issue: 194
+issue_title: "Align tool interfaces for structural typing"
+---
+
+# Retro: #194 — Align tool interfaces for structural typing
+
+## Stage: Planning (2026-05-24T12:00:00Z)
+
+### Session summary
+
+Produced an implementation plan for three targeted alignment changes: moving `getMaxConcurrent` off manager interfaces to the settings accessor, renaming `SubagentRuntime.updateWidget()` → `update()`, and removing the dead `getToolCallName` re-export.
+The plan includes a 4-step TDD order with type-check gates after each refactoring step.
+
+### Observations
+
+- Issue #193 (Layer 1) is already closed/implemented, confirming this layer can proceed immediately.
+
+## Stage: Implementation — TDD (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Completed all 4 TDD steps: renamed `SubagentRuntime.updateWidget()` → `update()`, moved `getMaxConcurrent` from manager interfaces to the `settings` narrow type, removed the dead `getToolCallName` re-export, and updated the architecture doc.
+Test count stayed flat at 854 (53 files) — all green.
+The `pnpm run check` type-gate caught a previously-unnoticed `test/helpers/make-deps.test.ts` that also validated `getMaxConcurrent` and the old `settings` shape; this file was updated as part of step 2.
+
+### Observations
+
+- An unexpected file `test/helpers/make-deps.test.ts` had three type errors after removing `getMaxConcurrent` (one test asserting `manager.getMaxConcurrent()`, one structural compatibility check referencing it, and one settings override that only passed `defaultMaxTurns`).
+  All three were fixed in the same commit as step 2 — no deviation from the plan.
+- Adding `settings` to `BackgroundParams` (instead of as a 5th function parameter) was the right call: it keeps `spawnBackground` at 4 arguments and groups all spawn-context values together.
+- The health metric update: dead exports 1 → 0, adapter closures 41 → 40 (only `getMaxConcurrent` was removed in this layer; the remaining 8 widget/manager adapter closures need #195 class conversion to collapse).
+- The `background-spawner.ts` module is the only consumer of `getMaxConcurrent` — grep confirms no other call sites beyond `agent-tool.ts`'s interface definition.
+- The `NotificationManager` constructor takes `updateWidget` as a positional callback parameter name — this does NOT need renaming (it's not a structural interface member).
+- The rename from `updateWidget` → `update` is safe because the `WidgetLike` interface in `runtime.ts` already uses `update()` — no naming conflict within the class.
+- All three changes are independent of each other and could be committed in any order, but the plan sequences them for clean `pnpm run check` passes at each step.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.1.0",
+  "version": "7.2.1",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/handlers/lifecycle.ts

@@ -1,3 +1,5 @@
+import type { SessionContext } from "#src/types";
+
 /**
  * Session lifecycle event handlers: session_start, session_before_switch, session_shutdown.
  *
@@ -14,7 +16,7 @@ export interface LifecycleManager {
 
 /** Narrow runtime interface — only the methods lifecycle handlers call. */
 export interface LifecycleRuntime {
-  setSessionContext(pi: unknown, ctx: unknown): void;
+  setSessionContext(ctx: SessionContext): void;
   clearSessionContext(): void;
 }
 
@@ -22,7 +24,6 @@ export interface LifecycleRuntime {
  * Handles session lifecycle events.
  *
  * Constructor deps:
- * - `pi` — the ExtensionAPI instance, stored in runtime on session_start
  * - `runtime` — owns session context state
  * - `manager` — manages agent lifecycle (clear, abort, dispose)
  * - `disposeNotifications` — tears down the notification system on shutdown
@@ -30,7 +31,6 @@ export interface LifecycleRuntime {
  */
 export class SessionLifecycleHandler {
   constructor(
-    private readonly pi: unknown,
     private readonly runtime: LifecycleRuntime,
     private readonly manager: LifecycleManager,
     private readonly disposeNotifications: () => void,
@@ -38,7 +38,7 @@ export class SessionLifecycleHandler {
   ) {}
 
   handleSessionStart(_event: unknown, ctx: unknown): void {
-    this.runtime.setSessionContext(this.pi, ctx);
+    this.runtime.setSessionContext(ctx as SessionContext);
     this.manager.clearCompleted();
   }
 

package/src/index.ts

@@ -1,4 +1,4 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-call, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
+/* eslint-disable @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-argument -- Pi SDK types are not fully exported; see upstream Pi SDK for type improvements */
 /**
  * pi-agents — A pi extension providing Claude Code-style autonomous sub-agents.
  *
@@ -35,7 +35,7 @@ import { publishSubagentsService, unpublishSubagentsService } from "#src/service
 import { createSubagentsService } from "#src/service/service-adapter";
 import { detectEnv } from "#src/session/env";
 
-import { type ModelRegistry, resolveModel } from "#src/session/model-resolver";
+import { resolveModel } from "#src/session/model-resolver";
 import { buildAgentPrompt } from "#src/session/prompts";
 import { deriveSubagentSessionDir } from "#src/session/session-dir";
 import { preloadSkills } from "#src/session/skill-loader";
@@ -67,7 +67,7 @@ export default function (pi: ExtensionAPI) {
     (msg, opts) => pi.sendMessage(msg, opts),
     runtime.agentActivity,
     (id) => runtime.markFinished(id),
-    () => runtime.updateWidget(),
+    () => runtime.update(),
   );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
@@ -162,16 +162,10 @@ export default function (pi: ExtensionAPI) {
 
   // Typed service published via Symbol.for() for cross-extension access.
   // Consumers: const { getSubagentsService } = await import("@gotgenes/pi-subagents");
-  const service = createSubagentsService(
-    manager,
-    resolveModel,
-    () => runtime.currentCtx,
-    () => (runtime.currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
-  );
+  const service = createSubagentsService(manager, resolveModel, runtime);
   publishSubagentsService(service);
 
   const lifecycle = new SessionLifecycleHandler(
-    pi,
     runtime,
     manager,
     () => notifications.dispose(),
@@ -197,31 +191,20 @@ export default function (pi: ExtensionAPI) {
       spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
-      getMaxConcurrent: () => settings.maxConcurrent,
     },
     widget: {
       setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),
       ensureTimer: () => runtime.ensureTimer(),
-      update: () => runtime.updateWidget(),
+      update: () => runtime.update(),
       markFinished: (id) => runtime.markFinished(id),
     },
     agentActivity: runtime.agentActivity,
     registry,
     agentDir: getAgentDir(),
     settings,
-    buildSnapshot: (inheritContext) =>
-      buildParentSnapshot(
-        runtime.currentCtx?.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext,
-        inheritContext,
-      ),
-    getModelInfo: () => ({
-      parentModel: (runtime.currentCtx?.ctx as any)?.model,
-      modelRegistry: (runtime.currentCtx?.ctx as any)?.modelRegistry,
-    }),
-    getSessionInfo: () => ({
-      parentSessionFile: (runtime.currentCtx?.ctx as any)?.sessionManager?.getSessionFile() ?? "",
-      parentSessionId: (runtime.currentCtx?.ctx as any)?.sessionManager?.getSessionId() ?? "",
-    }),
+    buildSnapshot: runtime.buildSnapshot.bind(runtime),
+    getModelInfo: runtime.getModelInfo.bind(runtime),
+    getSessionInfo: runtime.getSessionInfo.bind(runtime),
   })));
 
   // ---- get_subagent_result tool ----

package/src/lifecycle/parent-snapshot.ts

@@ -2,8 +2,8 @@
  * parent-snapshot.ts — Capture parent session state as a plain data snapshot.
  */
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { buildParentContext } from "#src/session/context";
+import type { SessionContext } from "#src/types";
 
 /**
  * Plain data snapshot of the parent session state captured at spawn time.
@@ -32,7 +32,7 @@ export interface ParentSnapshot {
  * when the user requested the agent, not when a queue slot opens.
  */
 export function buildParentSnapshot(
-  ctx: ExtensionContext,
+  ctx: SessionContext,
   inheritContext?: boolean,
 ): ParentSnapshot {
   const parentContext = inheritContext ? buildParentContext(ctx) : undefined;
@@ -40,7 +40,8 @@ export function buildParentSnapshot(
     cwd: ctx.cwd,
     systemPrompt: ctx.getSystemPrompt(),
     model: ctx.model,
-    modelRegistry: ctx.modelRegistry,
+
+    modelRegistry: ctx.modelRegistry!,
     // eslint-disable-next-line @typescript-eslint/prefer-nullish-coalescing -- || intentional: converts empty string to undefined as well as null/undefined
     parentContext: parentContext || undefined,
   };

package/src/runtime.ts

@@ -6,6 +6,9 @@
  * Follows the same pattern as pi-permission-system's ExtensionRuntime.
  */
 
+import { buildParentSnapshot, type ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { ModelInfo } from "#src/tools/spawn-config";
+import type { SessionContext } from "#src/types";
 import type { AgentActivityTracker } from "#src/ui/agent-activity-tracker";
 import type { UICtx } from "#src/ui/agent-widget";
 
@@ -39,7 +42,7 @@ export interface RunConfig {
 export class SubagentRuntime {
   // ── Session state (was closure-scoped in index.ts) ───────────────────────
   /** Active Pi session context — set on session_start, cleared on session_shutdown. */
-  currentCtx: { pi: unknown; ctx: unknown } | undefined = undefined;
+  currentCtx: SessionContext | undefined = undefined;
   /**
    * Per-agent live activity state shared across the notification system,
    * widget, and tool handlers. The Map itself is never replaced.
@@ -54,8 +57,8 @@ export class SubagentRuntime {
   // ── Session-context methods ──────────────────────────────────────────────
 
   /** Store the active Pi session context (called from session_start). */
-  setSessionContext(pi: unknown, ctx: unknown): void {
-    this.currentCtx = { pi, ctx };
+  setSessionContext(ctx: SessionContext): void {
+    this.currentCtx = ctx;
   }
 
   /** Clear the session context (called from session_shutdown). */
@@ -63,6 +66,31 @@ export class SubagentRuntime {
     this.currentCtx = undefined;
   }
 
+  /**
+   * Build a parent snapshot from the current session context.
+   * Only valid during an active session (currentCtx is defined).
+   */
+  buildSnapshot(inheritContext: boolean): ParentSnapshot {
+
+    return buildParentSnapshot(this.currentCtx!, inheritContext);
+  }
+
+  /** Extract model info from the current session context. */
+  getModelInfo(): ModelInfo {
+    return {
+      parentModel: this.currentCtx?.model as ModelInfo["parentModel"],
+      modelRegistry: this.currentCtx?.modelRegistry,
+    };
+  }
+
+  /** Extract session identity from the current session context. */
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string } {
+    return {
+      parentSessionFile: this.currentCtx?.sessionManager.getSessionFile() ?? "",
+      parentSessionId: this.currentCtx?.sessionManager.getSessionId() ?? "",
+    };
+  }
+
   // ── Widget delegation methods ─────────────────────────────────────────────
 
   /** Delegate to widget.setUICtx — no-op when widget is null. */
@@ -81,7 +109,7 @@ export class SubagentRuntime {
   }
 
   /** Delegate to widget.update — no-op when widget is null. */
-  updateWidget(): void {
+  update(): void {
     this.widget?.update();
   }
 

package/src/service/service-adapter.ts

@@ -5,12 +5,10 @@
  * (stripping non-serializable fields), and session gating.
  */
 
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
-import { buildParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { SubagentRecord, SubagentsService } from "#src/service/service";
 import type { ModelRegistry } from "#src/session/model-resolver";
-import type { AgentRecord } from "#src/types";
+import type { AgentRecord, SessionContext } from "#src/types";
 
 /** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
 export interface AgentManagerLike {
@@ -23,23 +21,30 @@ export interface AgentManagerLike {
   queueSteer(id: string, message: string): boolean;
 }
 
+/**
+ * Narrow runtime interface consumed by the service adapter.
+ * `SubagentRuntime` satisfies this structurally; tests use plain stubs.
+ */
+export interface ServiceRuntimeLike {
+  readonly currentCtx: SessionContext | undefined;
+  buildSnapshot(inheritContext: boolean): ParentSnapshot;
+}
+
 /** Create a SubagentsService backed by the given dependencies. */
 export function createSubagentsService(
   manager: AgentManagerLike,
   resolveModel: (input: string, registry: ModelRegistry) => unknown,
-  getCtx: () => { pi: unknown; ctx: unknown } | undefined,
-  getModelRegistry: () => ModelRegistry | undefined,
+  runtime: ServiceRuntimeLike,
 ): SubagentsService {
   return {
     spawn(type: string, prompt: string, options?) {
-      const session = getCtx();
-      if (!session) {
+      if (!runtime.currentCtx) {
         throw new Error("No active session — cannot spawn agents outside a session.");
       }
 
       let model: unknown;
       if (options?.model) {
-        const registry = getModelRegistry();
+        const registry = runtime.currentCtx.modelRegistry;
         if (!registry) {
           throw new Error("No model registry available.");
         }
@@ -53,10 +58,7 @@ export function createSubagentsService(
       const description = options?.description ?? prompt.slice(0, 80);
       const isBackground = !(options?.foreground ?? false);
 
-      const snapshot = buildParentSnapshot(
-        session.ctx as ExtensionContext,
-        options?.inheritContext,
-      );
+      const snapshot = runtime.buildSnapshot(options?.inheritContext ?? false);
       return manager.spawn(snapshot, type, prompt, {
         description,
         model,

package/src/session/context.ts

@@ -3,7 +3,19 @@
  */
 
 import type { TextContent } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { SessionContext } from "#src/types";
+
+/**
+ * Minimal structural types for session branch entries consumed by buildParentContext.
+ * `getBranch()` returns `unknown[]` in SessionContext (ISP), so we cast to these
+ * local shapes instead of coupling to the SDK's SessionEntry type.
+ */
+type MessageEntry = {
+  type: "message";
+  message: { role: string; content: string | { type: string }[] };
+};
+type CompactionEntry = { type: "compaction"; summary?: string };
+type BranchEntry = MessageEntry | CompactionEntry | { type: string };
 
 /** Type predicate: narrow an unknown content block to TextContent. */
 function isTextContent(c: unknown): c is TextContent {
@@ -23,15 +35,16 @@ export function extractText(content: unknown[]): string {
  * Used when inherit_context is true to give the subagent visibility
  * into what has been discussed/done so far.
  */
-export function buildParentContext(ctx: ExtensionContext): string {
+export function buildParentContext(ctx: SessionContext): string {
   const entries = ctx.sessionManager.getBranch();
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
   if (!entries || entries.length === 0) return "";
 
   const parts: string[] = [];
 
-  for (const entry of entries) {
-    if (entry.type === "message") {
+  for (const rawEntry of entries as BranchEntry[]) {
+    if (rawEntry.type === "message") {
+      const entry = rawEntry as MessageEntry;
       const msg = entry.message;
       if (msg.role === "user") {
         const text = typeof msg.content === "string"
@@ -39,12 +52,13 @@ export function buildParentContext(ctx: ExtensionContext): string {
           : extractText(msg.content);
         if (text.trim()) parts.push(`[User]: ${text.trim()}`);
       } else if (msg.role === "assistant") {
-        const text = extractText(msg.content);
+        const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
         if (text.trim()) parts.push(`[Assistant]: ${text.trim()}`);
       }
       // Skip toolResult messages — too verbose for context
-    } else if (entry.type === "compaction") {
+    } else if (rawEntry.type === "compaction") {
       // Include compaction summaries — they're already condensed
+      const entry = rawEntry as CompactionEntry;
       if (entry.summary) {
         parts.push(`[Summary]: ${entry.summary}`);
       }

package/src/tools/agent-tool.ts

@@ -23,7 +23,6 @@ export interface AgentToolManager {
   spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
-  getMaxConcurrent: () => number;
 }
 
 /** Narrow widget interface — only the methods the Agent tool calls. */
@@ -50,8 +49,8 @@ export interface AgentToolDeps {
   agentActivity: AgentActivityAccess;
   registry: AgentTypeRegistry;
   agentDir: string;
-  /** Narrow settings accessor — only the default max turns is needed here. */
-  settings: { readonly defaultMaxTurns: number | undefined };
+  /** Narrow settings accessor — only the fields the Agent tool reads. */
+  settings: { readonly defaultMaxTurns: number | undefined; readonly maxConcurrent: number };
   /** Build a ParentSnapshot from the current session context. */
   buildSnapshot: (inheritContext: boolean) => ParentSnapshot;
   /** Model info from the current session context. */
@@ -252,7 +251,7 @@ Guidelines:
           manager,
           widget,
           agentActivity,
-          { config, snapshot, parentSession },
+          { config, snapshot, parentSession, settings },
         );
       }
 

package/src/tools/background-spawner.ts

@@ -11,7 +11,6 @@ import { subscribeUIObserver } from "#src/ui/ui-observer";
 export interface BackgroundManagerDeps {
   spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
   getRecord(id: string): AgentRecord | undefined;
-  getMaxConcurrent(): number;
 }
 
 /** Narrow widget interface for the background spawner. */
@@ -25,6 +24,7 @@ export interface BackgroundParams {
   config: ResolvedSpawnConfig;
   snapshot: ParentSnapshot;
   parentSession: ParentSessionInfo;
+  settings: { readonly maxConcurrent: number };
 }
 
 /**
@@ -77,7 +77,7 @@ export function spawnBackground(
       `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
-        ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
+        ? `Position: queued (max ${params.settings.maxConcurrent} concurrent)\n`
         : "") +
       `\nYou will be notified when this agent completes.\n` +
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +

package/src/ui/message-formatters.ts

@@ -21,8 +21,6 @@ export interface FormatterContext {
 
 // ── File-local types and guards ─────────────────────────────────────────────
 
-export { getToolCallName } from "#src/session/content-items";
-
 /** Bash execution message — 'bashExecution' role is not in the SDK's AgentSession message role union. */
 export interface BashExecutionMessage {
   role: "bashExecution";