@gotgenes/pi-subagents 7.1.0 → 7.2.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.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

@@ -615,8 +615,8 @@ The approach is layered: each step makes the next step trivial.
 | 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                                      |
+| `as any` casts in index   | 1 (down from 5; Layer 1 resolved 4)     |
+| Adapter closures in index | 41 (down from 44; Layer 1 resolved 3)   |
 | Index fan-out             | 25 imports                              |
 
 ### Root cause
@@ -624,8 +624,10 @@ The approach is layered: each step makes the next step trivial.
 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.
+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).
 4. `AgentToolWidget` uses different method names than `SubagentRuntime` (name mismatch).
 
@@ -655,13 +657,13 @@ 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)

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/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,43 @@
+---
+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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "7.1.0",
+  "version": "7.2.0",
   "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";
@@ -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(),
@@ -209,19 +203,9 @@ export default function (pi: ExtensionAPI) {
     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. */

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}`);
       }