@gotgenes/pi-subagents 6.9.0 → 6.9.1

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.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
@@ -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,10 +480,12 @@ 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)
 

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.

package/docs/retro/0114-narrow-agent-tool-menu-deps.md

@@ -0,0 +1,38 @@
+---
+issue: 114
+issue_title: "refactor(pi-subagents): narrow AgentToolDeps and AgentMenuDeps"
+---
+
+# Retro: #114 — narrow AgentToolDeps and AgentMenuDeps
+
+## Final Retrospective (2026-05-21T21:43:48-04:00)
+
+### Session summary
+
+Narrowed `AgentToolDeps` from 9 to 6 fields and `AgentMenuDeps` from 8 to 7 fields.
+Moved `subagents:created` event emission from the Agent tool to a new `AgentManagerObserver.onAgentCreated` method.
+Extracted `buildTypeListText` to `tools/helpers.ts`, derived description text inside `createAgentTool`, removed dead `emitEvent` from `AgentMenuDeps`, and narrowed `agentActivity` to typed `AgentActivityAccess`/`AgentActivityReader` interfaces.
+Test count increased from 638 to 660.
+Released as `pi-subagents-v6.9.0`.
+
+### Observations
+
+#### What went well
+
+- The `ask_user` gate during planning was well-targeted.
+  The first question (where to move `emitEvent`) had a clear answer.
+  The second (description-text derivation) genuinely needed user input, and the user requested more context via the "I could use more context" response — the follow-up `preview`-type question with fenced code blocks handled this cleanly.
+- The 6-step TDD plan mapped to implementation with only one deviation (see below), caught exactly where the workflow is designed to catch it (the `pnpm run check` step).
+- All 6 prerequisites (#108, #109, #110, #112, #113, #118) were verified as closed before planning.
+  The observer issue (#112) was correctly identified from a `gh issue list` grep despite not being explicitly numbered in the issue body (the issue said "the observer issue").
+
+#### What caused friction (agent side)
+
+- `missing-context` (self-identified) — Step 6 narrowed `agentActivity` from `Map<string, AgentActivityTracker>` to `AgentActivityAccess` (which exposes only `get`/`set`/`delete`), but the test in `agent-tool.test.ts` used `.has()` on the map.
+  The `pnpm run check` typecheck caught `Property 'has' does not exist on type 'AgentActivityAccess'`.
+  Fixed by replacing `.has(id)` with `.get(id) !== undefined` in the same commit.
+  Impact: one extra read + edit cycle (~30 seconds), no rework.
+
+#### What caused friction (user side)
+
+- Nothing — no user corrections or redirections needed during the session.

package/package.json

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

package/src/agent-manager.ts

@@ -13,6 +13,7 @@ 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 { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
@@ -72,12 +73,14 @@ export interface AgentSpawnConfig {
   invocation?: AgentInvocation;
   /** Parent abort signal — when aborted, the subagent is also stopped. */
   signal?: AbortSignal;
-  /** Called when the agent session is created — the one remaining callback. */
-  onSessionCreated?: (session: AgentSession) => void;
+  /** 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;
 }
 
 export class AgentManager {
@@ -155,6 +158,10 @@ export class AgentManager {
     });
     this.agents.set(id, record);
 
+    if (options.toolCallId) {
+      record.notification = new NotificationState(options.toolCallId);
+    }
+
     if (options.isBackground) {
       this.observer?.onAgentCreated(record);
     }
@@ -244,7 +251,7 @@ export class AgentManager {
         unsubRecordObserver = subscribeRecordObserver(session, record, {
           onCompact: (r, info) => this.observer?.onAgentCompacted(r, info),
         });
-        options.onSessionCreated?.(session);
+        options.onSessionCreated?.(session, record);
       },
     })
       .then(({ responseText, session, aborted, steered, sessionFile }) => {

package/src/index.ts

@@ -169,7 +169,6 @@ export default function (pi: ExtensionAPI) {
       resume: (id, prompt, signal) => manager.resume(id, prompt, signal),
       getRecord: (id) => manager.getRecord(id),
       getMaxConcurrent: () => settings.maxConcurrent,
-      listAgents: () => manager.listAgents(),
     },
     widget: {
       setUICtx: (ctx) => runtime.setUICtx(ctx as UICtx),

package/src/tools/agent-tool.ts

@@ -7,13 +7,11 @@ import { AgentTypeRegistry } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 
-import { NotificationState } from "../notification-state.js";
 import type { AgentInvocation, AgentRecord, SubagentType } from "../types.js";
 import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
 import {
   type AgentDetails,
   buildInvocationTags,
-  describeActivity,
   formatMs,
   formatTurns,
   getDisplayName,
@@ -21,55 +19,9 @@ import {
   SPINNER,
   type UICtx,
 } from "../ui/agent-widget.js";
-import { subscribeUIObserver } from "../ui/ui-observer.js";
-import type { LifetimeUsage } from "../usage.js";
-import { buildTypeListText, formatLifetimeTokens, textResult } from "./helpers.js";
-
-// ---- Agent-tool-specific helpers ----
-
-/** Parenthetical status note for completed agent result text. */
-export function getStatusNote(status: string): string {
-  switch (status) {
-    case "aborted":
-      return " (aborted — max turns exceeded, output may be incomplete)";
-    case "steered":
-      return " (wrapped up — reached turn limit)";
-    case "stopped":
-      return " (stopped by user)";
-    default:
-      return "";
-  }
-}
-
-/** Build AgentDetails from a base + record-specific fields. */
-export function buildDetails(
-  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
-  record: {
-    toolUses: number;
-    startedAt: number;
-    completedAt?: number;
-    status: string;
-    error?: string;
-    id?: string;
-    session?: any;
-    lifetimeUsage: LifetimeUsage;
-  },
-  activity?: AgentActivityTracker,
-  overrides?: Partial<AgentDetails>,
-): AgentDetails {
-  return {
-    ...base,
-    toolUses: record.toolUses,
-    tokens: formatLifetimeTokens(record),
-    turnCount: activity?.turnCount,
-    maxTurns: activity?.maxTurns,
-    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
-    status: record.status as AgentDetails["status"],
-    agentId: record.id,
-    error: record.error,
-    ...overrides,
-  };
-}
+import { spawnBackground } from "./background-spawner.js";
+import { runForeground } from "./foreground-runner.js";
+import { buildDetails, buildTypeListText, formatLifetimeTokens, getStatusNote, textResult } from "./helpers.js";
 
 // ---- Deps interface ----
 
@@ -80,7 +32,6 @@ export interface AgentToolManager {
   resume: (id: string, prompt: string, signal: AbortSignal) => Promise<AgentRecord | undefined>;
   getRecord: (id: string) => AgentRecord | undefined;
   getMaxConcurrent: () => number;
-  listAgents: () => AgentRecord[];
 }
 
 /** Narrow widget interface — only the methods the Agent tool calls. */
@@ -412,167 +363,48 @@ Guidelines:
 
       // Background execution
       if (runInBackground) {
-        const bgState = new AgentActivityTracker(effectiveMaxTurns);
-
-        let id: string;
-
-        try {
-          id = deps.manager.spawn(ctx, subagentType, params.prompt as string, {
-            parentSessionFile: ctx.sessionManager.getSessionFile(),
-            parentSessionId: ctx.sessionManager.getSessionId(),
+        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,
-            maxTurns: effectiveMaxTurns,
+            effectiveMaxTurns,
             isolated,
             inheritContext,
-            thinkingLevel: thinking,
-            isBackground: true,
+            thinking,
             isolation,
-            invocation: agentInvocation,
-            onSessionCreated: (session: any) => {
-              bgState.setSession(session);
-              subscribeUIObserver(session, bgState);
-            },
-          });
-        } catch (err) {
-          return textResult(err instanceof Error ? err.message : String(err));
-        }
-
-        const record = deps.manager.getRecord(id);
-        if (record) {
-          // Born complete: notification-state object owns toolCallId + resultConsumed.
-          record.notification = new NotificationState(toolCallId);
-        }
-
-        deps.agentActivity.set(id, bgState);
-        deps.widget.ensureTimer();
-        deps.widget.update();
-
-        const isQueued = record?.status === "queued";
-        return textResult(
-          `Agent ${isQueued ? "queued" : "started"} in background.\n` +
-            `Agent ID: ${id}\n` +
-            `Type: ${displayName}\n` +
-            `Description: ${params.description}\n` +
-            (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
-            (isQueued
-              ? `Position: queued (max ${deps.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.`,
-          {
-            ...detailBase,
-            toolUses: 0,
-            tokens: "",
-            durationMs: 0,
-            status: "background" as const,
-            agentId: id,
+            agentInvocation,
           },
         );
       }
 
       // Foreground (synchronous) execution — stream progress via onUpdate
-      let spinnerFrame = 0;
-      const startedAt = Date.now();
-      let fgId: string | undefined;
-
-      const fgState = new AgentActivityTracker(effectiveMaxTurns);
-      let unsubUI: (() => void) | undefined;
-
-      const streamUpdate = () => {
-        const details: AgentDetails = {
-          ...detailBase,
-          toolUses: fgState.toolUses,
-          tokens: formatLifetimeTokens(fgState),
-          turnCount: fgState.turnCount,
-          maxTurns: fgState.maxTurns,
-          durationMs: Date.now() - startedAt,
-          status: "running",
-          activity: describeActivity(fgState.activeTools, fgState.responseText),
-          spinnerFrame: spinnerFrame % SPINNER.length,
-        };
-        onUpdate?.({
-          content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
-          details: details as any,
-        });
-      };
-
-      // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
-      const spinnerInterval = setInterval(() => {
-        spinnerFrame++;
-        streamUpdate();
-      }, 80);
-
-      streamUpdate();
-
-      let record: AgentRecord;
-      try {
-        record = await deps.manager.spawnAndWait(
+      return runForeground(
+        { manager: deps.manager, widget: deps.widget, agentActivity: deps.agentActivity },
+        {
           ctx,
           subagentType,
-          params.prompt as string,
-          {
-            description: params.description as string,
-            model,
-            maxTurns: effectiveMaxTurns,
-            isolated,
-            inheritContext,
-            thinkingLevel: thinking,
-            isolation,
-            invocation: agentInvocation,
-            signal,
-            parentSessionFile: ctx.sessionManager.getSessionFile(),
-            parentSessionId: ctx.sessionManager.getSessionId(),
-            onSessionCreated: (session: any) => {
-              fgState.setSession(session);
-              unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
-              for (const a of deps.manager.listAgents()) {
-                if (a.execution?.session === session) {
-                  fgId = a.id;
-                  deps.agentActivity.set(a.id, fgState);
-                  deps.widget.ensureTimer();
-                  break;
-                }
-              }
-            },
-          },
-        );
-      } catch (err) {
-        clearInterval(spinnerInterval);
-        unsubUI?.();
-        return textResult(err instanceof Error ? err.message : String(err));
-      }
-
-      clearInterval(spinnerInterval);
-      unsubUI?.();
-
-      // Clean up foreground agent from widget
-      if (fgId) {
-        deps.agentActivity.delete(fgId);
-        deps.widget.markFinished(fgId);
-      }
-
-      // Get final token count
-      const tokenText = formatLifetimeTokens(fgState);
-
-      const details = buildDetails(detailBase, record, fgState, { tokens: tokenText });
-
-      const fallbackNote = fellBack
-        ? `Note: Unknown agent type "${rawType}" — using general-purpose.\n\n`
-        : "";
-
-      if (record.status === "error") {
-        return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
-      }
-
-      const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
-      const statsParts = [`${record.toolUses} tool uses`];
-      if (tokenText) statsParts.push(tokenText);
-      return textResult(
-        `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
-          (record.result?.trim() || "No output."),
-        details,
+          prompt: params.prompt as string,
+          description: params.description as string,
+          detailBase,
+          rawType,
+          fellBack,
+          model,
+          effectiveMaxTurns,
+          isolated,
+          inheritContext,
+          thinking,
+          isolation,
+          agentInvocation,
+        },
+        signal,
+        onUpdate,
       );
     },
   };

package/src/tools/background-spawner.ts

@@ -0,0 +1,116 @@
+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 { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import type { AgentDetails } from "../ui/agent-widget.js";
+import { subscribeUIObserver } from "../ui/ui-observer.js";
+import type { AgentActivityAccess } from "./agent-tool.js";
+import { textResult } from "./helpers.js";
+
+/** Narrow manager interface for the background spawner. */
+export interface BackgroundManagerDeps {
+  spawn(ctx: any, type: string, prompt: string, opts: AgentSpawnConfig): string;
+  getRecord(id: string): AgentRecord | undefined;
+  getMaxConcurrent(): number;
+}
+
+/** Narrow widget interface for the background spawner. */
+export interface BackgroundWidgetDeps {
+  ensureTimer(): void;
+  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. */
+export interface BackgroundParams {
+  ctx: {
+    sessionManager: {
+      getSessionFile(): string;
+      getSessionId(): string;
+    };
+  };
+  subagentType: string;
+  prompt: string;
+  description: string;
+  displayName: 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;
+}
+
+/**
+ * Spawn a background agent and return the tool result immediately.
+ * Owns: activity tracker creation, UI observer subscription, activity map
+ * registration, widget update, and launch message formatting.
+ */
+export function spawnBackground(
+  deps: BackgroundDeps,
+  params: BackgroundParams,
+) {
+  const bgState = new AgentActivityTracker(params.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,
+      isBackground: true,
+      isolation: params.isolation,
+      invocation: params.agentInvocation,
+      toolCallId: params.toolCallId,
+      onSessionCreated: (session) => {
+        bgState.setSession(session);
+        subscribeUIObserver(session, bgState);
+      },
+    });
+  } catch (err) {
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  const record = deps.manager.getRecord(id);
+
+  deps.agentActivity.set(id, bgState);
+  deps.widget.ensureTimer();
+  deps.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` +
+      (record?.execution?.outputFile ? `Output file: ${record.execution.outputFile}\n` : "") +
+      (isQueued
+        ? `Position: queued (max ${deps.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,
+      toolUses: 0,
+      tokens: "",
+      durationMs: 0,
+      status: "background" as const,
+      agentId: id,
+    },
+  );
+}

package/src/tools/foreground-runner.ts

@@ -0,0 +1,175 @@
+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 { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import {
+  type AgentDetails,
+  describeActivity,
+  formatMs,
+  SPINNER,
+} from "../ui/agent-widget.js";
+import { subscribeUIObserver } from "../ui/ui-observer.js";
+import type { AgentActivityAccess } from "./agent-tool.js";
+import {
+  buildDetails,
+  formatLifetimeTokens,
+  getStatusNote,
+  textResult,
+} from "./helpers.js";
+
+/** Narrow manager interface for the foreground runner. */
+export interface ForegroundManagerDeps {
+  spawnAndWait(
+    ctx: any,
+    type: string,
+    prompt: string,
+    opts: Omit<AgentSpawnConfig, "isBackground">,
+  ): Promise<AgentRecord>;
+}
+
+/** Narrow widget interface for the foreground runner. */
+export interface ForegroundWidgetDeps {
+  ensureTimer(): void;
+  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. */
+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;
+}
+
+/**
+ * Run an agent synchronously in the foreground, streaming spinner updates.
+ * Owns: spinner interval, AgentActivityTracker creation, UI observer subscription,
+ * streaming onUpdate callbacks, cleanup, and result formatting.
+ */
+export async function runForeground(
+  deps: ForegroundDeps,
+  params: ForegroundParams,
+  signal: AbortSignal | undefined,
+  onUpdate: ((update: AgentToolResult<any>) => void) | undefined,
+) {
+  let spinnerFrame = 0;
+  const startedAt = Date.now();
+  let fgId: string | undefined;
+
+  const fgState = new AgentActivityTracker(params.effectiveMaxTurns);
+  let unsubUI: (() => void) | undefined;
+
+  const streamUpdate = () => {
+    const details: AgentDetails = {
+      ...params.detailBase,
+      toolUses: fgState.toolUses,
+      tokens: formatLifetimeTokens(fgState),
+      turnCount: fgState.turnCount,
+      maxTurns: fgState.maxTurns,
+      durationMs: Date.now() - startedAt,
+      status: "running",
+      activity: describeActivity(fgState.activeTools, fgState.responseText),
+      spinnerFrame: spinnerFrame % SPINNER.length,
+    };
+    onUpdate?.({
+      content: [{ type: "text", text: `${fgState.toolUses} tool uses...` }],
+      details: details as any,
+    });
+  };
+
+  // Animate spinner at ~80ms (smooth rotation through 10 braille frames)
+  const spinnerInterval = setInterval(() => {
+    spinnerFrame++;
+    streamUpdate();
+  }, 80);
+
+  streamUpdate();
+
+  let record: AgentRecord;
+  try {
+    record = await deps.manager.spawnAndWait(
+      params.ctx,
+      params.subagentType,
+      params.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,
+        signal,
+        parentSessionFile: params.ctx.sessionManager.getSessionFile(),
+        parentSessionId: params.ctx.sessionManager.getSessionId(),
+        onSessionCreated: (session, record) => {
+          fgState.setSession(session);
+          unsubUI = subscribeUIObserver(session, fgState, streamUpdate);
+          fgId = record.id;
+          deps.agentActivity.set(record.id, fgState);
+          deps.widget.ensureTimer();
+        },
+      },
+    );
+  } catch (err) {
+    clearInterval(spinnerInterval);
+    unsubUI?.();
+    return textResult(err instanceof Error ? err.message : String(err));
+  }
+
+  clearInterval(spinnerInterval);
+  unsubUI?.();
+
+  // Clean up foreground agent from widget
+  if (fgId) {
+    deps.agentActivity.delete(fgId);
+    deps.widget.markFinished(fgId);
+  }
+
+  const tokenText = formatLifetimeTokens(fgState);
+  const details = buildDetails(params.detailBase, record, fgState, { tokens: tokenText });
+
+  const fallbackNote = params.fellBack
+    ? `Note: Unknown agent type "${params.rawType}" \u2014 using general-purpose.\n\n`
+    : "";
+
+  if (record.status === "error") {
+    return textResult(`${fallbackNote}Agent failed: ${record.error}`, details);
+  }
+
+  const durationMs = (record.completedAt ?? Date.now()) - record.startedAt;
+  const statsParts = [`${record.toolUses} tool uses`];
+  if (tokenText) statsParts.push(tokenText);
+  return textResult(
+    `${fallbackNote}Agent completed in ${formatMs(durationMs)} (${statsParts.join(", ")})${getStatusNote(record.status)}.\n\n` +
+      (record.result?.trim() || "No output."),
+    details,
+  );
+}

package/src/tools/helpers.ts

@@ -1,7 +1,51 @@
 import type { AgentConfigLookup } from "../agent-types.js";
-import { formatTokens } from "../ui/agent-widget.js";
+import { AgentActivityTracker } from "../ui/agent-activity-tracker.js";
+import { type AgentDetails, formatTokens } from "../ui/agent-widget.js";
 import { getLifetimeTotal, type LifetimeUsage } from "../usage.js";
 
+/** Parenthetical status note for completed agent result text. */
+export function getStatusNote(status: string): string {
+  switch (status) {
+    case "aborted":
+      return " (aborted \u2014 max turns exceeded, output may be incomplete)";
+    case "steered":
+      return " (wrapped up \u2014 reached turn limit)";
+    case "stopped":
+      return " (stopped by user)";
+    default:
+      return "";
+  }
+}
+
+/** Build AgentDetails from a base + record-specific fields. */
+export function buildDetails(
+  base: Pick<AgentDetails, "displayName" | "description" | "subagentType" | "modelName" | "tags">,
+  record: {
+    toolUses: number;
+    startedAt: number;
+    completedAt?: number;
+    status: string;
+    error?: string;
+    id?: string;
+    lifetimeUsage: LifetimeUsage;
+  },
+  activity?: AgentActivityTracker,
+  overrides?: Partial<AgentDetails>,
+): AgentDetails {
+  return {
+    ...base,
+    toolUses: record.toolUses,
+    tokens: formatLifetimeTokens(record),
+    turnCount: activity?.turnCount,
+    maxTurns: activity?.maxTurns,
+    durationMs: (record.completedAt ?? Date.now()) - record.startedAt,
+    status: record.status as AgentDetails["status"],
+    agentId: record.id,
+    error: record.error,
+    ...overrides,
+  };
+}
+
 /** Tool execute return value for a text response. */
 export function textResult(msg: string, details?: unknown) {
   return { content: [{ type: "text" as const, text: msg }], details: details as any };