@gotgenes/pi-subagents 6.18.2 → 6.18.4

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [6.18.4](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.3...pi-subagents-v6.18.4) (2026-05-24)
+
+
+### Documentation
+
+* mark RunnerIO split done in architecture ([#167](https://github.com/gotgenes/pi-packages/issues/167)) ([824fd72](https://github.com/gotgenes/pi-packages/commit/824fd726361f62b6696dcc62de3b0bbb9cf45711))
+* plan narrow RunnerIO into EnvironmentIO + SessionFactoryIO ([#167](https://github.com/gotgenes/pi-packages/issues/167)) ([8110fec](https://github.com/gotgenes/pi-packages/commit/8110fec44dfaf08bd93d9cbc59ad04c6cba62a84))
+* **retro:** add planning stage notes for issue [#167](https://github.com/gotgenes/pi-packages/issues/167) ([1aceff7](https://github.com/gotgenes/pi-packages/commit/1aceff77c8177093c60b90b87a3f991cb0186602))
+* **retro:** add retro notes for issue [#180](https://github.com/gotgenes/pi-packages/issues/180) ([1fcd0ac](https://github.com/gotgenes/pi-packages/commit/1fcd0ace6fd7f5ec90a8d44423b276eb351875af))
+* **retro:** add TDD stage notes for issue [#167](https://github.com/gotgenes/pi-packages/issues/167) ([870c767](https://github.com/gotgenes/pi-packages/commit/870c7670fdab831d408232c126312d0b5010d6f4))
+
+## [6.18.3](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.2...pi-subagents-v6.18.3) (2026-05-24)
+
+
+### Performance Improvements
+
+* reorder append-mode prompt for KV cache reuse ([#180](https://github.com/gotgenes/pi-packages/issues/180)) ([5f688bd](https://github.com/gotgenes/pi-packages/commit/5f688bd1d008e20987d28626c5f5d0df0f66b854))
+
+
+### Documentation
+
+* plan reorder append-mode prompt for KV cache reuse ([#180](https://github.com/gotgenes/pi-packages/issues/180)) ([bb0ddec](https://github.com/gotgenes/pi-packages/commit/bb0ddec8a7beb37baace5698e4fa4d09e61497d6))
+* **retro:** add planning stage notes for issue [#180](https://github.com/gotgenes/pi-packages/issues/180) ([3413158](https://github.com/gotgenes/pi-packages/commit/341315898baa09652df18731ad318c89861ec62c))
+* **retro:** add retro notes for issue [#166](https://github.com/gotgenes/pi-packages/issues/166) ([fae30ce](https://github.com/gotgenes/pi-packages/commit/fae30cec3dd99bbac490a2764a8340aa12fc171c))
+* **retro:** add TDD stage notes for issue [#180](https://github.com/gotgenes/pi-packages/issues/180) ([1560f2d](https://github.com/gotgenes/pi-packages/commit/1560f2d6f7029cbbe0cc7b1efe1aba2a243e8357))
+
 ## [6.18.2](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v6.18.1...pi-subagents-v6.18.2) (2026-05-24)
 
 

package/docs/architecture/architecture.md

@@ -500,20 +500,20 @@ These are fire-and-forget broadcast events — no request IDs, no reply channels
 These interfaces carry hidden dependencies that obscure true coupling.
 Bags with 10+ fields are the highest priority for decomposition.
 
-| Interface                   | Fields                             | Consumers                                         | Severity |
-| --------------------------- | ---------------------------------- | ------------------------------------------------- | -------- |
-| `ResolvedSpawnConfig`       | 3 nested                           | foreground-runner, background-spawner, agent-tool | ✓ done   |
-| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested) | agent-manager (internal)                          | ✓ done   |
-| `RunOptions`                | 12                                 | agent-runner                                      | High     |
-| `SessionConfig`             | 11                                 | agent-runner (output of assembler)                | High     |
-| `NotificationDetails`       | 10                                 | notification                                      | Medium   |
-| `ResourceLoaderOptions`     | 10                                 | agent-runner (SDK bridge)                         | Medium   |
-| `RunnerIO`                  | 9 methods                          | agent-runner                                      | Medium   |
-| `CreateSessionOptions`      | 9                                  | agent-runner (SDK bridge)                         | Medium   |
-| `AgentToolDeps`             | 8                                  | agent-tool                                        | Low      |
-| `AgentMenuDeps`             | 8                                  | agent-menu                                        | Low      |
-| `ConversationViewerOptions` | 8                                  | conversation-viewer                               | Low      |
-| `AgentRecordInit`           | 8                                  | agent-record                                      | Low      |
+| Interface                   | Fields                                                 | Consumers                                         | Severity |
+| --------------------------- | ------------------------------------------------------ | ------------------------------------------------- | -------- |
+| `ResolvedSpawnConfig`       | 3 nested                                               | foreground-runner, background-spawner, agent-tool | ✓ done   |
+| `AgentSpawnConfig`          | 13 → 13 (ParentSessionInfo nested)                     | agent-manager (internal)                          | ✓ done   |
+| `RunOptions`                | 12                                                     | agent-runner                                      | High     |
+| `SessionConfig`             | 11                                                     | agent-runner (output of assembler)                | High     |
+| `NotificationDetails`       | 10                                                     | notification                                      | Medium   |
+| `ResourceLoaderOptions`     | 10                                                     | agent-runner (SDK bridge)                         | Medium   |
+| `RunnerIO`                  | split → `EnvironmentIO` (3) + `SessionFactoryIO` (5+1) | agent-runner                                      | ✓ done   |
+| `CreateSessionOptions`      | 9                                                      | agent-runner (SDK bridge)                         | Medium   |
+| `AgentToolDeps`             | 8                                                      | agent-tool                                        | Low      |
+| `AgentMenuDeps`             | 8                                                      | agent-menu                                        | Low      |
+| `ConversationViewerOptions` | 8                                                      | conversation-viewer                               | Low      |
+| `AgentRecordInit`           | 8                                                      | agent-record                                      | Low      |
 
 ### Complexity hotspots
 
@@ -681,10 +681,11 @@ Enables Step 3 (narrowing AgentSpawnConfig, [#166][166]).
 Extracted `parentSessionFile`, `parentSessionId`, `toolCallId` into `ParentSessionInfo`.
 `AgentSpawnConfig`, `BackgroundParams`, `ForegroundParams`, and `RunOptions` all carry the nested group.
 
-### Step 4: Narrow RunnerIO ([#167][167])
+### Step 4: Narrow RunnerIO ([#167][167]) ✓ Done
 
-Split into `EnvironmentIO` and `SessionFactoryIO`.
-Each half can be tested independently.
+`RunnerIO` split into `EnvironmentIO` (3 methods: environment discovery) and `SessionFactoryIO` (5 methods + `assemblerIO`: SDK object creation).
+`RunnerIO` kept as a backward-compatible type alias for the intersection.
+All existing consumers satisfy both sub-interfaces via structural typing with no call-site changes.
 
 ### Step 5: Extract ToolFilterConfig from SessionConfig ([#168][168])
 

package/docs/plans/0167-narrow-runner-io.md

@@ -0,0 +1,150 @@
+---
+issue: 167
+issue_title: "refactor(pi-subagents): narrow RunnerIO (9 methods → 2 focused interfaces)"
+---
+
+# Narrow RunnerIO into EnvironmentIO + SessionFactoryIO
+
+## Problem Statement
+
+`RunnerIO` in `agent-runner.ts` bundles 8 members (7 methods + 1 sub-interface) into a single IO boundary.
+The methods split naturally into two concerns — environment discovery vs. SDK object creation — but the current monolithic interface forces every consumer (and every test mock) to provide all members regardless of which subset they actually use.
+This violates Interface Segregation (ISP) and inflates test factory helpers.
+
+## Goals
+
+- Split `RunnerIO` into two focused interfaces: `EnvironmentIO` (3 methods) and `SessionFactoryIO` (5 methods + `assemblerIO`).
+- Keep `RunnerIO` as a type alias (`EnvironmentIO & SessionFactoryIO`) so the change is fully backward-compatible at the type level.
+- Update both test `createRunnerIO()` factories to use the new sub-interfaces in their comments/structure (no behavioral test changes needed — factories already return plain objects).
+- Zero runtime behavior change.
+
+## Non-Goals
+
+- Splitting the `runAgent()` function itself — that's a separate concern.
+- Changing how `createAgentRunner()` accepts its IO parameter — it keeps taking `RunnerIO` (the intersection).
+- Refactoring `index.ts` wiring — the construction site already builds a plain object; it will continue to satisfy `RunnerIO`.
+- Extracting `AssemblerIO` further — it already has its own interface in `session-config.ts`.
+
+## Background
+
+`RunnerIO` was introduced in issue #133 to decouple `agent-runner.ts` from direct Pi SDK imports.
+It succeeded at making the runner testable via plain stubs, but bundled all IO into one wide interface.
+Issue #164 (closed) reorganized source into domain directories; the current file path is `src/lifecycle/agent-runner.ts`.
+
+The 8 members group into two cohesive clusters:
+
+| Cluster               | Members                                                                                                 | Responsibility                                    |
+| --------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| Environment discovery | `detectEnv`, `getAgentDir`, `deriveSessionDir`                                                          | Discover runtime environment, resolve directories |
+| Session factory       | `createResourceLoader`, `createSessionManager`, `createSettingsManager`, `createSession`, `assemblerIO` | Create SDK objects for a child session            |
+
+In `runAgent()`, the environment methods are called first (lines ~265–275), then the factory methods build SDK objects (lines ~280–320).
+The two groups have no cross-dependencies within `runAgent()`.
+
+## Design Overview
+
+### New interfaces
+
+```typescript
+/** Environment discovery — detect runtime context and resolve directories. */
+export interface EnvironmentIO {
+  detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
+  getAgentDir: () => string;
+  deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+}
+
+/** Session factory — create SDK objects for a child agent session. */
+export interface SessionFactoryIO {
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
+  createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
+  createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
+  createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
+  assemblerIO: AssemblerIO;
+}
+
+/**
+ * IO boundary injected into runAgent().
+ * Backward-compatible intersection of the two focused interfaces.
+ */
+export type RunnerIO = EnvironmentIO & SessionFactoryIO;
+```
+
+### Backward compatibility
+
+- `RunnerIO` becomes a type alias for the intersection.
+  Any code that imports `RunnerIO` continues to compile unchanged.
+- `index.ts` builds a plain object literal that satisfies `RunnerIO` — no change needed.
+- Test factories return unannotated objects that are structurally compatible — no change needed for compilation, but comments can be updated to reference the sub-interfaces.
+
+### Consumer call-site verification
+
+The call site in `createAgentRunner()` (3 lines):
+
+```typescript
+export function createAgentRunner(io: RunnerIO): AgentRunner {
+  return {
+    run: (snapshot, type, prompt, options) => runAgent(snapshot, type, prompt, options, io),
+    resume: resumeAgent,
+  };
+}
+```
+
+This passes the full `io` to `runAgent()`, which continues to accept `RunnerIO`.
+No Tell-Don't-Ask or LoD violations introduced.
+
+## Module-Level Changes
+
+### `src/lifecycle/agent-runner.ts`
+
+1. Add `EnvironmentIO` interface (3 members) before the current `RunnerIO` definition.
+2. Add `SessionFactoryIO` interface (5 members) after `EnvironmentIO`.
+3. Change `RunnerIO` from an `interface` to a `type` alias: `type RunnerIO = EnvironmentIO & SessionFactoryIO`.
+4. Export the two new interfaces alongside `RunnerIO`.
+5. Move existing JSDoc from `RunnerIO` members to the sub-interfaces.
+6. No changes to function signatures — `runAgent()` and `createAgentRunner()` keep accepting `RunnerIO`.
+
+### `src/index.ts`
+
+No changes.
+The construction site builds a plain object satisfying all 8 members — TypeScript's structural typing ensures it satisfies `EnvironmentIO & SessionFactoryIO` without annotation changes.
+
+### Test files
+
+No behavioral changes.
+The `createRunnerIO()` factories in both test files return unannotated plain objects that structurally satisfy the intersection.
+Comments referencing `RunnerIO` can be updated to mention the sub-interfaces for documentation clarity.
+
+Files affected:
+
+- `test/lifecycle/agent-runner.test.ts` — update comment (line ~23–27).
+- `test/lifecycle/agent-runner-extension-tools.test.ts` — update comment (line ~46).
+
+## Test Impact Analysis
+
+1. **New unit tests enabled:** The split enables future tests that inject only `EnvironmentIO` or only `SessionFactoryIO` — useful when testing environment-only or factory-only code paths in future extractions.
+   No new tests are needed in this issue because `runAgent()` still consumes the full intersection.
+2. **Redundant tests:** None — existing tests already test through `runAgent()` which uses all members.
+3. **Tests that stay as-is:** All existing tests in both `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` remain valid; the factories produce objects compatible with the new type alias.
+
+## TDD Order
+
+1. **Red → Green: export `EnvironmentIO` and `SessionFactoryIO`, convert `RunnerIO` to type alias.**
+   Test surface: existing `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` suites (must still pass).
+   Run `pnpm run check` to verify type compatibility.
+   Commit: `refactor: split RunnerIO into EnvironmentIO and SessionFactoryIO (#167)`
+
+2. **Update test comments to reference sub-interfaces.**
+   Test surface: no behavioral test changes — comment-only updates.
+   Commit: `refactor: update test comments for RunnerIO sub-interfaces (#167)`
+
+## Risks and Mitigations
+
+| Risk                                          | Mitigation                                                                                          |
+| --------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| External consumers importing `RunnerIO` break | `RunnerIO` remains exported as a type alias for the intersection — fully backward-compatible        |
+| Test factories need updating                  | Factories return unannotated objects — structural typing handles the new type alias without changes |
+| Future extractions assume wrong interface     | Each sub-interface has a clear JSDoc explaining its scope                                           |
+
+## Open Questions
+
+None — the split follows the natural cohesion boundary identified in the issue body.

package/docs/plans/0180-reorder-append-prompt-for-kv-cache.md

@@ -0,0 +1,100 @@
+---
+issue: 180
+issue_title: "perf(pi-subagents): reorder append-mode system prompt to enable KV cache reuse"
+---
+
+# Reorder append-mode system prompt for KV cache reuse
+
+## Problem Statement
+
+In append mode, `buildAgentPrompt()` places varying, agent-specific content (the `<active_agent>` tag and env block) *before* the large shared inherited system prompt (~8k tokens).
+LLM KV caching works on prefixes — the cache is only reusable when the beginning of the prompt matches.
+Every subagent spawn reprocesses the entire inherited prompt from scratch because the prefix differs per agent.
+
+## Goals
+
+- Reorder the append-mode system prompt so shared/stable content comes first and varying content follows.
+- Preserve the `<active_agent>` tag at any position — pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` searches the full string.
+- Keep replace-mode prompt ordering unchanged (it has no shared inherited content to cache).
+- Update tests and JSDoc to reflect the new ordering.
+
+## Non-Goals
+
+- Changing replace-mode prompt assembly (no shared prefix to cache).
+- Modifying pi-permission-system (its regex parsing is already position-independent).
+- Changing the *content* of any prompt section — only reordering.
+
+## Background
+
+`buildAgentPrompt()` in `src/session/prompts.ts` assembles the system prompt for subagents.
+In append mode, the current ordering is:
+
+```text
+1. <active_agent name="${name}"/>     ← VARIES per agent
+2. # Environment ...                  ← VARIES per runtime
+3. <inherited_system_prompt>          ← SHARED (~8k tokens)
+4. <sub_agent_context>                ← SHARED (static)
+5. <agent_instructions>               ← VARIES per agent
+6. memory / skills                    ← VARIES
+```
+
+pi-permission-system's `getActiveAgentNameFromSystemPrompt()` in `src/active-agent.ts` uses `ACTIVE_AGENT_TAG_REGEX.exec(systemPrompt)` — a regex search that finds the tag at any position, confirmed by reading the source.
+
+## Design Overview
+
+Move shared/stable sections to the front of the append-mode prompt:
+
+```text
+1. <inherited_system_prompt>          ← SHARED (~8k tokens, NOW CACHEABLE)
+2. <sub_agent_context>                ← SHARED (static)
+3. <active_agent name="${name}"/>     ← VARIES (after cached prefix)
+4. # Environment ...                  ← VARIES
+5. <agent_instructions>               ← VARIES per agent
+6. memory / skills                    ← VARIES
+```
+
+This is a pure reordering — no content changes.
+The `<active_agent>` tag remains in the system prompt for pi-permission-system to find via regex.
+The env block and agent instructions still provide context to the model; their position relative to the inherited prompt is not semantically significant.
+
+## Module-Level Changes
+
+### `src/session/prompts.ts`
+
+1. Reorder the return statement in the `config.promptMode === "append"` branch to place `identity` (wrapped in `<inherited_system_prompt>`) and `bridge` before `activeAgentTag` and `envBlock`.
+2. Update the JSDoc comment on `buildAgentPrompt()` — replace "Both modes prepend" language with a description that notes the tag is included (not necessarily prepended) in append mode.
+
+### `test/session/prompts.test.ts`
+
+1. Update "prepends `<active_agent>` tag in append mode" — change from asserting `prompt.startsWith()` to asserting the tag appears *after* the inherited system prompt.
+2. Update "active_agent tag appears before envBlock in both modes" — the append-mode assertions change: the tag should still appear before the env block, but no longer at index 0.
+   The replace-mode assertions remain unchanged (`tagIdx === 0`).
+
+## Test Impact Analysis
+
+- Two existing tests assert `<active_agent>` is prepended (index 0) in append mode — these must change to assert the new ordering.
+- All other prompt tests use `toContain()` and are position-independent — they pass without changes.
+- No new test files or test surfaces are needed; the existing test suite covers the reordering adequately once the positional assertions are updated.
+
+## TDD Order
+
+1. **Red: update positional assertions for append mode.**
+   Change the two append-mode tests to assert the new ordering: `<inherited_system_prompt>` appears before `<active_agent>`, and the tag appears before the env block but not at index 0.
+   Commit: `test: assert cache-friendly prompt ordering in append mode (#180)`
+
+2. **Green: reorder the append-mode return statement.**
+   Move `identity` + `<inherited_system_prompt>` wrapper and `bridge` before `activeAgentTag` + `envBlock` in the return expression.
+   Update the JSDoc on `buildAgentPrompt()`.
+   Commit: `perf: reorder append-mode prompt for KV cache reuse (#180)`
+
+## Risks and Mitigations
+
+| Risk                                         | Mitigation                                                                                                                                         |
+| -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| pi-permission-system depends on tag position | Confirmed `ACTIVE_AGENT_TAG_REGEX.exec()` searches the full string — position-independent.                                                         |
+| Model behavior changes with reordered prompt | The same content is present; only ordering changes. The inherited system prompt as the "base" followed by specialization is arguably more natural. |
+| Replace mode accidentally affected           | Replace mode has its own code path and is not touched by this change.                                                                              |
+
+## Open Questions
+
+None — the design is straightforward and confirmed safe by code inspection.

package/docs/retro/0166-extract-parent-session-info.md

@@ -37,3 +37,30 @@ Type check and lint both clean after all steps.
 - `RunOptions` in `agent-runner.ts` needed a new import of `ParentSessionInfo` from `agent-manager.ts`; no circular dependency since `agent-runner.ts` already imports from `agent-manager.ts`.
 - `agent-tool.ts` still imports `AgentSpawnConfig` (needed by `AgentToolManager` interface) — the new `ParentSessionInfo` import was added alongside it.
 - All 5 commits are clean `refactor:` messages; architecture doc update is a separate `docs:` commit.
+
+## Stage: Final Retrospective (2026-05-24T18:00:00Z)
+
+### Session summary
+
+Planning, TDD implementation (5 steps), shipping, and CI verification all completed in a single session.
+Released as `pi-subagents-v6.18.2`.
+Zero rework — every TDD step went green on first attempt.
+
+### Observations
+
+#### What went well
+
+- The planning session's identification of the deep-merge trap in `background-spawner.test.ts`'s `makeParams` factory paid off — the TDD implementation handled it without friction because the risk was anticipated.
+- The 5-step inside-out TDD order (manager → runner → background → foreground → agent-tool) was the right sequence.
+  Each step only introduced type errors in files that subsequent steps would fix, with no circular breakage.
+- Clean mechanical execution — 805 tests before and after, zero rework commits, lint and type-check clean throughout.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan repeated the issue body's stale "13 fields" count without verifying against the actual `AgentSpawnConfig` interface (which had 15 fields after `bypassQueue` was added in a prior issue).
+  The plan also inconsistently claimed the extraction would reduce the count to both "11" and "10" in different places.
+  Impact: required corrections in the architecture doc update, but no implementation rework.
+
+#### What caused friction (user side)
+
+- None observed — the user let the session run autonomously through all stages without intervention.

package/docs/retro/0167-narrow-runner-io.md

@@ -0,0 +1,35 @@
+---
+issue: 167
+issue_title: "refactor(pi-subagents): narrow RunnerIO (9 methods → 2 focused interfaces)"
+---
+
+# Retro: #167 — narrow RunnerIO (9 methods → 2 focused interfaces)
+
+## Stage: Planning (2026-05-24T20:00:00Z)
+
+### Session summary
+
+Produced a plan to split the `RunnerIO` interface in `agent-runner.ts` into two focused sub-interfaces (`EnvironmentIO` and `SessionFactoryIO`) while keeping `RunnerIO` as a backward-compatible type alias for their intersection.
+The change is a pure refactoring with zero runtime behavior change.
+
+### Observations
+
+- The split is mechanical and low-risk: `RunnerIO` becomes `type RunnerIO = EnvironmentIO & SessionFactoryIO`, and all existing consumers (production code and test factories) continue to compile via structural typing.
+- Dependency #164 (reorganize into domain directories) is already closed, so file paths are current.
+- The two test `createRunnerIO()` factories are unannotated (intentionally, per testing skill guidelines), so they don't need type-level updates — only comment updates for documentation.
+- This is a two-commit TDD plan, suitable for `/build-plan` rather than full TDD cycles since no new tests are required.
+
+## Stage: Implementation — TDD (2026-05-24T20:45:00Z)
+
+### Session summary
+
+Completed both TDD steps in full.
+Step 1 added `EnvironmentIO` and `SessionFactoryIO` interfaces and converted `RunnerIO` to a type alias in `agent-runner.ts`; step 2 updated comments in both test factories.
+Test count held steady at 805/805 (50 files) — no behavioral changes.
+
+### Observations
+
+- The type check (`pnpm run check`) passed immediately after the interface split — structural typing meant zero call-site changes in `index.ts` or test factories.
+- `RunnerIO` JSDoc was split: `EnvironmentIO` got the environment-discovery description, `SessionFactoryIO` got the original "decouples from Pi SDK imports" description, and `RunnerIO` itself got a short backward-compatibility note.
+- Architecture doc updated: wide-interface table row and Step 4 roadmap entry both marked done.
+- No deviations from the plan.

package/docs/retro/0180-reorder-append-prompt-for-kv-cache.md

@@ -0,0 +1,62 @@
+---
+issue: 180
+issue_title: "perf(pi-subagents): reorder append-mode system prompt to enable KV cache reuse"
+---
+
+# Retro: #180 — Reorder append-mode system prompt for KV cache reuse
+
+## Stage: Planning (2026-05-24T20:00:00Z)
+
+### Session summary
+
+Produced a plan to reorder the append-mode system prompt in `buildAgentPrompt()` so the shared inherited content (~8k tokens) comes before the varying `<active_agent>` tag and env block, enabling LLM KV cache prefix reuse across subagent invocations.
+
+### Observations
+
+- Confirmed pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` is position-independent — no changes needed in that package despite the `pkg:pi-permission-system` label on the issue.
+- Only two tests assert positional ordering in append mode (`startsWith` and `tagIdx === 0`); all other prompt tests use `toContain()` and are unaffected.
+- Replace mode is a separate code path and is not touched.
+- The TDD cycle is minimal: one red step (update two positional assertions), one green step (reorder the return statement + update JSDoc).
+
+## Stage: Implementation — TDD (2026-05-24T20:15:00Z)
+
+### Session summary
+
+Completed both TDD cycles in `buildAgentPrompt()` in `src/session/prompts.ts`.
+Two positional assertions in `test/session/prompts.test.ts` were updated to expect the new ordering (red), then the append-mode return statement was reordered and the JSDoc updated (green).
+Test count unchanged at 805 across 50 files.
+
+### Observations
+
+- The JSDoc bullet for append mode also described the old ordering ("env header + parent system prompt + ...") and was corrected as part of the green step.
+- The `<active_agent>` tag is followed by a `\n\n`, so when it moves after `<sub_agent_context>`, a `\n\n` separator between the bridge and the tag was needed to maintain clean section boundaries.
+- No deviations from the plan; both steps were exactly as described.
+
+## Stage: Final Retrospective (2026-05-24T21:00:00Z)
+
+### Session summary
+
+Issue #180 went from external community observation through release (`pi-subagents-v6.18.3`) in a single continuous session.
+The plan predicted exactly two TDD steps; both executed without deviation or rework.
+
+### Observations
+
+#### What went well
+
+- End-to-end lifecycle in one session: external comment → issue → plan → TDD → ship → release.
+  No corrections, no scope drift, no rework across any stage.
+- The plan's test impact analysis was accurate — only two positional assertions needed updating; all `toContain()` tests passed untouched.
+- Confirming pi-permission-system's `ACTIVE_AGENT_TAG_REGEX.exec()` is position-independent during planning eliminated the second `pkg:*` label's scope entirely, keeping the change to a single file.
+
+#### What caused friction (agent side)
+
+- `wrong-abstraction` — Launched an Explore agent (75.9s, 18 tool uses) to map the prompt assembly flow when the `package-pi-subagents` skill already listed the file layout and `prompts.ts` is 107 lines.
+  Direct `read` + `grep` achieved the same confirmation in ~3 seconds during the planning phase.
+  Impact: added ~75 seconds of latency but no rework.
+- `missing-context` — The plan listed "Update the JSDoc comment" but missed that the mode-description bullet ("env header + parent system prompt + ...") also encoded the old ordering.
+  Caught during the green step and fixed in the same commit.
+  Impact: added friction but no rework.
+
+#### What caused friction (user side)
+
+- Nothing notable — the user's prompts were well-scoped and the issue description was unambiguous.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "6.18.2",
+  "version": "6.18.4",
   "type": "module",
   "exports": {
     ".": "./src/service.ts"

package/src/lifecycle/agent-runner.ts

@@ -91,7 +91,7 @@ export interface SessionManagerLike {
   getSessionFile(): string | undefined;
 }
 
-/** Options passed to RunnerIO.createResourceLoader. */
+/** Options passed to EnvironmentIO/SessionFactoryIO methods. */
 export interface ResourceLoaderOptions {
   cwd: string;
   agentDir: string;
@@ -105,7 +105,7 @@ export interface ResourceLoaderOptions {
   appendSystemPromptOverride?: (base: string[]) => string[];
 }
 
-/** Options passed to RunnerIO.createSession. */
+/** Options passed to SessionFactoryIO.createSession. */
 export interface CreateSessionOptions {
   cwd: string;
   agentDir: string;
@@ -119,22 +119,40 @@ export interface CreateSessionOptions {
 }
 
 /**
- * IO boundary injected into runAgent().
+ * Environment discovery — detect runtime context and resolve directories.
  *
- * Decouples the runner from direct Pi SDK imports and sibling-module IO,
- * making it testable via plain stub objects without vi.mock().
+ * Decouples the runner from direct process/SDK reads so each can be stubbed
+ * independently in tests.
  */
-export interface RunnerIO {
+export interface EnvironmentIO {
   detectEnv: (exec: ShellExec, cwd: string) => Promise<EnvInfo>;
   getAgentDir: () => string;
-  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   deriveSessionDir: (parentSessionFile: string | undefined, effectiveCwd: string) => string;
+}
+
+/**
+ * Session factory — create SDK objects for a child agent session.
+ *
+ * Decouples the runner from direct Pi SDK imports and sibling-module IO,
+ * making it testable via plain stub objects without vi.mock().
+ */
+export interface SessionFactoryIO {
+  createResourceLoader: (opts: ResourceLoaderOptions) => ResourceLoaderLike;
   createSessionManager: (cwd: string, sessionDir: string) => SessionManagerLike;
   createSettingsManager: (cwd: string, agentDir: string) => SettingsManager;
   createSession: (opts: CreateSessionOptions) => Promise<{ session: AgentSession }>;
   assemblerIO: AssemblerIO;
 }
 
+/**
+ * IO boundary injected into runAgent().
+ *
+ * Backward-compatible intersection of EnvironmentIO and SessionFactoryIO.
+ * Callers that previously constructed a RunnerIO object continue to satisfy
+ * both sub-interfaces via TypeScript's structural typing.
+ */
+export type RunnerIO = EnvironmentIO & SessionFactoryIO;
+
 // ── Public interfaces ─────────────────────────────────────────────────────────
 
 export interface RunOptions {

package/src/session/prompts.ts

@@ -17,12 +17,14 @@ export interface PromptExtras {
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * 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.
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
@@ -76,13 +78,17 @@ You are operating as a sub-agent invoked to handle a specific task.
       ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
       : "";
 
+    // Place shared/stable content first so the LLM's KV cache can reuse the
+    // inherited prefix across all subagent invocations. The <active_agent> tag
+    // and env block vary per call and are placed after the cacheable prefix.
     return (
-      activeAgentTag +
-      envBlock +
-      "\n\n<inherited_system_prompt>\n" +
+      "<inherited_system_prompt>\n" +
       identity +
       "\n</inherited_system_prompt>\n\n" +
       bridge +
+      "\n\n" +
+      activeAgentTag +
+      envBlock +
       customSection +
       extrasSuffix
     );