@gotgenes/pi-subagents 6.18.0 → 6.18.2

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.18.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.1...pi-subagents-v6.18.2) (2026-05-24)
+
+
+### Documentation
+
+* plan extract ParentSessionInfo from AgentSpawnConfig ([#166](https://github.com/gotgenes/pi-packages/issues/166)) ([aff7b35](https://github.com/gotgenes/pi-packages/commit/aff7b35c98503fbb3da6a287631a2aa5c4d498fd))
+* **retro:** add planning stage notes for issue [#166](https://github.com/gotgenes/pi-packages/issues/166) ([6138473](https://github.com/gotgenes/pi-packages/commit/613847313d56a9df8b479726d831679391bd0c1a))
+* **retro:** add retro notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([2a3e70d](https://github.com/gotgenes/pi-packages/commit/2a3e70dc6b903b4c053e7f6ebc09169bc3e34bf6))
+* **retro:** add TDD stage notes for issue [#166](https://github.com/gotgenes/pi-packages/issues/166) ([2696da5](https://github.com/gotgenes/pi-packages/commit/2696da599de72f1a881577a4de8fedc57472a695))
+* update architecture doc — AgentSpawnConfig step 3 complete ([125450b](https://github.com/gotgenes/pi-packages/commit/125450ba9ea5753b4cad07ed4d1675dcdbc7e319))
+
+## [6.18.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.0...pi-subagents-v6.18.1) (2026-05-24)
+
+
+### Documentation
+
+* plan decompose ResolvedSpawnConfig ([#165](https://github.com/gotgenes/pi-packages/issues/165)) ([1b14d56](https://github.com/gotgenes/pi-packages/commit/1b14d56aaada427a7344ec22adb4bbf8d7ce0bf7))
+* **retro:** add planning stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([8e0476a](https://github.com/gotgenes/pi-packages/commit/8e0476afa991953884455c7dd09c7ffb742cb329))
+* **retro:** add TDD stage notes for issue [#165](https://github.com/gotgenes/pi-packages/issues/165) ([68248e5](https://github.com/gotgenes/pi-packages/commit/68248e572d38ad6e0cdb61bdd22f2b46193eaac6))
+
 ## [6.18.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.17.2...pi-subagents-v6.18.0) (2026-05-24)
 
 

package/docs/architecture/architecture.md

@@ -500,20 +500,20 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields    | Consumers                                         | Severity |
-| --------------------------- | --------- | ------------------------------------------------- | -------- |
-| `ResolvedSpawnConfig`       | 15        | foreground-runner, background-spawner, agent-tool | Critical |
-| `AgentSpawnConfig`          | 13        | agent-manager (internal)                          | Critical |
-| `RunOptions`                | 12        | agent-runner                                      | High     |
-| `SessionConfig`             | 11        | agent-runner (output of assembler)                | High     |
-| `NotificationDetails`       | 10        | notification                                      | Medium   |
-| `ResourceLoaderOptions`     | 10        | agent-runner (SDK bridge)                         | Medium   |
-| `RunnerIO`                  | 9 methods | agent-runner                                      | Medium   |
-| `CreateSessionOptions`      | 9         | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8         | agent-tool                                        | Low      |
-| `AgentMenuDeps`             | 8         | agent-menu                                        | Low      |
-| `ConversationViewerOptions` | 8         | conversation-viewer                               | Low      |
-| `AgentRecordInit`           | 8         | agent-record                                      | Low      |
+| Interface                   | Fields                             | Consumers                                         | Severity |
+| --------------------------- | ---------------------------------- | ------------------------------------------------- | -------- |
+| `ResolvedSpawnConfig`       | 3 nested                           | foreground-runner, background-spawner, agent-tool | ✓ done   |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested) | agent-manager (internal)                          | ✓ done   |
+| `RunOptions`                | 12                                 | agent-runner                                      | High     |
+| `SessionConfig`             | 11                                 | agent-runner (output of assembler)                | High     |
+| `NotificationDetails`       | 10                                 | notification                                      | Medium   |
+| `ResourceLoaderOptions`     | 10                                 | agent-runner (SDK bridge)                         | Medium   |
+| `RunnerIO`                  | 9 methods                          | agent-runner                                      | Medium   |
+| `CreateSessionOptions`      | 9                                  | agent-runner (SDK bridge)                         | Medium   |
+| `AgentToolDeps`             | 8                                  | agent-tool                                        | Low      |
+| `AgentMenuDeps`             | 8                                  | agent-menu                                        | Low      |
+| `ConversationViewerOptions` | 8                                  | conversation-viewer                               | Low      |
+| `AgentRecordInit`           | 8                                  | agent-record                                      | Low      |
 
 ### Complexity hotspots
 
@@ -586,20 +586,20 @@ interface SpawnPresentation {
 `agent-tool` uses all three to build the `AgentSpawnConfig` and the result text.
 After decomposition, each consumer declares its real dependencies explicitly.
 
-#### AgentSpawnConfig (13 fields → extract ParentSessionInfo)
+#### AgentSpawnConfig — ParentSessionInfo extracted (done, [#166][166])
 
-Several fields form a natural cluster around parent session identity:
+The `parentSessionFile`, `parentSessionId`, and `toolCallId` fields were grouped into `ParentSessionInfo`:
 
 ```typescript
-/** Parent session identity — always travel together. */
-interface ParentSessionInfo {
+/** Parent session identity — always travel together from the tool boundary. */
+export interface ParentSessionInfo {
   parentSessionFile?: string;
   parentSessionId?: string;
   toolCallId?: string;
 }
 ```
 
-Extracting this from `AgentSpawnConfig` reduces it from 13 to 10 fields and introduces a named concept that currently exists only as scattered optional fields.
+`AgentSpawnConfig` now carries `parentSession?: ParentSessionInfo` instead of three flat optional fields.
 
 #### RunOptions (12 fields → extract RunContext)
 
@@ -676,10 +676,10 @@ Split the 15-field bag into `SpawnIdentity`, `SpawnExecution`, and `SpawnPresent
 Each consumer declares its real dependencies.
 Enables Step 3 (narrowing AgentSpawnConfig, [#166][166]).
 
-### Step 3: Extract ParentSessionInfo from AgentSpawnConfig ([#166][166])
+### Step 3: Extract ParentSessionInfo from AgentSpawnConfig ([#166][166]) — Complete
 
-Extract `parentSessionFile`, `parentSessionId`, `toolCallId` into a `ParentSessionInfo` value object.
-Reduces AgentSpawnConfig from 13 to 10 fields.
+Extracted `parentSessionFile`, `parentSessionId`, `toolCallId` into `ParentSessionInfo`.
+`AgentSpawnConfig`, `BackgroundParams`, `ForegroundParams`, and `RunOptions` all carry the nested group.
 
 ### Step 4: Narrow RunnerIO ([#167][167])
 

package/docs/plans/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,157 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Decompose ResolvedSpawnConfig into domain-aligned sub-interfaces
+
+## Problem Statement
+
+`ResolvedSpawnConfig` in `tools/spawn-config.ts` has 15 fields mixing identity, execution, and presentation concerns.
+Each consumer uses a different subset but receives the full bag — violating ISP and making the real dependencies of `foreground-runner` and `background-spawner` invisible.
+
+## Goals
+
+- Split `ResolvedSpawnConfig` into three focused interfaces: `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`.
+- Each consumer declares its real dependencies explicitly.
+- Preserve existing behavior — pure structural refactor with no behavioral changes.
+
+## Non-Goals
+
+- Extracting `ParentSessionInfo` from `AgentSpawnConfig` — that's #166.
+- Changing how `resolveSpawnConfig` computes values internally.
+- Modifying the `AgentSpawnConfig` interface passed to `AgentManager`.
+
+## Background
+
+`resolveSpawnConfig` is called by `agent-tool.ts` and produces a single flat config object.
+Three consumers read from it:
+
+1. `agent-tool.ts` — reads `inheritContext` (to build snapshot), `runInBackground` (to branch), and `detailBase` (for resume result).
+2. `foreground-runner.ts` — reads identity fields for fallback messages, execution fields for spawn options, and `detailBase` for result formatting.
+3. `background-spawner.ts` — reads identity fields for launch message, execution fields for spawn options, and `detailBase` for result formatting.
+
+Two fields (`modelName`, `agentTags`) are never accessed by any external consumer — they're intermediate values used only inside `resolveSpawnConfig` to build `detailBase`.
+They belong on `SpawnPresentation` for transparency but could also be made internal-only.
+
+The `code-design` skill's ISP and dependency-width guidance both apply: clients should not depend on properties they don't use, and a shared bag where each consumer only touches a subset hides real dependencies.
+
+## Design Overview
+
+### New interfaces
+
+```typescript
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
+  subagentType: string;
+  rawType: SubagentType;
+  fellBack: boolean;
+  displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
+  prompt: string;
+  description: string;
+  model: Model<any> | undefined;
+  effectiveMaxTurns: number | undefined;
+  thinking: ThinkingLevel | undefined;
+  inheritContext: boolean;
+  runInBackground: boolean;
+  isolated: boolean;
+  isolation: IsolationMode | undefined;
+  agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity + execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
+  agentTags: string[];
+  detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
+}
+
+/** Fully resolved config — now a composition of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+```
+
+### Consumer interaction pattern
+
+```typescript
+// agent-tool.ts — uses execution for routing, presentation for resume
+const config = resolveSpawnConfig(params, registry, modelInfo, settings);
+if ("error" in config) return textResult(config.error);
+const snapshot = buildSnapshot(config.execution.inheritContext);
+if (config.execution.runInBackground) { /* ... */ }
+return buildDetails(config.presentation.detailBase, record);
+
+// foreground-runner.ts — destructures what it needs
+const { identity, execution, presentation } = params.config;
+record = await manager.spawnAndWait(snapshot, identity.subagentType, execution.prompt, { ... });
+const fallbackNote = identity.fellBack ? `Note: Unknown agent type "${identity.rawType}"...` : "";
+```
+
+This follows Tell-Don't-Ask — callers pick the sub-object relevant to their concern rather than reaching through a flat bag.
+The one-level nesting (`config.execution.inheritContext`) is acceptable because it names the domain the field belongs to.
+
+### Test factory migration
+
+Both test files (`foreground-runner.test.ts`, `background-spawner.test.ts`) have `makeConfig()` factories that construct the full 15-field flat object.
+These will be updated to construct the nested structure.
+The `spawn-config.test.ts` assertions will shift from `result.subagentType` to `result.identity.subagentType` etc.
+
+## Module-Level Changes
+
+| File                                    | Change                                                                                                                                                                          |
+| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src/tools/spawn-config.ts`             | Add `SpawnIdentity`, `SpawnExecution`, `SpawnPresentation` interfaces. Change `ResolvedSpawnConfig` to nest them. Update `resolveSpawnConfig` return to build nested structure. |
+| `src/tools/agent-tool.ts`               | Update config access: `config.execution.inheritContext`, `config.execution.runInBackground`, `config.presentation.detailBase`.                                                  |
+| `src/tools/foreground-runner.ts`        | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `src/tools/background-spawner.ts`       | Destructure `config` into `identity`, `execution`, `presentation`. Update all field accesses.                                                                                   |
+| `test/tools/spawn-config.test.ts`       | Update all assertions to use nested paths (`result.identity.subagentType`, etc.).                                                                                               |
+| `test/tools/foreground-runner.test.ts`  | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+| `test/tools/background-spawner.test.ts` | Update `makeConfig()` factory to build nested structure.                                                                                                                        |
+
+## Test Impact Analysis
+
+1. No new unit tests are needed — this is a structural refactor, not new behavior.
+2. No existing tests become redundant — all current `spawn-config.test.ts` assertions still verify the same computation.
+3. All existing tests must be updated to match the new nested access paths, but they continue to exercise the same logic.
+
+## TDD Order
+
+1. **Red→Green: introduce sub-interfaces and nest `ResolvedSpawnConfig`** — change `spawn-config.ts` to export the three sub-interfaces and restructure `ResolvedSpawnConfig`.
+   Update `resolveSpawnConfig` to return the nested shape.
+   Update `spawn-config.test.ts` assertions to match.
+   Commit: `refactor(pi-subagents): introduce SpawnIdentity, SpawnExecution, SpawnPresentation`
+
+2. **Green: update `agent-tool.ts`** — migrate the three field accesses (`inheritContext`, `runInBackground`, `detailBase`) to nested paths.
+   Run `pnpm run check` to confirm types pass.
+   Commit: `refactor(pi-subagents): update agent-tool to use nested spawn config`
+
+3. **Green: update `foreground-runner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `foreground-runner.test.ts`.
+   Commit: `refactor(pi-subagents): update foreground-runner to use nested spawn config`
+
+4. **Green: update `background-spawner.ts` and its test** — destructure config and update all field accesses.
+   Update `makeConfig()` factory in `background-spawner.test.ts`.
+   Commit: `refactor(pi-subagents): update background-spawner to use nested spawn config`
+
+5. **Verify: full suite** — run `pnpm vitest run` and `pnpm run check` to confirm no regressions.
+   Commit (if any lint/type cleanup needed): `chore(pi-subagents): post-decomposition cleanup`
+
+## Risks and Mitigations
+
+| Risk                                                           | Mitigation                                                                                                                                                   |
+| -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Step 1 breaks type checking for all consumers simultaneously   | Steps 2–4 must land in the same branch before pushing; or use a transitional type alias that spreads the sub-interfaces flat, removing it in the final step. |
+| Test factories diverge from production shape                   | Each step updates the test factory in the same commit as the source change.                                                                                  |
+| `modelName` and `agentTags` on `SpawnPresentation` look unused | They are unused by external consumers today but provide inspection affordance for debugging/logging. Keep them; #166 or later work may consume them.         |
+
+## Open Questions
+
+- None — the issue's proposed shape aligns with actual field usage patterns.
+  The only observation is that `modelName` and `agentTags` are only consumed internally, but exposing them on `SpawnPresentation` is harmless and aids debuggability.

package/docs/plans/0166-extract-parent-session-info.md

@@ -0,0 +1,231 @@
+---
+issue: 166
+issue_title: "refactor(pi-subagents): extract ParentSessionInfo from AgentSpawnConfig (13 fields)"
+---
+
+# Extract ParentSessionInfo from AgentSpawnConfig
+
+## Problem Statement
+
+`AgentSpawnConfig` in `agent-manager.ts` has 13 fields.
+Three of those fields — `parentSessionFile`, `parentSessionId`, and `toolCallId` — form a natural cluster around parent session identity.
+They always travel together through `agent-tool.ts` → `foreground-runner.ts` / `background-spawner.ts` → `AgentManager.spawn()`.
+Extracting them into a named value object reduces `AgentSpawnConfig` from 13 to 11 fields (10 + 1 nested) and introduces the `ParentSessionInfo` domain concept.
+
+## Goals
+
+- Extract `ParentSessionInfo` interface with `parentSessionFile`, `parentSessionId`, and `toolCallId`.
+- Replace the three flat optional fields on `AgentSpawnConfig` with a single optional `parentSession?: ParentSessionInfo` field.
+- Replace the flat fields on `BackgroundParams`, `ForegroundParams`, and `RunOptions` with the same grouped type.
+- Update all callers (agent-tool, foreground-runner, background-spawner, agent-manager, agent-runner) and their tests.
+- Non-breaking refactor — no public API changes (the `SubagentsService` boundary does not expose these fields).
+
+## Non-Goals
+
+- Changing the `NotificationState` or `notification` module — they remain as-is; `toolCallId` is just extracted from the group at the `AgentManager.spawn` boundary.
+- Further decomposition of `AgentSpawnConfig` (e.g., extracting execution or callback clusters) — tracked separately.
+- Modifying `session-dir.ts` or `deriveSubagentSessionDir` — the function signature stays the same; callers just unwrap `parentSession.parentSessionFile` before calling it.
+
+## Background
+
+Issue #165 (closed) decomposed `ResolvedSpawnConfig` into `SpawnIdentity`, `SpawnExecution`, and `SpawnPresentation`.
+This issue continues that structural improvement by grouping the parent-session fields that flow from `agent-tool.ts` through to `agent-runner.ts`.
+
+The three fields are:
+
+- `parentSessionFile` — path to the parent session's JSONL file, used by `deriveSubagentSessionDir` to place child sessions next to the parent.
+- `parentSessionId` — session ID of the parent agent, stored in the child session's `parentSession` header via `sessionManager.newSession()`.
+- `toolCallId` — tool call ID for background notification wiring; when set, `AgentManager.spawn` creates a `NotificationState`.
+
+All three originate in `agent-tool.ts`'s `execute` function and are threaded unchanged through intermediate modules.
+
+### Current flow
+
+```text
+agent-tool execute → getSessionInfo() + toolCallId param
+  → BackgroundParams { parentSessionFile, parentSessionId, toolCallId }
+  → spawnBackground → manager.spawn(opts: AgentSpawnConfig { ...flat fields })
+    → AgentManager.spawn → options.toolCallId → NotificationState
+    → startAgent → runner.run(RunOptions { parentSessionFile, parentSessionId })
+      → deriveSessionDir(parentSessionFile, ...)
+      → sessionManager.newSession({ parentSession: parentSessionId })
+
+  → ForegroundParams { parentSessionFile, parentSessionId }
+  → runForeground → manager.spawnAndWait(opts: AgentSpawnConfig { ...flat fields })
+    → (same AgentManager path)
+```
+
+### After extraction
+
+```text
+agent-tool execute → getSessionInfo() + toolCallId param
+  → parentSession: ParentSessionInfo { parentSessionFile, parentSessionId, toolCallId }
+  → BackgroundParams { parentSession }
+  → spawnBackground → manager.spawn(opts: AgentSpawnConfig { parentSession })
+    → AgentManager.spawn → parentSession.toolCallId → NotificationState
+    → startAgent → runner.run(RunOptions { parentSession })
+      → deriveSessionDir(parentSession?.parentSessionFile, ...)
+      → sessionManager.newSession({ parentSession: parentSession?.parentSessionId })
+
+  → ForegroundParams { parentSession }
+  → runForeground → manager.spawnAndWait(opts: AgentSpawnConfig { parentSession })
+    → (same AgentManager path)
+```
+
+## Design Overview
+
+### `ParentSessionInfo` interface
+
+```typescript
+export interface ParentSessionInfo {
+  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+  parentSessionFile?: string;
+  /** Session ID of the parent agent (stored in the child session's parentSession header). */
+  parentSessionId?: string;
+  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
+  toolCallId?: string;
+}
+```
+
+All three fields remain optional — they are only available when spawning from an active session (the `SubagentsService` boundary omits them entirely).
+
+The interface lives in `lifecycle/agent-manager.ts` alongside `AgentSpawnConfig` since that is the primary consumer.
+If a future refactoring moves `AgentSpawnConfig` to its own file, `ParentSessionInfo` should move with it.
+
+### Consumer call-site sketch
+
+```typescript
+// agent-tool.ts execute():
+const parentSession: ParentSessionInfo = {
+  parentSessionFile: sessionInfo.parentSessionFile,
+  parentSessionId: sessionInfo.parentSessionId,
+  toolCallId,
+};
+// ...
+spawnBackground(manager, widget, agentActivity, { config, snapshot, parentSession });
+```
+
+The grouped object eliminates the three-field spread that was repeated in both `spawnBackground` and `runForeground` call sites.
+
+### `AgentSpawnConfig` change
+
+```typescript
+export interface AgentSpawnConfig {
+  // ... existing fields (description, model, maxTurns, etc.)
+  /** Parent session identity — grouped fields that travel together from the tool boundary. */
+  parentSession?: ParentSessionInfo;
+  // Remove: parentSessionFile, parentSessionId, toolCallId
+}
+```
+
+### `RunOptions` change
+
+```typescript
+export interface RunOptions {
+  // ... existing fields
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
+  // Remove: parentSessionFile, parentSessionId
+}
+```
+
+Note: `RunOptions` does not use `toolCallId` — it was never threaded to the runner.
+The runner only reads `parentSessionFile` and `parentSessionId` from the group.
+
+### `getSessionInfo` return type update
+
+The `getSessionInfo` callback in `AgentToolDeps` currently returns `{ parentSessionFile: string; parentSessionId: string }`.
+It should remain unchanged — it does not include `toolCallId` (which comes from the `execute` callback's first argument).
+The `agent-tool.ts` execute function constructs a `ParentSessionInfo` by merging `getSessionInfo()` output with `toolCallId`.
+
+## Module-Level Changes
+
+### New types
+
+1. `src/lifecycle/agent-manager.ts` — add `ParentSessionInfo` interface (exported).
+
+### Modified interfaces
+
+1. `src/lifecycle/agent-manager.ts` — `AgentSpawnConfig`: replace `parentSessionFile?`, `parentSessionId?`, `toolCallId?` with `parentSession?: ParentSessionInfo`.
+2. `src/lifecycle/agent-runner.ts` — `RunOptions`: replace `parentSessionFile?`, `parentSessionId?` with `parentSession?: ParentSessionInfo`.
+3. `src/tools/background-spawner.ts` — `BackgroundParams`: replace `parentSessionFile`, `parentSessionId`, `toolCallId` with `parentSession: ParentSessionInfo`.
+4. `src/tools/foreground-runner.ts` — `ForegroundParams`: replace `parentSessionFile`, `parentSessionId` with `parentSession: ParentSessionInfo`.
+
+### Modified implementations
+
+1. `src/lifecycle/agent-manager.ts` — `AgentManager.spawn()`: read `options.parentSession?.toolCallId` instead of `options.toolCallId`; pass `parentSession` to `RunOptions`.
+2. `src/lifecycle/agent-runner.ts` — `runAgent()`: read `options.parentSession?.parentSessionFile` and `options.parentSession?.parentSessionId`.
+3. `src/tools/agent-tool.ts` — `createAgentTool` execute: construct `ParentSessionInfo` from `getSessionInfo()` + `toolCallId`, pass as `parentSession` to both spawners.
+4. `src/tools/background-spawner.ts` — `spawnBackground()`: read `params.parentSession` and pass fields to `AgentSpawnConfig`.
+5. `src/tools/foreground-runner.ts` — `runForeground()`: read `params.parentSession` and pass fields to `AgentSpawnConfig`.
+
+### No changes needed
+
+- `src/tools/agent-tool.ts` — `AgentToolDeps.getSessionInfo` return type stays the same.
+- `src/session/session-dir.ts` — `deriveSubagentSessionDir` signature unchanged.
+- `src/observation/notification-state.ts` — constructor signature unchanged.
+- `src/service/service-adapter.ts` — does not pass parent session fields.
+- `src/index.ts` — `getSessionInfo` callback unchanged.
+
+## Test Impact Analysis
+
+### New tests enabled
+
+No new unit tests are enabled — this is a structural grouping, not new behavior.
+
+### Existing tests that need updates
+
+1. `test/lifecycle/agent-manager.test.ts` — update spawn calls from flat `parentSessionFile`/`parentSessionId`/`toolCallId` to nested `parentSession: { ... }` form; update assertions to read from `parentSession`.
+2. `test/lifecycle/agent-runner.test.ts` — update `RunOptions` construction from flat to nested `parentSession`.
+3. `test/tools/agent-tool.test.ts` — update assertion checking `toolCallId` on spawn opts to check `parentSession.toolCallId`.
+4. `test/tools/background-spawner.test.ts` — update `makeParams` factory from flat fields to `parentSession: { ... }`.
+5. `test/tools/foreground-runner.test.ts` — update params construction from flat fields to `parentSession: { ... }`.
+6. `test/helpers/make-deps.ts` — `getSessionInfo` mock stays unchanged (returns flat `{ parentSessionFile, parentSessionId }`).
+
+### Tests that stay as-is
+
+- `test/session/session-dir.test.ts` — tests `deriveSubagentSessionDir` directly, no interface change.
+- `test/observation/notification-state.test.ts` — tests `NotificationState` constructor directly.
+- `test/observation/notification.test.ts` — tests notification formatting with `record.notification`, not spawn config.
+
+## TDD Order
+
+1. **Define `ParentSessionInfo` and update `AgentSpawnConfig`** — add interface, replace three flat fields with `parentSession?`.
+   Update `AgentManager.spawn` and `startAgent` to read from the nested group.
+   Update `agent-manager.test.ts` to use nested form.
+   Run `pnpm run check` to verify no downstream type errors remain.
+   Commit: `refactor: define ParentSessionInfo and nest in AgentSpawnConfig`
+
+2. **Update `RunOptions` in `agent-runner.ts`** — replace flat `parentSessionFile?`/`parentSessionId?` with `parentSession?`.
+   Update `runAgent` to read `options.parentSession?.parentSessionFile` and `options.parentSession?.parentSessionId`.
+   Update `agent-runner.test.ts`.
+   Commit: `refactor: nest ParentSessionInfo in RunOptions`
+
+3. **Update `BackgroundParams` and `spawnBackground`** — replace three flat fields with `parentSession: ParentSessionInfo`.
+   Update `spawnBackground` to pass `parentSession` to spawn opts.
+   Update `background-spawner.test.ts`.
+   Commit: `refactor: nest ParentSessionInfo in BackgroundParams`
+
+4. **Update `ForegroundParams` and `runForeground`** — replace two flat fields with `parentSession: ParentSessionInfo`.
+   Update `runForeground` to pass `parentSession` to spawn opts.
+   Update `foreground-runner.test.ts`.
+   Commit: `refactor: nest ParentSessionInfo in ForegroundParams`
+
+5. **Update `agent-tool.ts` execute** — construct `ParentSessionInfo` from `getSessionInfo()` + `toolCallId`, pass as `parentSession` to both spawner call sites.
+   Update `agent-tool.test.ts`.
+   Commit: `refactor: construct ParentSessionInfo in agent-tool execute`
+
+6. **Final verification** — run full test suite (`pnpm vitest run`) and type check (`pnpm run check`).
+   No separate commit unless adjustments are needed.
+
+## Risks and Mitigations
+
+| Risk                                                                                                          | Mitigation                                                                                                                           |
+| ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| Deep-merge trap: test factories using `Partial<BackgroundParams>` spread may silently ignore nested overrides | Audit `makeParams` in `background-spawner.test.ts` — convert from flat-field spread to nested `parentSession` construction           |
+| `toolCallId` conditionally absent for foreground calls                                                        | `ParentSessionInfo.toolCallId` is optional; `ForegroundParams.parentSession` includes it but won't set it — matches current behavior |
+| Type check passes but runtime breaks due to nested access on undefined                                        | `parentSession?` is optional on `AgentSpawnConfig`; all reads use optional chaining (`options.parentSession?.toolCallId`)            |
+
+## Open Questions
+
+None — the extraction is mechanical and the issue description is unambiguous.

package/docs/retro/0165-decompose-resolved-spawn-config.md

@@ -0,0 +1,78 @@
+---
+issue: 165
+issue_title: "refactor(pi-subagents): decompose ResolvedSpawnConfig (15 fields)"
+---
+
+# Retro: #165 — decompose ResolvedSpawnConfig (15 fields)
+
+## Stage: Planning (2026-05-24T13:41:41Z)
+
+### Session summary
+
+Produced a 5-step TDD plan to decompose the 15-field `ResolvedSpawnConfig` into three nested sub-interfaces (`SpawnIdentity`, `SpawnExecution`, `SpawnPresentation`).
+Also improved skill descriptions for `colgrep` and `markdown-conventions` to signal decision-relevant content rather than tool reference material.
+
+### Observations
+
+- The proposed decomposition in the issue aligns well with actual field usage patterns — no adjustments needed.
+- `modelName` and `agentTags` are never accessed by external consumers; they're intermediate computation exposed on the return type.
+  Keeping them on `SpawnPresentation` is harmless and aids debuggability.
+- Step 1 (interface change + return restructure) will break type checking for all consumers simultaneously.
+  The plan addresses this by landing steps 1–4 in rapid succession on the same branch.
+- Both test files have `makeConfig()` factories that must be updated in lock-step with their respective source files.
+- Issue #164 (directory reorganization) is closed, so import paths are already in their final `#src/<domain>/` form.
+
+## Stage: Implementation — TDD (2026-05-24T14:32:58Z)
+
+### Session summary
+
+Completed all 4 TDD cycles plus full-suite verification in one session.
+The decomposition touched 7 files (4 source, 3 test) and kept the test count flat at 805 — no new tests needed for a pure structural refactor.
+
+### Observations
+
+- The `Partial<ResolvedSpawnConfig>` spread pattern in `makeConfig` factories doesn't deep-merge into nested sub-objects.
+  Two tests (`foreground-runner.test.ts` and `background-spawner.test.ts`) used flat field overrides (`{ fellBack: true }`, `{ description: "my task" }`) that silently stopped working after nesting.
+  Fixed by writing out the full nested sub-object at the override call site.
+  Future factories for nested config types should either deep-merge or avoid the `Partial<T>` spread pattern — see the `testing` skill's warning about this.
+- Step 1 breaking all consumers simultaneously was handled smoothly by completing all steps before pushing, as planned.
+  No transitional alias was needed.
+- The `background-spawner.test.ts` description-override test was the only unexpected friction point — the flat spread issue wasn't caught by the plan.
+
+## Stage: Final Retrospective (2026-05-24T15:00:14Z)
+
+### Session summary
+
+Shipped issue #165 (CI green, released as `pi-subagents-v6.18.1`) and ran the final retrospective.
+The most impactful outcome across all three sessions was the skill description improvements (commit `51f52ef`), which addressed a recurring `instruction-violation` pattern.
+
+### Observations
+
+#### What went well
+
+- The user's probing question ("This is consistent, though.
+  Why?") turned a simple skill-loading skip into a generalizable improvement to three skill descriptions and two prompt instructions.
+  This is a good example of the user investing a redirecting question instead of a correction.
+- TDD execution was clean — 4 cycles, no rework, no type errors at the end.
+  The plan's risk mitigation ("land steps 1–4 on the same branch") worked as intended.
+- Ship stage had zero friction: push, CI, close, release-please merge, tag — all first-try.
+
+#### What caused friction (agent side)
+
+- `instruction-violation` — Skipped loading the `colgrep` skill during planning despite explicit instructions.
+  Root cause: skill descriptions that read like tool reference manuals get deprioritized because the agent perceives them as redundant with the tool schema already in context.
+  Impact: no rework on the plan itself, but triggered a productive detour to improve skill descriptions.
+  User-caught.
+- `missing-context` — The plan didn't anticipate that `Partial<ResolvedSpawnConfig>` spread in test factories would silently break after nesting.
+  The `testing` skill already warns about spread-related pitfalls, but not this specific variant (flat keys ignored by top-level spread on a nested structure).
+  Impact: one test failure during step 4 that required a verbose inline fix (writing out the full `execution` sub-object).
+  Self-identified during implementation.
+
+#### What caused friction (user side)
+
+- None observed.
+  The user's intervention on the `colgrep` skill was well-timed and produced a higher-value outcome than skipping it would have.
+
+### Changes made
+
+1. Added a TDD planning rule to `.pi/skills/testing/SKILL.md` warning about `Partial<T>` spread not deep-merging into nested interfaces after a flat-to-nested refactor.

package/docs/retro/0166-extract-parent-session-info.md

@@ -0,0 +1,39 @@
+---
+issue: 166
+issue_title: "refactor(pi-subagents): extract ParentSessionInfo from AgentSpawnConfig (13 fields)"
+---
+
+# Retro: #166 — Extract ParentSessionInfo from AgentSpawnConfig
+
+## Stage: Planning (2026-05-24T16:00:00Z)
+
+### Session summary
+
+Produced a 6-step TDD plan to extract `ParentSessionInfo` from `AgentSpawnConfig`.
+The refactoring groups three co-traveling fields (`parentSessionFile`, `parentSessionId`, `toolCallId`) into a named value object, reducing `AgentSpawnConfig` from 13 to 11 fields.
+
+### Observations
+
+- The `SubagentsService` boundary (`service-adapter.ts`) does not pass any of the three fields, so this is a purely internal refactoring with no public API impact.
+- `getSessionInfo` in `AgentToolDeps` returns only `parentSessionFile` and `parentSessionId`; `toolCallId` comes from the `execute` callback's first argument — the plan keeps this separation and merges them at the `agent-tool.ts` boundary.
+- `RunOptions` in `agent-runner.ts` never carried `toolCallId` (it was consumed in `AgentManager.spawn` before reaching the runner), so the nested `parentSession` on `RunOptions` only holds the two session fields.
+- The deep-merge trap from the testing skill is relevant: `background-spawner.test.ts` has a `makeParams` factory that spreads flat fields — must be converted to nested `parentSession` construction.
+- Issue #165 (decompose `ResolvedSpawnConfig`) is closed, so this plan builds on stable ground.
+
+## Stage: Implementation — TDD (2026-05-24T17:00:00Z)
+
+### Session summary
+
+All 5 TDD cycles completed across `agent-manager.ts`, `agent-runner.ts`, `background-spawner.ts`, `foreground-runner.ts`, and `agent-tool.ts`.
+Test count held steady at 805 (no net new tests — refactor only).
+Type check and lint both clean after all steps.
+
+### Observations
+
+- The `AgentSpawnConfig` field count went from 15 to 13 (not 13 → 10 as originally estimated) — the architecture doc quoted the issue's stale count; the actual pre-refactor interface had 15 fields (`bypassQueue` and others were already present).
+  The architecture doc was updated to reflect "done" with a note about the nested group rather than a specific before/after number.
+- The deep-merge trap (noted in planning) did materialise: `background-spawner.test.ts`'s `makeParams` spread `Partial<BackgroundParams>` with flat fields.
+  Fixed by replacing the three flat fields with a single `parentSession` object at the factory level — top-level spread still works correctly since `parentSession` is one field.
+- `RunOptions` in `agent-runner.ts` needed a new import of `ParentSessionInfo` from `agent-manager.ts`; no circular dependency since `agent-runner.ts` already imports from `agent-manager.ts`.
+- `agent-tool.ts` still imports `AgentSpawnConfig` (needed by `AgentToolManager` interface) — the new `ParentSessionInfo` import was added alongside it.
+- All 5 commits are clean `refactor:` messages; architecture doc update is a separate `docs:` commit.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.18.0",
+  "version": "6.18.2",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-manager.ts

@@ -53,6 +53,15 @@ interface SpawnArgs {
   options: AgentSpawnConfig;
 }
 
+export interface ParentSessionInfo {
+  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
+  parentSessionFile?: string;
+  /** Session ID of the parent agent (stored in the child session's parentSession header). */
+  parentSessionId?: string;
+  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
+  toolCallId?: string;
+}
+
 export interface AgentSpawnConfig {
   description: string;
   model?: Model<any>;
@@ -75,12 +84,8 @@ export interface AgentSpawnConfig {
   signal?: AbortSignal;
   /** Called when the agent session is created — receives the session and the agent's record. */
   onSessionCreated?: (session: AgentSession, record: AgentRecord) => void;
-  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
-  parentSessionFile?: string;
-  /** Session ID of the parent agent (stored in the child session's parentSession header). */
-  parentSessionId?: string;
-  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
-  toolCallId?: string;
+  /** Parent session identity — grouped fields that travel together from the tool boundary. */
+  parentSession?: ParentSessionInfo;
 }
 
 export class AgentManager {
@@ -158,8 +163,8 @@ export class AgentManager {
     });
     this.agents.set(id, record);
 
-    if (options.toolCallId) {
-      record.notification = new NotificationState(options.toolCallId);
+    if (options.parentSession?.toolCallId) {
+      record.notification = new NotificationState(options.parentSession.toolCallId);
     }
 
     if (options.isBackground) {
@@ -228,8 +233,7 @@ export class AgentManager {
       isolated: options.isolated,
       thinkingLevel: options.thinkingLevel,
       cwd: worktreeCwd,
-      parentSessionFile: options.parentSessionFile,
-      parentSessionId: options.parentSessionId,
+      parentSession: options.parentSession,
       signal: record.abortController!.signal,
       registry: this.registry,
       onSessionCreated: (session) => {

package/src/lifecycle/agent-runner.ts

@@ -9,6 +9,7 @@ import {
   type SettingsManager,
 } from "@earendil-works/pi-coding-agent";
 import type { AgentConfigLookup } from "#src/config/agent-types";
+import type { ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { extractText } from "#src/session/context";
 import type { EnvInfo } from "#src/session/env";
@@ -146,10 +147,8 @@ export interface RunOptions {
   thinkingLevel?: ThinkingLevel;
   /** Override working directory (e.g. for worktree isolation). */
   cwd?: string;
-  /** Path to the parent session's JSONL file (for deriving the subagent session directory). */
-  parentSessionFile?: string;
-  /** Session ID of the parent agent (stored in the child session's parentSession header). */
-  parentSessionId?: string;
+  /** Parent session identity (file path + session ID). */
+  parentSession?: ParentSessionInfo;
   /** Called once after session creation — session delivery mechanism. */
   onSessionCreated?: (session: AgentSession) => void;
   /**
@@ -308,9 +307,9 @@ export async function runAgent(
   // Create a persisted SessionManager so transcripts are written in Pi's
   // official JSONL format. Falls back to a temp directory when the parent
   // session is not persisted (e.g. headless/API mode).
-  const sessionDir = io.deriveSessionDir(options.parentSessionFile, cfg.effectiveCwd);
+  const sessionDir = io.deriveSessionDir(options.parentSession?.parentSessionFile, cfg.effectiveCwd);
   const sessionManager = io.createSessionManager(cfg.effectiveCwd, sessionDir);
-  sessionManager.newSession({ parentSession: options.parentSessionId });
+  sessionManager.newSession({ parentSession: options.parentSession?.parentSessionId });
 
   const { session } = await io.createSession({
     cwd: cfg.effectiveCwd,

package/src/tools/agent-tool.ts

@@ -3,7 +3,7 @@ import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentTypeRegistry } from "#src/config/agent-types";
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import { spawnBackground } from "#src/tools/background-spawner";
 import { runForeground } from "#src/tools/foreground-runner";
@@ -301,8 +301,9 @@ Guidelines:
       if ("error" in config) return textResult(config.error);
 
       // ---- Boundary extraction (after config so inheritContext is resolved) ----
-      const snapshot = buildSnapshot(config.inheritContext);
+      const snapshot = buildSnapshot(config.execution.inheritContext);
       const { parentSessionFile, parentSessionId } = getSessionInfo();
+      const parentSession: ParentSessionInfo = { parentSessionFile, parentSessionId, toolCallId };
 
       // ---- Resume existing agent ----
       if (params.resume) {
@@ -327,17 +328,17 @@ Guidelines:
         }
         return textResult(
           record.result?.trim() ?? record.error?.trim() ?? "No output.",
-          buildDetails(config.detailBase, record),
+          buildDetails(config.presentation.detailBase, record),
         );
       }
 
       // ---- Background execution ----
-      if (config.runInBackground) {
+      if (config.execution.runInBackground) {
         return spawnBackground(
           manager,
           widget,
           agentActivity,
-          { config, snapshot, parentSessionFile, parentSessionId, toolCallId },
+          { config, snapshot, parentSession },
         );
       }
 
@@ -346,7 +347,7 @@ Guidelines:
         manager,
         widget,
         agentActivity,
-        { config, snapshot, parentSessionFile, parentSessionId },
+        { config, snapshot, parentSession },
         signal,
         onUpdate,
       );

package/src/tools/background-spawner.ts

@@ -1,4 +1,4 @@
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import { textResult } from "#src/tools/helpers";
@@ -24,9 +24,7 @@ export interface BackgroundWidgetDeps {
 export interface BackgroundParams {
   config: ResolvedSpawnConfig;
   snapshot: ParentSnapshot;
-  parentSessionFile: string;
-  parentSessionId: string;
-  toolCallId: string;
+  parentSession: ParentSessionInfo;
 }
 
 /**
@@ -40,24 +38,22 @@ export function spawnBackground(
   agentActivity: AgentActivityAccess,
   params: BackgroundParams,
 ) {
-  const { config } = params;
-  const bgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const { identity, execution, presentation } = params.config;
+  const bgState = new AgentActivityTracker(execution.effectiveMaxTurns);
 
   let id: string;
   try {
-    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,
+    id = manager.spawn(params.snapshot, identity.subagentType, execution.prompt, {
+      parentSession: params.parentSession,
+      description: execution.description,
+      model: execution.model,
+      maxTurns: execution.effectiveMaxTurns,
+      isolated: execution.isolated,
+      inheritContext: execution.inheritContext,
+      thinkingLevel: execution.thinking,
       isBackground: true,
-      isolation: config.isolation,
-      invocation: config.agentInvocation,
-      toolCallId: params.toolCallId,
+      isolation: execution.isolation,
+      invocation: execution.agentInvocation,
       onSessionCreated: (session) => {
         bgState.setSession(session);
         subscribeUIObserver(session, bgState);
@@ -77,8 +73,8 @@ export function spawnBackground(
   return textResult(
     `Agent ${isQueued ? "queued" : "started"} in background.\n` +
       `Agent ID: ${id}\n` +
-      `Type: ${config.displayName}\n` +
-      `Description: ${config.description}\n` +
+      `Type: ${identity.displayName}\n` +
+      `Description: ${execution.description}\n` +
       (record?.outputFile ? `Output file: ${record.outputFile}\n` : "") +
       (isQueued
         ? `Position: queued (max ${manager.getMaxConcurrent()} concurrent)\n`
@@ -87,7 +83,7 @@ export function spawnBackground(
       `Use get_subagent_result to retrieve full results, or steer_subagent to send it messages.\n` +
       `Do not duplicate this agent's work.`,
     {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses: 0,
       tokens: "",
       durationMs: 0,

package/src/tools/foreground-runner.ts

@@ -1,5 +1,5 @@
 import type { AgentToolResult } from "@earendil-works/pi-coding-agent";
-import type { AgentSpawnConfig } from "#src/lifecycle/agent-manager";
+import type { AgentSpawnConfig, ParentSessionInfo } from "#src/lifecycle/agent-manager";
 import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
 import type { AgentActivityAccess } from "#src/tools/agent-tool";
 import {
@@ -39,8 +39,7 @@ export interface ForegroundWidgetDeps {
 export interface ForegroundParams {
   config: ResolvedSpawnConfig;
   snapshot: ParentSnapshot;
-  parentSessionFile: string;
-  parentSessionId: string;
+  parentSession: ParentSessionInfo;
 }
 
 /**
@@ -56,19 +55,19 @@ export async function runForeground(
   signal: AbortSignal | undefined,
   onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
 ) {
-  const { config } = params;
+  const { identity, execution, presentation } = params.config;
   let spinnerFrame = 0;
   const startedAt = Date.now();
   let fgId: string | undefined;
 
-  const fgState = new AgentActivityTracker(config.effectiveMaxTurns);
+  const fgState = new AgentActivityTracker(execution.effectiveMaxTurns);
   let unsubUI: (() => void) | undefined;
   let recordRef: AgentRecord | undefined;
 
   const streamUpdate = () => {
     const toolUses = recordRef?.toolUses ?? 0;
     const details: AgentDetails = {
-      ...config.detailBase,
+      ...presentation.detailBase,
       toolUses,
       tokens: recordRef ? formatLifetimeTokens(recordRef) : "",
       turnCount: fgState.turnCount,
@@ -97,20 +96,19 @@ export async function runForeground(
   try {
     record = await manager.spawnAndWait(
       params.snapshot,
-      config.subagentType,
-      config.prompt,
+      identity.subagentType,
+      execution.prompt,
       {
-        description: config.description,
-        model: config.model,
-        maxTurns: config.effectiveMaxTurns,
-        isolated: config.isolated,
-        inheritContext: config.inheritContext,
-        thinkingLevel: config.thinking,
-        isolation: config.isolation,
-        invocation: config.agentInvocation,
+        description: execution.description,
+        model: execution.model,
+        maxTurns: execution.effectiveMaxTurns,
+        isolated: execution.isolated,
+        inheritContext: execution.inheritContext,
+        thinkingLevel: execution.thinking,
+        isolation: execution.isolation,
+        invocation: execution.agentInvocation,
         signal,
-        parentSessionFile: params.parentSessionFile,
-        parentSessionId: params.parentSessionId,
+        parentSession: params.parentSession,
         onSessionCreated: (session, record) => {
           fgState.setSession(session);
           recordRef = record;
@@ -137,10 +135,10 @@ export async function runForeground(
   }
 
   const tokenText = formatLifetimeTokens(record);
-  const details = buildDetails(config.detailBase, record, fgState, { tokens: tokenText });
+  const details = buildDetails(presentation.detailBase, record, fgState, { tokens: tokenText });
 
-  const fallbackNote = config.fellBack
-    ? `Note: Unknown agent type "${config.rawType}" — using general-purpose.\n\n`
+  const fallbackNote = identity.fellBack
+    ? `Note: Unknown agent type "${identity.rawType}" — using general-purpose.\n\n`
     : "";
 
   if (record.status === "error") {

package/src/tools/spawn-config.ts

@@ -26,12 +26,16 @@ export interface ModelInfo {
   modelRegistry: unknown;
 }
 
-/** Fully resolved config for spawning an agent. */
-export interface ResolvedSpawnConfig {
+/** Identity: who is being spawned. */
+export interface SpawnIdentity {
   subagentType: string;
   rawType: SubagentType;
   fellBack: boolean;
   displayName: string;
+}
+
+/** Execution: how the agent will run. */
+export interface SpawnExecution {
   prompt: string;
   description: string;
   model: Model<any> | undefined;
@@ -41,12 +45,23 @@ export interface ResolvedSpawnConfig {
   runInBackground: boolean;
   isolated: boolean;
   isolation: IsolationMode | undefined;
-  modelName: string | undefined;
   agentInvocation: AgentInvocation;
+}
+
+/** Presentation: display/UI values derived from identity and execution. */
+export interface SpawnPresentation {
+  modelName: string | undefined;
   agentTags: string[];
   detailBase: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">;
 }
 
+/** Fully resolved config for spawning an agent — composed of domain-aligned sub-interfaces. */
+export interface ResolvedSpawnConfig {
+  identity: SpawnIdentity;
+  execution: SpawnExecution;
+  presentation: SpawnPresentation;
+}
+
 /** Error result when model resolution fails. */
 export interface SpawnConfigError {
   error: string;
@@ -126,22 +141,19 @@ export function resolveSpawnConfig(
   };
 
   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,
+    identity: { subagentType, rawType, fellBack, displayName },
+    execution: {
+      prompt: params.prompt as string,
+      description: params.description as string,
+      model,
+      effectiveMaxTurns,
+      thinking,
+      inheritContext,
+      runInBackground,
+      isolated,
+      isolation,
+      agentInvocation,
+    },
+    presentation: { modelName, agentTags, detailBase },
   };
 }