@gotgenes/pi-subagents 6.9.0 → 6.9.2

package/docs/plans/0116-type-housekeeping.md

@@ -0,0 +1,351 @@
+---
+issue: 116
+issue_title: "refactor(pi-subagents): type housekeeping and small structural cleanups"
+---
+
+# Type housekeeping and small structural cleanups
+
+## Problem Statement
+
+`types.ts` is a type dumping ground — it collects types that don't have a natural home because the module that should own them didn't exist yet.
+With foundation extractions (#108 registry, `parent-snapshot.ts`, `env.ts`, `notification.ts`) now in place, most of these types have a natural home.
+Several other small housekeeping items share the same "polish" character: a closure-bag factory that is a class in disguise, a positional constructor that creates test friction, and a 22-field `AgentConfig` interface consumed by modules that touch 2–4 of its fields.
+
+## Goals
+
+- Move `NotificationDetails` to `notification.ts`, `ParentSnapshot` to `parent-snapshot.ts`, and `EnvInfo` to `env.ts`.
+- Convert `createNotificationSystem` closure to a `NotificationManager` class.
+- Convert `ConversationViewer` constructor from 7 positional parameters to an options bag.
+- Define narrow `AgentConfig` subset interfaces for consumers that use only a few fields.
+- Leave `types.ts` containing only genuinely cross-cutting types: `SubagentType`, `MemoryScope`, `IsolationMode`, `AgentConfig`, `AgentInvocation`, `ShellExec`, and re-exports (`AgentRecord`, `ThinkingLevel`).
+
+## Non-Goals
+
+- Refactoring `AgentConfig` itself (field additions, removals, renames).
+- Changing the `NotificationDeps` interface shape.
+- Modifying `agent-menu.ts` to use narrow subsets — it legitimately reads most `AgentConfig` fields as a config editor/viewer.
+- Touching `invocation-config.ts` — it already receives `AgentConfig | undefined` and only reads invocation-default fields; narrowing its parameter is a separate concern.
+
+## Background
+
+### Prerequisite status
+
+| Issue | Title                             | Status  |
+| ----- | --------------------------------- | ------- |
+| #108  | Extract `AgentTypeRegistry` class | ✅ Done |
+
+`DEFAULT_AGENT_NAMES` was already moved to `AgentTypeRegistry.DEFAULT_AGENT_NAMES` as part of #108.
+The remaining work from the issue's checklist is type relocations, two structural conversions, and narrow subset interfaces.
+
+### Current `types.ts` exports
+
+| Export                                             | Kind      | Should stay?                    |
+| -------------------------------------------------- | --------- | ------------------------------- |
+| `AgentRecord` (re-export)                          | class     | ✅ Cross-cutting                |
+| `AgentRecordInit`, `AgentRecordStatus` (re-export) | type      | ✅ Cross-cutting                |
+| `ThinkingLevel` (re-export)                        | type      | ✅ Cross-cutting                |
+| `SubagentType`                                     | type      | ✅ Cross-cutting                |
+| `MemoryScope`                                      | type      | ✅ Cross-cutting                |
+| `IsolationMode`                                    | type      | ✅ Cross-cutting                |
+| `AgentConfig`                                      | interface | ✅ Cross-cutting                |
+| `AgentInvocation`                                  | interface | ✅ Cross-cutting                |
+| `ShellExec`                                        | type      | ✅ Cross-cutting                |
+| `NotificationDetails`                              | interface | ❌ Move to `notification.ts`    |
+| `ParentSnapshot`                                   | interface | ❌ Move to `parent-snapshot.ts` |
+| `EnvInfo`                                          | interface | ❌ Move to `env.ts`             |
+
+### `createNotificationSystem` closure analysis
+
+The factory in `notification.ts` shares `pendingNudges` (a `Map`) and timer state across 4 inner functions (`cancelNudge`, `scheduleNudge`, `sendCompletion`, `cleanupCompleted`, `dispose`).
+This is a class in disguise — mutable state + methods that read/write it.
+Converting to a `NotificationManager` class makes the state explicit and lets tests use instance methods directly.
+
+### `ConversationViewer` constructor
+
+The constructor takes 7 positional parameters:
+
+```typescript
+constructor(tui, session, record, activity, theme, done, registry)
+```
+
+Every test must reconstruct all 7 in order.
+An options bag reduces friction and is resilient to new parameters.
+
+### `AgentConfig` field usage by consumer
+
+| Consumer                                                   | Fields used                                                                                  |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| `agent-widget.ts` (`getDisplayName`, `getPromptModeLabel`) | `name`, `displayName`, `promptMode`                                                          |
+| `tools/helpers.ts` (`formatAgentList`)                     | `name`, `description`, `model`                                                               |
+| `prompts.ts` (`buildAgentPrompt`)                          | `name`, `promptMode`, `systemPrompt`                                                         |
+| `session-config.ts` (`assembleSessionConfig`)              | `name`, `model`, `thinking`, `maxTurns`, `extensions`, `skills`, `memory`, `disallowedTools` |
+| `agent-menu.ts`                                            | Nearly all fields (config viewer/editor)                                                     |
+
+Natural clusters for narrow interfaces:
+
+- **`AgentIdentity`**: `name`, `displayName`, `description`, `promptMode` — UI display and agent listing.
+- **`AgentPromptConfig`**: `name`, `promptMode`, `systemPrompt` — prompt assembly.
+
+`session-config.ts` uses 8 fields; narrowing it yields limited value vs. complexity.
+`invocation-config.ts` receives `AgentConfig | undefined` and reads invocation-default fields; this is a separate concern.
+
+## Design Overview
+
+### Type relocations
+
+Move each type to its natural home module and re-export from `types.ts` during an interim step.
+After updating all importers to point at the new home, remove the re-export.
+This two-phase approach (move + re-export, then update importers + remove re-export) avoids a big-bang commit.
+
+However, since importers are few (2–4 each) and the types are only used internally, a single step per type is simpler: move the type, update all importers in the same commit.
+
+### `NotificationManager` class
+
+Replace the `createNotificationSystem` factory with a class that owns its state:
+
+```typescript
+export class NotificationManager {
+  private pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+
+  constructor(private deps: NotificationDeps) {}
+
+  cancelNudge(key: string): void { /* ... */ }
+  sendCompletion(record: AgentRecord): void { /* ... */ }
+  cleanupCompleted(id: string): void { /* ... */ }
+  dispose(): void { /* ... */ }
+
+  // private helpers
+  private scheduleNudge(key: string, send: () => void, delay?: number): void { /* ... */ }
+  private emitIndividualNudge(record: AgentRecord): void { /* ... */ }
+}
+```
+
+The `NotificationSystem` interface stays as-is — `NotificationManager implements NotificationSystem`.
+The `NotificationDeps` interface is unchanged.
+Callers in `index.ts` switch from `createNotificationSystem(deps)` to `new NotificationManager(deps)`.
+
+Consumer call site (index.ts):
+
+```typescript
+const notifications = new NotificationManager({
+  sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
+  agentActivity: runtime.agentActivity,
+  markFinished: (id) => runtime.markFinished(id),
+  updateWidget: () => runtime.updateWidget(),
+});
+```
+
+### `ConversationViewer` options bag
+
+Replace positional parameters with a named options interface:
+
+```typescript
+export interface ConversationViewerOptions {
+  tui: TUI;
+  session: AgentSession;
+  record: AgentRecord;
+  activity: AgentActivityTracker | undefined;
+  theme: Theme;
+  done: (result: undefined) => void;
+  registry: AgentConfigLookup;
+}
+
+export class ConversationViewer {
+  constructor(private options: ConversationViewerOptions) {
+    // destructure into private fields or use options.field access
+  }
+}
+```
+
+The existing private fields (`tui`, `session`, `record`, etc.) become reads from `this.options.*` or are destructured in the constructor to named private fields.
+The constructor body (session subscription) is unchanged.
+
+### Narrow `AgentConfig` subset interfaces
+
+Define two narrow interfaces in `types.ts` and make `AgentConfig` extend them:
+
+```typescript
+/** UI display and agent listing — name, display name, description, prompt mode. */
+export interface AgentIdentity {
+  name: string;
+  displayName?: string;
+  description: string;
+  promptMode: "replace" | "append";
+}
+
+/** Prompt assembly — name, prompt mode, system prompt. */
+export interface AgentPromptConfig {
+  name: string;
+  promptMode: "replace" | "append";
+  systemPrompt: string;
+}
+
+export interface AgentConfig extends AgentIdentity, AgentPromptConfig {
+  // remaining fields unchanged
+}
+```
+
+Then update consumers to accept the narrow interface:
+
+- `agent-widget.ts`: `getDisplayName(type, registry)` and `getPromptModeLabel(type, registry)` — these go through `AgentConfigLookup.resolveAgentConfig()`, which returns `AgentConfig`.
+  The narrowing applies to the *return type usage*, not the function signature.
+  No change needed here — the function already destructures only `displayName`, `name`, `promptMode`.
+- `tools/helpers.ts`: `formatAgentList` reads `description`, `model` — these are not in `AgentIdentity`.
+  `model` is session-config territory.
+  Leave as-is.
+- `prompts.ts`: `buildAgentPrompt(config: AgentPromptConfig, ...)` — narrow the parameter type.
+- `AgentConfigLookup.resolveAgentConfig()` return type stays `AgentConfig` — the registry always has the full config.
+
+Since `AgentConfig extends AgentIdentity, AgentPromptConfig`, any code passing an `AgentConfig` to a function expecting the narrow type works without casts.
+
+## Module-Level Changes
+
+### Modified files
+
+1. **`src/types.ts`**
+   - Remove `NotificationDetails`, `ParentSnapshot`, `EnvInfo` interface definitions.
+   - Add `AgentIdentity` and `AgentPromptConfig` interfaces.
+   - Make `AgentConfig` extend `AgentIdentity` and `AgentPromptConfig`.
+   - Remove fields from `AgentConfig` body that are now inherited (`name`, `displayName`, `description`, `promptMode`, `systemPrompt`).
+
+2. **`src/notification.ts`**
+   - Add `NotificationDetails` interface (moved from `types.ts`).
+   - Replace `createNotificationSystem` factory with `NotificationManager` class implementing `NotificationSystem`.
+   - Export `NotificationManager` (named export) and keep `NotificationSystem` interface export.
+   - Remove `createNotificationSystem` export.
+
+3. **`src/parent-snapshot.ts`**
+   - Add `ParentSnapshot` interface (moved from `types.ts`).
+
+4. **`src/env.ts`**
+   - Add `EnvInfo` interface (moved from `types.ts`).
+
+5. **`src/prompts.ts`**
+   - Change `config` parameter type from `AgentConfig` to `AgentPromptConfig`.
+   - Update import to use `AgentPromptConfig` from `./types.js`.
+
+6. **`src/index.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+   - Replace `createNotificationSystem(deps)` with `new NotificationManager(deps)`.
+   - Update import: `NotificationManager` from `./notification.js`.
+
+7. **`src/renderer.ts`**
+   - Update `NotificationDetails` import from `./types.js` to `./notification.js`.
+
+8. **`src/agent-runner.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+9. **`src/agent-manager.ts`**
+   - Update `ParentSnapshot` import from `./types.js` to `./parent-snapshot.js`.
+
+10. **`src/session-config.ts`**
+    - Update `EnvInfo` import from `./types.js` to `./env.js`.
+
+11. **`src/ui/conversation-viewer.ts`**
+    - Define `ConversationViewerOptions` interface.
+    - Replace 7 positional constructor parameters with single `options: ConversationViewerOptions` parameter.
+    - Assign private fields from `options` in constructor body.
+
+### Unchanged files
+
+- `src/agent-types.ts` — `DEFAULT_AGENT_NAMES` already moved in #108.
+- `src/invocation-config.ts` — narrowing is a separate concern.
+- `src/ui/agent-menu.ts` — legitimately uses most `AgentConfig` fields.
+
+### Test files
+
+12. **`test/notification.test.ts`**
+    - Replace `createNotificationSystem(deps)` calls with `new NotificationManager(deps)`.
+    - Update import.
+    - All existing assertions stay — the public API is identical.
+
+13. **`test/conversation-viewer.test.ts`**
+    - Replace positional `new ConversationViewer(tui, session, record, activity, theme, done, registry)` calls with `new ConversationViewer({ tui, session, record, activity, theme, done, registry })`.
+    - All existing assertions stay.
+
+14. **`test/prompts.test.ts`**
+    - Verify existing test fixtures satisfy `AgentPromptConfig` (they should — tests already pass `name`, `promptMode`, `systemPrompt`).
+    - May need to narrow mock type annotations.
+
+15. **Other test files importing relocated types** (`test/parent-snapshot.test.ts`, `test/renderer.test.ts`)
+    - Update import paths if they import directly from `types.ts` (most import from the source module already).
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:**
+   - `NotificationManager` as a class can be tested with standard `new` + method calls — no factory indirection.
+     However, the existing factory tests are already clean and simply switch to `new NotificationManager(deps)`.
+     No fundamentally new test capabilities.
+
+2. **Existing tests that simplify:**
+   - `conversation-viewer.test.ts` — the options bag makes test construction more readable and resilient to parameter additions.
+     Each test only needs to specify the fields it cares about (with a helper providing defaults).
+   - `prompts.test.ts` — narrower `AgentPromptConfig` parameter means test fixtures can omit 19 irrelevant `AgentConfig` fields.
+
+3. **Existing tests that must stay as-is:**
+   - `notification.test.ts` — all factory tests stay, just switch constructor syntax.
+   - `conversation-viewer.test.ts` — all render and input tests stay, just switch constructor syntax.
+   - `parent-snapshot.test.ts`, `env.test.ts`, `renderer.test.ts` — behavior unchanged.
+
+## TDD Order
+
+1. **Move `NotificationDetails` from `types.ts` to `notification.ts`.**
+   Cut the interface from `types.ts`, paste into `notification.ts`.
+   Update importers: `index.ts`, `renderer.ts` (change import from `./types.js` to `./notification.js`).
+   `notification.ts` already imports from `./types.js` for `AgentRecord` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move NotificationDetails to notification.ts`
+
+2. **Move `ParentSnapshot` from `types.ts` to `parent-snapshot.ts`.**
+   Cut the interface from `types.ts`, paste into `parent-snapshot.ts`.
+   Update importers: `agent-manager.ts`, `agent-runner.ts` (change import from `./types.js` to `./parent-snapshot.js`).
+   Run `pnpm run check`.
+   Commit: `refactor: move ParentSnapshot to parent-snapshot.ts`
+
+3. **Move `EnvInfo` from `types.ts` to `env.ts`.**
+   Cut the interface from `types.ts`, paste into `env.ts`.
+   Update importers: `session-config.ts`, `prompts.ts` (change import from `./types.js` to `./env.js`).
+   `env.ts` already imports `ShellExec` from `./types.js` — no circular dependency.
+   Run `pnpm run check`.
+   Commit: `refactor: move EnvInfo to env.ts`
+
+4. **Convert `createNotificationSystem` to `NotificationManager` class.**
+   Replace the factory with a class implementing `NotificationSystem`.
+   Move `pendingNudges` and timer logic to private instance state.
+   Convert inner functions to methods.
+   Keep `NotificationSystem` interface, `NotificationDeps` interface, and `NUDGE_HOLD_MS` constant unchanged.
+   Remove `createNotificationSystem` export, add `NotificationManager` export.
+   Update `index.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`.
+   Update `test/notification.test.ts`: `new NotificationManager(deps)` instead of `createNotificationSystem(deps)`, update import.
+   Run `pnpm vitest run test/notification.test.ts`.
+   Commit: `refactor: convert createNotificationSystem to NotificationManager class`
+
+5. **Convert `ConversationViewer` constructor to options bag.**
+   Define `ConversationViewerOptions` interface.
+   Replace 7 positional parameters with `options: ConversationViewerOptions`.
+   Assign private fields from options in constructor body.
+   Update all call sites in `test/conversation-viewer.test.ts` and `src/index.ts` (or wherever `new ConversationViewer(...)` is called).
+   Run `pnpm vitest run test/conversation-viewer.test.ts`.
+   Commit: `refactor: convert ConversationViewer to options bag constructor`
+
+6. **Define narrow `AgentIdentity` and `AgentPromptConfig` interfaces.**
+   Add interfaces to `types.ts`.
+   Make `AgentConfig` extend both; remove inherited fields from `AgentConfig` body.
+   Narrow `prompts.ts` `buildAgentPrompt` parameter from `AgentConfig` to `AgentPromptConfig`.
+   Update `test/prompts.test.ts` type annotations if needed.
+   Run `pnpm run check` and `pnpm vitest run`.
+   Commit: `refactor: define AgentIdentity and AgentPromptConfig subset interfaces`
+
+## Risks and Mitigations
+
+| Risk                                                                                    | Mitigation                                                                                                                                    |
+| --------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| Moving types breaks import paths in files not caught by grep                            | Run `pnpm run check` (full `tsc --noEmit`) after each type relocation step.                                                                   |
+| `NotificationManager` class changes test mock patterns (e.g., spreading instances)      | Tests already use the factory return as an opaque object — switching to `new` is mechanical. No spread patterns in notification tests.        |
+| `ConversationViewer` options bag breaks all test call sites at once                     | All 314 lines of tests use the same 7-arg pattern. A search-and-replace handles it. The options bag is a single-step change.                  |
+| `AgentConfig extends AgentIdentity, AgentPromptConfig` changes structural compatibility | `extends` is purely additive — existing code passing `AgentConfig` anywhere still works. Narrowed consumers gain type safety, nothing breaks. |
+| `prompts.ts` parameter narrowing breaks callers passing `AgentConfig`                   | `AgentConfig extends AgentPromptConfig`, so all existing call sites are compatible without changes.                                           |
+
+## Open Questions
+
+- Whether to define an `AgentSessionConfig` subset for `session-config.ts` (8 fields) — deferred because the narrowing ratio (8 of 22) yields less clarity benefit than `AgentIdentity` (4 of 22) or `AgentPromptConfig` (3 of 22).

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/docs/retro/0115-decompose-agent-tool.md

@@ -0,0 +1,51 @@
+---
+issue: 115
+issue_title: "refactor(pi-subagents): decompose agent-tool.ts into foreground/background modules"
+---
+
+# Retro: #115 — decompose agent-tool.ts into foreground/background modules
+
+## Final Retrospective (2026-05-21T22:30:00-04:00)
+
+### Session summary
+
+Decomposed the 579-line `tools/agent-tool.ts` into focused modules: `foreground-runner.ts` (spinner, streaming, cleanup) and `background-spawner.ts` (activity setup, notification wiring), with `agent-tool.ts` remaining as the orchestrator (411 lines).
+Before extracting, fixed two upstream API gaps: widened `onSessionCreated` callback to `(session, record)` to eliminate a `listAgents()` reverse-search, and added `toolCallId` to `AgentSpawnConfig` so the manager wires `NotificationState` at spawn time.
+Test count increased from 641 to 690.
+Released as `pi-subagents-v6.9.1`.
+
+### Observations
+
+#### What went well
+
+- The revised plan (after user feedback) was structurally clean — fixing API gaps first made the extraction trivial; each extracted module received only what it needed without workarounds.
+- TDD execution was smooth: 6 steps, all green after each commit, only minor deviations (type annotation issue, `index.ts` call-site fix).
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` (user-caught) — The initial plan was a mechanical code-move that defined 4 new interfaces (`ForegroundRunDeps`, `BackgroundSpawnDeps`, `ForegroundRunParams`, `BackgroundSpawnParams`) to paper over two upstream API gaps: a `listAgents()` reverse-search in the foreground `onSessionCreated` callback, and a post-spawn `record.notification` mutation in the background path.
+  The user asked *"What dependencies are still missing for these split tools, that they want, rather than some low level state or collaborators that they have?"*
+  — redirecting me to fix the API surface before extracting.
+  Impact: entire plan rewritten (~15 minutes), but the revised plan was significantly cleaner and the implementation went smoothly.
+
+- `missing-context` (self-identified) — During step 5 (foreground extraction), two tests in `foreground-runner.test.ts` failed because mock sessions were `{}` objects lacking a `subscribe` method required by `subscribeUIObserver`.
+  The function's dependency on `SubscribableSession` (requiring `.subscribe()`) wasn't accounted for in the test mock.
+  Impact: one test fix cycle (~2 minutes), no rework.
+
+- `missing-context` (self-identified) — Annotating `runForeground` with an explicit `Promise<AgentToolResult<any>>` return type widened the content array type from `{ type: "text", text: string }[]` to `(TextContent | ImageContent)[]`, breaking existing `content[0].text` patterns in tests.
+  Fixed by removing the explicit annotation and letting TypeScript infer the narrow type.
+  Impact: three edit cycles to diagnose and fix (~5 minutes).
+
+- `missing-context` (self-identified) — Step 1 removed `listAgents` from `AgentToolManager` but didn't update the construction site in `index.ts`.
+  `pnpm run check` caught it in step 4.
+  Impact: one-line fix in the same commit, no rework.
+
+#### What caused friction (user side)
+
+- The initial plan's size and mechanical nature required a user redirect.
+  The `/plan-issue` prompt's Design Overview section asks to sketch consumer call sites for *new collaborators*, but the same Tell-Don't-Ask check should apply to *extracted* modules' interactions with their upstream dependencies.
+  A prompt tweak could help the agent catch this pattern earlier.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added extraction-specific Tell-Don't-Ask verification step to the Design Overview section: sketch the extracted module's upstream interactions before planning the extraction, fix API gaps first.

package/package.json

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

package/src/agent-manager.ts

@@ -13,10 +13,12 @@ import { AgentRecord } from "./agent-record.js";
 import type { AgentRunner } from "./agent-runner.js";
 import { AgentTypeRegistry } from "./agent-types.js";
 import { debugLog } from "./debug.js";
+import { NotificationState } from "./notification-state.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { buildParentSnapshot } from "./parent-snapshot.js";
 import { subscribeRecordObserver } from "./record-observer.js";
 import type { RunConfig } from "./runtime.js";
-import type { AgentInvocation, IsolationMode, ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { AgentInvocation, IsolationMode, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 import type { WorktreeManager } from "./worktree.js";
 import { WorktreeState } from "./worktree-state.js";
 
@@ -72,12 +74,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 +159,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 +252,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/agent-runner.ts

@@ -15,9 +15,10 @@ import {
 import type { AgentConfigLookup } from "./agent-types.js";
 import { extractText } from "./context.js";
 import { detectEnv } from "./env.js";
+import type { ParentSnapshot } from "./parent-snapshot.js";
 import { assembleSessionConfig } from "./session-config.js";
 import { deriveSubagentSessionDir } from "./session-dir.js";
-import type { ParentSnapshot, ShellExec, SubagentType, ThinkingLevel } from "./types.js";
+import type { ShellExec, SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
 const EXCLUDED_TOOL_NAMES = ["Agent", "get_subagent_result", "steer_subagent"];

package/src/env.ts

@@ -3,7 +3,13 @@
  */
 
 import { debugLog } from "./debug.js";
-import type { EnvInfo, ShellExec } from "./types.js";
+import type { ShellExec } from "./types.js";
+
+export interface EnvInfo {
+  isGitRepo: boolean;
+  branch: string;
+  platform: string;
+}
 
 export async function detectEnv(exec: ShellExec, cwd: string): Promise<EnvInfo> {
   let isGitRepo = false;

package/src/index.ts

@@ -18,7 +18,7 @@ import { AgentTypeRegistry } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { SessionLifecycleHandler, ToolStartHandler } from "./handlers/index.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
-import { buildEventData, createNotificationSystem } from "./notification.js";
+import { buildEventData, type NotificationDetails, NotificationManager } from "./notification.js";
 import { createNotificationRenderer } from "./renderer.js";
 import { createSubagentRuntime } from "./runtime.js";
 import { publishSubagentsService, unpublishSubagentsService } from "./service.js";
@@ -28,7 +28,6 @@ import { createAgentTool } from "./tools/agent-tool.js";
 import { createGetResultTool } from "./tools/get-result-tool.js";
 import { getModelLabelFromConfig } from "./tools/helpers.js";
 import { createSteerTool } from "./tools/steer-tool.js";
-import { type NotificationDetails } from "./types.js";
 import { createAgentsMenuHandler } from "./ui/agent-menu.js";
 import {
   AgentWidget,
@@ -48,7 +47,7 @@ export default function (pi: ExtensionAPI) {
   // ---- Notification system ----
   // runtime.widget is assigned after AgentManager construction; arrow closures
   // capture `runtime` by reference so they always read the current value.
-  const notifications = createNotificationSystem({
+  const notifications = new NotificationManager({
     sendMessage: (msg, opts) => pi.sendMessage(msg, opts),
     agentActivity: runtime.agentActivity,
     markFinished: (id) => runtime.markFinished(id),
@@ -169,7 +168,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),