@gotgenes/pi-subagents 6.9.0 → 6.9.2

package/CHANGELOG.md

@@ -5,6 +5,24 @@ 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.9.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.1...pi-subagents-v6.9.2) (2026-05-22)
+
+
+### Documentation
+
+* mark E2 type housekeeping done in architecture ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([89f18a8](https://github.com/gotgenes/pi-packages/commit/89f18a82fac39b4a62be8e440355b859afaa6d2f))
+* plan type housekeeping and small structural cleanups ([#116](https://github.com/gotgenes/pi-packages/issues/116)) ([e1cbd26](https://github.com/gotgenes/pi-packages/commit/e1cbd269961a1bff3b11e2e916733a79c39a087d))
+* **retro:** add retro notes for issue [#115](https://github.com/gotgenes/pi-packages/issues/115) ([05b8809](https://github.com/gotgenes/pi-packages/commit/05b88093f7b70ea886b6c7cb5f0cc96161a95df6))
+
+## [6.9.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.9.0...pi-subagents-v6.9.1) (2026-05-22)
+
+
+### Documentation
+
+* plan decompose agent-tool.ts into foreground/background modules ([#115](https://github.com/gotgenes/pi-packages/issues/115)) ([4b9aefb](https://github.com/gotgenes/pi-packages/commit/4b9aefb18fe0431a033d90f10bcbe7d37c53a6b8))
+* **retro:** add retro notes for issue [#114](https://github.com/gotgenes/pi-packages/issues/114) ([e6095e7](https://github.com/gotgenes/pi-packages/commit/e6095e7465f482ac18756305b9740f1101dbd41a))
+* update architecture for E1 agent-tool decomposition ([#115](https://github.com/gotgenes/pi-packages/issues/115)) ([8bccf0a](https://github.com/gotgenes/pi-packages/commit/8bccf0ab90787d906c82c5a362c0763d3b7bd2f5))
+
 ## [6.9.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.8.3...pi-subagents-v6.9.0) (2026-05-22)
 
 

package/docs/architecture/architecture.md

@@ -54,10 +54,12 @@ settings.ts               — persistent operational settings; `SettingsManager`
 service.ts                — SubagentsService interface + Symbol.for() accessors
 service-adapter.ts        — SubagentsService implementation wrapping AgentManager
 
-tools/agent-tool.ts       — Agent tool definition + execute
-tools/get-result-tool.ts  — get_subagent_result tool
-tools/steer-tool.ts       — steer_subagent tool
-tools/helpers.ts          — shared tool utilities
+tools/agent-tool.ts          — Agent tool definition, parameter validation, dispatch
+tools/foreground-runner.ts   — foreground execution loop (spinner, streaming, result)
+tools/background-spawner.ts  — background spawn (activity setup, notification wiring)
+tools/get-result-tool.ts     — get_subagent_result tool
+tools/steer-tool.ts          — steer_subagent tool
+tools/helpers.ts             — shared tool utilities (textResult, buildDetails, getStatusNote, …)
 
 handlers/lifecycle.ts     — session_start, session_before_switch, session_shutdown
 handlers/tool-start.ts    — tool_execution_start handler
@@ -259,10 +261,12 @@ src/
 ├── index.ts                  — slimmed entry point: init, tool registration
 ├── runtime.ts                — SubagentRuntime: session-scoped state + methods
 ├── tools/
-│   ├── agent-tool.ts         — Agent tool definition + execute
+│   ├── agent-tool.ts         — Agent tool definition, parameter validation, dispatch
+│   ├── foreground-runner.ts  — foreground execution loop (spinner, streaming, result)
+│   ├── background-spawner.ts — background spawn (activity setup, notification wiring)
 │   ├── get-result-tool.ts    — get_subagent_result tool
 │   ├── steer-tool.ts         — steer_subagent tool
-│   └── helpers.ts            — shared tool utilities
+│   └── helpers.ts            — shared tool utilities (textResult, buildDetails, getStatusNote, …)
 ├── handlers/
 │   ├── lifecycle.ts          — session_start, session_before_switch, session_shutdown
 │   └── tool-start.ts         — tool_execution_start handler
@@ -380,13 +384,13 @@ Each step is sequenced so it makes the next step easier.
 | Smell                          | Location                                     | Evidence                                                                                                                                                                          |
 | ------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | ~~Global mutable state~~       | ~~`agent-types.ts`~~                         | **Fixed #108**: `AgentTypeRegistry` class; `reloadCustomAgents` callback removed from `AgentToolDeps` and `AgentMenuDeps`                                                         |
-| Closure bag as class           | `createNotificationSystem()`                 | Returns 4 functions sharing closure state (`pendingNudges`, timers)                                                                                                               |
+| ~~Closure bag as class~~       | ~~`createNotificationSystem()`~~             | **Fixed #116**: `NotificationManager` class; `pendingNudges` and timer state are private fields                                                                                   |
 | ~~Mutable state bag~~          | ~~`AgentActivity` (7 fields)~~               | **Fixed #110**: `AgentActivityTracker` class; `ui-observer.ts` calls transition methods; widget, notification, agent-tool use read-only accessors                                 |
 | ~~Settings relay~~             | ~~`AgentMenuDeps` (13 fields)~~              | **Fixed #109**: `SettingsManager` class; 6 callback fields collapsed to `settings: SettingsManager`; `AgentMenuDeps` now 8 fields                                                 |
 | ~~Post-construction mutation~~ | ~~`AgentRecord` non-transition state~~       | **Fixed #111**: `ExecutionState`, `WorktreeState`, `NotificationState` collaborators; `pendingSteers` moved to `AgentManager`; stats encapsulated behind mutation methods         |
 | ~~Fire-and-forget callbacks~~  | ~~`AgentManagerOptions`~~                    | **Fixed #112**: `AgentManagerObserver` interface; `observer` replaces 3 callbacks; `index.ts` constructs one observer object instead of 3 closure lambdas                         |
 | ~~Duplicate `SpawnOptions`~~   | ~~`service.ts` + `agent-manager.ts`~~        | **Fixed #113**: internal type renamed to `AgentSpawnConfig`; public `SpawnOptions` in `service.ts` unchanged                                                                      |
-| Type dumping ground            | `types.ts`                                   | `NotificationDetails` used only by notification/renderer; ~~`DEFAULT_AGENT_NAMES` moved to `AgentTypeRegistry` (#108)~~; `AgentConfig` (21 fields) consumers use 2–4 each         |
+| ~~Type dumping ground~~        | ~~`types.ts`~~                               | **Fixed #116**: `NotificationDetails` → `notification.ts`; `ParentSnapshot` → `parent-snapshot.ts`; `EnvInfo` → `env.ts`; `AgentIdentity` and `AgentPromptConfig` narrow subsets  |
 | ~~Wide dependency bags~~       | ~~`AgentToolDeps` (9), `AgentMenuDeps` (8)~~ | **Fixed #114**: `AgentToolDeps` 9 → 6; `AgentMenuDeps` 8 → 7; `emitEvent` removed from both; description text derived from registry; `agentActivity` narrowed to typed interfaces |
 
 ### Step A: Extract state into classes (foundation, parallel)
@@ -437,7 +441,7 @@ Split post-construction mutation into phase-specific collaborators, each born co
 
 - **`ExecutionState`** (`session`, `outputFile`) — constructed in `onSessionCreated`, attached as `record.execution`.
 - **`WorktreeState`** (`path`, `branch`, `cleanupResult`) — constructed at worktree setup, attached as `record.worktreeState`.
-- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by agent-tool after spawn, attached as `record.notification`.
+- **`NotificationState`** (`toolCallId`, `resultConsumed`) — constructed by `AgentManager.spawn()` when `toolCallId` is provided in `AgentSpawnConfig`, attached as `record.notification`.
 - **`pendingSteers`** moved to `Map<string, string[]>` on `AgentManager`; steer-tool and service-adapter call `manager.queueSteer()`.
 - Stats (`toolUses`, `lifetimeUsage`, `compactionCount`) encapsulated behind mutation methods (`incrementToolUses`, `addUsage`, `incrementCompactions`) with read-only getters.
 - `AgentRecordInit` trimmed from 19 optional fields to 4 construction-time fields.
@@ -476,34 +480,35 @@ Public `SpawnOptions` in `service.ts` is unchanged.
 
 ### Step E: Decompose large files and relocate types (parallel)
 
-#### E1. Split `agent-tool.ts` foreground/background (#115)
+#### E1. Split `agent-tool.ts` foreground/background (#115) ✅
 
-Extract the foreground execution loop (spinner, streaming, result rendering) and background spawn path into separate modules.
-The 654-line file splits along a natural seam.
+**Done.**
+Fixed two upstream API gaps before extracting: `onSessionCreated` now receives `(session, record)` (eliminating a `listAgents()` reverse-search), and `AgentSpawnConfig` accepts `toolCallId` (moving `NotificationState` wiring into `AgentManager.spawn()`).
+Extracted `foreground-runner.ts` (~175 lines) and `background-spawner.ts` (~116 lines).
+`agent-tool.ts` reduced from 579 → 411 lines (orchestrator + rendering).
 
-#### E2. Type housekeeping (#116)
+#### ~~E2. Type housekeeping (#116)~~ — **Done**
 
-- Move `NotificationDetails` from `types.ts` to `notification.ts`.
-- Move `DEFAULT_AGENT_NAMES` from `types.ts` to the registry.
-- Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.
-- Move `EnvInfo` from `types.ts` to `env.ts`.
-- Convert `createNotificationSystem` closure to `NotificationManager` class.
-- Convert `ConversationViewer` constructor from 6 positional parameters to an options bag.
-- Define narrow `AgentConfig` subset interfaces for consumers that use 2–4 fields of the 21-field type.
+- Moved `NotificationDetails` from `types.ts` to `notification.ts`.
+- Moved `ParentSnapshot` from `types.ts` to `parent-snapshot.ts` (`DEFAULT_AGENT_NAMES` was already moved in #108).
+- Moved `EnvInfo` from `types.ts` to `env.ts`.
+- Converted `createNotificationSystem` closure to `NotificationManager` class.
+- Converted `ConversationViewer` constructor from 7 positional parameters to `ConversationViewerOptions` bag.
+- Defined `AgentIdentity` and `AgentPromptConfig` narrow subsets; `AgentConfig extends` both; `buildAgentPrompt` narrowed to `AgentPromptConfig`.
 
 ### Expected impact
 
-| Metric                                     | Before                                                                           | After   |
-| ------------------------------------------ | -------------------------------------------------------------------------------- | ------- |
-| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                     | **0** ✓ |
-| Closure-bag "classes"                      | ~~2~~ 1 (`createNotificationSystem`; settings free functions **fixed #109**)     | 0       |
-| Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**) | 0 ✓     |
-| `AgentManagerOptions` fields               | 8                                                                                | 5       |
-| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed) | 6 ✓     |
-| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)        | 7 ✓     |
-| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                           | 0       |
-| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain     | 0       |
-| Types in `types.ts` without a natural home | 4                                                                                | 0       |
+| Metric                                     | Before                                                                                 | After   |
+| ------------------------------------------ | -------------------------------------------------------------------------------------- | ------- |
+| Module-scoped mutable state                | ~~1 (`agent-types.ts` Map)~~                                                           | **0** ✓ |
+| Closure-bag "classes"                      | ~~2~~ ~~1~~ **0** (`createNotificationSystem` **fixed #116**; settings **fixed #109**) | 0 ✓     |
+| Externally-mutated state bags              | ~~2~~ ~~1~~ **0** (`AgentRecord` **fixed #111**; `AgentActivity` **fixed #110**)       | 0 ✓     |
+| `AgentManagerOptions` fields               | 8                                                                                      | 5       |
+| `AgentToolDeps` fields                     | ~~9~~ **6** (−3 text fields derived; −1 emitEvent → observer; activity narrowed)       | 6 ✓     |
+| `AgentMenuDeps` fields                     | ~~13~~ **7** (−6 settings #109; −1 registry #108; −1 dead emitEvent #114)              | 7 ✓     |
+| `SpawnOptions` callback fields             | 1 (`onSessionCreated`)                                                                 | 0       |
+| Callbacks threaded through deps            | ~~8~~ 0 remaining settings callbacks (**fixed #109**); `emitEvent` ×3 remain           | 0       |
+| Types in `types.ts` without a natural home | ~~4~~ **0** ✓ (all moved #116)                                                         | 0 ✓     |
 
 ### Dependency graph
 

package/docs/plans/0115-decompose-agent-tool.md

@@ -0,0 +1,337 @@
+---
+issue: 115
+issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
+---
+
+# Decompose agent-tool.ts into foreground/background modules
+
+## Problem Statement
+
+`tools/agent-tool.ts` is the largest file in the package at 579 lines.
+The `execute` function handles three distinct execution paths — resume, background spawn, and foreground streaming — each with different dependencies.
+Before those paths can be cleanly extracted, two upstream API gaps force the tool to work around the manager:
+
+1. The foreground `onSessionCreated` callback loops through `manager.listAgents()` matching by session object just to discover the agent's ID — because `onSessionCreated` only receives the session, not the record.
+2. The background path mutates `record.notification` after spawn — reaching into the record returned by `getRecord()` to attach a `NotificationState` — because the manager has no way to wire notification state at spawn time.
+
+These workarounds would simply move into the extracted modules unchanged.
+Fixing the API gaps first makes the extraction clean: each extracted module receives what it actually needs from the manager, without reaching through or reverse-searching.
+
+## Goals
+
+- Widen `onSessionCreated` to `(session, record)` so callers receive the agent ID and record directly.
+- Accept `toolCallId` in `AgentSpawnConfig` so the manager wires `record.notification` internally for background agents.
+- Extract the foreground execution loop into `tools/foreground-runner.ts`.
+- Extract the background spawn path into `tools/background-spawner.ts`.
+- Move `getStatusNote` and `buildDetails` to `tools/helpers.ts`.
+- Keep `agent-tool.ts` as the orchestrator (~250 lines): tool definition, parameter validation, shared setup, dispatch, resume.
+- Preserve all existing behavior.
+
+## Non-Goals
+
+- Extracting the resume path (~27 lines) — too small to warrant a separate file.
+- Extracting `renderCall`/`renderResult` — tightly coupled to the tool definition.
+- Changing `AgentToolDeps` shape — #114 already narrowed it.
+- Removing `onSessionCreated` from `AgentSpawnConfig` entirely — it is still useful for UI observer wiring that the manager should not own.
+
+## Background
+
+### Prerequisite status
+
+| Issue | Title                                      | Status  |
+| ----- | ------------------------------------------ | ------- |
+| #114  | Narrow `AgentToolDeps` and `AgentMenuDeps` | ✅ Done |
+
+### Current API gaps
+
+#### Gap 1: foreground ID discovery
+
+The foreground path needs the agent ID *during* execution (inside `onSessionCreated`, before `spawnAndWait` resolves) to register the activity tracker in the widget.
+The manager's internal `onSessionCreated` handler already has `id` and `record` in scope but passes only `session` to the caller's callback.
+The tool works around this by iterating `listAgents()` and matching by session identity:
+
+```typescript
+onSessionCreated: (session) => {
+  for (const a of deps.manager.listAgents()) {
+    if (a.execution?.session === session) {
+      fgId = a.id;
+      deps.agentActivity.set(a.id, fgState);
+      // ...
+    }
+  }
+}
+```
+
+This is a violation of Tell-Don't-Ask: the tool asks the manager for data it already has.
+
+#### Gap 2: post-spawn notification mutation
+
+The background path calls `manager.spawn()`, then immediately calls `manager.getRecord(id)` to mutate `record.notification`:
+
+```typescript
+const id = deps.manager.spawn(ctx, subagentType, prompt, { ... });
+const record = deps.manager.getRecord(id);
+if (record) {
+  record.notification = new NotificationState(toolCallId);
+}
+```
+
+This is an output argument — the tool writes back into a record it doesn't own.
+The notification could be wired at spawn time if the manager accepted a `toolCallId`.
+
+### Relevant design principles
+
+- **Tell-Don't-Ask** (code-design skill): the `listAgents()` loop asks the manager for data it already has.
+- **Output arguments** (code-design skill): writing `record.notification` after spawn mutates an object owned by the manager.
+- **SRP**: foreground streaming and background spawning are independent concerns.
+- **One concern per file** (AGENTS.md): the file mixes orchestration, streaming, spawning, and formatting.
+
+## Design Overview
+
+### Phase 1: Fix manager API gaps
+
+#### Widen `onSessionCreated` to include record
+
+Change the callback signature in both `AgentSpawnConfig` and the runner's `RunOptions`:
+
+```typescript
+// agent-manager.ts — AgentSpawnConfig
+onSessionCreated?: (session: AgentSession, record: AgentRecord) => void;
+```
+
+The manager's internal handler already has `record` in scope — pass it through:
+
+```typescript
+// In startAgent(), existing line:
+options.onSessionCreated?.(session);
+// Becomes:
+options.onSessionCreated?.(session, record);
+```
+
+The runner's `onSessionCreated` stays `(session: AgentSession) => void` — it doesn't know about records.
+The manager wraps the runner callback and adds `record` before forwarding to the caller.
+
+This lets the foreground tool callback access `record.id` directly, eliminating the `listAgents()` loop.
+
+#### Accept `toolCallId` in `AgentSpawnConfig`
+
+Add an optional `toolCallId` field to `AgentSpawnConfig`:
+
+```typescript
+export interface AgentSpawnConfig {
+  // ... existing fields ...
+  /** Tool call ID for background notification wiring. When set, spawn attaches NotificationState. */
+  toolCallId?: string;
+}
+```
+
+In `AgentManager.spawn()`, after creating the record:
+
+```typescript
+if (options.toolCallId) {
+  record.notification = new NotificationState(options.toolCallId);
+}
+```
+
+This moves the notification wiring into the manager, eliminating the post-spawn mutation in the tool.
+
+### Phase 2: Extract modules
+
+With the API gaps fixed, the extracted modules no longer need `listAgents` or `getRecord` or post-spawn record mutation.
+
+#### Foreground runner
+
+After the `onSessionCreated` widening, the foreground callback simplifies to:
+
+```typescript
+onSessionCreated: (session, record) => {
+  fgState.setSession(session);
+  unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+  fgId = record.id;
+  deps.agentActivity.set(record.id, fgState);
+  deps.widget.ensureTimer();
+}
+```
+
+The `runForeground` function receives narrow deps:
+
+```typescript
+export interface ForegroundDeps {
+  manager: { spawnAndWait: AgentToolManager["spawnAndWait"] };
+  widget: { ensureTimer(): void; markFinished(id: string): void };
+  agentActivity: AgentActivityAccess;
+}
+```
+
+No `listAgents` needed — the record is delivered by the callback.
+
+#### Background spawner
+
+After the `toolCallId` change, the background path simplifies to:
+
+```typescript
+const id = deps.manager.spawn(ctx, subagentType, prompt, {
+  ...spawnConfig,
+  toolCallId,
+});
+// No getRecord + mutation needed — notification already wired
+```
+
+The `spawnBackground` function receives narrow deps:
+
+```typescript
+export interface BackgroundDeps {
+  manager: { spawn: AgentToolManager["spawn"]; getRecord: AgentToolManager["getRecord"]; getMaxConcurrent: AgentToolManager["getMaxConcurrent"] };
+  widget: { ensureTimer(): void; update(): void };
+  agentActivity: AgentActivityAccess;
+}
+```
+
+`getRecord` is still needed for building the result message (checking `status`, `execution.outputFile`), but not for mutation.
+
+#### What stays in agent-tool.ts
+
+- `AgentToolDeps`, `AgentToolManager`, `AgentToolWidget`, `AgentActivityAccess` interfaces.
+- `createAgentTool` factory: tool name/label/description, parameters schema, `renderCall`, `renderResult`.
+- Execute's shared setup: registry reload, type resolution, model resolution, config assembly, detail base.
+- Resume path (~27 lines).
+- Dispatch to `spawnBackground()` or `runForeground()`.
+
+#### Helpers relocation
+
+`getStatusNote` and `buildDetails` move to `tools/helpers.ts`.
+Both are pure formatting functions with no dependency on `AgentToolDeps`.
+
+### Post-extraction file sizes (estimated)
+
+| File                    | Lines          |
+| ----------------------- | -------------- |
+| `agent-tool.ts`         | ~250 (was 579) |
+| `foreground-runner.ts`  | ~110           |
+| `background-spawner.ts` | ~70            |
+| `helpers.ts` additions  | ~50            |
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/agent-manager.ts`**
+   - Change `onSessionCreated` in `AgentSpawnConfig` to `(session: AgentSession, record: AgentRecord) => void`.
+   - Pass `record` as second argument in `startAgent`'s internal `onSessionCreated` call.
+   - Add optional `toolCallId?: string` to `AgentSpawnConfig`.
+   - Wire `record.notification = new NotificationState(options.toolCallId)` in `spawn()` when present.
+   - Add `NotificationState` import.
+
+2. **`src/tools/agent-tool.ts`**
+   - Update `onSessionCreated` callbacks to accept `(session, record)`.
+   - Remove `listAgents()` loop in foreground callback — use `record.id` directly.
+   - Pass `toolCallId` in background spawn config — remove post-spawn `getRecord` + mutation.
+   - Remove foreground block → `runForeground()` call.
+   - Remove background block → `spawnBackground()` call.
+   - Remove `getStatusNote`, `buildDetails` → imported from `helpers.ts`.
+   - Remove `listAgents` from `AgentToolManager` interface (no longer needed).
+   - Remove unused imports: `NotificationState`, `describeActivity`, `SPINNER`, `formatMs`.
+
+3. **`src/tools/helpers.ts`**
+   - Add `getStatusNote()` and `buildDetails()` (relocated from `agent-tool.ts`).
+
+### New files
+
+4. **`src/tools/foreground-runner.ts`**
+   - `ForegroundDeps` interface, `runForeground()` function.
+   - Owns: spinner interval, `AgentActivityTracker` creation, `subscribeUIObserver`, streaming `onUpdate`, cleanup, result formatting via `buildDetails`/`getStatusNote`.
+
+5. **`src/tools/background-spawner.ts`**
+   - `BackgroundDeps` interface, `spawnBackground()` function.
+   - Owns: `AgentActivityTracker` creation, `subscribeUIObserver`, activity map registration, widget update, launch message formatting.
+
+### Test files
+
+6. **`test/agent-manager.test.ts`**
+   - Update mock runner calls to pass `record` in `onSessionCreated`.
+   - Add test: `spawn` wires `NotificationState` when `toolCallId` is provided.
+   - Add test: `spawn` does not wire `NotificationState` when `toolCallId` is absent.
+
+7. **`test/tools/agent-tool.test.ts`**
+   - Update `onSessionCreated` mock signatures if needed (structural — tests call through `execute`).
+   - Existing tests remain as integration tests for the dispatch path.
+
+8. **`test/tools/helpers.test.ts`** (new or extended)
+   - Unit tests for `getStatusNote` (all status branches) and `buildDetails`.
+
+9. **`test/tools/foreground-runner.test.ts`** (new)
+   - Spinner lifecycle, streaming updates, cleanup on success/error, result formatting, fallback note.
+
+10. **`test/tools/background-spawner.test.ts`** (new)
+    - Activity tracker registered, widget updated, queued message, launch message format.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:**
+   - `foreground-runner.test.ts` tests spinner lifecycle and streaming with narrow mocks (no full `AgentToolDeps`).
+   - `background-spawner.test.ts` tests activity registration and message formatting in isolation.
+   - `helpers.test.ts` tests `getStatusNote` and `buildDetails` as pure functions.
+   - `agent-manager.test.ts` tests notification wiring at the manager level — moved from tool-level integration.
+
+2. **Existing tests that simplify:**
+   - `agent-tool.test.ts` background tests no longer need to verify notification wiring (now the manager's job).
+   - The "registers activity in agentActivity map" test stays but becomes a dispatch-level integration test.
+
+3. **Existing tests that must stay:**
+   - All `agent-tool.test.ts` tests exercise the full dispatch path and remain valuable as integration tests.
+   - All `agent-manager.test.ts` tests that fire `onSessionCreated` must update the mock signature to `(session, record)`.
+
+## TDD Order
+
+1. **Widen `onSessionCreated` callback to include record.**
+   Change `AgentSpawnConfig.onSessionCreated` signature to `(session, record)`.
+   Update `startAgent` to pass `record` as second argument.
+   Update `agent-tool.ts` foreground callback to use `record.id` instead of `listAgents()` loop.
+   Remove `listAgents` from `AgentToolManager` interface.
+   Update `agent-manager.test.ts` mock runner calls.
+   Test: verify foreground callback receives `record.id` (existing integration tests pass).
+   Commit: `refactor: widen onSessionCreated to include record`
+
+2. **Accept `toolCallId` in `AgentSpawnConfig`.**
+   Add `toolCallId?: string` to `AgentSpawnConfig`.
+   Wire `NotificationState` in `spawn()` when `toolCallId` is provided.
+   Update `agent-tool.ts` background path to pass `toolCallId` instead of post-spawn mutation.
+   Test: `agent-manager.test.ts` — `spawn` wires notification when `toolCallId` present, skips when absent.
+   Commit: `refactor: wire NotificationState at spawn time via toolCallId`
+
+3. **Relocate `getStatusNote` and `buildDetails` to `tools/helpers.ts`.**
+   Move both functions.
+   Update imports in `agent-tool.ts`.
+   Test: unit tests for `getStatusNote` (all branches) and `buildDetails`.
+   Commit: `refactor: move getStatusNote and buildDetails to tools/helpers`
+
+4. **Extract `spawnBackground` into `tools/background-spawner.ts`.**
+   Define `BackgroundDeps` interface and `spawnBackground()` function.
+   Replace background block in `execute` with a call to `spawnBackground()`.
+   Remove unused imports from `agent-tool.ts`.
+   Test: `background-spawner.test.ts` — activity registration, widget update, launch message.
+   Commit: `refactor: extract background spawn to tools/background-spawner`
+
+5. **Extract `runForeground` into `tools/foreground-runner.ts`.**
+   Define `ForegroundDeps` interface and `runForeground()` function.
+   Replace foreground block in `execute` with a call to `runForeground()`.
+   Remove unused imports from `agent-tool.ts`.
+   Test: `foreground-runner.test.ts` — spinner lifecycle, streaming, cleanup, result formatting.
+   Commit: `refactor: extract foreground execution to tools/foreground-runner`
+
+6. **Verify integration.**
+   Run full test suite and `pnpm run check`.
+   Commit: `test: verify agent-tool decomposition integration`
+
+## Risks and Mitigations
+
+| Risk                                                                                           | Mitigation                                                                                                                                                                                                              |
+| ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Widening `onSessionCreated` signature is a breaking change to `AgentSpawnConfig`               | `AgentSpawnConfig` is internal (not in package `exports`). The only external caller is `agent-tool.ts`. All test mocks update in the same step.                                                                         |
+| `toolCallId` on `AgentSpawnConfig` couples the manager to notification concerns                | The manager already owns the record lifecycle. `NotificationState` is a record collaborator like `execution` and `worktreeState` — the manager already wires those. `toolCallId` is a data-in, not a behavior coupling. |
+| Runner's `onSessionCreated` signature stays `(session)` while manager's is `(session, record)` | The manager wraps the runner's callback — the runner never sees the record. No change to runner interface.                                                                                                              |
+| Circular imports between new modules and `helpers.ts`                                          | `helpers.ts` is a leaf module. The new modules import from it but it imports nothing from them.                                                                                                                         |
+
+## Open Questions
+
+None — the design is unambiguous after resolving the two API gaps.