@gotgenes/pi-subagents 7.0.0 → 7.2.0

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

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

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

@@ -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/0185-remove-persistent-agent-memory.md

@@ -37,3 +37,37 @@ New file `safe-fs.test.ts` was created with 13 tests for the extracted utilities
   Fix: inline the literal union `"user" | "project" | "local"` directly in `memory.ts` as a local type, so it compiles cleanly until deletion in step 4.
 - The `SKILL.md` for `package-pi-subagents` also listed `memory.ts` in the session domain table — updated alongside `architecture.md` in the docs commit.
 - No deviations from the plan other than the two minor bugs above (both self-corrected within the same TDD step).
+
+## Stage: Final Retrospective (2026-05-24T22:47:55Z)
+
+### Session summary
+
+Shipped issue #185 as `pi-subagents-v7.0.0`.
+CI passed, issue closed, release-please PR #190 merged.
+Three sessions total: planning, TDD (5 steps / 5 commits), shipping.
+
+### Observations
+
+#### What went well
+
+- The issue's "Scope" section was precise enough that the planning session required no `ask_user` and the Explore agent's trace matched the final commit diff exactly.
+- Consumers-first, declaration-last ordering kept each commit independently compilable (after the two self-corrected fixes).
+- The `SKILL.md` domain table update was caught naturally during the docs step even though the plan didn't list it.
+
+#### What caused friction (agent side)
+
+- `missing-context` — In TDD step 1, `memory.ts` was updated to re-export `isUnsafeName` from `safe-fs`, but the function was not imported into `memory.ts`'s own scope.
+  `resolveMemoryDir` threw a `ReferenceError` at runtime.
+  Impact: one extra test-run cycle (~5 seconds) and a trivial one-line fix; no rework commit.
+- `missing-context` — In TDD step 3, removing `MemoryScope` from `types.ts` broke `memory.ts` (scheduled for deletion in step 4).
+  The plan said "consumers-first" but didn't account for the doomed module itself being a consumer of the type.
+  Impact: one extra `pnpm run check` cycle and a local type inline; no rework commit.
+  Both share the same root cause: incremental deletion plans must account for doomed files' own imports at each intermediate step.
+
+#### What caused friction (user side)
+
+- None observed — all three sessions ran without user corrections or redirections.
+
+### Changes made
+
+1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` about accounting for doomed modules' own imports during multi-step deletion.

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

@@ -0,0 +1,59 @@
+---
+issue: 192
+issue_title: "Define SessionContext narrow interface"
+---
+
+# Retro: #192 — Define SessionContext narrow interface
+
+## Stage: Planning (2026-05-24T16:00:00Z)
+
+### Session summary
+
+Planned the pure-additive `SessionContext` interface for `src/types.ts`.
+Traced all 5 consumed fields against the SDK's `ExtensionContext` type declarations to confirm shape alignment.
+Single TDD step: add the interface and verify with `pnpm run check`.
+
+### Observations
+
+- The interface is trivial in scope — one new export with no consumers changing.
+  This is intentionally the smallest possible first step to unblock Layer 1 (#193).
+- `ModelRegistry` already exists as a local narrow interface in `src/session/model-resolver.ts`; `SessionContext` imports it rather than redeclaring.
+- `sessionManager` uses an inline structural type (3 methods) rather than importing the SDK's `ReadonlySessionManager` (13 methods) — ISP applies here.
+- No design ambiguity required `ask_user`; the issue's proposed change section was fully specified.
+
+## Stage: Implementation — TDD (2026-05-24T19:55:00Z)
+
+### Session summary
+
+Added the `SessionContext` interface to `src/types.ts` with an `import type { ModelRegistry }` from `#src/session/model-resolver`.
+Single compile-time step — no runtime tests needed for a pure type definition.
+Baseline: 53 test files, 848 tests; final: unchanged.
+
+### Observations
+
+- 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.0.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,
   };