@gotgenes/pi-subagents 15.0.2 → 16.0.0

package/CHANGELOG.md

@@ -5,6 +5,22 @@ 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.0.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v15.0.2...pi-subagents-v16.0.0) (2026-06-14)
+
+
+### ⚠ BREAKING CHANGES
+
+* replace-mode subagents (built-in Explore/Plan and any custom prompt_mode: replace agent) now inherit the parent system prompt as their base instead of a thin standalone header. The custom prompt is appended last and retains full control; the <sub_agent_context> bridge and <agent_instructions> wrapper are still omitted in replace mode.
+
+### Performance Improvements
+
+* include parent system prompt in replace mode ([#400](https://github.com/gotgenes/pi-packages/issues/400)) ([1cc25cf](https://github.com/gotgenes/pi-packages/commit/1cc25cf0106cbfe3015ceb69a820c745c07038e2))
+
+
+### Documentation
+
+* describe replace-mode parent inheritance ([#400](https://github.com/gotgenes/pi-packages/issues/400)) ([6b6e61d](https://github.com/gotgenes/pi-packages/commit/6b6e61d649582c26d2c36edf67dfd1e35d87a802))
+
 ## [15.0.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v15.0.1...pi-subagents-v15.0.2) (2026-06-12)
 
 

package/README.md

@@ -113,14 +113,14 @@ The LLM receives structured `<task-notification>` XML for parsing, while the use
 
 ## Default Agent Types
 
-| Type              | Tools                      | Model                         | Prompt Mode            | Description                                                                           |
-| ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------- |
-| `general-purpose` | all 7                      | inherit                       | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions |
-| `Explore`         | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace` (standalone) | Fast codebase exploration (read-only)                                                 |
-| `Plan`            | read, bash, grep, find, ls | inherit                       | `replace` (standalone) | Software architect for implementation planning (read-only)                            |
+| Type              | Tools                      | Model                         | Prompt Mode            | Description                                                                                      |
+| ----------------- | -------------------------- | ----------------------------- | ---------------------- | ------------------------------------------------------------------------------------------------ |
+| `general-purpose` | all 7                      | inherit                       | `append` (parent twin) | Inherits the parent's full system prompt — same rules, CLAUDE.md, project conventions            |
+| `Explore`         | read, bash, grep, find, ls | haiku (falls back to inherit) | `replace`              | Fast codebase exploration (read-only); inherits the parent prompt as a base                      |
+| `Plan`            | read, bash, grep, find, ls | inherit                       | `replace`              | Software architect for implementation planning (read-only); inherits the parent prompt as a base |
 
 The `general-purpose` agent is a **parent twin** — it receives the parent's entire system prompt plus a sub-agent context bridge, so it follows the same rules the parent does.
-Explore and Plan use standalone prompts tailored to their read-only roles.
+Explore and Plan use `replace` mode: the parent prompt is the cacheable base and their specialist read-only instructions are appended last, giving them the final say.
 
 Default agents can be **ejected** (`/agents` → select agent → Eject) to export them as `.md` files for customization, **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/general-purpose.md`), or **disabled** per-project with `enabled: false` frontmatter.
 
@@ -172,23 +172,23 @@ subagent({ subagent_type: "auditor", prompt: "Review the auth module", descripti
 
 All fields are optional — sensible defaults for everything.
 
-| Field               | Default        | Description                                                                                                                                                                                            |
-| ------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `description`       | filename       | Agent description shown in tool listings                                                                                                                                                               |
-| `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                          |
-| `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                           |
-| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                          |
-| `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                |
-| `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                            |
-| `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                   |
-| `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                       |
-| `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                 |
-| `max_turns`         | unlimited      | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                  |
-| `prompt_mode`       | `append`       | `replace`: body is the full system prompt (no AGENTS.md / CLAUDE.md inheritance). `append`: body appended to parent's prompt (agent acts as a "parent twin" — inherits parent's AGENTS.md / CLAUDE.md) |
-| `inherit_context`   | `false`        | Fork parent conversation into agent                                                                                                                                                                    |
-| `run_in_background` | `false`        | Run in background by default                                                                                                                                                                           |
-| `isolated`          | `false`        | No extension/MCP tools, only built-in                                                                                                                                                                  |
-| `enabled`           | `true`         | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                     |
+| Field               | Default        | Description                                                                                                                                                                                                                                                                                                             |
+| ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `description`       | filename       | Agent description shown in tool listings                                                                                                                                                                                                                                                                                |
+| `display_name`      | —              | Display name for UI (e.g. widget, agent list)                                                                                                                                                                                                                                                                           |
+| `tools`             | all 7          | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools                                                                                                                                                                                                                            |
+| `extensions`        | `true`         | `true` to inherit all MCP/extension tools, `false` to disable                                                                                                                                                                                                                                                           |
+| `skills`            | `true`         | Inherit skills from parent. Can be a comma-separated list of skill names to preload (see [Skill Preloading](#skill-preloading) for discovery locations)                                                                                                                                                                 |
+| `memory`            | —              | Persistent agent memory scope: `project`, `local`, or `user`. Auto-detects read-only agents                                                                                                                                                                                                                             |
+| `isolation`         | —              | Set to `worktree` to run in an isolated git worktree                                                                                                                                                                                                                                                                    |
+| `model`             | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`)                                                                                                                                                                                                                                                        |
+| `thinking`          | inherit        | off, minimal, low, medium, high, xhigh                                                                                                                                                                                                                                                                                  |
+| `max_turns`         | unlimited      | Max agentic turns before graceful shutdown. `0` or omit for unlimited                                                                                                                                                                                                                                                   |
+| `prompt_mode`       | `append`       | `replace`: parent prompt is the cacheable base; body is appended last with full control (no `<sub_agent_context>` bridge, no `<agent_instructions>` wrapper). `append`: parent prompt is the base; body is wrapped in `<agent_instructions>` and a sub-agent context bridge is injected (agent acts as a "parent twin") |
+| `inherit_context`   | `false`        | Fork parent conversation into agent                                                                                                                                                                                                                                                                                     |
+| `run_in_background` | `false`        | Run in background by default                                                                                                                                                                                                                                                                                            |
+| `isolated`          | `false`        | No extension/MCP tools, only built-in                                                                                                                                                                                                                                                                                   |
+| `enabled`           | `true`         | Set to `false` to disable an agent (useful for hiding a default agent per-project)                                                                                                                                                                                                                                      |
 
 Frontmatter is authoritative.
 If an agent file sets `model`, `thinking`, `max_turns`, `inherit_context`, `run_in_background`, `isolated`, or `isolation`, those values are locked for that agent.
@@ -491,7 +491,7 @@ Each has a corresponding upstream PR:
    Upstream PR: [tintinweb/pi-subagents#71](https://github.com/tintinweb/pi-subagents/pull/71).
 2. **Post-`bindExtensions` active-tool re-filter** (`src/agent-runner.ts`) — `runAgent` re-runs its active-tool filter after `session.bindExtensions(...)` so the `EXCLUDED_TOOL_NAMES` recursion guard applies to extension-registered tools (which join the active set during `bindExtensions`).
    Upstream PR: [tintinweb/pi-subagents#72](https://github.com/tintinweb/pi-subagents/pull/72).
-3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` prepends `<active_agent name="${config.name}"/>` to every assembled child system prompt (both `replace` and `append` modes).
+3. **`<active_agent>` system-prompt tag** (`src/prompts.ts`) — `buildAgentPrompt` includes `<active_agent name="${config.name}"/>` in every assembled child system prompt (both `replace` and `append` modes); the tag follows the cacheable parent-prompt prefix in both modes.
    Downstream extensions like [`@gotgenes/pi-permission-system`](https://github.com/gotgenes/pi-permission-system) parse this tag to resolve per-agent `permission:` frontmatter inside the child session.
    Upstream PR: [tintinweb/pi-subagents#73](https://github.com/tintinweb/pi-subagents/pull/73).
 4. **Child-execution lifecycle events** (`src/lifecycle/child-lifecycle.ts`) — the child-session execution lifecycle is published as ordered events on `pi.events` (`subagents:child:spawning`, `session-created`, `completed`, `disposed`).

package/docs/architecture/architecture.md

@@ -492,6 +492,10 @@ The governing rule — **no vacant hooks**: the architecture must _admit_ a seam
 A provider seam with no consumer is a speculative abstraction that taxes every reader and that `fallow` flags as dead.
 Latent extensibility is the deliverable; a vacant hook is not.
 
+The [first-principles refinement](#first-principles-refinement-the-deeper-target) below sharpens this two-surface split.
+The awaited, behavior-affecting lifecycle events (notably `session-created` before `bindExtensions`) are _hooks_ — the child's own extension surface applied recursively, generative because the core waits on the handler before deciding what to do next.
+The observational surface then carries only fire-and-forget broadcasts of immutable snapshots, which no consumer can use to change the core.
+
 ### Core responsibilities (keep)
 
 - **Agent definitions** — name, model, thinking, system prompt, tools list.
@@ -522,12 +526,90 @@ In the target state, pi-subagents publishes events and a provider seam; other pa
 
 - **pi-permission-system** (observational) subscribes to child-session lifecycle events, detects subagent execution context in the child, and gates tool calls at runtime.
 - **pi-subagents-worktrees** (generative) registers a `WorkspaceProvider` that prepares a git worktree at run-start and tears it down after, supplying the child's cwd.
-- **pi-subagents-ui** (future) subscribes to the service API, renders the widget, conversation viewer, and `/agents` menu.
+- **pi-subagents-ui** (future, under reconsideration — see the [first-principles refinement](#first-principles-refinement-the-deeper-target)) subscribes to the broadcast and the query/behavior interfaces; whether the inherited widget, conversation viewer, and `/agents` menu survive is judged on our principles, not preserved by default.
 - **Any future extension** (OTel, auditing, cost tracking) subscribes to the same events without pi-subagents knowing.
 
 Composition test: install neither extension, only permissions, only workspaces, or both — the core is byte-for-byte identical in all four cases, and the two extensions never reference each other.
 
-This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 18 (extract UI).
+This is achieved across phases: Phase 14 (strip policy), Phase 16 (invert dependencies — extensions on a minimal core), and Phase 18 (reconsider UI).
+
+### First-principles refinement (the deeper target)
+
+The two-surface model above is correct but coarse.
+Pushing it against our own principles — construct complete, state owns its mutations, tell-don't-ask, dependency inversion — surfaces sharper boundaries that the current code draws through the middle of classes.
+This subsection records the deeper target; the steps that realize it are sequenced in later phases.
+
+#### `Subagent` is four conflated domains
+
+The construction duality that motivates Phase 17 — a class that is simultaneously a passive record and an executor — is only the two most visible of four domains fused into one class.
+Pulling each apart by asking "who changes this, how often, and who needs to know" surfaces:
+
+1. **Lifecycle state** — status, result, error, timestamps.
+   Owned by the subagent; transitions are rare and meaningful; the right outward shape is an immutable snapshot announced on change.
+2. **Metrics** — tool uses, token usage, compaction count.
+   These are not lifecycle state; they are a projection aggregated over the child session's event stream.
+   `record-observer` already computes them — its only error is writing the aggregate back onto the subagent.
+3. **The hook surface** — the points where an extension alters or augments the child before and around its run.
+   This is the child session's own extension binding (see below), not data on the subagent.
+4. **Result delivery** — whether the parent has consumed the result, when to nudge, how the result reaches the caller.
+   The homeless `notification.resultConsumed` field belongs to this domain, not to execution.
+
+The ~20 optional constructor fields and the runtime `run()` throws are the pressure these four domains exert on one class.
+Separating them is what makes the Phase 17 steps fall out rather than fight back.
+
+#### The subagent is a recursive Pi
+
+A subagent is a child Pi session: created with `createAgentSession`, then `bindExtensions`.
+Its extension surface is therefore Pi's extension surface applied recursively — not a bespoke event bus.
+What the current doc calls "awaited, ordered lifecycle events" are not observations; they are **hooks**, structurally identical to Pi's own (`session_start`, `tool_execution_start`).
+The tell is the awaiting: the core waits for the handler because the handler's completion changes what the core does next — an extension registers before the child binds.
+A handler that can change subsequent behavior is generative, not observational, whatever we name the channel.
+
+This splits the current "lifecycle events" surface cleanly in two:
+
+1. **Broadcast** (observational, fire-and-forget) — "this happened; react if you want; you cannot change anything."
+   Carries immutable snapshots for telemetry, notification, and any renderer.
+   No consumer holds a live `Subagent`.
+2. **Hooks** (generative, awaited, ordered) — the recursive Pi extension surface where workspace, permissions, and future concerns attach to the child.
+   The `WorkspaceProvider` is one _typed_ hook; the general form is "be an extension of the child session."
+
+The "no vacant hooks" rule still governs the generative side: admit the surface, ship a hook only when a real consumer exists.
+
+#### Reactive versus discrete (not internal versus external)
+
+The axis that decides push versus pull is whether a need is reactive or discrete — never whether the consumer is in-package or out.
+
+- **Reactive** (ambient state that changes underneath you) → subscribe to the broadcast; be told.
+  The state-owner announces; the consumer maintains its own read-model; nobody pulls.
+- **Discrete** (a one-shot question: current value, full transcript) → pull a query.
+  `get_subagent_result`, opening a transcript, and the external `SubagentsService.getRecord` are queries by nature and stay pull, in-package or not.
+
+Behavior is a third interface: **tell by id, with outcomes**.
+`steer` and `abort` own their own rules — a non-running agent rejects a steer from inside `steer`, not via a caller's status pre-check — so coordinators never ask-then-tell.
+
+#### Consequences
+
+Two consequences fall straight out, and both cut scope.
+
+1. **The activity/metrics push tier is provisional.**
+   Its only reactive consumer is the inherited widget.
+   Treated from first principles, metrics are accumulated by an observer, exposed as a discrete query, and folded into the completion snapshot — so the high-frequency stream may not need to exist at all.
+   We do not contort the core's event design to feed an inherited consumer.
+2. **Phase 18 is "reconsider the UI," not "extract the UI."**
+   The widget and `/agents` menu predate the fork; they are consumers to be judged on our principles, not requirements to preserve.
+   If a UI survives, it survives as a reactive consumer of the broadcast and a caller of the query/behavior interfaces — built on our terms, possibly smaller, possibly removed.
+
+#### Sibling packages follow the same discipline
+
+`@gotgenes/pi-permission-system` is one of these hooks, and it is subject to the same scrutiny.
+Its boundaries deserve the same first-principles treatment: surface its conflated domains, distinguish what it observes from what it injects, and prefer being told over asking.
+The recursion principle means a consumer's internal design is not exempt because it lives in another package — the same axes (reactive versus discrete, hook versus broadcast, construct complete) apply across the seam.
+
+#### How we find these boundaries
+
+The boundaries above were not deduced top-down; they were surfaced by friction.
+Each place the target got _harder_ to test marked a domain seam drawn through the middle of a class.
+That method — testability friction as a boundary probe, with its limits — is recorded in the `improvement-discovery` skill so it outlives this phase.
 
 ## Current structural analysis
 
@@ -768,9 +850,13 @@ See [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md) f
 
 ## Improvement roadmap (Phase 17 — core consolidation)
 
-Phase 17 consolidates the core's remaining structural debt before the UI extraction (now Phase 18).
+Phase 17 consolidates the core's remaining structural debt before the UI reconsideration (now Phase 18).
 The findings come from the standard discovery pass — fallow suite, entry-point trace, design-review checklist, and test-constructibility audit — run after Phase 16 landed.
 
+Phase 17 is the consolidation slice of the [first-principles refinement](#first-principles-refinement-the-deeper-target), not the full domain split.
+It lands the first cut of the lifecycle-state domain (Step 2's `SubagentState`) plus the wiring, queue, and duplication cleanups.
+The fuller four-domain split — metrics as a projection, result delivery as its own domain, the hook/broadcast reclassification, and the push/pull (DIP) inversion — is recorded in the refinement and sequenced into later phases.
+
 ### Findings summary
 
 Updated health metrics (fallow, package-wide including tests):
@@ -793,6 +879,7 @@ The syntactic metrics are healthy and stable — the remaining debt is structura
    `SubagentInit` carries ~20 fields, nearly all optional with "required for run(), optional for tests" semantics, and `run()` compensates with runtime throws ("not configured for execution").
    This violates principle 8 (construct complete): the class is simultaneously a passive record (tests build display-only snapshots) and an executor (production wires factory, observer, run config, workspace provider).
    The symptoms are in the tests: external writes `record.promise = …` (manager, queue callback, four test files) and `record.notification = new NotificationState(…)` (seven test sites) are output-argument smells on fields the object should own.
+   This duality is the two most visible of four domains fused into `Subagent`; Phase 17 resolves it (Step 2) and defers the remaining split (metrics, result delivery) to a later phase per the [first-principles refinement](#first-principles-refinement-the-deeper-target).
 2. **Wiring debt in `index.ts`.**
    Two forward references (settings → queue, queue → manager) are replicated with an `eslint-disable prefer-const` dance in `test/lifecycle/subagent-manager.test.ts`; the queue's start callback (`record.promise = record.run()` after a status check) is duplicated verbatim between `index.ts` and the test helper.
    A ~70-line inline `SubagentManagerObserver` literal mixes three concerns (event emission, `appendEntry` persistence, notification dispatch).
@@ -809,7 +896,7 @@ Priority = Impact × (6 − Risk).
 | Step | Title                                                                                | Category | Impact | Risk | Priority |
 | ---- | ------------------------------------------------------------------------------------ | -------- | ------ | ---- | -------- |
 | 1    | Replace ConcurrencyQueue with a thunk-based ConcurrencyLimiter                       | A/C      | 4      | 2    | 16       |
-| 2    | Decompose `SubagentInit` into `SubagentOptions` (identity, run spec, execution deps) | B/D      | 4      | 3    | 12       |
+| 2    | Extract `SubagentState`; make `Subagent` execution deps mandatory                    | B/D      | 4      | 3    | 12       |
 | 3    | Encapsulate run start and notification attachment on Subagent                        | C        | 3      | 2    | 12       |
 | 4    | Extract run-listener and workspace-bracket collaborators from Subagent               | B/C      | 3      | 2    | 12       |
 | 5    | Extract the manager observer from index.ts into a class                              | B/E      | 3      | 2    | 12       |
@@ -827,19 +914,25 @@ 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 — Decompose `SubagentInit` into `SubagentOptions` (identity, run spec, execution deps) ([#373])
+#### Step 2 — Extract `SubagentState`; make `Subagent` execution deps mandatory ([#373])
 
-- Targets: `src/lifecycle/subagent.ts` (`SubagentInit`, constructor, `run()` guards), `src/lifecycle/subagent-manager.ts` (`spawn`), `test/helpers/make-subagent.ts`.
+- 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).
-- Change: group the per-run fields (snapshot, prompt, model, maxTurns, thinkingLevel, parentSession, signal) into a `SubagentRunSpec` and the shared collaborators (createSubagentSession, observer, getRunConfig, getWorkspaceProvider, baseCwd) into `SubagentExecutionDeps`; the pair is either fully present (executable agent) or fully absent (passive record), collapsing `run()`'s two guards into one.
-  Rename the decomposed bag `SubagentInit` → `SubagentOptions`: it is the codebase's only DOM-style `*Init` name, while sibling constructor bags use `Options` (`SubagentManagerOptions`, `TurnLoopOptions`).
-- Outcome: `SubagentOptions` (née `SubagentInit`) top-level fields ~20 → ≤ 9; a passive test record is constructible without any execution fields; the record-vs-executor duality is explicit in the types.
+  The record/executor duality is the two most visible of the four conflated domains (see [First-principles refinement](#first-principles-refinement-the-deeper-target)).
+- Change: extract the passive-record state — status, result, error, timestamps, and the stats (toolUses, lifetimeUsage, compactionCount) — into a `SubagentState` value object that owns the transition and accumulation methods.
+  `Subagent` holds one privately; its existing getters and `markX`/`incrementX`/`addUsage` methods become one-line delegations, so the ~40 read sites and the mutation callers are unchanged.
+  This is not reach-through: `SubagentState` is a private owned value, not a foreign collaborator (contrast [#277], which removed reach-through to the raw SDK session).
+  With the readable state extracted, the remaining execution inputs (snapshot, prompt, model, maxTurns, thinkingLevel, parentSession, signal, createSubagentSession, observer, getRunConfig, getWorkspaceProvider, baseCwd) collapse into a single **mandatory** `SubagentExecution` collaborator: production always supplies it (the one `spawn()` site), the passive-record construction moves entirely into `make-subagent.ts`, and `run()`'s two "not configured" throws vanish by construction.
+- 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.
 
 #### Step 3 — Encapsulate run start and notification attachment on Subagent ([#374])
 
 - Targets: `src/lifecycle/subagent.ts`, `src/lifecycle/subagent-manager.ts`, `test/tools/get-result-tool.test.ts`, `test/lifecycle/subagent-manager.test.ts`, `test/service/service-adapter.test.ts`, `test/observation/notification.test.ts`, `test/helpers/make-subagent.ts`.
 - Smell: Category C — output arguments: external writes to `record.promise` (3 production/test sites) and `record.notification` (7 test sites).
-- Change: add `Subagent.start()` that runs and stores its own promise (plus an awaitable accessor for `spawnAndWait`/`waitForAll`); make `promise` and `notification` externally read-only; tests attach notification state through `SubagentOptions.parentSession.toolCallId` or a dedicated options field.
+- Change: add `Subagent.start()` that runs and stores its own promise (plus an awaitable accessor for `spawnAndWait`/`waitForAll`); make `promise` and `notification` externally read-only; tests attach notification state through `SubagentExecution.parentSession.toolCallId` or a dedicated options field.
 - Outcome: zero external writes to `Subagent` fields outside its own methods (grep-verifiable: `\.promise =` and `\.notification =` appear only inside `subagent.ts`).
 
 #### Step 4 — Extract run-listener and workspace-bracket collaborators from Subagent ([#375])
@@ -890,7 +983,7 @@ Priority = Impact × (6 − Risk).
 ```mermaid
 flowchart TB
     S1["Step 1 (#381)<br/>ConcurrencyLimiter replacement"]
-    S2["Step 2 (#373)<br/>SubagentOptions decomposition"]
+    S2["Step 2 (#373)<br/>SubagentState extraction"]
     S3["Step 3 (#374)<br/>Encapsulate start + notification"]
     S4["Step 4 (#375)<br/>Run collaborators extraction"]
     S5["Step 5 (#376)<br/>Observer class from index.ts"]
@@ -933,7 +1026,7 @@ Detailed records are preserved in per-phase history files:
 | 3     | Remove group-join, RPC; replace output-file         | Complete            | [phase-3-remove-rpc-groupjoin.md](history/phase-3-remove-rpc-groupjoin.md)           |
 | 4     | Implement and publish SubagentsService              | Complete            | [phase-4-implement-service.md](history/phase-4-implement-service.md)                 |
 | 5     | Decompose index.ts                                  | Complete            | [phase-5-decompose-index.md](history/phase-5-decompose-index.md)                     |
-| 6     | Extract UI to separate package                      | Deferred → Phase 17 | —                                                                                    |
+| 6     | Extract UI to separate package                      | Deferred → Phase 18 | —                                                                                    |
 | 7     | Encapsulation and dependency narrowing              | Complete            | [phase-7-encapsulation.md](history/phase-7-encapsulation.md)                         |
 | 8     | Testability, display extraction, menu decomposition | Complete            | [phase-8-testability.md](history/phase-8-testability.md)                             |
 | 9     | Observation consolidation, ctx elimination          | Complete            | [phase-9-observation-ctx.md](history/phase-9-observation-ctx.md)                     |
@@ -945,7 +1038,7 @@ Detailed records are preserved in per-phase history files:
 | 15    | Domain model evolution                              | Complete            | [phase-15-domain-model-evolution.md](history/phase-15-domain-model-evolution.md)     |
 | 16    | Invert dependencies (extensions on a minimal core)  | Complete            | [phase-16-invert-dependencies.md](history/phase-16-invert-dependencies.md)           |
 | 17    | Core consolidation                                  | Planned             | —                                                                                    |
-| 18    | Extract UI to separate package                      | Planned             | —                                                                                    |
+| 18    | Reconsider UI (first principles)                    | Planned             | —                                                                                    |
 
 ### Structural refactoring issues
 

package/docs/plans/0400-include-parent-prompt-in-replace-mode.md

@@ -0,0 +1,199 @@
+---
+issue: 400
+issue_title: "perf(pi-subagents): include parent system prompt in replace mode for KV cache reuse"
+---
+
+# Include parent system prompt in replace mode for KV cache reuse
+
+## Problem Statement
+
+In replace mode, `buildAgentPrompt()` discards the parent system prompt entirely and substitutes a thin two-line header (`"You are a pi coding agent sub-agent. / You have been invoked to handle a specific task autonomously."`).
+Replace-mode agents therefore lose the core identity, tool-usage guidelines, and AGENTS.md context the parent carries, and they share no prompt prefix with the parent or with each other — defeating LLM KV cache reuse.
+The `parentSystemPrompt` parameter is already passed into `buildAgentPrompt()` but the replace branch ignores it.
+
+## Goals
+
+- Place the parent system prompt (or `genericBase` when no parent is available) at the front of the replace-mode prompt as a shared, cacheable prefix.
+- Order the replace-mode prompt as: parent/`genericBase` → `<active_agent>` tag → env block → `config.systemPrompt`.
+- Preserve the distinguishing feature of replace mode: it injects neither the `<sub_agent_context>` bridge nor the `<agent_instructions>` wrapper — the custom prompt keeps full control of the agent's instructions, placed last so it has the final say.
+- Apply the change uniformly to every replace-mode agent, including the built-in `Explore` and `Plan` agents.
+- This is a **breaking change**: replace-mode agents (including `Explore`/`Plan` and any custom `prompt_mode: replace` agent) now inherit the parent system prompt on upgrade with no user edit, and the thin two-line header is removed.
+  Ship it as `perf!:` with a `BREAKING CHANGE:` footer.
+
+## Non-Goals
+
+- No change to append-mode assembly (already reordered for KV cache in [#180]).
+- No change to how `parentSystemPrompt` is sourced — `create-subagent-session.ts` already passes `snapshot.systemPrompt` through `session-config.ts`.
+- No new mode or flag to distinguish "replace with parent" from "replace without parent" — the operator confirmed the change applies uniformly, so `Explore`/`Plan` are not special-cased.
+- No change to `pi-permission-system` — its `<active_agent>` tag parsing is a full-string regex search, position-independent.
+- No change to `pi-anthropic-auth` — its OAuth shaping is unaffected (see Background).
+
+## Background
+
+`buildAgentPrompt()` in `packages/pi-subagents/src/session/prompts.ts` assembles the child system prompt.
+The append branch was reordered in [#180] (shipped in `pi-subagents-v6.18.3`) to place shared/stable content first; the parent prompt is placed verbatim (no wrapper tag) so it forms an identical byte prefix with the parent session, maximising KV cache hits.
+The replace branch was left untouched and still emits the thin header.
+
+Current replace branch:
+
+```typescript
+// "replace" mode — env header + the config's full system prompt
+const replaceHeader = `You are a pi coding agent sub-agent.
+You have been invoked to handle a specific task autonomously.
+
+${envBlock}`;
+
+return activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt;
+```
+
+`const identity = parentSystemPrompt ?? genericBase;` currently lives inside the append branch.
+`genericBase` (a `# Role` / general-purpose coding agent blurb) is the shared fallback.
+
+### Cross-extension interaction — `pi-anthropic-auth` OAuth
+
+The operator asked how the `genericBase` fallback interacts with `@gotgenes/pi-anthropic-auth`.
+Findings from reading that package's `src/system-prompt-shaping.ts` and `src/request-shaping.ts`:
+
+- The OAuth de-fingerprinting (`shapeAnthropicOAuthSystemPrompt`) only activates when the system prompt contains `PI_DEFAULT_PROMPT_PREFIX` (Pi's default expert-coding-assistant preamble); otherwise it returns the prompt untouched.
+- The `x-anthropic-billing-header` system block is prepended **unconditionally** for every OAuth request (`prependBillingHeader`), independent of the base prompt content — this is the primary Claude Code billing signal.
+
+Implications for this change:
+
+- Normal case (parent present): replace mode places the parent prompt verbatim at the front, structurally identical to append mode, which already works under the OAuth transport wrapper.
+  The inherited Pi preamble is de-fingerprinted exactly as it is for append-mode subagents and the main session today.
+- `genericBase` fallback (only when the parent snapshot has no system prompt — effectively never in real sessions, since `parentSystemPrompt` is a required `string` at the `session-config` layer): `genericBase` carries no Pi fingerprint, so the OAuth shaping no-ops and the billing header is still prepended.
+  `genericBase` is already neutral, so nothing leaks.
+
+Conclusion: #400 introduces no new OAuth interaction. `genericBase` remains the correct fallback and stays consistent with append mode.
+
+### Constraints from AGENTS.md
+
+- This package carries a type-declaration bundle for its public API, but `buildAgentPrompt` is internal — no `dist/public.d.ts` or `exports` impact, so `verify:public-types` is not required for this change.
+- Conventional Commits; do not edit `CHANGELOG.md` (release-please owns it).
+- The `BREAKING CHANGE:` footer text is reused verbatim in the release-please CHANGELOG and the issue close comment — name only real surface (`prompt_mode: replace`).
+
+## Design Overview
+
+Hoist the `identity` resolution above the branch so both modes share it, then rewrite the replace branch.
+
+```typescript
+const activeAgentTag = `<active_agent name="${config.name}"/>\n\n`;
+const envBlock = `# Environment\n...`;
+const identity = parentSystemPrompt ?? genericBase;
+
+if (config.promptMode === "append") {
+  // ...unchanged...
+}
+
+// "replace" mode — shared parent prompt (or generic base) first for KV cache
+// reuse, then the active_agent tag, env block, and the config's full system
+// prompt. Unlike append mode, replace mode injects neither the
+// <sub_agent_context> bridge nor the <agent_instructions> wrapper — the custom
+// prompt keeps full control of the agent's instructions.
+return identity + "\n\n" + activeAgentTag + envBlock + "\n\n" + config.systemPrompt;
+```
+
+Resulting replace-mode order (`activeAgentTag` already ends with `\n\n`):
+
+```text
+1. parentSystemPrompt (or genericBase)    ← SHARED, cacheable prefix
+2. <active_agent name="${name}"/>         ← varies per agent
+3. # Environment ...                      ← varies per runtime
+4. config.systemPrompt                    ← custom instructions (full control)
+```
+
+This mirrors append mode's prefix-first ordering, minus the bridge and the `<agent_instructions>` wrapper.
+The change is a pure single-function edit — no new collaborator, no new module, no interface change — so the design-review structural checklist (dependency width, Law of Demeter, extraction seams) does not apply.
+
+### Edge cases
+
+- Empty `config.systemPrompt` (e.g. a replace agent with no body): the prompt ends with a trailing `\n\n` after the env block.
+  Acceptable and consistent with current behavior; no special-casing.
+  `genericBase` only substitutes on a nullish parent (the `??` operator), so an empty-string parent prompt is preserved as-is, matching append mode.
+
+## Module-Level Changes
+
+### `packages/pi-subagents/src/session/prompts.ts`
+
+1. Hoist `const identity = parentSystemPrompt ?? genericBase;` from the append branch to before the `if (config.promptMode === "append")` check so both branches use it.
+2. Replace the replace-branch `replaceHeader` template and return statement with the new ordering (`identity` → `activeAgentTag` → `envBlock` → `config.systemPrompt`); remove the thin two-line header.
+3. Update the JSDoc summary: replace-mode bullet becomes "parent system prompt (or generic base) + active_agent tag + env header + config.systemPrompt; no bridge, no agent_instructions wrapper," and update the trailing note about tag position (it is included, not prepended, in either mode).
+
+### `packages/pi-subagents/test/session/prompts.test.ts`
+
+See Test Impact Analysis and TDD Order for the specific test changes.
+
+### `packages/pi-subagents/README.md`
+
+1. Lines 119–120 — the `Explore` and `Plan` rows: revise the `replace` (standalone) framing, since replace mode now inherits the parent prompt as its base.
+2. Line 187 — the `prompt_mode` frontmatter table: `replace` no longer means "no AGENTS.md / CLAUDE.md inheritance."
+   Reword to describe the new semantics: replace inherits the parent prompt as the base, then the body takes full control (no `<sub_agent_context>` bridge, no `<agent_instructions>` wrapper), whereas append wraps the body and adds the bridge.
+3. Line 494 (Patch 3, `<active_agent>` tag): change "prepends ... to every assembled child system prompt (both `replace` and `append` modes)" to "includes ... in every assembled child system prompt (both modes)" — the tag follows the cacheable parent prefix in both modes now, so "prepends" is inaccurate.
+
+No `docs/architecture/` updates: the architecture doc references `prompts.ts` only as a one-line file listing (no prompt-assembly description, no complexity/health table entry tied to this change).
+
+## Test Impact Analysis
+
+This is a behavior change, not an extraction, so the extraction-specific questions are limited.
+
+- New behavior to cover: replace mode now includes the parent prompt as a cacheable prefix; falls back to `genericBase` with no parent; still excludes the bridge and the `<agent_instructions>` wrapper.
+- Existing replace-mode tests that assert the old behavior must change (they pin the removed thin header and the "ignores parent prompt" premise).
+- `toContain`-based tests for cwd/git/env and the `genericBase` fallback remain valid where position-independent.
+- No existing test becomes redundant beyond the ones being rewritten; no test must stay frozen for a layer being extracted (nothing is extracted).
+
+Tests that change in `test/session/prompts.test.ts`:
+
+1. `"replace mode uses config systemPrompt directly"` — asserts `toContain("You are a pi coding agent sub-agent")`; that header is removed.
+   Rewrite to assert the config prompt is present and the thin header is gone.
+2. `"replace mode ignores parent prompt"` — asserts the parent content is absent.
+   The premise inverts: rename to `"replace mode includes parent prompt as base (no bridge/wrapper)"` and assert the parent content is present while `<sub_agent_context>` and `<agent_instructions>` are absent.
+3. `"prepends <active_agent name=...> tag in replace mode"` — asserts `prompt.startsWith('<active_agent name="Explore"/>\n\n')`.
+   The tag no longer leads (parent/`genericBase` does); rewrite to assert the tag appears after the identity prefix and before the env block.
+4. `"active_agent tag appears before envBlock in both modes"` — the replace assertions pin `tagIdx === 0`.
+   Update the replace assertions: the tag is no longer at index 0 but still precedes `# Environment`.
+   The append assertions stay as-is.
+
+## TDD Order
+
+All test and source changes live in two files that the type checker links (the replace branch and its tests).
+Each cycle is a single commit that leaves the suite green.
+
+1. **Red: rewrite replace-mode behavioral tests.**
+   Update tests 1–2 above to the new behavior (parent prompt included as base; thin header removed; no bridge/wrapper), and add a test for the `genericBase` fallback when no parent is supplied in replace mode, plus a test pinning the full order (`identity` → `<active_agent>` → `# Environment` → `config.systemPrompt`).
+   These fail against the current implementation.
+   Commit: `test: assert replace mode inherits parent prompt as cacheable prefix (#400)`
+
+2. **Green: rewrite the replace branch.**
+   Hoist `identity`, replace the `replaceHeader` block with the new ordering, remove the thin header, and update the JSDoc.
+   Update the positional `<active_agent>` tests (3–4 above) in the same commit — they break at runtime the moment the branch changes.
+   Commit body carries the `BREAKING CHANGE:` footer.
+   Commit: `perf!: include parent system prompt in replace mode (#400)`
+
+   ```text
+   BREAKING CHANGE: replace-mode subagents (built-in Explore/Plan and any
+   custom prompt_mode: replace agent) now inherit the parent system prompt as
+   their base instead of a thin standalone header. The custom prompt is
+   appended last and retains full control; the <sub_agent_context> bridge and
+   <agent_instructions> wrapper are still omitted in replace mode.
+   ```
+
+3. **Docs: update README replace-mode semantics.**
+   Apply the three README edits (Explore/Plan rows, `prompt_mode` table, Patch 3 `<active_agent>` wording).
+   Commit: `docs: describe replace-mode parent inheritance (#400)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                  | Mitigation                                                                                                                                                                                                    |
+| --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Explore`/`Plan` behavior shifts — they now carry the full parent prompt plus their read-only specialist instructions | Operator confirmed uniform application; specialist instructions are placed last so they have the final say; existing read-only assertions (`READ-ONLY`, `file search specialist`) still hold via `toContain`. |
+| `pi-permission-system` depends on `<active_agent>` tag position                                                       | Tag parsing is a full-string regex search; position-independent (same basis as [#180]).                                                                                                                       |
+| `pi-anthropic-auth` OAuth shaping breaks with the new base                                                            | No new interaction — billing header is prepended unconditionally; de-fingerprinting keys off `PI_DEFAULT_PROMPT_PREFIX` and `genericBase` is already neutral (see Background).                                |
+| A custom replace agent relied on the clean-slate (no parent) behavior                                                 | Documented as breaking in the `BREAKING CHANGE:` footer and README; this aligns with the expectation reported in the issue ([@jeffutter] expected the parent identity to be present).                         |
+| Stale README claims that replace = no inheritance                                                                     | README edits in cycle 3 correct lines 119–120, 187, and 494.                                                                                                                                                  |
+
+## Open Questions
+
+None — the three design decisions (breaking classification, `genericBase` fallback, uniform application to built-ins) were resolved with the operator before planning.
+
+[#180]: https://github.com/gotgenes/pi-packages/issues/180
+[@jeffutter]: https://github.com/jeffutter

package/docs/retro/0400-include-parent-prompt-in-replace-mode.md

@@ -0,0 +1,44 @@
+---
+issue: 400
+issue_title: "perf(pi-subagents): include parent system prompt in replace mode for KV cache reuse"
+---
+
+# Retro: #400 — Include parent system prompt in replace mode for KV cache reuse
+
+## Stage: Planning (2026-06-14T00:42:49Z)
+
+### Session summary
+
+Produced a numbered plan for including the parent system prompt as a cacheable prefix in `buildAgentPrompt()`'s replace branch, mirroring the [#180] append-mode reorder.
+The change is a single-function edit plus test and README updates, planned across three TDD/docs commits.
+
+### Observations
+
+- Three design decisions were confirmed with the operator (issue author = gh user) before planning:
+  1. Ship as breaking `perf!:` with a `BREAKING CHANGE:` footer — replace-mode agents inherit the parent prompt on upgrade with no user edit, and the thin two-line header is removed.
+  2. Use `genericBase` as the no-parent fallback, consistent with append mode.
+  3. Apply uniformly to all replace agents, including built-in `Explore` and `Plan` (one code path, no special-casing).
+- The operator raised a cross-extension concern about the `genericBase` fallback interacting with `@gotgenes/pi-anthropic-auth`.
+  Investigation of that package's `system-prompt-shaping.ts` / `request-shaping.ts` showed no new interaction: the `x-anthropic-billing-header` block is prepended unconditionally for OAuth, and de-fingerprinting keys off `PI_DEFAULT_PROMPT_PREFIX` (absent from `genericBase`, which is already neutral).
+  Captured this in the plan's Background and Risks.
+- `parentSystemPrompt` is a required `string` at the `session-config` layer (sourced from `snapshot.systemPrompt`), so the `genericBase` fallback is effectively a defensive/test-only path in real sessions.
+- The thin replace header string (`You are a pi coding agent sub-agent`) appears only in `prompts.ts` and its test — no skill or live doc pins it; README needs three edits (Explore/Plan rows, `prompt_mode` table, Patch 3 `<active_agent>` wording, the last already slightly stale post-#180).
+- Notable emergent scope point: `Explore`/`Plan` are built-in replace-mode agents, so this change affects them visibly — surfaced and confirmed rather than assumed.
+
+## Stage: Implementation — TDD (2026-06-14T00:54:46Z)
+
+### Session summary
+
+Completed all 3 TDD cycles in `packages/pi-subagents`.
+The change is a single-function edit to `src/session/prompts.ts` (hoist `identity`, rewrite replace branch) plus test updates and README/skill-doc corrections.
+Test count went from 973 to 975 (+2 net new tests) across 59 test files.
+
+### Observations
+
+- Step 1 (Red): rewrote 2 existing replace-mode tests and added 2 new ones (4 failures confirmed against old code); the old "ignores parent prompt" test premise inverted cleanly into "includes parent prompt as base."
+- Step 2 (Green): hoisting `const identity = parentSystemPrompt ?? genericBase;` above the `if` block and replacing the `replaceHeader` template were the only `src/` changes; also updated two positional `<active_agent>` tests in the same commit since they broke the moment the branch changed (`tagIdx === 0` → `toBeGreaterThan(0)`).
+- The `BREAKING CHANGE:` footer wording was taken verbatim from the plan and landed in the `perf!:` commit.
+- Pre-completion reviewer: WARN — one finding: `.pi/skills/package-pi-subagents/SKILL.md` still said "prepends" for the `<active_agent>` tag; fixed in a follow-up `docs:` commit before shipping.
+- No deviations from the plan's Module-Level Changes list; no lockfile changes; fallow dead-code exited zero.
+
+[#180]: https://github.com/gotgenes/pi-packages/issues/180

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "15.0.2",
+  "version": "16.0.0",
   "type": "module",
   "exports": {
     ".": {

package/src/session/prompts.ts

@@ -8,17 +8,25 @@ import type { AgentPromptConfig } from "#src/types";
 /**
  * Build the system prompt for an agent from its config.
  *
- * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
- * - "append" with empty systemPrompt: pure parent clone
+ * Both modes place the shared/stable parent prompt (or `genericBase` when no
+ * parent is available) first so the LLM's KV cache can reuse the inherited
+ * prefix across all subagent invocations.
  *
- * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
- * extensions (e.g. `@gotgenes/pi-permission-system`) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
- * In replace mode the tag is prepended; in append mode it follows the shared
- * inherited content so the stable prefix is cacheable by the LLM's KV cache.
+ * - "replace" mode: parent/genericBase + active_agent tag + env header +
+ *   config.systemPrompt.  No `<sub_agent_context>` bridge and no
+ *   `<agent_instructions>` wrapper — the custom prompt has full control and
+ *   the final say.
+ * - "append" mode: parent/genericBase + sub-agent context bridge +
+ *   active_agent tag + env header + config.systemPrompt (wrapped in
+ *   `<agent_instructions>` when non-empty).
+ * - "append" with empty systemPrompt: pure parent clone.
  *
- * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so
+ * downstream extensions (e.g. `@gotgenes/pi-permission-system`) can resolve
+ * per-agent policy inside the child session by parsing the system prompt.
+ * The tag follows the cacheable parent prefix in both modes.
+ *
+ * @param parentSystemPrompt  The parent agent's effective system prompt.
  */
 export function buildAgentPrompt(
   config: AgentPromptConfig,
@@ -33,8 +41,9 @@ Working directory: ${cwd}
 ${env.isGitRepo ? `Git repository: yes\nBranch: ${env.branch}` : "Not a git repository"}
 Platform: ${env.platform}`;
 
+  const identity = parentSystemPrompt ?? genericBase;
+
   if (config.promptMode === "append") {
-    const identity = parentSystemPrompt ?? genericBase;
 
     const bridge = `<sub_agent_context>
 You are operating as a sub-agent invoked to handle a specific task.
@@ -69,18 +78,14 @@ You are operating as a sub-agent invoked to handle a specific task.
     );
   }
 
-  // "replace" mode — env header + the config's full system prompt
-  const replaceHeader = `You are a pi coding agent sub-agent.
-You have been invoked to handle a specific task autonomously.
-
-${envBlock}`;
-
-  return (
-    activeAgentTag + replaceHeader + "\n\n" + config.systemPrompt
-  );
+  // "replace" mode — parent/genericBase prefix first for KV cache reuse, then
+  // the active_agent tag, env block, and the config's full system prompt.
+  // Unlike append mode, no <sub_agent_context> bridge or <agent_instructions>
+  // wrapper is injected — the custom prompt retains full control.
+  return identity + "\n\n" + activeAgentTag + envBlock + "\n\n" + config.systemPrompt;
 }
 
-/** Fallback base prompt when parent system prompt is unavailable in append mode. */
+/** Fallback base prompt when parent system prompt is unavailable (both modes). */
 const genericBase = `# Role
 You are a general-purpose coding agent for complex, multi-step tasks.
 You have full access to read, write, edit files, and execute commands.