@gotgenes/pi-subagents 6.14.1 → 6.15.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.15.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.1...pi-subagents-v6.15.0) (2026-05-23)
+
+
+### Features
+
+* extract resolveSpawnConfig pure function ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([e89724a](https://github.com/gotgenes/pi-packages/commit/e89724a87480713529160d0fa23975becbcfe162))
+
+
+### Documentation
+
+* plan decompose execute and push ctx to boundary ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([aae7d7b](https://github.com/gotgenes/pi-packages/commit/aae7d7b4e04ab0dddedd2a0f9f2b806719956ced))
+* update architecture doc for completed Step M ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([33ec0c7](https://github.com/gotgenes/pi-packages/commit/33ec0c73479076c180381dcc1cb4106ba635f33f))
+* update plan with injected collaborators for ctx elimination ([#145](https://github.com/gotgenes/pi-packages/issues/145)) ([76bb57b](https://github.com/gotgenes/pi-packages/commit/76bb57b4b5190078ded8685907f0878640031e13))
+
 ## [6.14.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.14.0...pi-subagents-v6.14.1) (2026-05-23)
 
 

package/docs/architecture/architecture.md

@@ -647,38 +647,24 @@ Apply the dependency bag convention to touched modules: `NotificationDeps` (4 fi
 
 Impact: eliminates dual counting; removes `??` fallback pattern from widget and conversation viewer; hides `ExecutionState` structure from consumers.
 
-### Step M: Decompose execute and push ExtensionContext to the boundary (#145)
+### Step M: Decompose execute and push ExtensionContext to the boundary (#145) ✓
 
-`execute` is 145 lines with three responsibilities mixed together:
+Extracted config resolution into `resolveSpawnConfig` (pure function in `spawn-config.ts`).
+Injected three collaborators (`buildSnapshot`, `getModelInfo`, `getSessionInfo`) into `createAgentTool` so `execute` no longer reads `ctx` beyond `ctx.ui` (already delegated to `widget.setUICtx`).
+`AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
+`service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+`foreground-runner` and `background-spawner` receive `ResolvedSpawnConfig` + domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
 
-1. **Boundary extraction** (~5 lines) - read `ctx.model`, `ctx.modelRegistry`, `ctx.ui`, `ctx.sessionManager`, call `buildParentSnapshot(ctx)`.
-2. **Config resolution** (~60 lines) - resolve agent type, merge invocation config, resolve model, compute max turns, build tags and display metadata.
-3. **Dispatch** (~80 lines) - resume / background / foreground, each passing 14-16 field parameter bags.
-
-The config resolution section is working for the dependencies: manually unpacking `resolvedConfig` field by field, computing derived values, then repacking everything into massive objects for `spawnBackground` and `runForeground`.
-The 16-field bags are the symptom - they exist because the resolution happened in the wrong place.
-
-The fix has two parts:
-
-1. **Extract config resolution** into a pure function (e.g. `resolveSpawnConfig`) that accepts the raw tool params, registry, model info, and settings, and returns a single `ResolvedSpawnConfig` object.
-   `execute` becomes: extract ctx → resolve config → dispatch.
-   `spawnBackground` and `runForeground` receive `ResolvedSpawnConfig` instead of 16 individual fields.
-2. **Push `ctx` to the boundary.**
-   `execute` extracts everything from `ctx` in its first few lines.
-   `foreground-runner.ts` and `background-spawner.ts` receive domain values (`snapshot`, `parentSessionFile`, `parentSessionId`) instead of `ctx`.
-   `AgentManager.spawn()` and `spawnAndWait()` accept `ParentSnapshot` instead of `ExtensionContext`.
-   `service-adapter.ts` calls `buildParentSnapshot(session.ctx)` at its boundary.
+Dissolved `ForegroundDeps`, `BackgroundDeps`, and `AdapterDeps` into plain parameters.
+`AgentToolDeps` is destructured in the `createAgentTool` signature.
 
 After this step, `ExtensionContext` appears only in:
 
-- `agent-tool.ts execute` (SDK callback - unavoidable)
+- `index.ts` closures (wired at extension startup)
 - `service-adapter.ts` (cross-extension boundary)
-- `index.ts` (extension entry point)
 - Menu handlers (addressed by Step N)
 
-Apply the dependency bag convention to touched modules: `ForegroundDeps` (3 fields) and `BackgroundDeps` (3 fields) become plain parameters; `AdapterDeps` (3 fields) becomes plain parameters; `AgentToolDeps` (6 fields) is destructured in the signature.
-
-Impact: `execute` drops from ~145 to ~30 lines; eliminates 16-field parameter bags; eliminates 1 `vi.mock()` call in `agent-manager.test.ts`; `foreground-runner` and `background-spawner` tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
+Impact: `execute` dropped from ~145 to ~25 lines; eliminated 16-field parameter bags; eliminated `vi.mock("../src/parent-snapshot.js")` in `agent-manager.test.ts`; foreground/background runner tests no longer need `ctx` mocks; `AgentManager` operates entirely on domain types.
 
 ### Step N: Narrow UI context for menu handlers (#146)
 
@@ -690,7 +676,7 @@ Creation wizard’s `spawnAndWait` call changes: the narrow `AgentMenuManager.sp
 
 Apply the dependency bag convention to touched modules: `AgentConfigEditorDeps` (4 fields), `SteerToolDeps` (4 fields), and `GetResultDeps` (4 fields) become plain parameters; `AgentMenuDeps` (8 fields) and `AgentCreationWizardDeps` (5 fields) are destructured in the signature.
 
-After Steps M and N, `ExtensionContext` appears only at true boundaries: `agent-tool.ts execute` (SDK callback), `service-adapter.ts` (cross-extension bridge), and `index.ts` (extension entry point).
+After Steps M and N, `ExtensionContext` appears only at true boundaries: `index.ts` closures, `service-adapter.ts` (cross-extension bridge), and `index.ts` (extension entry point).
 
 Impact: eliminates ~43 `ctx as any` casts across menu, editor, and wizard test files; tests construct a plain object satisfying `MenuUI` with no cast.
 

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.14.1",
+  "version": "6.15.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;

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";
@@ -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/service-adapter.ts

@@ -5,13 +5,16 @@
  * (stripping non-serializable fields), and session gating.
  */
 
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import type { ModelRegistry } from "./model-resolver.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
+import { buildParentSnapshot } from "./parent-snapshot.js";
 import type { SubagentRecord, SubagentsService } from "./service.js";
 import type { AgentRecord } from "./types.js";
 
 /** Narrow interface for the AgentManager — avoids coupling to the concrete class. */
 export interface AgentManagerLike {
-  spawn(ctx: unknown, type: string, prompt: string, options: unknown): string;
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: unknown): string;
   getRecord(id: string): AgentRecord | undefined;
   listAgents(): AgentRecord[];
   abort(id: string): boolean;
@@ -20,32 +23,27 @@ export interface AgentManagerLike {
   queueSteer(id: string, message: string): boolean;
 }
 
-/** Dependencies injected into the adapter factory. */
-export interface AdapterDeps {
-  manager: AgentManagerLike;
-  resolveModel: (input: string, registry: ModelRegistry) => unknown | string;
-  getCtx: () => { pi: unknown; ctx: unknown } | undefined;
-  getModelRegistry: () => ModelRegistry | undefined;
-}
-
 /** Create a SubagentsService backed by the given dependencies. */
-export function createSubagentsService(deps: AdapterDeps): SubagentsService {
-  const { manager } = deps;
-
+export function createSubagentsService(
+  manager: AgentManagerLike,
+  resolveModel: (input: string, registry: ModelRegistry) => unknown | string,
+  getCtx: () => { pi: unknown; ctx: unknown } | undefined,
+  getModelRegistry: () => ModelRegistry | undefined,
+): SubagentsService {
   return {
     spawn(type: string, prompt: string, options?) {
-      const session = deps.getCtx();
+      const session = getCtx();
       if (!session) {
         throw new Error("No active session — cannot spawn agents outside a session.");
       }
 
       let model: unknown;
       if (options?.model) {
-        const registry = deps.getModelRegistry();
+        const registry = getModelRegistry();
         if (!registry) {
           throw new Error("No model registry available.");
         }
-        const resolved = deps.resolveModel(options.model, registry);
+        const resolved = resolveModel(options.model, registry);
         if (typeof resolved === "string") {
           throw new Error(resolved);
         }
@@ -55,7 +53,11 @@ export function createSubagentsService(deps: AdapterDeps): SubagentsService {
       const description = options?.description ?? prompt.slice(0, 80);
       const isBackground = !(options?.foreground ?? false);
 
-      return manager.spawn(session.ctx, type, prompt, {
+      const snapshot = buildParentSnapshot(
+        session.ctx as ExtensionContext,
+        options?.inheritContext,
+      );
+      return manager.spawn(snapshot, type, prompt, {
         description,
         model,
         maxTurns: options?.maxTurns,

package/src/tools/agent-tool.ts

@@ -1,34 +1,31 @@
-import type { AgentToolResult, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import type { AgentSpawnConfig } from "../agent-manager.js";
-import { normalizeMaxTurns } from "../agent-runner.js";
 import { AgentTypeRegistry } from "../agent-types.js";
-import { resolveAgentInvocationConfig } from "../invocation-config.js";
-import { resolveInvocationModel } from "../model-resolver.js";
+import type { ParentSnapshot } from "../parent-snapshot.js";
 
-import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import { type UICtx } from "../ui/agent-widget.js";
 import {
   type AgentDetails,
-  buildInvocationTags,
   formatMs,
   formatTurns,
   getDisplayName,
-  getPromptModeLabel,
   SPINNER,
 } from "../ui/display.js";
 import { spawnBackground } from "./background-spawner.js";
 import { runForeground } from "./foreground-runner.js";
 import { buildDetails, buildTypeListText, textResult } from "./helpers.js";
+import { type ModelInfo, resolveSpawnConfig } from "./spawn-config.js";
 
 // ---- Deps interface ----
 
 /** Narrow manager interface — only the methods the Agent tool calls. */
 export interface AgentToolManager {
-  spawn: (ctx: ExtensionContext, type: string, prompt: string, opts: AgentSpawnConfig) => string;
-  spawnAndWait: (ctx: ExtensionContext, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
+  spawn: (snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig) => string;
+  spawnAndWait: (snapshot: ParentSnapshot, type: string, prompt: string, opts: Omit<AgentSpawnConfig, "isBackground">) => Promise<AgentRecord>;
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;
@@ -60,14 +57,30 @@ export interface AgentToolDeps {
   agentDir: string;
   /** Narrow settings accessor — only the default max turns is needed here. */
   settings: { readonly defaultMaxTurns: number | undefined };
+  /** Build a ParentSnapshot from the current session context. */
+  buildSnapshot: (inheritContext: boolean) => ParentSnapshot;
+  /** Model info from the current session context. */
+  getModelInfo: () => ModelInfo;
+  /** Parent session identity from the current session context. */
+  getSessionInfo: () => { parentSessionFile: string; parentSessionId: string };
 }
 
 // ---- Factory ----
 
 /** Create the Agent tool definition (without Pi SDK wrapper). */
-export function createAgentTool(deps: AgentToolDeps) {
-  const typeListText = buildTypeListText(deps.registry, deps.agentDir);
-  const availableTypesText = deps.registry.getAvailableTypes().join(", ");
+export function createAgentTool({
+  manager,
+  widget,
+  agentActivity,
+  registry,
+  agentDir,
+  settings,
+  buildSnapshot,
+  getModelInfo,
+  getSessionInfo,
+}: AgentToolDeps) {
+  const typeListText = buildTypeListText(registry, agentDir);
+  const availableTypesText = registry.getAvailableTypes().join(", ");
   return {
     name: "Agent" as const,
     label: "Agent",
@@ -101,7 +114,7 @@ Guidelines:
         description: "A short (3-5 word) description of the task (shown in UI).",
       }),
       subagent_type: Type.String({
-        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${deps.agentDir}/agents/<name>.md (global) are also available.`,
+        description: `The type of specialized agent to use. Available types: ${availableTypesText}. Custom agents from .pi/agents/<name>.md (project) or ${agentDir}/agents/<name>.md (global) are also available.`,
       }),
       model: Type.Optional(
         Type.String({
@@ -156,7 +169,7 @@ Guidelines:
 
     renderCall(args: Record<string, unknown>, theme: any) {
       const displayName = args.subagent_type
-        ? getDisplayName(args.subagent_type as string, deps.registry)
+        ? getDisplayName(args.subagent_type as string, registry)
         : "Agent";
       const desc = (args.description as string) ?? "";
       return new Text(
@@ -273,71 +286,27 @@ Guidelines:
       ctx: any,
     ) => {
       // Ensure we have UI context for widget rendering
-      deps.widget.setUICtx(ctx.ui as UICtx);
+      widget.setUICtx(ctx.ui as UICtx);
 
       // Reload custom agents so new .pi/agents/*.md files are picked up without restart
-      deps.registry.reload();
-
-      const rawType = params.subagent_type as SubagentType;
-      const resolved = deps.registry.resolveType(rawType);
-      const subagentType = resolved ?? "general-purpose";
-      const fellBack = resolved === undefined;
-
-      const displayName = getDisplayName(subagentType, deps.registry);
-
-      // Get agent config for invocation resolution
-      const customConfig = deps.registry.resolveAgentConfig(subagentType);
-
-      const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
-
-      // Resolve model from agent config first; tool-call params only fill gaps.
-      const resolution = resolveInvocationModel(
-        ctx.model,
-        resolvedConfig.modelInput,
-        resolvedConfig.modelFromParams,
-        ctx.modelRegistry,
+      registry.reload();
+
+      // ---- Config resolution (pure) ----
+      const config = resolveSpawnConfig(
+        params,
+        registry,
+        getModelInfo(),
+        settings,
       );
-      if (resolution.error) return textResult(resolution.error);
-      const model = resolution.model;
+      if ("error" in config) return textResult(config.error);
 
-      const thinking = resolvedConfig.thinking;
-      const inheritContext = resolvedConfig.inheritContext;
-      const runInBackground = resolvedConfig.runInBackground;
-      const isolated = resolvedConfig.isolated;
-      const isolation = resolvedConfig.isolation;
-
-      const parentModelId = ctx.model?.id;
-      const effectiveModelId = model?.id;
-      const modelName =
-        effectiveModelId && effectiveModelId !== parentModelId
-          ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
-          : undefined;
-      const effectiveMaxTurns = normalizeMaxTurns(
-        resolvedConfig.maxTurns ?? deps.settings.defaultMaxTurns,
-      );
-      const agentInvocation: AgentInvocation = {
-        modelName,
-        thinking,
-        maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
-        isolated,
-        inheritContext,
-        runInBackground,
-        isolation,
-      };
-      const modeLabel = getPromptModeLabel(subagentType, deps.registry);
-      const { tags: invocationTags } = buildInvocationTags(agentInvocation);
-      const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
-      const detailBase = {
-        displayName,
-        description: params.description as string,
-        subagentType,
-        modelName,
-        tags: agentTags.length > 0 ? agentTags : undefined,
-      };
+      // ---- Boundary extraction (after config so inheritContext is resolved) ----
+      const snapshot = buildSnapshot(config.inheritContext);
+      const { parentSessionFile, parentSessionId } = getSessionInfo();
 
-      // Resume existing agent
+      // ---- Resume existing agent ----
       if (params.resume) {
-        const existing = deps.manager.getRecord(params.resume as string);
+        const existing = manager.getRecord(params.resume as string);
         if (!existing) {
           return textResult(
             `Agent not found: "${params.resume}". It may have been cleaned up.`,
@@ -348,7 +317,7 @@ Guidelines:
             `Agent "${params.resume}" has no active session to resume.`,
           );
         }
-        const record = await deps.manager.resume(
+        const record = await manager.resume(
           params.resume as string,
           params.prompt as string,
           signal ?? new AbortController().signal,
@@ -358,52 +327,26 @@ Guidelines:
         }
         return textResult(
           record.result?.trim() || record.error?.trim() || "No output.",
-          buildDetails(detailBase, record),
+          buildDetails(config.detailBase, record),
         );
       }
 
-      // Background execution
-      if (runInBackground) {
+      // ---- Background execution ----
+      if (config.runInBackground) {
         return spawnBackground(
-          { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
-          {
-            ctx,
-            subagentType,
-            prompt: params.prompt as string,
-            description: params.description as string,
-            displayName,
-            toolCallId,
-            detailBase,
-            model,
-            effectiveMaxTurns,
-            isolated,
-            inheritContext,
-            thinking,
-            isolation,
-            agentInvocation,
-          },
+          manager,
+          widget,
+          agentActivity,
+          { config, snapshot, parentSessionFile, parentSessionId, toolCallId },
         );
       }
 
-      // Foreground (synchronous) execution — stream progress via onUpdate
+      // ---- Foreground execution — stream progress via onUpdate ----
       return runForeground(
-        { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
-        {
-          ctx,
-          subagentType,
-          prompt: params.prompt as string,
-          description: params.description as string,
-          detailBase,
-          rawType,
-          fellBack,
-          model,
-          effectiveMaxTurns,
-          isolated,
-          inheritContext,
-          thinking,
-          isolation,
-          agentInvocation,
-        },
+        manager,
+        widget,
+        agentActivity,
+        { config, snapshot, parentSessionFile, parentSessionId },
         signal,
         onUpdate,
       );

package/src/tools/background-spawner.ts

@@ -1,15 +1,15 @@
-import type { Model } from "@earendil-works/pi-ai";
 import type { AgentSpawnConfig } from "../agent-manager.js";
-import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
+import type { ParentSnapshot } from "../parent-snapshot.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
-import type { AgentDetails } from "../ui/display.js";
 import { subscribeUIObserver } from "../ui/ui-observer.js";
 import type { AgentActivityAccess } from "./agent-tool.js";
 import { textResult } from "./helpers.js";
+import type { ResolvedSpawnConfig } from "./spawn-config.js";
 
 /** Narrow manager interface for the background spawner. */
 export interface BackgroundManagerDeps {
-  spawn(ctx: any, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, opts: AgentSpawnConfig): string;
   getRecord(id: string): AgentRecord | undefined;
   getMaxConcurrent(): number;
 }
@@ -20,34 +20,13 @@ export interface BackgroundWidgetDeps {
   update(): void;
 }
 
-/** Injected collaborators for spawnBackground. */
-export interface BackgroundDeps {
-  manager: BackgroundManagerDeps;
-  widget: BackgroundWidgetDeps;
-  agentActivity: AgentActivityAccess;
-}
-
-/** All values the background spawner needs, bundled from shared execute setup. */
+/** All values the background spawner needs beyond the resolved config. */
 export interface BackgroundParams {
-  ctx: {
-    sessionManager: {
-      getSessionFile(): string;
-      getSessionId(): string;
-    };
-  };
-  subagentType: string;
-  prompt: string;
-  description: string;
-  displayName: string;
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSessionFile: string;
+  parentSessionId: string;
   toolCallId: string;
-  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
-  model: Model<any> | undefined;
-  effectiveMaxTurns: number | undefined;
-  isolated: boolean | undefined;
-  inheritContext: boolean | undefined;
-  thinking: ThinkingLevel | undefined;
-  isolation: IsolationMode | undefined;
-  agentInvocation: AgentInvocation;
 }
 
 /**
@@ -56,25 +35,28 @@ export interface BackgroundParams {
  * registration, widget update, and launch message formatting.
  */
 export function spawnBackground(
-  deps: BackgroundDeps,
+  manager: BackgroundManagerDeps,
+  widget: BackgroundWidgetDeps,
+  agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
-  const bgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  const { config } = params;
+  const bgState = new AgentActivityTracker(config.effectiveMaxTurns);
 
   let id: string;
   try {
-    id = deps.manager.spawn(params.ctx, params.subagentType, params.prompt, {
-      parentSessionFile: params.ctx.sessionManager.getSessionFile(),
-      parentSessionId: params.ctx.sessionManager.getSessionId(),
-      description: params.description,
-      model: params.model,
-      maxTurns: params.effectiveMaxTurns,
-      isolated: params.isolated,
-      inheritContext: params.inheritContext,
-      thinkingLevel: params.thinking,
+    id = manager.spawn(params.snapshot, config.subagentType, config.prompt, {
+      parentSessionFile: params.parentSessionFile,
+      parentSessionId: params.parentSessionId,
+      description: config.description,
+      model: config.model,
+      maxTurns: config.effectiveMaxTurns,
+      isolated: config.isolated,
+      inheritContext: config.inheritContext,
+      thinkingLevel: config.thinking,
       isBackground: true,
-      isolation: params.isolation,
-      invocation: params.agentInvocation,
+      isolation: config.isolation,
+      invocation: config.agentInvocation,
       toolCallId: params.toolCallId,
       onSessionCreated: (session) => {
         bgState.setSession(session);
@@ -85,27 +67,27 @@ export function spawnBackground(
     return textResult(err instanceof Error ? err.message : String(err));
   }
 
-  const record = deps.manager.getRecord(id);
+  const record = manager.getRecord(id);
 
-  deps.agentActivity.set(id, bgState);
-  deps.widget.ensureTimer();
-  deps.widget.update();
+  agentActivity.set(id, bgState);
+  widget.ensureTimer();
+  widget.update();
 
   const isQueued = record?.status === "queued";
   return textResult(
     `Agent ${isQueued ? "queued" : "started"} in background.\n` +
       `Agent ID: ${id}\n` +
-      `Type: ${params.displayName}\n` +
-      `Description: ${params.description}\n` +
+      `Type: ${config.displayName}\n` +
+      `Description: ${config.description}\n` +
       (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
       (isQueued
-        ? `Position: queued (max ${deps.manager.getMaxConcurrent()} concurrent)\n`
+        ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
         : "") +
       `\nYou will be notified when this agent completes.\n` +
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
       `Do not duplicate this agent's work.`,
     {
-      ...params.detailBase,
+      ...config.detailBase,
       toolUses: 0,
       tokens: "",
       durationMs: 0,

package/src/tools/foreground-runner.ts

@@ -1,7 +1,7 @@
-import type { Model } from "@earendil-works/pi-ai";
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import type { AgentSpawnConfig } from "../agent-manager.js";
-import type { AgentInvocation, AgentRecord, IsolationMode, ThinkingLevel } from "../types.js";
+import type { ParentSnapshot } from "../parent-snapshot.js";
+import type { AgentRecord } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
   type AgentDetails,
@@ -17,11 +17,12 @@ import {
   getStatusNote,
   textResult,
 } from "./helpers.js";
+import type { ResolvedSpawnConfig } from "./spawn-config.js";
 
 /** Narrow manager interface for the foreground runner. */
 export interface ForegroundManagerDeps {
   spawnAndWait(
-    ctx: any,
+    snapshot: ParentSnapshot,
     type: string,
     prompt: string,
     opts: Omit<AgentSpawnConfig, "isBackground">,
@@ -34,37 +35,12 @@ export interface ForegroundWidgetDeps {
   markFinished(id: string): void;
 }
 
-/** Injected collaborators for runForeground. */
-export interface ForegroundDeps {
-  manager: ForegroundManagerDeps;
-  widget: ForegroundWidgetDeps;
-  agentActivity: AgentActivityAccess;
-}
-
-/** All values the foreground runner needs, bundled from shared execute setup. */
+/** All values the foreground runner needs beyond the resolved config. */
 export interface ForegroundParams {
-  ctx: {
-    sessionManager: {
-      getSessionFile(): string;
-      getSessionId(): string;
-    };
-  };
-  subagentType: string;
-  prompt: string;
-  description: string;
-  detailBase: Pick<
-    AgentDetails,
-    "displayName" | "description" | "subagentType" | "modelName" | "tags"
-  >;
-  rawType: string;
-  fellBack: boolean;
-  model: Model<any> | undefined;
-  effectiveMaxTurns: number | undefined;
-  isolated: boolean | undefined;
-  inheritContext: boolean | undefined;
-  thinking: ThinkingLevel | undefined;
-  isolation: IsolationMode | undefined;
-  agentInvocation: AgentInvocation;
+  config: ResolvedSpawnConfig;
+  snapshot: ParentSnapshot;
+  parentSessionFile: string;
+  parentSessionId: string;
 }
 
 /**
@@ -73,21 +49,24 @@ export interface ForegroundParams {
  * streaming onUpdate callbacks, cleanup, and result formatting.
  */
 export async function runForeground(
-  deps: ForegroundDeps,
+  manager: ForegroundManagerDeps,
+  widget: ForegroundWidgetDeps,
+  agentActivity: AgentActivityAccess,
   params: ForegroundParams,
   signal: AbortSignal | undefined,
   onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
 ) {
+  const { config } = params;
   let spinnerFrame = 0;
   const startedAt = Date.now();
   let fgId: string | undefined;
 
-  const fgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
 
   const streamUpdate = () => {
     const details: AgentDetails = {
-      ...params.detailBase,
+      ...config.detailBase,
       toolUses: fgState.toolUses,
       tokens: formatLifetimeTokens(fgState),
       turnCount: fgState.turnCount,
@@ -113,28 +92,28 @@ export async function runForeground(
 
   let record: AgentRecord;
   try {
-    record = await deps.manager.spawnAndWait(
-      params.ctx,
-      params.subagentType,
-      params.prompt,
+    record = await manager.spawnAndWait(
+      params.snapshot,
+      config.subagentType,
+      config.prompt,
       {
-        description: params.description,
-        model: params.model,
-        maxTurns: params.effectiveMaxTurns,
-        isolated: params.isolated,
-        inheritContext: params.inheritContext,
-        thinkingLevel: params.thinking,
-        isolation: params.isolation,
-        invocation: params.agentInvocation,
+        description: config.description,
+        model: config.model,
+        maxTurns: config.effectiveMaxTurns,
+        isolated: config.isolated,
+        inheritContext: config.inheritContext,
+        thinkingLevel: config.thinking,
+        isolation: config.isolation,
+        invocation: config.agentInvocation,
         signal,
-        parentSessionFile: params.ctx.sessionManager.getSessionFile(),
-        parentSessionId: params.ctx.sessionManager.getSessionId(),
+        parentSessionFile: params.parentSessionFile,
+        parentSessionId: params.parentSessionId,
         onSessionCreated: (session, record) => {
           fgState.setSession(session);
           unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
           fgId = record.id;
-          deps.agentActivity.set(record.id, fgState);
-          deps.widget.ensureTimer();
+          agentActivity.set(record.id, fgState);
+          widget.ensureTimer();
         },
       },
     );
@@ -149,15 +128,15 @@ export async function runForeground(
 
   // Clean up foreground agent from widget
   if (fgId) {
-    deps.agentActivity.delete(fgId);
-    deps.widget.markFinished(fgId);
+    agentActivity.delete(fgId);
+    widget.markFinished(fgId);
   }
 
   const tokenText = formatLifetimeTokens(fgState);
-  const details = buildDetails(params.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
 
-  const fallbackNote = params.fellBack
-    ? `Note: Unknown agent type "${params.rawType}" \u2014 using general-purpose.\n\n`
+  const fallbackNote = config.fellBack
+    ? `Note: Unknown agent type "${config.rawType}" — using general-purpose.\n\n`
     : "";
 
   if (record.status === "error") {

package/src/tools/spawn-config.ts

@@ -0,0 +1,146 @@
+/**
+ * spawn-config.ts — Pure config resolution for the Agent tool.
+ *
+ * Extracts all config resolution logic from execute: type resolution,
+ * invocation config merge, model resolution, max-turns normalization,
+ * tag building, and detail-base construction.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { normalizeMaxTurns } from "../agent-runner.js";
+import type { AgentTypeRegistry } from "../agent-types.js";
+import { resolveAgentInvocationConfig } from "../invocation-config.js";
+import { resolveInvocationModel } from "../model-resolver.js";
+import type { AgentInvocation, IsolationMode, SubagentType, ThinkingLevel } from "../types.js";
+import {
+  type AgentDetails,
+  buildInvocationTags,
+  getDisplayName,
+  getPromptModeLabel,
+} from "../ui/display.js";
+
+/** Model info extracted from the parent session context. */
+export interface ModelInfo {
+  parentModel: { id: string; name?: string } | undefined;
+  modelRegistry: unknown;
+}
+
+/** Fully resolved config for spawning an agent. */
+export interface ResolvedSpawnConfig {
+  subagentType: string;
+  rawType: SubagentType;
+  fellBack: boolean;
+  displayName: string;
+  prompt: string;
+  description: string;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  thinking: ThinkingLevel | undefined;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation: IsolationMode | undefined;
+  modelName: string | undefined;
+  agentInvocation: AgentInvocation;
+  agentTags: string[];
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Error result when model resolution fails. */
+export interface SpawnConfigError {
+  error: string;
+}
+
+/**
+ * Resolve all config for an Agent tool invocation.
+ *
+ * Pure function — no SDK types, no side effects.
+ * Returns either a fully resolved config or an error.
+ */
+export function resolveSpawnConfig(
+  params: Record<string, unknown>,
+  registry: AgentTypeRegistry,
+  modelInfo: ModelInfo,
+  settings: { readonly defaultMaxTurns: number | undefined },
+): ResolvedSpawnConfig | SpawnConfigError {
+  const rawType = params.subagent_type as SubagentType;
+  const resolved = registry.resolveType(rawType);
+  const subagentType = resolved ?? "general-purpose";
+  const fellBack = resolved === undefined;
+
+  const displayName = getDisplayName(subagentType, registry);
+
+  // Merge agent config defaults with tool-call params
+  const customConfig = registry.resolveAgentConfig(subagentType);
+  const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
+
+  // Resolve model
+  const resolution = resolveInvocationModel(
+    modelInfo.parentModel,
+    resolvedConfig.modelInput,
+    resolvedConfig.modelFromParams,
+    modelInfo.modelRegistry as any,
+  );
+  if (resolution.error) return { error: resolution.error };
+  const model = resolution.model;
+
+  const thinking = resolvedConfig.thinking;
+  const inheritContext = resolvedConfig.inheritContext;
+  const runInBackground = resolvedConfig.runInBackground;
+  const isolated = resolvedConfig.isolated;
+  const isolation = resolvedConfig.isolation;
+
+  // Compute display model name (only shown when different from parent)
+  const parentModelId = modelInfo.parentModel?.id;
+  const effectiveModelId = model?.id;
+  const modelName =
+    effectiveModelId && effectiveModelId !== parentModelId
+      ? (model?.name ?? effectiveModelId).replace(/^Claude\s+/i, "").toLowerCase()
+      : undefined;
+
+  const effectiveMaxTurns = normalizeMaxTurns(
+    resolvedConfig.maxTurns ?? settings.defaultMaxTurns,
+  );
+
+  const agentInvocation: AgentInvocation = {
+    modelName,
+    thinking,
+    maxTurns: normalizeMaxTurns(resolvedConfig.maxTurns),
+    isolated,
+    inheritContext,
+    runInBackground,
+    isolation,
+  };
+
+  const modeLabel = getPromptModeLabel(subagentType, registry);
+  const { tags: invocationTags } = buildInvocationTags(agentInvocation);
+  const agentTags = modeLabel ? [modeLabel, ...invocationTags] : invocationTags;
+
+  const detailBase = {
+    displayName,
+    description: params.description as string,
+    subagentType,
+    modelName,
+    tags: agentTags.length > 0 ? agentTags : undefined,
+  };
+
+  return {
+    subagentType,
+    rawType,
+    fellBack,
+    displayName,
+    prompt: params.prompt as string,
+    description: params.description as string,
+    model,
+    effectiveMaxTurns,
+    thinking,
+    inheritContext,
+    runInBackground,
+    isolated,
+    isolation,
+    modelName,
+    agentInvocation,
+    agentTags,
+    detailBase,
+  };
+}