@gotgenes/pi-subagents 6.1.0 → 6.3.0

package/CHANGELOG.md

@@ -5,6 +5,34 @@ 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.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.2.0...pi-subagents-v6.3.0) (2026-05-21)
+
+
+### Features
+
+* add record observer for direct session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([3776345](https://github.com/gotgenes/pi-packages/commit/37763454609d38d55c85f89bb051b8c592d425bf))
+* add UI observer for direct session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([5b35e80](https://github.com/gotgenes/pi-packages/commit/5b35e80e784d96883ee44bf5e890284efa1047ef))
+
+
+### Documentation
+
+* plan callback-threading replacement with session subscription ([#100](https://github.com/gotgenes/pi-packages/issues/100)) ([7a8e262](https://github.com/gotgenes/pi-packages/commit/7a8e262ebaf99cba017aac00691cc3614ef8c80a))
+* **retro:** add retro notes for issue [#99](https://github.com/gotgenes/pi-packages/issues/99) ([b596d0c](https://github.com/gotgenes/pi-packages/commit/b596d0c34862542d0ebb9fae67dd90e9fc660a8b))
+
+## [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.