@gotgenes/pi-subagents 6.1.0 → 6.2.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [6.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.1.0...pi-subagents-v6.2.0) (2026-05-21)
+
+
+### Features
+
+* add ParentSnapshot type and builder ([#99](https://github.com/gotgenes/pi-packages/issues/99)) ([ee24eb9](https://github.com/gotgenes/pi-packages/commit/ee24eb907eba9f6f917bc166c912e5482eff5bd5))
+
+
+### Documentation
+
+* **pi-subagents:** cross-reference issues in architecture decomposition plan ([2242e45](https://github.com/gotgenes/pi-packages/commit/2242e457b7e1bf8cb44e9a1df6fb4d2fd1ba1116))
+* plan replace live ctx capture with ParentSnapshot ([#99](https://github.com/gotgenes/pi-packages/issues/99)) ([b6b63f8](https://github.com/gotgenes/pi-packages/commit/b6b63f8677231617a00cb1e3d1227667cbae7ecd))
+* **retro:** add retro notes for issue [#98](https://github.com/gotgenes/pi-packages/issues/98) ([ef52aaa](https://github.com/gotgenes/pi-packages/commit/ef52aaa4d8b690b309f2129ff34f90c44368cc57))
+
 ## [6.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.0.1...pi-subagents-v6.1.0) (2026-05-20)
 
 

package/docs/architecture/architecture.md

@@ -489,7 +489,7 @@ The `if (record.status !== "stopped")` guards in `.then()` and `.catch()` become
 The three designs are independent and can land in any order.
 The recommended sequence minimizes intermediate churn.
 
-#### Step 1: Record state machine
+#### Step 1: Record state machine ✓ (done — #98, #102)
 
 Extract status-transition methods onto `AgentRecord` (or a `RecordManager` wrapper).
 Purely mechanical — replace scattered field writes with method calls.
@@ -497,7 +497,9 @@ No interface changes for callers.
 
 This is the lowest-risk change and immediately reduces `startAgent()` line count.
 
-#### Step 2: Parent snapshot
+Issue #102 consolidated test `AgentRecord` construction into a shared factory as follow-up.
+
+#### Step 2: Parent snapshot (#99)
 
 Replace `ctx: ExtensionContext` in `SpawnArgs` with a `ParentSnapshot` data object.
 Capture the snapshot in `spawn()` or at the tool call site.
@@ -506,7 +508,7 @@ Remove `pi: ExtensionAPI` from `SpawnArgs` (it is only used to pass to `runner.r
 
 This change narrows the `AgentRunner` interface and eliminates live-reference capture.
 
-#### Step 3: Session-event observation
+#### Step 3: Session-event observation (#100)
 
 Replace the callback-threading pattern with direct session subscriptions.
 AgentManager subscribes to the session after creation to update the record.

package/docs/plans/0099-replace-ctx-with-parent-snapshot.md

@@ -0,0 +1,488 @@
+---
+issue: 99
+issue_title: "Replace live `ctx` capture with ParentSnapshot in AgentManager"
+---
+
+# Replace live ctx capture with ParentSnapshot
+
+## Problem Statement
+
+`AgentManager.spawn()` captures a live `ctx: ExtensionContext` reference into `SpawnArgs`, which is held in the concurrency queue until a slot opens.
+When the queued agent eventually dequeues, `runAgent()` reads from this live reference — `ctx.cwd`, `ctx.getSystemPrompt()`, `ctx.model`, `ctx.modelRegistry` — all of which may have changed since the agent was queued (model switch, cwd change, session restart).
+
+Additionally, `inheritContext` calls `ctx.sessionManager.getBranch()` at run time, forking the conversation as it exists at dequeue rather than at the point the user asked for the agent.
+
+`pi: ExtensionAPI` is also stored in `SpawnArgs` but is only relayed to `runner.run()`, which only uses it for `detectEnv()` — a classic parameter-relay smell.
+
+## Goals
+
+- Replace `ctx: ExtensionContext` in `SpawnArgs` with a `ParentSnapshot` data object captured once at spawn time.
+- Remove `pi: ExtensionAPI` from `SpawnArgs` by injecting a narrow `ShellExec` callback into `AgentManager` at construction.
+- Update `AgentRunner.run()` to accept `ParentSnapshot` instead of `ctx`.
+- Narrow `detectEnv()` to accept `ShellExec` instead of the full `ExtensionAPI`.
+- Simplify test mocks — plain data snapshots replace SDK mock objects.
+
+## Non-Goals
+
+- Session-event observation / callback-threading removal (architecture.md Step 3, #100) — separate issue, depends on this one.
+- Cleaning up `runtime.currentCtx` — it holds a live `{ pi, ctx }` for the service-adapter but is always "current" (set on `session_start`, cleared on `session_shutdown`); staleness is not a risk there.
+  Simplifying it is a natural follow-up but out of scope.
+- Changes to `SpawnOptions` or the public `SubagentsService` API — both are unchanged.
+
+## Background
+
+### Relevant modules
+
+| Module                   | Role in this change                                                                     |
+| ------------------------ | --------------------------------------------------------------------------------------- |
+| `src/agent-manager.ts`   | Owns `SpawnArgs`, `spawn()`, `startAgent()` — primary target                            |
+| `src/agent-runner.ts`    | `runAgent()` consumes `ctx` + `pi`; `AgentRunner` interface defines `run()` signature   |
+| `src/env.ts`             | `detectEnv()` accepts `ExtensionAPI` — narrowing to `ShellExec`                         |
+| `src/context.ts`         | `buildParentContext()` reads `ctx.sessionManager.getBranch()` — called at snapshot time |
+| `src/session-config.ts`  | `AssemblerContext` is already a narrow interface; `runAgent` builds it from ctx today   |
+| `src/types.ts`           | Will host `ParentSnapshot` and `ShellExec` type definitions                             |
+| `src/service-adapter.ts` | `AgentManagerLike.spawn` — narrow interface that mirrors `AgentManager.spawn()`         |
+| `src/index.ts`           | Wires `pi.exec` into `AgentManager`; wraps `spawn`/`spawnAndWait` for tools             |
+| `src/ui/agent-menu.ts`   | `AgentMenuManagerDeps.spawnAndWait` — narrow interface referencing `pi` parameter       |
+
+### Code-style constraints
+
+- **Parameter relay** (code-design skill): `pi` threads through `spawn` → `SpawnArgs` → `startAgent` → `RunOptions` → `runAgent` → `detectEnv`.
+  The intermediaries (`spawn`, `startAgent`) never read `pi`.
+  Fix: inject exec at the `AgentManager` level.
+- **Dependency width** (code-design skill): `runAgent` receives `ctx: ExtensionContext` but only reads 4 fields plus `sessionManager.getBranch()`.
+  Fix: `ParentSnapshot` — a narrow interface with exactly the fields consumed.
+- **Law of Demeter** (design-review): `ctx.sessionManager.getBranch()` is a reach-through that forces tests to mock a nested `sessionManager` object.
+  Fix: snapshot pre-computes `parentContext` as a string.
+
+### Prerequisite status
+
+- Issue #98 (AgentRecord state machine) — **done**.
+  `AgentRecord` is a class with encapsulated transition methods.
+- Issue #102 (shared test record factory) — **done**.
+  All test record construction goes through `createTestRecord()`.
+
+## Design Overview
+
+### ParentSnapshot interface
+
+A plain data object capturing everything `runAgent()` reads from `ctx`:
+
+```typescript
+export interface ParentSnapshot {
+  /** Parent working directory. */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  systemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  model: unknown;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+  /** Pre-built parent conversation text (when inheritContext was requested). */
+  parentContext?: string;
+}
+```
+
+The `modelRegistry` field is a reference capture, not a data copy — it's a registry object with methods.
+This is acceptable because the registry is structurally stable within a session (models don't change at runtime).
+The key staleness risks (`cwd`, `systemPrompt`, `model`, conversation state) are all captured as values.
+
+### ShellExec type
+
+A narrow callback type replacing `ExtensionAPI` in `detectEnv`:
+
+```typescript
+export type ShellExec = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr: string; code: number }>;
+```
+
+This matches the shape of `pi.exec()` but carries no SDK dependency.
+
+### Snapshot built in spawn()
+
+`spawn()` keeps receiving `ctx` as a parameter (so callers don't need to know about `ParentSnapshot`).
+Internally, it immediately snapshots `ctx` and stores the snapshot in `SpawnArgs` — never the live `ctx` reference.
+
+```typescript
+spawn(ctx: ExtensionContext, type: SubagentType, prompt: string, options: SpawnOptions): string {
+  const snapshot: ParentSnapshot = buildParentSnapshot(ctx, options.inheritContext);
+  const args: SpawnArgs = { snapshot, type, prompt, options };
+  // ...
+}
+```
+
+The `pi` parameter is removed from `spawn()`.
+The `exec` function is injected into `AgentManager` at construction time via `AgentManagerOptions`, since `pi.exec` is a stable capability (same function reference for the extension's lifetime).
+
+### buildParentSnapshot helper
+
+A new `src/parent-snapshot.ts` module with a single exported function:
+
+```typescript
+export function buildParentSnapshot(
+  ctx: ExtensionContext,
+  inheritContext?: boolean,
+): ParentSnapshot {
+  return {
+    cwd: ctx.cwd,
+    systemPrompt: ctx.getSystemPrompt(),
+    model: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+    parentContext: inheritContext ? buildParentContext(ctx) : undefined,
+  };
+}
+```
+
+This is the only place that touches `ExtensionContext` to build a snapshot.
+It calls `buildParentContext(ctx)` (from `context.ts`) which reads `ctx.sessionManager.getBranch()` — capturing the conversation at spawn time, not dequeue time.
+
+### SpawnArgs changes
+
+```typescript
+// Before
+interface SpawnArgs {
+  pi: ExtensionAPI;
+  ctx: ExtensionContext;
+  type: SubagentType;
+  prompt: string;
+  options: SpawnOptions;
+}
+
+// After
+interface SpawnArgs {
+  snapshot: ParentSnapshot;
+  type: SubagentType;
+  prompt: string;
+  options: SpawnOptions;
+}
+```
+
+### AgentRunner.run() signature change
+
+```typescript
+// Before
+run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+
+// After
+run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+```
+
+### RunOptions changes
+
+```typescript
+// Removed fields:
+//   pi: ExtensionAPI         → replaced by exec: ShellExec
+//   inheritContext?: boolean → handled by snapshot.parentContext
+
+// Added field:
+exec: ShellExec;
+```
+
+### runAgent flow changes
+
+Inside `runAgent()`, all `ctx.*` reads become `snapshot.*` reads:
+
+```typescript
+// Before
+const effectiveCwd = options.cwd ?? ctx.cwd;
+const env = await detectEnv(options.pi, effectiveCwd);
+const cfg = assembleSessionConfig(type, {
+  cwd: ctx.cwd,
+  parentSystemPrompt: ctx.getSystemPrompt(),
+  parentModel: ctx.model,
+  modelRegistry: ctx.modelRegistry,
+}, ...);
+
+// After
+const effectiveCwd = options.cwd ?? snapshot.cwd;
+const env = await detectEnv(options.exec, effectiveCwd);
+const cfg = assembleSessionConfig(type, {
+  cwd: snapshot.cwd,
+  parentSystemPrompt: snapshot.systemPrompt,
+  parentModel: snapshot.model,
+  modelRegistry: snapshot.modelRegistry,
+}, ...);
+```
+
+The `inheritContext` block changes:
+
+```typescript
+// Before
+if (options.inheritContext) {
+  const parentContext = buildParentContext(ctx);
+  if (parentContext) effectivePrompt = parentContext + prompt;
+}
+
+// After
+if (snapshot.parentContext) {
+  effectivePrompt = snapshot.parentContext + prompt;
+}
+```
+
+The `createAgentSession()` call changes:
+
+```typescript
+// Before: modelRegistry: ctx.modelRegistry
+// After:  modelRegistry: snapshot.modelRegistry as ModelRegistry
+```
+
+### AgentManager constructor change
+
+```typescript
+export interface AgentManagerOptions {
+  runner: AgentRunner;
+  worktrees: WorktreeManager;
+  exec: ShellExec;              // NEW — injected from pi.exec
+  maxConcurrent?: number;
+  getRunConfig?: () => RunConfig;
+  onStart?: OnAgentStart;
+  onComplete?: OnAgentComplete;
+  onCompact?: OnAgentCompact;
+}
+```
+
+`startAgent()` uses `this.exec` when building `RunOptions`:
+
+```typescript
+const promise = this.runner.run(snapshot, type, prompt, {
+  exec: this.exec,
+  model: options.model,
+  // ... (no more pi field)
+});
+```
+
+### Caller updates
+
+`index.ts`:
+
+```typescript
+// Before
+const manager = new AgentManager({
+  runner: { run: runAgent, resume: resumeAgent },
+  worktrees: new GitWorktreeManager(process.cwd()),
+  // ...
+});
+
+// After — adds exec
+const manager = new AgentManager({
+  runner: { run: runAgent, resume: resumeAgent },
+  worktrees: new GitWorktreeManager(process.cwd()),
+  exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
+  // ...
+});
+```
+
+Spawn wrappers simplify — no more `pi` injection:
+
+```typescript
+// Before
+spawn: (ctx, type, prompt, opts) => manager.spawn(pi, ctx, type, prompt, opts),
+// After
+spawn: (ctx, type, prompt, opts) => manager.spawn(ctx, type, prompt, opts),
+```
+
+`service-adapter.ts`:
+
+```typescript
+// AgentManagerLike.spawn — drops pi parameter
+spawn(ctx: unknown, type: string, prompt: string, options: unknown): string;
+```
+
+`ui/agent-menu.ts` — `spawnAndWait` drops `pi` parameter:
+
+```typescript
+// Before
+spawnAndWait: (pi: ExtensionAPI | null, ctx: ExtensionContext, ...) => Promise<AgentRecord>;
+// After
+spawnAndWait: (ctx: ExtensionContext, ...) => Promise<AgentRecord>;
+```
+
+## Module-Level Changes
+
+### New files
+
+1. `src/parent-snapshot.ts` — `buildParentSnapshot()` function (cycle 3).
+2. `test/parent-snapshot.test.ts` — unit tests for the builder (cycle 3).
+
+### Changed files (source)
+
+Phase 1 (pi elimination):
+
+1. `src/types.ts` — add `ShellExec` type (cycle 1); add `ParentSnapshot` interface (cycle 3).
+2. `src/env.ts` — `detectEnv()` accepts `ShellExec` instead of `ExtensionAPI` (cycle 1).
+3. `src/agent-runner.ts` — `RunOptions` replaces `pi` with `exec` (cycle 1); `runAgent()` first param changes to `ParentSnapshot`, removes `inheritContext` from `RunOptions` (cycle 4).
+4. `src/agent-manager.ts` — `AgentManagerOptions` adds `exec`, `startAgent` uses `this.exec` (cycle 1); `spawn`/`spawnAndWait` drop `pi`, `SpawnArgs` drops `pi` (cycle 2); `spawn` builds snapshot, `SpawnArgs` replaces `ctx` with `snapshot` (cycle 5).
+5. `src/index.ts` — pass `exec` to `AgentManager` constructor (cycle 1); simplify `spawn`/`spawnAndWait` wrappers (cycle 2).
+6. `src/service-adapter.ts` — `AgentManagerLike.spawn` drops `pi` (cycle 2).
+7. `src/ui/agent-menu.ts` — `AgentMenuManagerDeps.spawnAndWait` drops `pi` (cycle 2).
+
+### Changed files (tests)
+
+1. `test/env.test.ts` — `mockPi()` → `mockExec()` (cycle 1).
+2. `test/agent-runner.test.ts` — `{ pi }` → `{ exec: vi.fn() }` (cycle 1); `ctx` mock → `ParentSnapshot` (cycle 4).
+3. `test/agent-runner-extension-tools.test.ts` — same as agent-runner (cycles 1, 4).
+4. `test/agent-manager.test.ts` — add `exec` to `createManager()` (cycle 1); remove `mockPi` from 27 `spawn()` calls (cycle 2); mock `buildParentSnapshot` (cycle 5).
+5. `test/service-adapter.test.ts` — `AgentManagerLike.spawn` mock drops `pi` (cycle 2).
+6. `test/ui/agent-menu.test.ts` — `spawnAndWait` mock drops `pi` (cycle 2).
+
+### Unchanged files
+
+- `src/service.ts` — public API unchanged.
+- `src/context.ts` — `buildParentContext()` keeps its current signature; called by `buildParentSnapshot()`.
+- `src/session-config.ts` — `AssemblerContext` unchanged; `runAgent` builds it from snapshot fields.
+- `src/agent-record.ts` — unrelated.
+- `src/tools/agent-tool.ts` — already uses narrow `deps.manager` interface without `pi`; the `(ctx, type, prompt, opts)` shape is unchanged.
+- All other source and test files.
+
+## Test Impact Analysis
+
+### New tests enabled by the extraction
+
+- `buildParentSnapshot()` tested in isolation — verifies field mapping and `inheritContext` pre-computation.
+  Previously impossible: the snapshot was implicit (live ctx was passed through).
+- `detectEnv()` tests become SDK-free — a plain `ShellExec` stub replaces the `ExtensionAPI` mock.
+
+### Existing tests that simplify
+
+- `agent-runner.test.ts` — the `ctx` mock loses its methods (`getSystemPrompt: vi.fn()`, `sessionManager.getBranch: vi.fn()`) and becomes a plain data object.
+  The `pi` mock (`{} as any`) is replaced by `exec: vi.fn()`.
+  Every `runAgent(ctx, ...)` call is a mechanical replacement.
+- `agent-manager.test.ts` — `mockPi` is eliminated entirely (28 spawn calls).
+  The `createManager()` helper gains an `exec` field.
+- `env.test.ts` — `mockPi()` factory simplifies to a `vi.fn()` returning exec results.
+
+### Existing tests that stay as-is
+
+All `agent-manager.test.ts` tests that verify lifecycle (spawn, complete, abort, resume, queue drain, worktree) remain unchanged in intent — they verify the wiring between `AgentManager` and the record/runner.
+Only the mock construction and `spawn()` call sites change mechanically.
+
+## TDD Order
+
+The cycles are organized into two phases following the Kent Beck principle "make the change that makes the change easy."
+Phase 1 (cycles 1–2) eliminates the `pi` parameter relay — an orthogonal concern that would otherwise cascade through every snapshot cycle.
+Phase 2 (cycles 3–5) introduces `ParentSnapshot`, landing on clean ground.
+
+### Phase 1: Eliminate pi relay
+
+#### Cycle 1: ShellExec type + exec injection into runner path
+
+Test surface: `test/env.test.ts`, `test/agent-runner.test.ts`, `test/agent-runner-extension-tools.test.ts`, `test/agent-manager.test.ts` (updated).
+
+This cycle replaces `pi: ExtensionAPI` with `exec: ShellExec` in the runner path (leaf → middle → top), and injects `exec` into `AgentManager`.
+`SpawnArgs` still carries `pi` (unused) — removed in cycle 2.
+
+Changes:
+
+- `src/types.ts`: add `ShellExec` type.
+- `src/env.ts`: `detectEnv()` accepts `ShellExec` instead of `ExtensionAPI`.
+- `src/agent-runner.ts`: `RunOptions` replaces `pi: ExtensionAPI` with `exec: ShellExec`; `runAgent()` uses `options.exec` for `detectEnv()`; remove `ExtensionAPI` import.
+- `src/agent-manager.ts`: `AgentManagerOptions` adds `exec: ShellExec`; `startAgent()` passes `exec: this.exec` in `RunOptions` instead of `pi` from `SpawnArgs`; stop destructuring `pi` from `SpawnArgs` (it stays in the type for one cycle).
+- `src/index.ts`: pass `exec: (cmd, args, opts) => pi.exec(cmd, args, opts)` to `AgentManager` constructor.
+- `test/env.test.ts`: `mockPi()` → `mockExec()` returning a `ShellExec` stub.
+- `test/agent-runner.test.ts`: `{ pi }` → `{ exec: vi.fn() }` in all `runAgent()` calls.
+- `test/agent-runner-extension-tools.test.ts`: same.
+- `test/agent-manager.test.ts`: add `exec: vi.fn()` to `createManager()` defaults.
+- Run full test suite + `pnpm run check`.
+
+Commit: `refactor: inject ShellExec into runner path, replacing ExtensionAPI (#99)`
+
+#### Cycle 2: Remove pi from spawn path and callers
+
+Test surface: `test/agent-manager.test.ts`, `test/service-adapter.test.ts`, `test/ui/agent-menu.test.ts` (updated).
+
+With `exec` already injected and `pi` unused in `startAgent()`, this cycle removes it from the remaining surfaces.
+
+Changes:
+
+- `src/agent-manager.ts`: `SpawnArgs` drops `pi`; `spawn()` drops `pi` parameter; `spawnAndWait()` drops `pi` parameter; remove `ExtensionAPI` import.
+- `src/service-adapter.ts`: `AgentManagerLike.spawn()` drops `pi` parameter; `createSubagentsService().spawn()` passes `session.ctx` only.
+- `src/ui/agent-menu.ts`: `AgentMenuManagerDeps.spawnAndWait()` drops `pi` parameter; call site drops `null` first arg.
+- `src/index.ts`: simplify `spawn` wrapper — `(ctx, type, prompt, opts) => manager.spawn(ctx, type, prompt, opts)`; simplify `spawnAndWait` wrappers similarly.
+- `test/agent-manager.test.ts`: remove `mockPi` constant; drop it from all 27 `spawn()` call sites.
+- `test/service-adapter.test.ts`: update `AgentManagerLike.spawn` mock.
+- `test/ui/agent-menu.test.ts`: update `spawnAndWait` mock.
+- Run full test suite + `pnpm run check`.
+
+Commit: `refactor: remove pi parameter from spawn path (#99)`
+
+### Phase 2: ParentSnapshot
+
+#### Cycle 3: ParentSnapshot type and builder
+
+Test surface: `test/parent-snapshot.test.ts` (new file).
+
+Tests cover:
+
+- Snapshots `cwd`, `systemPrompt` (from `getSystemPrompt()`), `model`, `modelRegistry` from a mock `ctx`.
+- When `inheritContext` is true and conversation exists, `parentContext` is populated.
+- When `inheritContext` is false or undefined, `parentContext` is undefined.
+- When `inheritContext` is true but conversation is empty, `parentContext` is undefined.
+
+Changes:
+
+- Add `ParentSnapshot` interface to `src/types.ts`.
+- Create `src/parent-snapshot.ts` with `buildParentSnapshot()`.
+- Create `test/parent-snapshot.test.ts`.
+
+Commit: `feat: add ParentSnapshot type and builder (#99)`
+
+#### Cycle 4: runAgent and AgentRunner accept ParentSnapshot
+
+Test surface: `test/agent-runner.test.ts`, `test/agent-runner-extension-tools.test.ts` (updated).
+
+With `pi` already eliminated (phase 1), this cycle only changes the first parameter of `runAgent()` — no other `RunOptions` churn.
+
+Changes:
+
+- `src/agent-runner.ts`:
+  - `runAgent()` first parameter: `ctx: ExtensionContext` → `snapshot: ParentSnapshot`.
+  - `AgentRunner.run()` interface: first parameter changes to `snapshot: ParentSnapshot`.
+  - Remove `inheritContext` from `RunOptions` (snapshot has `parentContext`).
+  - `inheritContext` block → `if (snapshot.parentContext)`.
+  - `assembleSessionConfig` and `createAgentSession` calls read from `snapshot.*` instead of `ctx.*`.
+  - Remove `ExtensionContext` import; remove `buildParentContext` import (no longer called here).
+- `test/agent-runner.test.ts`: replace `ctx` mock with a plain `ParentSnapshot` object.
+- `test/agent-runner-extension-tools.test.ts`: same.
+- Run `pnpm run check` — catches `agent-manager.ts` type error in `startAgent()`'s `runner.run()` call (still passing `ctx`); addressed in cycle 5.
+
+Commit: `refactor: AgentRunner accepts ParentSnapshot instead of ExtensionContext (#99)`
+
+#### Cycle 5: AgentManager spawn builds snapshot
+
+Test surface: `test/agent-manager.test.ts` (updated).
+
+Changes:
+
+- `src/agent-manager.ts`:
+  - `spawn()` calls `buildParentSnapshot(ctx, options.inheritContext)` and stores the snapshot in `SpawnArgs`.
+  - `SpawnArgs`: replace `ctx: ExtensionContext` with `snapshot: ParentSnapshot`.
+  - `startAgent()` destructures `snapshot` from `SpawnArgs`; passes it to `runner.run(snapshot, ...)`.
+  - Remove `ExtensionContext` import.
+- `test/agent-manager.test.ts`: `vi.mock("../src/parent-snapshot.js")` to isolate `buildParentSnapshot`; `mockCtx` stays minimal (`{ cwd: "/tmp" } as any`) because `spawn()` delegates to the mocked builder.
+- Run full test suite + `pnpm run check`.
+
+Commit: `refactor: AgentManager captures ParentSnapshot at spawn time (#99)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                       | Mitigation                                                                                                                                                     |
+| ---------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `modelRegistry` is a reference capture, not a data copy — could theoretically go stale                     | Registries are structurally stable within a session; the staleness risk applies to `cwd`/`systemPrompt`/`model`/conversation, all of which are value-captured  |
+| Large test files (~410 + ~686 lines) need mechanical updates                                               | Phase 1 handles `pi` churn (27 spawn calls) separately from phase 2's `ctx` → `snapshot` change, so each cycle touches one concern per test file               |
+| `spawn()` still receives `ctx` — caller could accidentally use it post-snapshot                            | `ctx` is a function parameter, not stored; `SpawnArgs` holds only the snapshot; the type system prevents re-storing ctx since `SpawnArgs.ctx` no longer exists |
+| `buildParentContext` still accepts `ExtensionContext` — mocking it requires a nested `sessionManager` mock | The mock only appears in `parent-snapshot.test.ts` (one place); a follow-up could narrow `buildParentContext` to accept just the branch data                   |
+| Phase 1 temporarily leaves `pi` in `SpawnArgs` (cycle 1) before removing it (cycle 2)                      | The field is unused after cycle 1 (`startAgent` uses `this.exec` instead); cycle 2 removes it in the next commit                                               |
+
+## Open Questions
+
+- Whether to narrow `buildParentContext()` to accept `getBranch()` data directly instead of `ExtensionContext`.
+  This would eliminate the last `ExtensionContext` usage in the snapshot path but is a separate refactoring of `context.ts`.
+  Deferred — the current `buildParentSnapshot` wrapper isolates the SDK dependency to one module.
+- Whether `runtime.currentCtx` should be simplified from `{ pi, ctx }` to just `ctx` now that `pi` is not passed to `spawn()`.
+  Natural follow-up but out of scope — `currentCtx.pi` has no other consumers and removing it is a 3-line change.

package/docs/retro/0098-extract-agent-record-state-machine.md

@@ -0,0 +1,46 @@
+---
+issue: 98
+issue_title: "Extract AgentRecord state machine from scattered status transitions"
+---
+
+# Retro: #98 — Extract AgentRecord state machine
+
+## Final Retrospective (2026-05-20T23:45:00Z)
+
+### Session summary
+
+Converted `AgentRecord` from a plain interface to a class with 7 encapsulated transition methods, centralizing the scattered status-transition logic from 6 locations in `agent-manager.ts`.
+The prerequisite issue #102 (shared test factory) made the class conversion a 2-file change instead of an 8-file rewrite.
+Released as `pi-subagents-v6.1.0`.
+
+### Observations
+
+#### What went well
+
+- The "encapsulate last" TDD strategy (cycles 1–5 with public fields, cycle 6 makes them private) let the compiler verify migration completeness before locking down access.
+  `get-result-tool.test.ts` and `make-record.test.ts` failures were caught immediately.
+- The worktree-reorder design insight (compute final result including branch text before calling the transition method) avoided the need for an `appendToResult()` method and survived implementation unchanged.
+- The prerequisite issue #102 (shared `createTestRecord` factory) proved essential — the class conversion touched only the factory and `agent-manager.ts`, not 8 individual test files.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — The initial plan proposed `MutableAgentRecord` alongside the existing interface, which was the lowest-friction path but the wrong abstraction.
+  The user redirected twice ("It should definitely become a class" → "I meant encapsulate") before the design was right.
+  Impact: full plan rewrite and an extra prerequisite issue (#102).
+  The plan template's "use ask-user for ambiguous design choices" instruction applied (class vs wrapper was genuinely ambiguous), but I didn't invoke it.
+
+- `missing-context` — The revised plan stated "No test files need updating (except the shared factory)" but missed `{ ...baseRecord, field }` spread patterns in `test/notification.test.ts`, `test/service-adapter.test.ts`, `test/tools/get-result-tool.test.ts`, and `test/helpers/make-record.test.ts`.
+  Spreading a class instance produces a plain object that lacks the class's methods.
+  Impact: 4 extra test files needed mechanical fixes in cycles 4 and 6; plan's "Unchanged files" list was wrong.
+  The compiler caught all of them, so no behavioral risk, but the plan should have predicted the churn.
+
+#### What caused friction (user side)
+
+- The issue body was intentionally flexible ("onto AgentRecord (or a thin wrapper)"), which left the wrapper-vs-class decision open.
+  The user's preference for a class with encapsulated state became clear only after seeing the initial plan.
+  Earlier signal (e.g., labeling the issue with a "class conversion" tag or stating "must encapsulate" in the issue body) would have avoided the plan rewrite.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — Added interface→class spread-pattern rule to TDD planning rules.
+2. `.pi/skills/package-pi-subagents/SKILL.md` — Added `agent-record.ts` to the Core engine module table and updated `types.ts` description.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-manager.ts

@@ -8,12 +8,13 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentSession, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner, ToolActivity } from "./agent-runner.js";
 import { debugLog } from "./debug.js";
+import { buildParentSnapshot } from "./parent-snapshot.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import { addUsage } from "./usage.js";
 import type { WorktreeManager } from "./worktree.js";
 
@@ -28,6 +29,7 @@ const DEFAULT_MAX_CONCURRENT = 4;
 export interface AgentManagerOptions {
   runner: AgentRunner;
   worktrees: WorktreeManager;
+  exec: ShellExec;
   maxConcurrent?: number;
   getRunConfig?: () => RunConfig;
   onStart?: OnAgentStart;
@@ -36,8 +38,7 @@ export interface AgentManagerOptions {
 }
 
 interface SpawnArgs {
-  pi: ExtensionAPI;
-  ctx: ExtensionContext;
+  snapshot: ParentSnapshot;
   type: SubagentType;
   prompt: string;
   options: SpawnOptions;
@@ -89,6 +90,7 @@ export class AgentManager {
   private onCompact?: OnAgentCompact;
   private readonly runner: AgentRunner;
   private readonly worktrees: WorktreeManager;
+  private readonly exec: ShellExec;
   private maxConcurrent: number;
   private getRunConfig?: () => RunConfig;
 
@@ -100,6 +102,7 @@ export class AgentManager {
   constructor(options: AgentManagerOptions) {
     this.runner = options.runner;
     this.worktrees = options.worktrees;
+    this.exec = options.exec;
     this.onComplete = options.onComplete;
     this.onStart = options.onStart;
     this.onCompact = options.onCompact;
@@ -126,7 +129,6 @@ export class AgentManager {
    * If the concurrency limit is reached, the agent is queued.
    */
   spawn(
-    pi: ExtensionAPI,
     ctx: ExtensionContext,
     type: SubagentType,
     prompt: string,
@@ -145,7 +147,8 @@ export class AgentManager {
     });
     this.agents.set(id, record);
 
-    const args: SpawnArgs = { pi, ctx, type, prompt, options };
+    const snapshot = buildParentSnapshot(ctx, options.inheritContext);
+    const args: SpawnArgs = { snapshot, type, prompt, options };
 
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this.maxConcurrent) {
       // Queue it — will be started when a running agent completes
@@ -165,7 +168,7 @@ export class AgentManager {
   }
 
   /** Actually start an agent (called immediately or from queue drain). */
-  private startAgent(id: string, record: AgentRecord, { pi, ctx, type, prompt, options }: SpawnArgs) {
+  private startAgent(id: string, record: AgentRecord, { snapshot, type, prompt, options }: SpawnArgs) {
     // Worktree isolation: try to create a temporary git worktree. Strict —
     // fail loud if not possible (no silent fallback to main tree). Done
     // BEFORE state mutation so a throw doesn't leave the record half-running.
@@ -196,14 +199,13 @@ export class AgentManager {
     const detach = () => { detachParentSignal?.(); detachParentSignal = undefined; };
 
     const runConfig = this.getRunConfig?.();
-    const promise = this.runner.run(ctx, type, prompt, {
-      pi,
+    const promise = this.runner.run(snapshot, type, prompt, {
+      exec: this.exec,
       model: options.model,
       maxTurns: options.maxTurns,
       defaultMaxTurns: runConfig?.defaultMaxTurns,
       graceTurns: runConfig?.graceTurns,
       isolated: options.isolated,
-      inheritContext: options.inheritContext,
       thinkingLevel: options.thinkingLevel,
       cwd: worktreeCwd,
       parentSessionFile: options.parentSessionFile,
@@ -314,13 +316,12 @@ export class AgentManager {
    * Foreground agents bypass the concurrency queue.
    */
   async spawnAndWait(
-    pi: ExtensionAPI,
     ctx: ExtensionContext,
     type: SubagentType,
     prompt: string,
     options: Omit<SpawnOptions, "isBackground">,
   ): Promise<AgentRecord> {
-    const id = this.spawn(pi, ctx, type, prompt, { ...options, isBackground: false });
+    const id = this.spawn(ctx, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
     await record.promise;
     return record;

package/src/agent-runner.ts

@@ -3,22 +3,20 @@
  */
 
 import type { Model } from "@earendil-works/pi-ai";
-import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import {
   type AgentSession,
   type AgentSessionEvent,
   createAgentSession,
   DefaultResourceLoader,
-  type ExtensionAPI,
   getAgentDir,
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import { buildParentContext, extractText } from "./context.js";
+import { extractText } from "./context.js";
 import { detectEnv } from "./env.js";
 import { assembleSessionConfig } from "./session-config.js";
 import { deriveSubagentSessionDir } from "./session-dir.js";
-import type { SubagentType, ThinkingLevel } from "./types.js";
+import type { ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];
@@ -73,13 +71,12 @@ export interface ToolActivity {
 }
 
 export interface RunOptions {
-  /** ExtensionAPI instance — used for pi.exec() instead of execSync. */
-  pi: ExtensionAPI;
+  /** Shell-exec callback for detectEnv — injected from pi.exec(). */
+  exec: ShellExec;
   model?: Model<any>;
   maxTurns?: number;
   signal?: AbortSignal;
   isolated?: boolean;
-  inheritContext?: boolean;
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
@@ -149,7 +146,7 @@ export interface ResumeOptions {
  * SDK session orchestration in runAgent/resumeAgent.
  */
 export interface AgentRunner {
-  run(ctx: ExtensionContext, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
+  run(snapshot: ParentSnapshot, type: SubagentType, prompt: string, options: RunOptions): Promise<RunResult>;
   resume(session: AgentSession, prompt: string, options?: ResumeOptions): Promise<string>;
 }
 
@@ -199,23 +196,23 @@ function forwardAbortSignal(
 }
 
 export async function runAgent(
-  ctx: ExtensionContext,
+  snapshot: ParentSnapshot,
   type: SubagentType,
   prompt: string,
   options: RunOptions,
 ): Promise<RunResult> {
   // Resolve working directory upfront — needed for detectEnv before assembly.
-  const effectiveCwd = options.cwd ?? ctx.cwd;
-  const env = await detectEnv(options.pi, effectiveCwd);
+  const effectiveCwd = options.cwd ?? snapshot.cwd;
+  const env = await detectEnv(options.exec, effectiveCwd);
 
   // Assemble session configuration (synchronous, no SDK objects).
   const cfg = assembleSessionConfig(
     type,
     {
-      cwd: ctx.cwd,
-      parentSystemPrompt: ctx.getSystemPrompt(),
-      parentModel: ctx.model,
-      modelRegistry: ctx.modelRegistry,
+      cwd: snapshot.cwd,
+      parentSystemPrompt: snapshot.systemPrompt,
+      parentModel: snapshot.model,
+      modelRegistry: snapshot.modelRegistry,
     },
     {
       cwd: options.cwd,
@@ -259,7 +256,7 @@ export async function runAgent(
     agentDir,
     sessionManager,
     settingsManager: SettingsManager.create(cfg.effectiveCwd, agentDir),
-    modelRegistry: ctx.modelRegistry,
+    modelRegistry: snapshot.modelRegistry as any,
     model: cfg.model as Model<any> | undefined,
     tools: cfg.toolNames,
     resourceLoader: loader,
@@ -378,13 +375,10 @@ export async function runAgent(
   const collector = collectResponseText(session);
   const cleanupAbort = forwardAbortSignal(session, options.signal);
 
-  // Build the effective prompt: optionally prepend parent context
+  // Prepend parent context if it was captured at spawn time
   let effectivePrompt = prompt;
-  if (options.inheritContext) {
-    const parentContext = buildParentContext(ctx);
-    if (parentContext) {
-      effectivePrompt = parentContext + prompt;
-    }
+  if (snapshot.parentContext) {
+    effectivePrompt = snapshot.parentContext + prompt;
   }
 
   try {

package/src/env.ts

@@ -2,16 +2,15 @@
  * env.ts — Detect environment info (git, platform) for subagent system prompts.
  */
 
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { debugLog } from "./debug.js";
-import type { EnvInfo } from "./types.js";
+import type { EnvInfo, ShellExec } from "./types.js";
 
-export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo> {
+export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
   let isGitRepo = false;
   let branch = "";
 
   try {
-    const result = await pi.exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
+    const result = await exec("git", ["rev-parse", "--is-inside-work-tree"], { cwd, timeout: 5000 });
     isGitRepo = result.code === 0 && result.stdout.trim() === "true";
   } catch (err) {
     debugLog("git rev-parse", err);
@@ -19,7 +18,7 @@ export async function detectEnv(pi: ExtensionAPI, cwd: string): Promise<EnvInfo>
 
   if (isGitRepo) {
     try {
-      const result = await pi.exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
+      const result = await exec("git", ["branch", "--show-current"], { cwd, timeout: 5000 });
       branch = result.code === 0 ? result.stdout.trim() : "unknown";
     } catch (err) {
       debugLog("git branch", err);

package/src/index.ts

@@ -66,6 +66,7 @@ export default function (pi: ExtensionAPI) {
   const manager = new AgentManager({
     runner: { run: runAgent, resume: resumeAgent },
     worktrees: new GitWorktreeManager(process.cwd()),
+    exec: (cmd, args, opts) => pi.exec(cmd, args, opts),
     onComplete: (record) => {
       // Emit lifecycle event based on terminal status
       const isError = record.status === "error" || record.status === "stopped" || record.status === "aborted";
@@ -185,8 +186,8 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerTool(defineTool(createAgentTool({
     manager: {
-      spawn: (ctx, type, prompt, opts) => manager.spawn(pi, ctx, type, prompt, opts),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(pi, ctx, type, prompt, opts),
+      spawn: (ctx, type, prompt, opts) => manager.spawn(ctx, type, prompt, opts),
+      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
       getMaxConcurrent: () => manager.getMaxConcurrent(),
@@ -229,7 +230,7 @@ export default function (pi: ExtensionAPI) {
     manager: {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (piArg, ctx, type, prompt, opts) => manager.spawnAndWait(piArg ?? pi, ctx, type, prompt, opts),
+      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
       getMaxConcurrent: () => manager.getMaxConcurrent(),
       setMaxConcurrent: (n) => manager.setMaxConcurrent(n),
     },

package/src/parent-snapshot.ts

@@ -0,0 +1,27 @@
+/**
+ * parent-snapshot.ts — Capture parent session state as a plain data snapshot.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { buildParentContext } from "./context.js";
+import type { ParentSnapshot } from "./types.js";
+
+/**
+ * Build an immutable snapshot of the parent session state.
+ *
+ * Called once at spawn time so queued agents capture state as it existed
+ * when the user requested the agent, not when a queue slot opens.
+ */
+export function buildParentSnapshot(
+  ctx: ExtensionContext,
+  inheritContext?: boolean,
+): ParentSnapshot {
+  const parentContext = inheritContext ? buildParentContext(ctx) : undefined;
+  return {
+    cwd: ctx.cwd,
+    systemPrompt: ctx.getSystemPrompt(),
+    model: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+    parentContext: parentContext || undefined,
+  };
+}

package/src/service-adapter.ts

@@ -11,7 +11,7 @@ import type { AgentRecord } from "./types.js";
 
 /** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
 export interface AgentManagerLike {
-  spawn(pi: unknown, ctx: unknown, type: string, prompt: string, options: unknown): string;
+  spawn(ctx: unknown, type: string, prompt: string, options: unknown): string;
   getRecord(id: string): AgentRecord | undefined;
   listAgents(): AgentRecord[];
   abort(id: string): boolean;
@@ -54,7 +54,7 @@ export function createSubagentsService(deps: AdapterDeps): SubagentsService {
       const description = options?.description ?? prompt.slice(0, 80);
       const isBackground = !(options?.foreground ?? false);
 
-      return manager.spawn(session.pi, session.ctx, type, prompt, {
+      return manager.spawn(session.ctx, type, prompt, {
         description,
         model,
         maxTurns: options?.maxTurns,

package/src/types.ts

@@ -83,8 +83,38 @@ export interface NotificationDetails {
 
 }
 
+/**
+ * Plain data snapshot of the parent session state captured at spawn time.
+ * Replaces live `ExtensionContext` references so queued agents don't read stale state.
+ */
+export interface ParentSnapshot {
+  /** Parent working directory. */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  systemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  model: unknown;
+  /** Model registry for resolving config.model strings and creating sessions. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+  /** Pre-built parent conversation text (when inheritContext was requested). */
+  parentContext?: string;
+}
+
 export interface EnvInfo {
   isGitRepo: boolean;
   branch: string;
   platform: string;
 }
+
+/**
+ * Narrow shell-exec callback replacing `ExtensionAPI` in `detectEnv()`.
+ * Matches the shape of `pi.exec()` without carrying an SDK dependency.
+ */
+export type ShellExec = (
+  command: string,
+  args: string[],
+  options?: { cwd?: string; timeout?: number },
+) => Promise<{ stdout: string; stderr: string; code: number }>;

package/src/ui/agent-menu.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { SpawnOptions } from "../agent-manager.js";
 import {
   BUILTIN_TOOL_NAMES,
@@ -21,7 +21,7 @@ export interface AgentMenuManager {
   listAgents: () => AgentRecord[];
   getRecord: (id: string) => AgentRecord | undefined;
   /** Used by generate wizard to spawn an agent that writes the .md file. */
-  spawnAndWait: (pi: ExtensionAPI | null, ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
+  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<SpawnOptions, "isBackground">) => Promise<AgentRecord>;
   getMaxConcurrent: () => number;
   setMaxConcurrent: (n: number) => void;
 }
@@ -487,7 +487,6 @@ Guidelines for choosing settings:
 Write the file using the write tool. Only write the file, nothing else.`;
 
     const record = await deps.manager.spawnAndWait(
-      null,
       ctx,
       "general-purpose",
       generatePrompt,