@gotgenes/pi-subagents 16.1.0 → 16.1.1

package/CHANGELOG.md

@@ -5,6 +5,13 @@ 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).
 
+## [16.1.1](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.1.0...pi-subagents-v16.1.1) (2026-06-14)
+
+
+### Bug Fixes
+
+* abort all subagents on parent interrupt ([#403](https://github.com/gotgenes/pi-packages/issues/403)) ([0c951d3](https://github.com/gotgenes/pi-packages/commit/0c951d3da27123a61c95a7f9a07ddb4cf5ed7e89))
+
 ## [16.1.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v16.0.0...pi-subagents-v16.1.0) (2026-06-14)
 
 

package/dist/public.d.ts

@@ -29,6 +29,25 @@ type LifetimeUsage = {
     cacheWrite: number;
 };
 
+/**
+ * subagent-state.ts — SubagentState value object: lifecycle status and metrics.
+ *
+ * Owns the passive, readable state of a subagent — status, result, error,
+ * timestamps, and stats (toolUses, lifetimeUsage, compactionCount) — together
+ * with the transition methods (markRunning, markCompleted, …) and accumulation
+ * methods (incrementToolUses, addUsage, incrementCompactions) that mutate it.
+ *
+ * State is encapsulated behind getters; external code reads through them but
+ * mutates only via the transition/accumulation methods. The value object owns
+ * all of its own mutations — no field is written from outside.
+ *
+ * Subagent holds one of these privately and delegates its getters and mutation
+ * methods to it. Extracting it lets the lifecycle state machine and the
+ * session-event observer be unit-tested without constructing an executor.
+ */
+
+type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
+
 /**
  * workspace.ts — The single generative extension seam (ADR 0002, Phase 16 Step 2).
  *
@@ -70,28 +89,6 @@ interface WorkspaceProvider {
     prepare(ctx: WorkspacePrepareContext): Promise<Workspace | undefined>;
 }
 
-/**
- * subagent.ts — Subagent class with encapsulated status-transition logic and per-subagent behavior.
- *
- * Status transitions (status, result, error, startedAt, completedAt) are owned
- * by the class and exposed via transition methods. External code reads these
- * fields through public properties but cannot write them directly.
- *
- * Stats (toolUses, lifetimeUsage, compactionCount) are owned by the class and
- * accumulated via mutation methods (incrementToolUses, addUsage, incrementCompactions).
- *
- * Behavior (abort, steer buffering) lives on the subagent rather than on
- * SubagentManager — each subagent manages its own lifecycle concerns.
- *
- * The child's working directory is supplied by a registered WorkspaceProvider
- * (the workspace seam); with no provider the child runs in the parent cwd.
- *
- * Phase-specific collaborators (subagentSession, notification) are attached
- * after construction as lifecycle information becomes available.
- */
-
-type SubagentStatus = "queued" | "running" | "completed" | "steered" | "aborted" | "stopped" | "error";
-
 /**
  * service.ts — Public API surface for cross-extension access to subagents.
  *

package/docs/architecture/architecture.md

@@ -107,6 +107,8 @@ classDiagram
         +id: string
         +type: SubagentType
         +description: string
+        -state: SubagentState
+        -execution: SubagentExecution
         +status: SubagentStatus
         +result?: string
         +error?: string
@@ -114,13 +116,8 @@ classDiagram
         +lifetimeUsage: LifetimeUsage
         +subagentSession?: SubagentSession
         +notification?: NotificationState
-        +markRunning()
-        +markCompleted()
-        +markAborted()
-        +markSteered()
-        +markError()
-        +markStopped()
-        +resetForResume()
+        +markRunning() delegates
+        +markCompleted() delegates
         +run()
         +resume(prompt, signal)
         +abort(): boolean
@@ -138,6 +135,34 @@ classDiagram
         +releaseListeners()
     }
 
+    class SubagentState {
+        +status: SubagentStatus
+        +result?: string
+        +error?: string
+        +startedAt: number
+        +completedAt?: number
+        +toolUses: number
+        +lifetimeUsage: LifetimeUsage
+        +compactionCount: number
+        +markRunning() ... markStopped()
+        +resetForResume()
+        +incrementToolUses()
+        +addUsage(delta)
+        +incrementCompactions()
+    }
+
+    class SubagentExecution {
+        +createSubagentSession(params)
+        +snapshot: ParentSnapshot
+        +prompt: string
+        +baseCwd: string
+        +observer?: SubagentLifecycleObserver
+        +getRunConfig?()
+        +getWorkspaceProvider?()
+        +model?, maxTurns?, thinkingLevel?
+        +parentSession?, signal?
+    }
+
     class SubagentManager {
         +spawn(snapshot, type, prompt, config)
         +spawnAndWait(snapshot, type, prompt, config)
@@ -173,6 +198,8 @@ classDiagram
     }
 
     SubagentManager --> Subagent : creates/manages
+    Subagent --> SubagentState : owns (private)
+    Subagent --> SubagentExecution : runs via (mandatory)
     SubagentManager --> ParentSnapshot : receives at spawn
     SubagentsService --> SubagentManager : wraps via adapter
     SubagentManager --> AgentTypeRegistry : resolves types
@@ -247,7 +274,7 @@ sequenceDiagram
 
 ## Module organization
 
-The extension has 56 source files organized into six domains plus entry-point wiring.
+The extension has 58 source files organized into six domains plus entry-point wiring.
 All eight domains have directories: `config/`, `session/`, `lifecycle/`, `observation/`, `service/`, `tools/`, `ui/`, and `handlers/`.
 Issue #164 moved the 26 previously flat root-level files into five new domain directories, reducing the root to 5 files + 8 directories.
 
@@ -283,6 +310,7 @@ src/
 │   ├── subagent-session.ts         born-complete child session: turn loop, steer, dispose
 │   ├── turn-limits.ts              normalizeMaxTurns (turn-count policy)
 │   ├── subagent.ts                 owns full execution lifecycle (run, abort, steer, workspace)
+│   ├── subagent-state.ts           lifecycle status + metrics value object (transitions, accumulators)
 │   ├── concurrency-limiter.ts       background admission gate: schedules run thunks FIFO against the limit
 │   ├── parent-snapshot.ts          immutable spawn-time parent state
 │   ├── child-lifecycle.ts          child-execution lifecycle event publisher
@@ -325,6 +353,7 @@ src/
 │
 └── handlers/                       event handlers
     ├── index.ts                    barrel re-export
+    ├── interrupt.ts                turn_start handler — abort all subagents on parent interrupt (ESC)
     ├── lifecycle.ts                session_start, session_before_switch, session_shutdown
     └── tool-start.ts               tool_execution_start handler
 ```
@@ -646,7 +675,8 @@ Bags with 10+ fields are the highest priority for decomposition.
 | `AgentToolDeps`               | 8                                                            | agent-tool                                        | ✓ done    |
 | `AgentMenuDeps`               | 8                                                            | agent-menu                                        | ✓ done    |
 | `ConversationViewerOptions`   | 8                                                            | conversation-viewer                               | Low       |
-| `SubagentInit`                | 8                                                            | subagent                                          | Low       |
+| `SubagentInit`                | 5 (id, type, description, invocation, execution, state)      | subagent (one production site)                    | ✓ done    |
+| `SubagentExecution`           | 12 (4 mandatory: factory, snapshot, prompt, baseCwd)         | subagent (mandatory collaborator)                 | ✓ done    |
 
 ### Complexity hotspots
 
@@ -864,7 +894,7 @@ Updated health metrics (fallow, package-wide including tests):
 | Metric                     | Phase 16 baseline              | Current                                       |
 | -------------------------- | ------------------------------ | --------------------------------------------- |
 | Health score               | 78/100 (B)                     | 78/100 (B)                                    |
-| Source LOC                 | 7,778 (57 files)               | ~7,400 (56 files)                             |
+| Source LOC                 | 7,778 (57 files)               | ~7,400 (57 files)                             |
 | Dead code                  | 0 files, 0 exports             | 0 files, 0 exports                            |
 | Maintainability index      | 90.8 (good)                    | 90.8 (good)                                   |
 | Avg / P90 cyclomatic       | 1.4 / 2                        | 1.4 / 2                                       |
@@ -914,7 +944,7 @@ Priority = Impact × (6 − Risk).
   The settings `onMaxConcurrentChanged` hook wires to `limiter.recheck()` in `index.ts`; `dispose()` calls `limiter.clear()` to drop pending thunks.
 - Outcome: dependency direction is strictly manager → limiter (no callback back-edge; the `prefer-const` eslint-disable in the test helper is deleted); the observer's two queue relays are gone; every spawned agent has a `promise` at spawn, collapsing `waitForAll`'s `while (true)` drain loop and its eslint-disable.
 
-#### Step 2 — Extract `SubagentState`; make `Subagent` execution deps mandatory ([#373])
+#### Step 2 — Extract `SubagentState`; make `Subagent` execution deps mandatory ([#373]) ✅ Complete
 
 - Targets: `src/lifecycle/subagent.ts` (state fields, transition/accumulation methods, constructor, `run()` guards), `src/lifecycle/subagent-manager.ts` (`spawn`), `test/helpers/make-subagent.ts`, `test/lifecycle/subagent.test.ts`, `test/observation/record-observer.test.ts`.
 - Smell: Category B (god interface — ~20 fields) and Category D (constructibility: "optional for tests" fields with compensating runtime throws).
@@ -926,7 +956,9 @@ Priority = Impact × (6 − Risk).
 - Outcome: state-machine and observer tests target `SubagentState` directly (no stub execution); `Subagent` is construct-complete with no optional execution fields and no runtime throws (grep-verifiable: no "not configured for execution" in `subagent.ts`); the record-vs-executor duality is resolved, not type-encoded.
 - Scope boundary: stats stay on `SubagentState` for now.
   Hoisting **metrics** into a projection over the child session's event stream and extracting **result delivery** (`notification`/`resultConsumed`) into its own domain are the remaining two of the four domains, deferred to a later phase per the refinement.
-- The issue ([#373]) is filed under the prior "decompose `SubagentInit` into present-or-absent bags" framing; update its description to this stronger target before implementation.
+- Landed: `SubagentState` (`src/lifecycle/subagent-state.ts`) owns status/result/error/timestamps/stats and the transition/accumulation methods; `Subagent` delegates getters and `markX`/`incrementX`/`addUsage` to it.
+  `subscribeSubagentObserver` targets `SubagentState`, so observer and state-machine tests no longer stub execution.
+  `SubagentExecution` is a mandatory constructor collaborator (production wires it in the single `spawn()` site; passive records build via `make-subagent.ts`), and the two `run()` throws are gone.
 
 #### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374])
 

package/docs/plans/0373-extract-subagent-state.md

@@ -0,0 +1,250 @@
+---
+issue: 373
+issue_title: "Extract SubagentState; make Subagent execution deps mandatory"
+---
+
+# Extract `SubagentState`; make `Subagent` execution deps mandatory
+
+## Problem Statement
+
+`Subagent` is simultaneously a passive record and an executor.
+Its `SubagentInit` carries ~20 fields — nearly all optional with "required for `run()`, optional for tests" semantics — and `run()` compensates with two runtime guards that throw `"Subagent not configured for execution"`.
+This violates the construct-complete principle: one class is both a display-only snapshot (tests and the UI read `.status`/`.result`/stats) and an executor (production wires the session factory, observer, run config, and workspace provider).
+
+The earlier framing — split `SubagentInit` into a present-or-absent `SubagentRunSpec` + `SubagentExecutionDeps` pair — only *type-encodes* the duality; it does not remove it.
+The stronger move (captured in the architecture doc's "First-principles refinement") observes that the passive-record need is *test-only*: production constructs a `Subagent` in exactly one place (`SubagentManager.spawn`), always fully wired.
+So the readable state is the common denominator (extract it as a value object), and the execution deps are the optional-only-for-tests part (make them mandatory; push the passive case into the test factory).
+
+## Goals
+
+- Extract `SubagentState` — a value object owning status, result, error, timestamps, and stats (`toolUses`, `lifetimeUsage`, `compactionCount`) plus their transition (`markRunning`, `markCompleted`, …) and accumulation (`incrementToolUses`, `addUsage`, `incrementCompactions`) methods.
+- `Subagent` holds one `SubagentState` privately; its existing getters and `markX`/`incrementX`/`addUsage` methods become one-line delegations, leaving the ~40 read sites and the external mutation callers (`markStopped` in the manager, `markCompleted` in `get-result-tool.test.ts`) unchanged.
+- Collapse the ~12 remaining execution inputs into a single **mandatory** `SubagentExecution` collaborator; `SubagentManager.spawn` always supplies it.
+- Delete the two `"not configured for execution"` throws in `run()` — impossible by construction.
+- Move the passive-record construction entirely into `test/helpers/make-subagent.ts`.
+- Retarget `subscribeSubagentObserver` at `SubagentState` so state-machine and observer tests need no stub execution.
+
+This change is **not breaking** for the published service surface.
+`src/service/service.ts` exposes `SubagentRecord`, `SubagentStatus`, and the spawn-config types — not `SubagentInit` or the `Subagent` constructor.
+The read API (getters, `SubagentStatus`) is unchanged; only the internal constructor signature changes.
+
+## Non-Goals
+
+- Hoisting **metrics** (tool uses, token usage, compaction count) into a projection over the child session's event stream — stats stay on `SubagentState` for now (the third of four domains in the refinement, deferred).
+- Extracting **result delivery** (`notification` / `resultConsumed`) into its own domain — the fourth domain, deferred.
+- Encapsulating run start / making `promise` and `notification` read-only — that is Step 3 (#374); `notification` stays created in the constructor here.
+- Extracting run-listener / workspace-bracket collaborators — Step 4 (#375).
+- Renaming `record-observer.ts` — only its parameter type changes.
+
+## Background
+
+- `src/lifecycle/subagent.ts` — the class under change.
+  State fields (`_status`, `_result`, `_error`, `_startedAt`, `_completedAt`, `_toolUses`, `_lifetimeUsage`, `_compactionCount`) sit behind getters; transition/accumulation methods mutate them.
+  `run()` reads the execution inputs and throws if `createSubagentSession`/`snapshot`/`prompt` are missing.
+  `resume()` reads `observer` and throws only on a missing session (a genuine runtime condition — kept).
+- `src/lifecycle/subagent-manager.ts` — `spawn()` (line ~139) is the **only** production `new Subagent(...)` site; it sets the initial status (`queued` for background so the limiter thunk's `status !== "queued"` guard works, `running` for foreground).
+- `src/observation/record-observer.ts` — `subscribeSubagentObserver(session, record, { onCompact })` calls `record.incrementToolUses()`, `record.addUsage(…)`, `record.incrementCompactions()`, and forwards `onCompact(record, info)`.
+- `src/lifecycle/usage.ts` — `LifetimeUsage` type and the `addUsage(into, delta)` accumulator that `SubagentState` will own.
+- `test/helpers/make-subagent.ts` — `createTestSubagent` builds passive records; stat shorthands apply via mutation methods.
+- `test/lifecycle/subagent.test.ts` (~700 LOC) and `test/observation/record-observer.test.ts` — the test files that construct `Subagent` directly.
+
+AGENTS.md / code-design constraints that apply:
+
+- Keep Pi SDK imports out of `SubagentState` — it is a pure value object (imports only `LifetimeUsage`/`addUsage`).
+- `Subagent` is exported from the `types.ts` barrel; verify the barrel re-export still resolves after the file split.
+- `SubagentStatus` is re-exported by `src/service/service.ts` from `#src/lifecycle/subagent` — keep that import path valid (re-export `SubagentStatus` from `subagent.ts` even if its definition moves to `subagent-state.ts`), so the public type bundle path is unchanged.
+
+## Design Overview
+
+### `SubagentState` value object (`src/lifecycle/subagent-state.ts`)
+
+A pure, independently constructible value object. `SubagentStatus` moves here (its natural home) and is re-exported from `subagent.ts`.
+
+```ts
+export type SubagentStatus =
+	| "queued" | "running" | "completed" | "steered"
+	| "aborted" | "stopped" | "error";
+
+export interface SubagentStateInit {
+	status?: SubagentStatus;
+	result?: string;
+	error?: string;
+	startedAt?: number;
+	completedAt?: number;
+	// stats always start at zero; callers accumulate via mutation methods
+}
+
+export class SubagentState {
+	constructor(init?: SubagentStateInit); // status ?? "queued", startedAt ?? Date.now()
+	// getters: status, result, error, startedAt, completedAt,
+	//          toolUses, lifetimeUsage (Readonly), compactionCount
+	// transitions: markRunning, markCompleted, markAborted, markSteered,
+	//              markError, markStopped, resetForResume
+	// accumulators: incrementToolUses, addUsage, incrementCompactions
+}
+```
+
+It owns its mutations (no output arguments — methods write only its own private fields) and carries no upstream dependency beyond `usage.ts`.
+
+### `SubagentExecution` collaborator (in `src/lifecycle/subagent.ts`)
+
+```ts
+export interface SubagentExecution {
+	createSubagentSession: (params: CreateSubagentSessionParams) => Promise<SubagentSession>;
+	snapshot: ParentSnapshot;
+	prompt: string;
+	baseCwd: string;
+	observer?: SubagentLifecycleObserver;
+	getRunConfig?: () => RunConfig;
+	getWorkspaceProvider?: () => WorkspaceProvider | undefined;
+	model?: Model<any>;
+	maxTurns?: number;
+	thinkingLevel?: ThinkingLevel;
+	parentSession?: ParentSessionInfo;
+	signal?: AbortSignal;
+}
+```
+
+The four fields the old `run()` guards required (`createSubagentSession`, `snapshot`, `prompt`, plus `baseCwd`) are mandatory; the genuinely-optional behavior knobs stay optional.
+
+### `Subagent` constructor
+
+```ts
+export interface SubagentInit {
+	id: string;
+	type: SubagentType;
+	description: string;
+	invocation?: AgentInvocation;
+	execution: SubagentExecution;   // mandatory — no more "optional for tests"
+	state?: SubagentState;          // defaults to new SubagentState() (fresh "queued")
+}
+```
+
+`SubagentInit` drops from ~20 fields to 5.
+`Subagent` keeps `id`/`type`/`description`/`invocation`, `abortController`, `subagentSession?`, `notification?`, steer buffer, and per-run listener handles; it holds `private readonly state` and `private readonly execution`.
+Getters and mutation methods delegate one line to `this.state`.
+`notification` is still created in the constructor from `execution.parentSession?.toolCallId` (Step 3 moves it).
+
+### Consumer call site — `SubagentManager.spawn`
+
+```ts
+const execution: SubagentExecution = {
+	createSubagentSession: this.createSubagentSession,
+	snapshot, prompt, baseCwd: this.baseCwd,
+	observer: this.buildObserver(options),
+	getRunConfig: this.getRunConfig,
+	getWorkspaceProvider: () => this._workspaceProvider,
+	model: options.model, maxTurns: options.maxTurns,
+	thinkingLevel: options.thinkingLevel,
+	parentSession: options.parentSession, signal: options.signal,
+};
+const record = new Subagent({
+	id, type, description: options.description, invocation: options.invocation,
+	execution,
+	state: new SubagentState({ status: options.isBackground ? "queued" : "running", startedAt: Date.now() }),
+});
+```
+
+Tell-Don't-Ask: the execution bundle is assembled once and handed over; nothing reaches back into `spawn`'s locals afterward.
+
+### Observer retarget (`src/observation/record-observer.ts`)
+
+The observer accumulates *stats*, not lifecycle — point it at `SubagentState` and drop the record from `onCompact`:
+
+```ts
+export function subscribeSubagentObserver(
+	session: SubscribableSession,
+	state: SubagentState,
+	options?: { onCompact?: (info: CompactionInfo) => void },
+): () => void
+```
+
+`Subagent.run()`/`resume()` wire it with `this.state` and close over `this` to forward itself to the lifecycle observer:
+
+```ts
+this.attachObserver(subscribeSubagentObserver(this.subagentSession, this.state, {
+	onCompact: (info) => this.execution.observer?.onCompacted?.(this, info),
+}));
+```
+
+This removes the observer's only dependency on `Subagent`, so observer tests construct a `SubagentState` directly.
+`SubagentLifecycleObserver.onCompacted(agent, info)` is unchanged — it still receives the `Subagent`.
+
+Decision: the observer takes `SubagentState` concretely rather than a one-off narrow `incrementToolUses`/`addUsage`/`incrementCompactions` interface.
+`SubagentState` is a cohesive owned value object, not a wide dependency bag, and a single internal call site does not justify a speculative interface (recorded in Open Questions).
+
+### Edge cases
+
+- **Initial status for the limiter guard** — production passes `state: new SubagentState({ status: queued|running })`; the background path still observes `queued` so `limiter.schedule(() => record.status !== "queued" ? … : record.run())` behaves identically.
+- **`resume()` without a prior run** — the `"not configured for resume — missing session"` throw stays; it guards a genuine runtime state (no session was ever created), not a construction concern.
+- **`make-subagent.ts` passive records** — built as `state: new SubagentState({ status: "completed", result, startedAt, completedAt })` plus a `makeStubExecution()`; stat shorthands keep delegating through `Subagent`'s methods.
+
+## Module-Level Changes
+
+- **`src/lifecycle/subagent-state.ts`** (new) — `SubagentState`, `SubagentStateInit`, and the `SubagentStatus` type (moved from `subagent.ts`).
+- **`src/lifecycle/subagent.ts`** —
+  - Re-export `SubagentStatus` from `subagent-state.ts` (keeps service.ts import path valid).
+  - Add `SubagentExecution`; rewrite `SubagentInit` to the 5-field shape; remove the flat execution/run-config fields.
+  - Remove the (unused) `isBackground?` field from `SubagentInit` — never read in this class.
+  - Hold `private readonly state` / `private readonly execution`; convert getters and `markX`/`incrementX`/`addUsage`/`resetForResume` to delegations.
+  - `run()`: delete the two `"not configured for execution"` throws; read inputs from `this.execution`; wire the observer at `this.state`.
+  - `resume()`: read `observer` from `this.execution`; keep the missing-session throw.
+- **`src/lifecycle/subagent-manager.ts`** — `spawn()` builds the `SubagentExecution` bundle and the initial `SubagentState`; no other change (`markStopped` calls untouched).
+- **`src/observation/record-observer.ts`** — param `record: Subagent` → `state: SubagentState`; `onCompact` signature `(record, info)` → `(info)`; update the JSDoc bullet wording.
+- **`test/helpers/make-subagent.ts`** — add `makeStubExecution()`; build the passive record via `state` + `execution`.
+- **`test/lifecycle/subagent.test.ts`** — funnel constructions through a local helper (prep refactor); move the pure state-machine `describe` blocks to the new state test; supply `execution` everywhere; update the missing-factory test (the throw is gone — replace with a type-level/construction assertion or remove).
+- **`test/lifecycle/subagent-state.test.ts`** (new) — state-machine + accumulation tests targeting `SubagentState` directly.
+- **`test/observation/record-observer.test.ts`** — `makeRecord` → build a `SubagentState`; assert stats on it; `onCompact` test uses `(info)`.
+- **Docs** —
+  - `docs/architecture/architecture.md`: add `subagent-state.ts` to the lifecycle directory listing; update the `Subagent` class diagram (state delegations, new collaborators); mark **Step 2 ✅ Complete**; refresh the Phase 17 problem-statement prose (line ~879) and the type-complexity table (`SubagentInit` row at line ~649, add `SubagentExecution`).
+  - `.pi/skills/package-pi-subagents/SKILL.md`: Lifecycle domain `10 → 11` modules (add `subagent-state.ts`); total `56 → 57` files.
+
+Grep sweep confirmed no other `src/`, `test/`, or `SKILL.md` references to the removed flat fields or the `"not configured for execution"` string outside `subagent.ts`.
+
+## Test Impact Analysis
+
+1. **New tests the extraction enables** — `test/lifecycle/subagent-state.test.ts` exercises every transition and accumulator on `SubagentState` with no `Subagent`, no execution stub, no session.
+   This is the construct-complete payoff: the state machine is now unit-testable in isolation.
+2. **Tests that become redundant** — the state-machine `describe` blocks in `subagent.test.ts` (`markRunning`, `markCompleted`, `markAborted`, `markSteered`, `markError`, `markStopped`, `incrementToolUses`, `addUsage`, `incrementCompactions`, `resetForResume`, and the pure constructor-defaults cases) move out, leaving `subagent.test.ts` to cover identity, session-encapsulation delegation, abort, `run()`/`resume()`, `completeRun`/`failRun`, and listeners.
+   `record-observer.test.ts` no longer constructs a `Subagent` — it builds a `SubagentState`.
+3. **Tests that must stay as-is** — `run()`/`resume()` integration tests genuinely exercise the executor (factory wiring, observer lifecycle, workspace bracket); the `createTestSubagent` consumers across `test/ui/` and `test/tools/` exercise read sites and are unaffected (the helper absorbs the construction change).
+
+## TDD Order
+
+1. **Extract `SubagentState` (pure addition; lift-and-shift prep).**
+   - Create `src/lifecycle/subagent-state.ts` and `test/lifecycle/subagent-state.test.ts` (red → green for every transition/accumulator).
+   - Refactor `Subagent` to hold a `SubagentState` built from the *existing* `SubagentInit` fields; getters/mutators delegate. `SubagentStatus` moves to `subagent-state.ts`, re-exported from `subagent.ts`.
+   - In `subagent.test.ts`, introduce a local construction helper and route call sites through it; move the pure state-machine `describe` blocks into `subagent-state.test.ts`.
+   - No consumer breaks (init shape unchanged). `pnpm run check` + `test`.
+   - Commit: `refactor: extract SubagentState value object (#373)`.
+2. **Retarget the observer at `SubagentState`.**
+   - Change `subscribeSubagentObserver` to accept `SubagentState` and an `onCompact(info)`; update the two `subagent.ts` call sites (pass `this.state`, close over `this`).
+   - Rewrite `record-observer.test.ts` to build a `SubagentState`.
+   - Commit: `refactor: target SubagentState in subagent observer (#373)`.
+3. **Make execution mandatory (the atomic construction flip).**
+   - Add `SubagentExecution`; rewrite `SubagentInit` to the 5-field shape; remove flat execution/run-config fields and `isBackground?`; delete the two `run()` throws; read from `this.execution`.
+   - Update the single production site (`subagent-manager.ts spawn`) and `make-subagent.ts` (`makeStubExecution` + `state`) and the `subagent.test.ts` helper/`createRunnableAgent`/`createResumableAgent` in the **same commit** — removing the optional fields breaks every construction at the type level simultaneously.
+   - Adjust the now-obsolete "missing session factory" test (throw is gone).
+   - `pnpm run check`, `lint`, `test`, `fallow dead-code`.
+   - Commit: `refactor: make Subagent execution deps mandatory (#373)`.
+4. **Docs.**
+   - Update `architecture.md` (file listing, class diagram, mark Step 2 complete, prose, type table) and `SKILL.md` (domain counts).
+   - Commit: `docs: record SubagentState extraction in architecture and skill (#373)`.
+
+Optionally run `pnpm run verify:public-types` after Step 3 to confirm the public bundle is unaffected (expected: no change — the bundle does not reference `SubagentInit`).
+
+## Risks and Mitigations
+
+- **Large test file churn (`subagent.test.ts`, ~700 LOC).**
+  Mitigated by lift-and-shift: Step 1 funnels constructions through a local helper and moves state tests out, so Step 3's mandatory-execution flip edits the helper + two run/resume factories rather than rewriting the file.
+- **Initial-status regression for the limiter.**
+  Production explicitly sets `state` status in `spawn`; a `subagent-manager` test should assert a background spawn reports `queued` before its slot opens (existing coverage; re-verify).
+- **`SubagentStatus` re-export path.**
+  Keep `SubagentStatus` re-exported from `subagent.ts`; `verify:public-types` (and `pnpm run check`) confirm `service.ts` still resolves it.
+- **Circular import (`subagent.ts` ↔ `subagent-state.ts`).**
+  Avoided: `subagent-state.ts` defines `SubagentStatus` and imports nothing from `subagent.ts`; `subagent.ts` imports `SubagentState`/`SubagentStatus` from `subagent-state.ts`.
+
+## Open Questions
+
+- Whether the observer should accept a narrow `{ incrementToolUses; addUsage; incrementCompactions }` interface instead of `SubagentState` concretely — deferred; revisit if a second consumer of the stats sink appears (defer-until-needed, per the metrics-projection work in a later phase).
+- Whether the `make-subagent.ts` stat shorthands should construct `SubagentState` directly rather than delegating through `Subagent` — cosmetic; left until Step 7's fixture consolidation (#378).

package/docs/plans/0403-abort-subagents-on-interrupt.md

@@ -0,0 +1,180 @@
+---
+issue: 403
+issue_title: "Pressing Escape does not stop subagent/background agent"
+---
+
+# Abort subagents on parent interrupt (ESC)
+
+## Problem Statement
+
+A user reports that pressing Escape in the Pi terminal to cancel the current work does not stop a running subagent — the agent keeps going despite the cancel request.
+The reporter is a third party (`khalid244`); the operator confirmed the direction is to implement ESC-to-abort for both foreground and background subagents, aborting all running and queued background agents on a single ESC.
+
+The root cause splits cleanly by execution mode:
+
+1. Foreground subagents already receive the parent's abort signal through the tool boundary (`tool.execute(signal)` → `Subagent.wireSignal` → `abort()` → child `session.abort()`), so they should already stop on ESC.
+2. Background subagents are detached by design: `spawnBackground()` never forwards the parent signal, and `manager.abortAll()` runs only on `session_shutdown`.
+   There is no wiring from a parent interrupt to background-agent abort, so ESC does nothing to them.
+   This is the reproducible bug.
+
+## Goals
+
+- Pressing ESC (the parent agent-loop interrupt) aborts all running and queued background subagents.
+- Add a regression guard test proving a foreground subagent's child session is aborted when the parent signal fires.
+- Reuse the existing `manager.abortAll()` semantics (abort running, mark queued stopped, clear the limiter) so ESC stops every active subagent in one action.
+
+This is an intentional behavior change: background subagents that previously survived ESC will now stop.
+It is a bug fix (`fix:`), not a breaking change — no config key, default value, or output shape changes, and detached-survives-ESC was a limitation rather than a contract.
+
+## Non-Goals
+
+- Selective or interactive abort (choosing which agent to stop) — out of scope.
+- A dedicated `abortBackground()` that excludes foreground agents — `abortAll()` is reused; foreground agents are already aborted by their own signal wiring, so the overlap is redundant-but-harmless.
+- Changing background-agent detachment for any path other than the ESC interrupt (e.g., the tool still returns immediately on spawn).
+- Confirmation prompts or status messaging on abort.
+
+## Background
+
+Relevant modules and the verified runtime facts behind the design:
+
+- `src/tools/foreground-runner.ts` — `runForeground(..., signal, ...)` forwards the parent `signal` into `manager.spawnAndWait({ signal })`.
+- `src/lifecycle/subagent.ts` — `run()` calls `this.wireSignal(this.execution.signal, () => this.abort())`; `abort()` fires `abortController.abort()` and marks the record stopped.
+- `src/lifecycle/subagent-session.ts` — `runTurnLoop` calls `forwardAbortSignal(session, opts.signal)`, which calls `session.abort()` when the signal fires.
+- `src/tools/background-spawner.ts` — `spawnBackground()` omits `signal` entirely; background agents are detached.
+- `src/lifecycle/subagent-manager.ts` — `abortAll()` aborts running, marks queued stopped, and clears the limiter; currently called only from `src/handlers/lifecycle.ts` on shutdown.
+- `src/handlers/tool-start.ts`, `src/handlers/lifecycle.ts`, `src/handlers/index.ts` — the existing `handlers/` pattern: small classes with a narrow injected interface, registered in `index.ts`.
+
+Verified SDK facts (from the pinned peer deps under `node_modules/@earendil-works/`):
+
+- The interactive ESC handler calls `agent.abort()` while streaming (`pi-coding-agent` `interactive-mode.js`, `restoreQueuedMessagesToEditor({ abort: true })`).
+- `pi-agent-core` `agent.js`: each run creates a fresh `AbortController`; `agent.abort()` calls `activeRun.abortController.abort()`; on normal completion `finishRun()` discards the controller **without** aborting it.
+  Therefore the parent signal's `abort` event fires only on a real interrupt, never on normal turn completion — latching `abortAll()` to it will not spuriously kill background agents at turn end.
+- The signal passed to `tool.execute(...)` (`agent-loop.js` line ~419) is that same per-run signal.
+- Extensions read the live per-run parent signal via `ctx.signal` (`ExtensionContext.signal: AbortSignal | undefined`, undefined when idle).
+- `pi.on("turn_start", (event, ctx) => ...)` is a registered event whose handler receives `ExtensionContext`; `turn_start` fires once at the start of every turn while streaming, so its `ctx.signal` is always the current run's signal.
+
+AGENTS.md constraint: pi-subagents is a minimal core with dependency arrows pointing inward.
+The new handler depends only on a narrow manager interface; no consumer knowledge leaks into the manager.
+
+## Design Overview
+
+Add a small `InterruptHandler` that latches the current parent abort signal and, on abort, tells the manager to abort all subagents.
+Drive it from `turn_start` so the latch always tracks the live per-run signal — including across runs and turns that execute no tools.
+
+Why `turn_start` rather than `tool_execution_start`: a background agent can outlive the run that spawned it.
+If the user later interrupts a turn that ran no subagent tool, only a turn-level latch still holds that run's signal.
+`turn_start` fires every turn with the current `ctx.signal`, so the latch is always current.
+
+The latch dedups by reference: most turns reuse the same signal (no-op); a new run's signal triggers a detach-and-rewire.
+The `abort` listener is `{ once: true }`; on normal completion the run's `AbortController` is discarded and garbage-collected with its listener, and the next `turn_start` detaches the stale reference.
+
+### Manager interface (narrow, Tell-Don't-Ask)
+
+```typescript
+/** Narrow manager interface — only the method the interrupt handler calls. */
+export interface InterruptManager {
+  abortAll(): number;
+}
+
+/** Minimal context shape — only the field the handler reads. */
+interface InterruptCtx {
+  signal: AbortSignal | undefined;
+}
+```
+
+### Handler
+
+```typescript
+export class InterruptHandler {
+  private latched?: AbortSignal;
+  private detach?: () => void;
+
+  constructor(private readonly manager: InterruptManager) {}
+
+  handleTurnStart(ctx: InterruptCtx): void {
+    const signal = ctx.signal;
+    if (signal === this.latched) return;
+    this.detach?.();
+    this.detach = undefined;
+    this.latched = signal;
+    if (!signal) return;
+    const onAbort = (): void => {
+      this.manager.abortAll();
+    };
+    signal.addEventListener("abort", onAbort, { once: true });
+    this.detach = () => signal.removeEventListener("abort", onAbort);
+  }
+}
+```
+
+### Consumer call site (`index.ts`)
+
+```typescript
+const interrupt = new InterruptHandler(manager);
+pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx));
+```
+
+The handler talks to `manager` through a one-method interface, reads one field of `ctx`, and performs no chained access — no Law-of-Demeter or output-argument smells.
+The latch state (current signal, detach handle) is owned by the handler.
+
+### Edge cases
+
+- Same signal across consecutive turns → reference equality short-circuits; no listener churn.
+- `ctx.signal` undefined (idle, defensive) → detach the old listener and hold no signal.
+- Signal already aborted when latched → `{ once: true }` listener does not fire; the prior signal's listener already ran `abortAll()`, so no agent is missed.
+- ESC during a foreground subagent → the foreground agent is aborted twice (once via its own `wireSignal`, once via `abortAll`); `abort()` is guarded by status and `markStopped` is idempotent, so this is harmless.
+
+## Module-Level Changes
+
+- `src/handlers/interrupt.ts` (new) — `InterruptHandler` class and `InterruptManager` interface.
+- `src/handlers/index.ts` — add `export { InterruptHandler } from "#src/handlers/interrupt";`.
+- `src/index.ts` — instantiate `new InterruptHandler(manager)` and register `pi.on("turn_start", (_event, ctx) => interrupt.handleTurnStart(ctx))`.
+- `src/lifecycle/subagent-manager.ts` — no code change; `abortAll()` is reused.
+  Its `// fallow-ignore-next-line unused-class-member` comment stays (it is still reached only through narrow interfaces that fallow does not trace); the pre-completion `fallow dead-code` check will confirm.
+- `docs/architecture/architecture.md` — extend the `handlers/` directory listing (around line 354) with `interrupt.ts` (turn_start handler → abort all subagents on interrupt).
+  Check the same file for any handler file-count or complexity row that names the `handlers/` domain and update if present.
+
+No exports are removed or renamed.
+Grep confirms `.pi/skills/package-pi-subagents/SKILL.md` does not mention `abortAll`, interrupt, or ESC, so no skill update is required.
+
+## Test Impact Analysis
+
+This is a feature/fix addition, not an extraction, so no existing tests become redundant.
+
+1. New unit tests enabled — `InterruptHandler`: latches the current signal, fires `abortAll()` on abort, dedups the same signal reference, re-wires on a new signal, and handles an undefined signal.
+2. New integration guard — foreground abort: aborting the parent signal passed to `runTurnLoop` invokes the child `session.abort()`.
+   This pins the currently-untested foreground link in `forwardAbortSignal`.
+3. Existing tests stay as-is — `test/lifecycle/subagent.test.ts` (`wireSignal`, `abort`), `test/lifecycle/subagent-session.test.ts` (max-turns abort path), and `test/handlers/lifecycle.test.ts` (`abortAll` on shutdown) continue to exercise their layers unchanged.
+
+## TDD Order
+
+1. Foreground guard — `test/lifecycle/subagent-session.test.ts`.
+   Add a test: when the `signal` passed to `runTurnLoop` aborts while `session.prompt` is in flight, `session.abort()` is called.
+   Expected to pass immediately (proving the foreground chain already works); if the trace is wrong and it fails, fix `forwardAbortSignal` in `src/lifecycle/subagent-session.ts`.
+   Commit `test: guard foreground subagent abort on parent signal (#403)` (or `fix:` if a code fix is needed).
+2. Interrupt handler + wiring — `test/handlers/interrupt.test.ts` (new) → `src/handlers/interrupt.ts`, `src/handlers/index.ts`, `src/index.ts`.
+   Red: write the handler unit tests (latch, abort→abortAll, dedup, re-wire, undefined signal) against the not-yet-existing class.
+   Green: implement `InterruptHandler` + `InterruptManager`, export from the barrel, and register `pi.on("turn_start", ...)` in `index.ts`.
+   The handler, its test, and the composition-root wiring land together because the handler is inert without the registration.
+   Commit `fix: abort all subagents on parent interrupt (#403)`.
+3. Architecture doc — `docs/architecture/architecture.md`.
+   Add `interrupt.ts` to the `handlers/` directory listing and update any handler-domain count/row if present.
+   Commit `docs: note interrupt handler in subagents architecture (#403)`.
+
+## Risks and Mitigations
+
+- ESC now stops background agents the user might have wanted to keep running.
+  Mitigation: this is the operator's explicit choice (abort all running + queued); the behavior is documented in the plan and reflected in the `fix:` commit body.
+- Re-latching on every `turn_start` could add overhead.
+  Mitigation: the latch is a single reference comparison and short-circuits on the common same-signal case.
+- A `{ once: true }` listener lingers on a signal that completes normally.
+  Mitigation: the run's `AbortController` is discarded and GC'd with its listener; the next `turn_start` detaches the stale handle.
+- Non-interactive modes (print/rpc) may not emit `turn_start` the same way.
+  Mitigation: ESC interrupt is an interactive concern; the handler is a no-op when no signal is present.
+
+## Open Questions
+
+- Should a dedicated `abortBackground()` (excluding foreground) replace `abortAll()` here?
+  Deferred: `abortAll()` is simpler and foreground is already signal-aborted; revisit only if the redundant double-abort proves problematic.
+- Should ESC abort surface a confirmation or status message?
+  Deferred: out of scope for this fix.