@gotgenes/pi-subagents 6.14.1 → 6.16.0

package/docs/plans/0145-decompose-execute-push-ctx-to-boundary.md

@@ -0,0 +1,290 @@
+---
+issue: 145
+issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
+---
+
+# Decompose execute and push ctx to the boundary
+
+## Problem Statement
+
+`agent-tool.ts` `execute` is ~140 lines mixing three concerns: boundary extraction (~5 lines reading `ctx`), config resolution (~60 lines unpacking `resolvedConfig` field by field), and dispatch (~80 lines building 14–16 field parameter bags for `spawnBackground` and `runForeground`).
+The large parameter bags exist because config resolution happens inline instead of in a dedicated function.
+Meanwhile, `ExtensionContext` is threaded from `execute` through `ForegroundParams.ctx` / `BackgroundParams.ctx` into `foreground-runner` and `background-spawner`, where the only thing consumed is `sessionManager.getSessionFile()` and `sessionManager.getSessionId()`.
+`AgentManager.spawn()` and `spawnAndWait()` accept `ExtensionContext` directly and call `buildParentSnapshot(ctx)` internally — but this is already a pure boundary concern that belongs at the call site.
+Additionally, `execute` reaches into `ctx` for model info and session identity — these are session-scoped values that `index.ts` already captures and could inject as collaborators, removing `execute`'s need to read `ctx` beyond the UI context it already delegates to `widget.setUICtx()`.
+
+## Goals
+
+- Extract config resolution into a pure function (`resolveSpawnConfig`) so `execute` becomes: resolve config → dispatch.
+- Inject three missing collaborators into `createAgentTool` so `execute` no longer extracts values from `ctx`:
+  - `buildSnapshot: (inheritContext: boolean) => ParentSnapshot` — closure over `ctx`, wired in `index.ts`.
+  - `getModelInfo: () => ModelInfo` — provides `parentModel` and `modelRegistry` for `resolveSpawnConfig`.
+  - `getSessionInfo: () => { parentSessionFile: string; parentSessionId: string }` — parent session identity.
+- Replace `ForegroundParams.ctx` and `BackgroundParams.ctx` with plain domain values (`parentSessionFile`, `parentSessionId`, `snapshot`).
+- Change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot` instead of `ExtensionContext`.
+- Move `buildParentSnapshot(ctx)` calls to the two boundaries: `index.ts` (via closure) and `service-adapter.ts`.
+- Eliminate the `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`.
+- Apply the dependency bag convention: dissolve `ForegroundDeps`, `BackgroundDeps`, `AdapterDeps` (each ≤3 fields) into plain parameters.
+- This is a breaking internal refactor — no public API changes.
+
+## Non-Goals
+
+- Narrowing menu handler ctx (Step N, #146) — deferred.
+- Injecting text wrapping into ConversationViewer (Step O, #147) — unrelated track.
+- Observation model consolidation (Step L, #144) — independent track.
+- Changing the `SubagentsService` public API in `service.ts`.
+
+## Background
+
+### Relevant modules
+
+| Module                        | Current role                                                                                     |
+| ----------------------------- | ------------------------------------------------------------------------------------------------ |
+| `tools/agent-tool.ts`         | `execute` callback — 140 lines, mixes boundary extraction, config resolution, dispatch           |
+| `tools/foreground-runner.ts`  | `runForeground()` — receives 14-field `ForegroundParams` including `ctx` with `sessionManager`   |
+| `tools/background-spawner.ts` | `spawnBackground()` — receives 14-field `BackgroundParams` including `ctx` with `sessionManager` |
+| `agent-manager.ts`            | `spawn()` / `spawnAndWait()` accept `ExtensionContext`, call `buildParentSnapshot()` internally  |
+| `parent-snapshot.ts`          | `buildParentSnapshot(ctx)` — pure function capturing `ParentSnapshot` from ctx                   |
+| `service-adapter.ts`          | Cross-extension boundary — calls `manager.spawn(session.ctx, ...)`                               |
+| `invocation-config.ts`        | `resolveAgentInvocationConfig()` — merges agent config with tool params                          |
+| `model-resolver.ts`           | `resolveInvocationModel()` — resolves model strings to model instances                           |
+| `index.ts`                    | Extension entry point — wires `createAgentTool` deps, captures `runtime.currentCtx`              |
+| `runtime.ts`                  | `SubagentRuntime` — holds session-scoped mutable state including `currentCtx`                    |
+
+### Constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Prefer explicit configuration over hidden behavior.
+- Keep Pi SDK imports out of business-logic modules.
+- Business logic should be pure functions — keep IO at the edges.
+
+### Phase 9 context
+
+This is Step M of Phase 9.
+It has no blockers and blocks Step N (#146), which narrows menu handler ctx.
+After this step, `ExtensionContext` appears only at true SDK/extension boundaries: `index.ts` closures, `service-adapter.ts`, and menu handlers.
+
+## Design Overview
+
+### Part 1: Extract config resolution (done)
+
+A new pure function `resolveSpawnConfig` in `spawn-config.ts` encapsulates all config resolution logic previously inline in `execute`.
+`execute` calls `resolveSpawnConfig(params, registry, modelInfo, settings)` and dispatches on the result.
+This is already committed.
+
+### Part 2: Inject collaborators and push ctx out of execute
+
+`execute` currently reads `ctx.model`, `ctx.modelRegistry`, `ctx.sessionManager`, and passes `ctx` to `buildParentSnapshot`.
+These are all session-scoped values that `index.ts` captures at session start.
+Three collaborators replace the `ctx` reads:
+
+```typescript
+// Injected as plain parameters into createAgentTool:
+buildSnapshot: (inheritContext: boolean) => ParentSnapshot,
+getModelInfo: () => ModelInfo,
+getSessionInfo: () => { parentSessionFile: string; parentSessionId: string },
+```
+
+`index.ts` wires them as closures over `runtime.currentCtx`:
+
+```typescript
+createAgentTool({
+  // ... existing params ...
+  buildSnapshot: (inheritContext) => buildParentSnapshot(ctx, inheritContext),
+  getModelInfo: () => ({
+    parentModel: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+  }),
+  getSessionInfo: () => ({
+    parentSessionFile: ctx.sessionManager.getSessionFile(),
+    parentSessionId: ctx.sessionManager.getSessionId(),
+  }),
+})
+```
+
+After this, `execute` touches `ctx` only for `ctx.ui` — which is already delegated via `widget.setUICtx()`.
+The `ExtensionContext` import in `agent-tool.ts` is removed entirely.
+
+### Part 3: Push ctx out of AgentManager
+
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+The internal `buildParentSnapshot(ctx, ...)` call is removed — `snapshot` arrives pre-built from the call sites.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx, ...)` at its boundary before delegating.
+
+### Part 4: Push ctx out of foreground-runner and background-spawner
+
+`ForegroundParams.ctx` and `BackgroundParams.ctx` are replaced by `snapshot: ParentSnapshot`, `parentSessionFile: string`, `parentSessionId: string`.
+The narrow manager interfaces change from `ctx: any` to `snapshot: ParentSnapshot`.
+
+### Part 5: Shrink params bags with ResolvedSpawnConfig
+
+`ForegroundParams` and `BackgroundParams` carry `ResolvedSpawnConfig` instead of 10+ individual fields that were computed during config resolution.
+Only dispatch-specific fields (`rawType`, `fellBack`, `toolCallId`, `displayName`) remain as separate params fields.
+
+### Part 6: Dissolve small dependency bags
+
+Per the dependency bag convention:
+
+- `ForegroundDeps` (3 fields) → plain parameters on `runForeground`.
+- `BackgroundDeps` (3 fields) → plain parameters on `spawnBackground`.
+- `AdapterDeps` (4 fields) → plain parameters on `createSubagentsService`.
+- `AgentToolDeps` → destructured in the `createAgentTool` signature; the interface stays as a named type for the test factory.
+
+The narrow `*ManagerDeps` and `*WidgetDeps` interfaces stay — they define the contract each function needs from its collaborators.
+
+## Module-Level Changes
+
+### New file: `src/tools/spawn-config.ts` (done)
+
+- `ResolvedSpawnConfig` interface.
+- `ModelInfo` interface.
+- `resolveSpawnConfig()` pure function.
+
+### Modified: `src/tools/agent-tool.ts`
+
+- `execute` shrinks from ~140 to ~20 lines.
+- `ExtensionContext` import removed — `execute` no longer reads `ctx` directly (beyond `ctx.ui` via widget).
+- Three new collaborator parameters: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
+- Calls `resolveSpawnConfig(params, registry, getModelInfo(), settings)`.
+- Calls `buildSnapshot(config.inheritContext)` for the snapshot.
+- Calls `getSessionInfo()` for parent session identity.
+- Passes domain values (not `ctx`) to `runForeground` / `spawnBackground`.
+- `AgentToolManager.spawn` and `spawnAndWait` signatures change to accept `ParentSnapshot`.
+- `AgentToolDeps` stays as a named type (used by test factory) but its fields are destructured in `createAgentTool`.
+
+### Modified: `src/tools/foreground-runner.ts`
+
+- `ForegroundDeps` interface removed — `runForeground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
+- `ForegroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
+- `ForegroundManagerDeps.spawnAndWait` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
+- Individual config fields move into `ResolvedSpawnConfig`.
+
+### Modified: `src/tools/background-spawner.ts`
+
+- `BackgroundDeps` interface removed — `spawnBackground` accepts `manager`, `widget`, `agentActivity` as plain parameters.
+- `BackgroundParams.ctx` removed — replaced by `snapshot`, `parentSessionFile`, `parentSessionId`.
+- `BackgroundManagerDeps.spawn` signature changes from `ctx: any` to `snapshot: ParentSnapshot`.
+- Individual config fields move into `ResolvedSpawnConfig`.
+
+### Modified: `src/agent-manager.ts`
+
+- `spawn()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
+- `spawnAndWait()` signature changes from `ctx: ExtensionContext` to `snapshot: ParentSnapshot`.
+- Internal `buildParentSnapshot(ctx, ...)` call removed.
+- Imports of `ExtensionContext` and `buildParentSnapshot` removed.
+
+### Modified: `src/service-adapter.ts`
+
+- `AdapterDeps` interface removed — `createSubagentsService` accepts plain parameters.
+- `AgentManagerLike.spawn` signature changes from `ctx: unknown` to `snapshot: ParentSnapshot`.
+- `spawn()` method calls `buildParentSnapshot(session.ctx, options?.inheritContext)` before delegating.
+- Adds imports of `buildParentSnapshot` and `ParentSnapshot`.
+
+### Modified: `src/index.ts`
+
+- Wiring for `createAgentTool` adds three collaborator closures: `buildSnapshot`, `getModelInfo`, `getSessionInfo`.
+- `manager.spawn` / `spawnAndWait` wiring adapters removed (closures no longer need to relay `ctx`).
+- Wiring for `createSubagentsService` changes from bag to plain arguments.
+
+## Test Impact Analysis
+
+### New unit tests enabled
+
+- `spawn-config.test.ts` (done) — pure-function tests for `resolveSpawnConfig`.
+
+### Existing tests that simplify
+
+- `agent-manager.test.ts` — the `vi.mock("../src/parent-snapshot.js")` block is removed.
+  All tests pass a plain `ParentSnapshot` object directly instead of `mockCtx`.
+- `foreground-runner.test.ts` — `makeCtx()` helper removed; plain strings for session identity.
+- `background-spawner.test.ts` — same as foreground.
+- `agent-tool.test.ts` — `makeCtx()` simplified; collaborator stubs replace `ctx.model` / `ctx.modelRegistry` reads.
+- `service-adapter.test.ts` — adapter test setup changes from bag to plain parameters.
+
+### Existing tests that stay
+
+- `parent-snapshot.test.ts` — unchanged; `buildParentSnapshot` is still a standalone pure function.
+
+## TDD Order
+
+### Step 1: Extract resolveSpawnConfig (done)
+
+1. ~~Write `spawn-config.test.ts`, implement `spawn-config.ts`.~~
+   Commit: `feat: extract resolveSpawnConfig pure function (#145)` ✓
+
+2. ~~Rewire `execute` to call `resolveSpawnConfig`.~~
+   Commit: `refactor: use resolveSpawnConfig in execute (#145)` ✓
+
+### Step 2: Push ctx out of AgentManager
+
+3. Red: update `agent-manager.test.ts` — replace `mockCtx` with a plain `ParentSnapshot` object, remove `vi.mock("../src/parent-snapshot.js")`.
+   Green: change `AgentManager.spawn()` and `spawnAndWait()` to accept `ParentSnapshot`.
+   Update `agent-tool.ts` manager interface, `service-adapter.ts` to call `buildParentSnapshot` at its boundary, and `index.ts` wiring.
+   Commit: `refactor: AgentManager accepts ParentSnapshot instead of ExtensionContext (#145)`
+
+### Step 3: Inject collaborators into createAgentTool
+
+4. Red: update `agent-tool.test.ts` — add `buildSnapshot`, `getModelInfo`, `getSessionInfo` stubs to `createToolDeps`; simplify `makeCtx()`.
+   Green: add three collaborator parameters to `createAgentTool`; rewrite `execute` to use them instead of `ctx.model` / `ctx.modelRegistry` / `ctx.sessionManager`.
+   Remove `ExtensionContext` import from `agent-tool.ts`.
+   Update `index.ts` wiring to provide closures.
+   Commit: `refactor: inject collaborators into createAgentTool, eliminate ctx reads (#145)`
+
+### Step 4: Push ctx out of foreground-runner and background-spawner
+
+5. Red: update `foreground-runner.test.ts` — remove `makeCtx()`, replace `ForegroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
+   Green: change `ForegroundParams` to use plain domain values, update `runForeground` accordingly.
+   Commit: `refactor: foreground-runner receives domain values instead of ctx (#145)`
+
+6. Red: update `background-spawner.test.ts` — remove `makeCtx()`, replace `BackgroundParams.ctx` with `snapshot` / `parentSessionFile` / `parentSessionId`.
+   Green: change `BackgroundParams` to use plain domain values, update `spawnBackground` accordingly.
+   Commit: `refactor: background-spawner receives domain values instead of ctx (#145)`
+
+### Step 5: Shrink params bags with ResolvedSpawnConfig
+
+7. Red: update `foreground-runner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
+   Green: change `ForegroundParams` to carry `ResolvedSpawnConfig`.
+   Update `agent-tool.ts` dispatch to pass the config through.
+   Commit: `refactor: ForegroundParams carries ResolvedSpawnConfig (#145)`
+
+8. Red: update `background-spawner.test.ts` `makeParams()` to use `ResolvedSpawnConfig` fields.
+   Green: change `BackgroundParams` to carry `ResolvedSpawnConfig`.
+   Update `agent-tool.ts` dispatch to pass the config through.
+   Commit: `refactor: BackgroundParams carries ResolvedSpawnConfig (#145)`
+
+### Step 6: Dissolve small dependency bags
+
+9. Red: update `foreground-runner.test.ts` calls to pass `manager`, `widget`, `agentActivity` as plain args.
+   Green: remove `ForegroundDeps` interface, change `runForeground` signature.
+   Commit: `refactor: dissolve ForegroundDeps into plain parameters (#145)`
+
+10. Red: update `background-spawner.test.ts` calls to pass plain args.
+    Green: remove `BackgroundDeps` interface, change `spawnBackground` signature.
+    Commit: `refactor: dissolve BackgroundDeps into plain parameters (#145)`
+
+11. Red: update `service-adapter.test.ts` to pass plain parameters instead of `AdapterDeps` bag.
+    Green: remove `AdapterDeps` interface, change `createSubagentsService` signature.
+    Update `index.ts` wiring call site.
+    Commit: `refactor: dissolve AdapterDeps into plain parameters (#145)`
+
+12. Refactor: destructure `AgentToolDeps` in `createAgentTool` signature (keep the named type for test factory).
+    Commit: `refactor: destructure AgentToolDeps in createAgentTool (#145)`
+
+### Step 7: Final verification
+
+13. Run full test suite and type check.
+
+## Risks and Mitigations
+
+| Risk                                                                  | Mitigation                                                                                                                                                                      |
+| --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Wide blast radius — touches 7+ source files and 5+ test files         | Incremental TDD steps; each commit leaves the repo green                                                                                                                        |
+| `service-adapter.ts` now imports `buildParentSnapshot` — new coupling | Acceptable: the adapter is already a boundary module that bridges `ExtensionContext` to domain types                                                                            |
+| `ResolvedSpawnConfig` could become a new "god object"                 | It is a pure data return from a single function; consumers destructure what they need                                                                                           |
+| Three new collaborators grow `AgentToolDeps` from 6 to 9 fields       | The deps bag is destructured at the signature; the named type exists only for the test factory. The real dependency count stays the same — previously hidden behind `ctx` reads |
+| `index.ts` closures capture `ctx` — stale reference risk              | Same pattern `service-adapter.ts` already uses via `runtime.currentCtx`; session lifecycle clears on shutdown                                                                   |
+
+## Open Questions
+
+- The exact boundary between fields that stay in `ForegroundParams` / `BackgroundParams` vs. fields that move into `ResolvedSpawnConfig` may shift during implementation.
+  The guiding principle: if the field is computed during config resolution, it belongs in `ResolvedSpawnConfig`; if it is dispatch-specific (e.g., `toolCallId`, `signal`, `onUpdate`), it stays in the params type.

package/docs/retro/0145-decompose-execute-push-ctx-to-boundary.md

@@ -0,0 +1,56 @@
+---
+issue: 145
+issue_title: "Decompose execute and push ExtensionContext to the boundary (Phase 9, Step M)"
+---
+
+# Retro: #145 — Decompose execute and push ExtensionContext to the boundary
+
+## Final Retrospective (2026-05-23)
+
+### Session summary
+
+Extracted config resolution into a pure `resolveSpawnConfig` function, injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` to eliminate `ctx` reads from `execute`, pushed `ParentSnapshot` to `AgentManager`'s public API, and dissolved three small dependency bags (`ForegroundDeps`, `BackgroundDeps`, `AdapterDeps`) into plain parameters.
+Released as `pi-subagents-v6.15.0`.
+
+### Observations
+
+#### What went well
+
+- User's two escalating questions ("Are there any other missing collaborators?"
+  → "Hiding dependencies in an object bag still counts as dependencies!") caught a `premature-convergence` before it landed as committed code.
+  The reverted partial step 3 attempt was ~4 files of changes that would have needed rework.
+  The resulting design (injected collaborators) is meaningfully better than the original plan's mechanical relocation.
+- Folding tightly-coupled TDD steps (ctx elimination + params shrinking + deps dissolution) into fewer commits avoided intermediate states with broken types.
+  The plan's 12-step sequence would have required lift-and-shift gymnastics; the actual 7-commit sequence was cleaner.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` — the original plan relocated `buildParentSnapshot` calls to `execute` without questioning whether `execute` should read `ctx` at all.
+  The existing `code-design` skill has DIP and parameter-relay rules that should have flagged this.
+  The `service-adapter.ts` module already demonstrated the getter-injection pattern (`getCtx`, `getModelRegistry`), but I didn't search for it during plan writing.
+  Impact: one plan rewrite commit (76bb57b), one reverted partial implementation (~15 minutes of rework).
+  User-caught.
+
+- `missing-context` — didn't use `colgrep` during initial plan writing to discover the established getter-injection convention in `service-adapter.ts`.
+  Used `grep` exclusively for exact symbol matching.
+  When prompted by the user to use `colgrep`, the results were confirmatory rather than revelatory because I'd already read the relevant files by that point.
+  The miss was not using it *earlier* for intent-based exploration ("how do existing modules inject session-scoped state?").
+  Impact: added friction but no rework — the user's questions surfaced the pattern before code was committed.
+  User-caught.
+
+- `instruction-violation` — wrote an inline `import()` type assertion (`session.ctx as import("@earendil-works/pi-coding-agent").ExtensionContext`) in `service-adapter.ts`.
+  AGENTS.md says "Use standard top-level imports only."
+  Impact: one extra edit round, caught before committing.
+  User-caught.
+
+#### What caused friction (user side)
+
+- The user's redirecting questions were well-timed and effective.
+  The escalation from "Are there any other missing collaborators?"
+  to the more pointed "Hiding dependencies in an object bag still counts as dependencies!"
+  was the right amount of pressure.
+  No friction observed on the user side.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added `colgrep` skill loading to the "Load skills" section for code-change plans, so convention discovery happens during exploration rather than after committing to a design.

package/package.json

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

package/src/agent-manager.ts

@@ -8,14 +8,13 @@
 
 import { randomUUID } from "node:crypto";
 import type { Model } from "@earendil-works/pi-ai";
-import type { AgentSession, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
 import { NotificationState } from "./notification-state.js";
 import type { ParentSnapshot } from "./parent-snapshot.js";
-import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
 import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
@@ -141,7 +140,7 @@ export class AgentManager {
    * If the concurrency limit is reached, the agent is queued.
    */
   spawn(
-    ctx: ExtensionContext,
+    snapshot: ParentSnapshot,
     type: SubagentType,
     prompt: string,
     options: AgentSpawnConfig,
@@ -167,7 +166,6 @@ export class AgentManager {
       this.observer?.onAgentCreated(record);
     }
 
-    const snapshot = buildParentSnapshot(ctx, options.inheritContext);
     const args: SpawnArgs = { snapshot, type, prompt, options };
 
     if (options.isBackground && !options.bypassQueue && this.runningBackground >= this._getMaxConcurrent()) {
@@ -332,12 +330,12 @@ export class AgentManager {
    * Foreground agents bypass the concurrency queue.
    */
   async spawnAndWait(
-    ctx: ExtensionContext,
+    snapshot: ParentSnapshot,
     type: SubagentType,
     prompt: string,
     options: Omit<AgentSpawnConfig, "isBackground">,
   ): Promise<AgentRecord> {
-    const id = this.spawn(ctx, type, prompt, { ...options, isBackground: false });
+    const id = this.spawn(snapshot, type, prompt, { ...options, isBackground: false });
     const record = this.agents.get(id)!;
     await record.promise;
     return record;
@@ -352,7 +350,7 @@ export class AgentManager {
     signal?: AbortSignal,
   ): Promise<AgentRecord | undefined> {
     const record = this.agents.get(id);
-    const session = record?.execution?.session;
+    const session = record?.session;
     if (!session) return undefined;
 
     record.resetForResume(Date.now());
@@ -404,7 +402,7 @@ export class AgentManager {
 
   /** Dispose a record's session and remove it from the map. */
   private removeRecord(id: string, record: AgentRecord): void {
-    record.execution?.session?.dispose?.();
+    record.session?.dispose?.();
     this.agents.delete(id);
     this.pendingSteers.delete(id);
   }
@@ -482,7 +480,7 @@ export class AgentManager {
     // Clear queue
     this.queue = [];
     for (const record of this.agents.values()) {
-      record.execution?.session?.dispose();
+      record.session?.dispose();
     }
     this.agents.clear();
     // Prune any orphaned git worktrees (crash recovery)

package/src/agent-record.ts

@@ -12,6 +12,7 @@
  * after construction as lifecycle information becomes available.
  */
 
+import type { AgentSession } from "@earendil-works/pi-coding-agent";
 import type { ExecutionState } from "./execution-state.js";
 import type { NotificationState } from "./notification-state.js";
 import type { AgentInvocation, SubagentType } from "./types.js";
@@ -85,6 +86,16 @@ export class AgentRecord {
 	worktreeState?: WorktreeState;
 	notification?: NotificationState;
 
+	/** The active agent session, or undefined before the session is created. */
+	get session(): AgentSession | undefined {
+		return this.execution?.session;
+	}
+
+	/** Path to the agent's session JSONL file, or undefined if not yet available. */
+	get outputFile(): string | undefined {
+		return this.execution?.outputFile;
+	}
+
 	constructor(init: AgentRecordInit) {
 		this.id = init.id;
 		this.type = init.type;

package/src/index.ts

@@ -29,6 +29,7 @@ import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
+import { buildParentSnapshot } from "./parent-snapshot.js";
 import { buildAgentPrompt } from "./prompts.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
@@ -61,12 +62,12 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = new NotificationManager({
-    sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
-    agentActivity: runtime.agentActivity,
-    markFinished: (id) => runtime.markFinished(id),
-    updateWidget: () => runtime.updateWidget(),
-  });
+  const notifications = new NotificationManager(
+    (msg, opts) => pi.sendMessage(msg, opts),
+    runtime.agentActivity,
+    (id) => runtime.markFinished(id),
+    () => runtime.updateWidget(),
+  );
 
   // Settings: owns all three in-memory values and handles load/save/emit.
   // onMaxConcurrentChanged is wired after manager is constructed (closure captures by reference).
@@ -162,12 +163,12 @@ 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({
+  const service = createSubagentsService(
     manager,
     resolveModel,
-    getCtx: () => runtime.currentCtx,
-    getModelRegistry: () => (runtime.currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
-  });
+    () => runtime.currentCtx,
+    () => (runtime.currentCtx?.ctx as { modelRegistry?: ModelRegistry } | undefined)?.modelRegistry,
+  );
   publishSubagentsService(service);
 
   const lifecycle = new SessionLifecycleHandler(
@@ -193,8 +194,8 @@ export default function (pi: ExtensionAPI) {
 
   pi.registerTool(defineTool(createAgentTool({
     manager: {
-      spawn: (ctx, type, prompt, opts) => manager.spawn(ctx, type, prompt, opts),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
+      spawn: (snapshot, type, prompt, opts) => manager.spawn(snapshot, type, prompt, opts),
+      spawnAndWait: (snapshot, type, prompt, opts) => manager.spawnAndWait(snapshot, type, prompt, opts),
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
       getMaxConcurrent: () => settings.maxConcurrent,
@@ -209,6 +210,19 @@ 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() ?? "",
+    }),
   })));
 
   // ---- get_subagent_result tool ----
@@ -235,7 +249,7 @@ export default function (pi: ExtensionAPI) {
     manager: {
       listAgents: () => manager.listAgents(),
       getRecord: (id) => manager.getRecord(id),
-      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(ctx, type, prompt, opts),
+      spawnAndWait: (ctx, type, prompt, opts) => manager.spawnAndWait(buildParentSnapshot(ctx), type, prompt, opts),
     },
     registry,
     agentActivity: runtime.agentActivity,

package/src/notification.ts

@@ -46,7 +46,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
   const status = getStatusLabel(record.status, record.error);
   const durationMs = record.completedAt ? record.completedAt - record.startedAt : 0;
   const totalTokens = getLifetimeTotal(record.lifetimeUsage);
-  const contextPercent = getSessionContextPercent(record.execution?.session);
+  const contextPercent = getSessionContextPercent(record.session);
   const ctxXml = contextPercent !== null ? `<context_percent>${Math.round(contextPercent)}</context_percent>` : "";
   const compactXml = record.compactionCount ? `<compactions>${record.compactionCount}</compactions>` : "";
 
@@ -57,7 +57,7 @@ export function formatTaskNotification(record: AgentRecord, resultMaxLen: number
     : "No output.";
 
   const toolCallId = record.notification?.toolCallId;
-  const outputFile = record.execution?.outputFile;
+  const outputFile = record.outputFile;
   return [
     "<task-notification>",
     `<task-id>${record.id}</task-id>`,
@@ -90,7 +90,7 @@ export function buildNotificationDetails(
     maxTurns: activity?.maxTurns,
     totalTokens,
     durationMs: record.completedAt ? record.completedAt - record.startedAt : 0,
-    outputFile: record.execution?.outputFile,
+    outputFile: record.outputFile,
     error: record.error,
     resultPreview: record.result
       ? record.result.length > resultMaxLen
@@ -124,17 +124,6 @@ export function buildEventData(record: AgentRecord) {
 
 // ---- Notification system factory ----
 
-/** Narrow deps for the notification system — only the methods it actually calls. */
-export interface NotificationDeps {
-  sendMessage: (
-    msg: { customType: string; content: string; display: boolean; details?: unknown },
-    opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
-  ) => void;
-  agentActivity: Map<string, AgentActivityTracker>;
-  markFinished: (id: string) => void;
-  updateWidget: () => void;
-}
-
 export interface NotificationSystem {
   cancelNudge: (key: string) => void;
   sendCompletion: (record: AgentRecord) => void;
@@ -147,7 +136,15 @@ const NUDGE_HOLD_MS = 200;
 export class NotificationManager implements NotificationSystem {
   private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
 
-  constructor(private deps: NotificationDeps) {}
+  constructor(
+    private sendMessage: (
+      msg: { customType: string; content: string; display: boolean; details?: unknown },
+      opts?: { triggerTurn?: boolean; deliverAs?: "steer" | "followUp" | "nextTurn" },
+    ) => void,
+    private agentActivity: Map<string, AgentActivityTracker>,
+    private markFinished: (id: string) => void,
+    private updateWidget: () => void,
+  ) {}
 
   cancelNudge(key: string): void {
     const timer = this.pendingNudges.get(key);
@@ -158,16 +155,16 @@ export class NotificationManager implements NotificationSystem {
   }
 
   sendCompletion(record: AgentRecord): void {
-    this.deps.agentActivity.delete(record.id);
-    this.deps.markFinished(record.id);
+    this.agentActivity.delete(record.id);
+    this.markFinished(record.id);
     this.scheduleNudge(record.id, () => this.emitIndividualNudge(record));
-    this.deps.updateWidget();
+    this.updateWidget();
   }
 
   cleanupCompleted(id: string): void {
-    this.deps.agentActivity.delete(id);
-    this.deps.markFinished(id);
-    this.deps.updateWidget();
+    this.agentActivity.delete(id);
+    this.markFinished(id);
+    this.updateWidget();
   }
 
   dispose(): void {
@@ -194,15 +191,15 @@ export class NotificationManager implements NotificationSystem {
     if (record.notification?.resultConsumed) return;
 
     const notification = formatTaskNotification(record, 500);
-    const outputFile = record.execution?.outputFile;
+    const outputFile = record.outputFile;
     const footer = outputFile ? `\nFull transcript available at: ${outputFile}` : "";
 
-    this.deps.sendMessage(
+    this.sendMessage(
       {
         customType: "subagent-notification",
         content: notification + footer,
         display: true,
-        details: buildNotificationDetails(record, 500, this.deps.agentActivity.get(record.id)),
+        details: buildNotificationDetails(record, 500, this.agentActivity.get(record.id)),
       },
       { deliverAs: "followUp", triggerTurn: true },
     );