@gotgenes/pi-subagents 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -5,6 +5,20 @@ 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).
 
+## [5.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.2.0...pi-subagents-v5.3.0) (2026-05-19)
+
+
+### Features
+
+* add assembleSessionConfig in session-config.ts ([ee8076d](https://github.com/gotgenes/pi-packages/commit/ee8076dc2292ec957b64894af3fcd22567f23be5))
+
+
+### Documentation
+
+* add [#80](https://github.com/gotgenes/pi-packages/issues/80) to architecture roadmap, mark [#69](https://github.com/gotgenes/pi-packages/issues/69) and [#71](https://github.com/gotgenes/pi-packages/issues/71) done ([5744e28](https://github.com/gotgenes/pi-packages/commit/5744e28ac993454f8cb33afb18e5247569f9f971))
+* plan session-config assembler extraction ([#71](https://github.com/gotgenes/pi-packages/issues/71)) ([5d2cd4f](https://github.com/gotgenes/pi-packages/commit/5d2cd4f8de214a03a11688b56221679591aedafd))
+* **retro:** add retro notes for issue [#69](https://github.com/gotgenes/pi-packages/issues/69) ([18cbbdb](https://github.com/gotgenes/pi-packages/commit/18cbbdb627f2ae63f8109c1f5597c31265738415))
+
 ## [5.2.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.1.0...pi-subagents-v5.2.0) (2026-05-19)
 
 

package/docs/architecture/architecture.md

@@ -342,14 +342,14 @@ The following issues track the work needed to bring `pi-subagents` to the same l
 
 ### Phase 1: Foundation
 
-These three issues are independent of each other and can land in any order.
-Together they eliminate module-scope mutable state and create a testable functional core.
+These issues are independent of each other and can land in any order.
+Together they eliminate module-scope mutable state, create a testable functional core, and simplify the agent-types API.
 
-1. **gotgenes/pi-packages#69** — Create `SubagentRuntime`
+1. **gotgenes/pi-packages#69** ✓ — Create `SubagentRuntime`
    - Move `defaultMaxTurns`, `graceTurns`, `agentActivity`, `currentCtx`, and widget references out of closure/module scope into a single factory-constructed object.
    - This unblocks handler extraction (Issue #70) by giving handlers a concrete deps bag instead of closure variables.
 
-2. **gotgenes/pi-packages#71** — Extract pure agent-session assembler from `agent-runner.ts`
+2. **gotgenes/pi-packages#71** ✓ — Extract pure agent-session assembler from `agent-runner.ts`
    - Split `runAgent()` into a pure configuration assembler (~200 lines) and an IO shell (~200 lines).
    - The assembler becomes independently testable without mocking the Pi SDK.
 
@@ -357,6 +357,10 @@ Together they eliminate module-scope mutable state and create a testable functio
    - Replace the `process.cwd()` call in `dispose()` with a constructor parameter.
    - A small, mechanical prerequisite for Issue #72.
 
+4. **gotgenes/pi-packages#80** — Consolidate `getConfig` / `getAgentConfig` into a single resolution path
+   - Replace the two overlapping lookup functions with a single `resolveAgentConfig(type): AgentConfig` that handles the unknown-type fallback internally.
+   - Eliminates the duplicated fallback chain exposed by #71 and simplifies test mock setup.
+
 ### Phase 2: Core decomposition
 
 These build on Phase 1 and should land after it.
@@ -394,19 +398,21 @@ Small cleanups that are safest after the structural changes settle.
 ### Dependency graph
 
 ```text
-#69 (SubagentRuntime) ──┬──► #70 (handler extraction)
+#69 (SubagentRuntime) ✓ ─┬─► #70 (handler extraction)
                         │
-                        └──► #72 (AgentManager DI) ──(optional)──► #70
+                        └─► #72 (AgentManager DI) ──(optional)──► #70
+
+#71 (pure assembler) ✓ ──► #80 (consolidate getConfig/getAgentConfig)
 
-#71 (pure assembler) ─────(independent)────► (can land any time)
+#76 (cwd injection) ────► #72
 
-#76 (cwd injection) ──────► #72
+#80 (config lookup) ────(independent, simplifies #72 and test mocks)
 
-#66 (type casts) ◄────────(after structural changes settle)
-#77 (projectAgentsDir) ◄──(after #66 or parallel)
+#66 (type casts) ◄─────(after structural changes settle)
+#77 (projectAgentsDir) ◄─(after #66 or parallel)
 
-#61 (transcript format) ◄─(after structural refactor)
-#22 (parent session) ◄────(cross-extension, independent)
+#61 (transcript format) ◄(after structural refactor)
+#22 (parent session) ◄──(cross-extension, independent)
 ```
 
 ### Recommended order
@@ -414,9 +420,10 @@ Small cleanups that are safest after the structural changes settle.
 The recommended sequence is:
 
 ```text
-#69 → #71 → #76 → #72 → #70 → #66 → #77 → #61
+#69 ✓ → #71 ✓ → #80 → #76 → #72 → #70 → #66 → #77 → #61
 ```
 
+Issue #80 slots after #71 because it cleans up the redundant lookup that #71 exposed, and simplifies mock setup for subsequent issues.
 Issue #22 is a parallel cross-extension track and does not gate the structural work.
 
 ## Relationship with upstream

package/docs/plans/0071-extract-session-config-assembler.md

@@ -0,0 +1,362 @@
+---
+issue: 71
+issue_title: "refactor: extract pure agent-session assembler from agent-runner.ts"
+---
+
+# Extract session-config assembler from agent-runner
+
+## Problem Statement
+
+`agent-runner.ts` `runAgent()` is ~390 lines (post-#69 cleanup) and mixes three concerns:
+
+1. Configuration assembly — resolve model, detect env, build prompt extras, preload skills, build memory blocks, assemble system prompt, compute tool names (~200 lines).
+2. Session construction — create `DefaultResourceLoader`, call `createAgentSession`, filter tools, bind extensions (~100 lines).
+3. Runtime orchestration — subscribe to events, enforce turn limits, collect results (~90 lines).
+
+The configuration assembly is deterministic given resolved inputs and does not need an `AgentSession`.
+Because it is inlined in `runAgent()`, it cannot be unit-tested without mocking the entire Pi SDK (`createAgentSession`, `DefaultResourceLoader`, `SessionManager`, `SettingsManager`).
+
+## Goals
+
+- Extract a pure `assembleSessionConfig()` function into a new `src/session-config.ts` module.
+- The assembler takes resolved inputs (agent config, environment info, narrow context) and returns a data object with everything `runAgent()` needs to create the session.
+- Reduce `runAgent()` to an IO shell: call the assembler, create SDK objects, wire subscriptions, and run the event loop.
+- Add focused unit tests for the assembler covering model resolution fallback chain, skill preloading, memory block selection (read-write vs read-only), prompt mode, tool name assembly, and disallowed-tool computation.
+- No behavior change.
+
+## Non-Goals
+
+- Changing the `RunResult` shape or `RunOptions` interface.
+- Refactoring the event subscription / turn-limit logic (stays in `runAgent()`).
+- Extracting `resumeAgent` or `steerAgent`.
+- Modifying the public API surface (`service.ts`).
+
+## Background
+
+### Prior art
+
+`pi-permission-system` extracted `evaluate()` — a pure function of `(surface, pattern, ruleset)` — from `PermissionManager.checkPermission()`.
+That made permission decisions independently testable without filesystem access or a manager instance.
+This plan follows the same pattern: extract a pure core from an IO-heavy function.
+
+### Current `runAgent()` structure
+
+Lines 220–460 of `agent-runner.ts` break into these logical phases:
+
+| Phase                           | Lines (approx) | SDK dependency                                           |
+| ------------------------------- | -------------- | -------------------------------------------------------- |
+| Config + agentConfig lookup     | 224–225        | None (agent-types registry)                              |
+| effectiveCwd                    | 228            | None                                                     |
+| detectEnv                       | 230            | `pi.exec` (async IO)                                     |
+| parentSystemPrompt              | 233            | `ctx.getSystemPrompt()`                                  |
+| extensions / skills resolution  | 237–245        | None                                                     |
+| Skill preloading                | 247–252        | `preloadSkills` (filesystem)                             |
+| Tool names + memory             | 254–274        | None (agent-types registry)                              |
+| System prompt assembly          | 277–303        | `buildAgentPrompt` (pure)                                |
+| noSkills flag                   | 306            | None                                                     |
+| DefaultResourceLoader           | 308–320        | `DefaultResourceLoader` (SDK)                            |
+| Model resolution                | 323–324        | `ctx.modelRegistry` (narrow)                             |
+| Thinking level                  | 327            | None                                                     |
+| sessionOpts construction        | 329–345        | `SessionManager`, `SettingsManager`, `getAgentDir` (SDK) |
+| createAgentSession              | 347            | SDK                                                      |
+| Tool filtering + bindExtensions | 350–400        | `session.*` methods (SDK)                                |
+| Event subscriptions + prompt    | 402–460        | `session.*` methods (SDK)                                |
+
+Everything above the `DefaultResourceLoader` line is configuration assembly — deterministic given resolved inputs.
+Everything from `DefaultResourceLoader` onward is SDK orchestration.
+
+### Modules the assembler will call
+
+All are internal to this package — not Pi SDK:
+
+- `agent-types.ts` — `getConfig()`, `getAgentConfig()`, `getToolNamesForType()`, `getMemoryToolNames()`, `getReadOnlyMemoryToolNames()`
+- `prompts.ts` — `buildAgentPrompt()`
+- `memory.ts` — `buildMemoryBlock()`, `buildReadOnlyMemoryBlock()`
+- `skill-loader.ts` — `preloadSkills()`
+- `default-agents.ts` — `DEFAULT_AGENTS` (fallback config)
+
+### Relevant constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Keep Pi SDK imports out of business-logic modules.
+- Prefer explicit configuration over hidden behavior.
+- Business logic should be pure functions wherever possible — keep IO at the edges.
+
+### Issue #69 status
+
+Issue #69 (`SubagentRuntime`) is implemented.
+Module-scope mutable state has been removed from `agent-runner.ts`.
+`defaultMaxTurns` and `graceTurns` flow through `RunOptions`.
+This plan builds on the post-#69 codebase.
+
+## Design Overview
+
+### Separation of concerns
+
+`detectEnv()` is the only async IO call in the assembly phase — it calls `pi.exec()` to check git state.
+The assembler is synchronous and takes `EnvInfo` as a pre-resolved parameter.
+`runAgent()` calls `detectEnv()` first, then calls the assembler, then does SDK work.
+
+### Narrow context interface
+
+The assembler does not accept `ExtensionContext` — it accepts a narrow interface with only the fields it reads:
+
+```typescript
+interface AssemblerContext {
+  /** Parent working directory (overridable via options.cwd). */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  parentSystemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  parentModel?: Model<any>;
+  /** Model registry for resolving config.model strings. */
+  modelRegistry: ModelRegistry;
+}
+```
+
+`ModelRegistry` is a narrow interface (already exists in `model-resolver.ts`):
+
+```typescript
+interface ModelRegistry {
+  find(provider: string, modelId: string): Model<any> | undefined;
+  getAvailable?(): Model<any>[];
+}
+```
+
+Tests construct plain objects satisfying these interfaces — no SDK mocking needed.
+
+### Assembler signature
+
+```typescript
+function assembleSessionConfig(
+  type: SubagentType,
+  ctx: AssemblerContext,
+  options: AssemblerOptions,
+  env: EnvInfo,
+): SessionConfig;
+```
+
+`AssemblerOptions` is a narrow pick of `RunOptions`:
+
+```typescript
+interface AssemblerOptions {
+  cwd?: string;
+  isolated?: boolean;
+  model?: Model<any>;
+  thinkingLevel?: ThinkingLevel;
+}
+```
+
+### Return type
+
+```typescript
+interface SessionConfig {
+  /** Resolved working directory (options.cwd ?? ctx.cwd). */
+  effectiveCwd: string;
+  /** Fully-assembled system prompt string. */
+  systemPrompt: string;
+  /** Tool names for session creation and filtering. */
+  toolNames: string[];
+  /** Disallowed tool set from agent config (for filterActiveTools). */
+  disallowedSet: Set<string> | undefined;
+  /** Resolved extensions setting (for resource loader and tool filtering). */
+  extensions: boolean | string[];
+  /** Resolved model instance (or undefined → parent fallback). */
+  model: Model<any> | undefined;
+  /** Resolved thinking level (or undefined → inherit). */
+  thinkingLevel: ThinkingLevel | undefined;
+  /** Whether to skip skill loading in the resource loader. */
+  noSkills: boolean;
+  /** Prompt extras for transparency / debugging. */
+  extras: PromptExtras;
+}
+```
+
+### `resolveDefaultModel` moves to session-config.ts
+
+`resolveDefaultModel()` is a pure function that resolves model strings against a registry.
+It belongs in the assembler module alongside the other resolution logic.
+It becomes an internal function (not exported) — its behavior is tested through `assembleSessionConfig()`.
+
+### `filterActiveTools` stays in agent-runner.ts
+
+`filterActiveTools()` operates on a live session's active tool list.
+It runs twice (pre- and post-`bindExtensions`) and is an IO-layer concern.
+It stays in `agent-runner.ts` and consumes `toolNames`, `extensions`, and `disallowedSet` from the `SessionConfig` return.
+
+### `normalizeMaxTurns` stays in agent-runner.ts
+
+`normalizeMaxTurns()` is used in the turn-limit subscription callback — runtime orchestration, not config assembly.
+It stays in `agent-runner.ts`.
+
+### What runAgent() looks like after
+
+```typescript
+export async function runAgent(
+  ctx: ExtensionContext,
+  type: SubagentType,
+  prompt: string,
+  options: RunOptions,
+): Promise<RunResult> {
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+  const env = await detectEnv(options.pi, effectiveCwd);
+
+  const config = assembleSessionConfig(type, {
+    cwd: ctx.cwd,
+    parentSystemPrompt: ctx.getSystemPrompt(),
+    parentModel: ctx.model,
+    modelRegistry: ctx.modelRegistry,
+  }, {
+    cwd: options.cwd,
+    isolated: options.isolated,
+    model: options.model,
+    thinkingLevel: options.thinkingLevel,
+  }, env);
+
+  // SDK orchestration: create loader, session, filter tools, bind, run
+  const agentDir = getAgentDir();
+  const loader = new DefaultResourceLoader({ ... });
+  await loader.reload();
+  const { session } = await createAgentSession({ ... });
+
+  // Tool filtering (two passes), bindExtensions, subscriptions, prompt
+  // ...same as today, using config.toolNames, config.disallowedSet, etc.
+}
+```
+
+Target: `runAgent()` drops to ~200 lines (down from ~390).
+
+### Edge cases
+
+- Unknown agent type: `getAgentConfig()` returns `undefined`.
+  The assembler falls back to `DEFAULT_AGENTS.get("general-purpose")` with `name: type`, matching the current `runAgent()` fallback.
+- Empty `builtinToolNames`: `getToolNamesForType()` already falls back to `BUILTIN_TOOL_NAMES`.
+- `isolated: true` overrides `extensions` and `skills` to `false` — same as today, now inside the assembler.
+- Memory block selection: write-capable agents (have `write` or `edit` in effective tool set, not denied) get read-write memory; others get read-only.
+  The denylist check uses `disallowedSet` from the agent config.
+
+## Module-Level Changes
+
+### `src/session-config.ts` (new)
+
+- `AssemblerContext` interface — narrow context (cwd, parentSystemPrompt, parentModel, modelRegistry).
+- `AssemblerOptions` interface — narrow options subset (cwd, isolated, model, thinkingLevel).
+- `SessionConfig` interface — return type with all assembled configuration.
+- `assembleSessionConfig()` function — pure configuration assembly.
+- `resolveDefaultModel()` — moved from `agent-runner.ts` (internal, not exported).
+
+### `src/agent-runner.ts` (modified)
+
+- Import `assembleSessionConfig` and `SessionConfig` from `./session-config.js`.
+- Remove ~200 lines of configuration assembly from `runAgent()`.
+- Replace with a call to `assembleSessionConfig()` followed by SDK orchestration using the returned `SessionConfig`.
+- Remove `resolveDefaultModel()` (moved to session-config.ts).
+- `filterActiveTools()`, `normalizeMaxTurns()`, `collectResponseText()`, `getLastAssistantText()`, `forwardAbortSignal()` — all stay.
+- `RunOptions`, `RunResult`, `ToolActivity` — all stay (unchanged).
+
+### `test/session-config.test.ts` (new)
+
+- Unit tests for `assembleSessionConfig()` covering all assembly logic.
+- Tests use plain objects for `AssemblerContext` — no SDK mocks.
+- Mocks for `agent-types`, `prompts`, `memory`, `skill-loader` — simple function mocks.
+
+### `test/agent-runner.test.ts` (modified)
+
+- Existing tests stay as-is — they already mock the SDK and test the full `runAgent()` flow.
+- Tests that verified assembly details (e.g., `suppresses AGENTS.md/CLAUDE.md` or `passes effective cwd to the loader`) remain valid because `runAgent()` still does the SDK orchestration.
+- No tests are removed or rewritten.
+
+### `test/agent-runner-extension-tools.test.ts` (unchanged)
+
+- Tests extension-tool filtering via `filterActiveTools` — stays in `agent-runner.ts`.
+- No impact.
+
+## Test Impact Analysis
+
+### New unit tests enabled by the extraction
+
+1. Model resolution fallback chain — test that `assembleSessionConfig` returns the correct model for: explicit option model, config model string (valid/invalid), parent model fallback, and no model.
+2. Skill preloading — test that `skills: string[]` triggers `preloadSkills` and populates `extras.skillBlocks`; `skills: false` and `skills: true` skip preloading.
+3. Memory block selection — test read-write vs read-only memory based on tool availability and denylist interaction.
+4. Tool name assembly — test that `getToolNamesForType` result is augmented with memory tool names when memory is configured.
+5. Extensions / isolated interaction — test that `isolated: true` forces `extensions: false` and `skills: false`.
+6. System prompt assembly — test that `buildAgentPrompt` is called with the correct config, extras, and env.
+7. Disallowed tool set — test construction from `agentConfig.disallowedTools`.
+8. Unknown type fallback — test that missing `agentConfig` triggers the general-purpose fallback.
+9. Thinking level resolution — test explicit option vs config vs undefined.
+
+### Existing tests that stay as-is
+
+All tests in `test/agent-runner.test.ts`, `test/agent-runner-extension-tools.test.ts`, and `test/agent-runner-settings.test.ts` continue to pass unchanged.
+They test the SDK orchestration layer which is not modified (only reduced in scope).
+The assembly logic they implicitly tested is now covered more thoroughly by `test/session-config.test.ts`.
+
+### Existing tests that could be simplified (future follow-up)
+
+Some `agent-runner.test.ts` tests verify assembly-layer behavior through the full `runAgent()` call (e.g., checking `defaultResourceLoaderCtor` args).
+These become redundant with the new assembler tests.
+Simplifying them is a separate follow-up — not part of this issue's scope.
+
+## TDD Order
+
+1. **Red: assembler returns correct defaults for a standard agent type.**
+   Create `test/session-config.test.ts` with a test that calls `assembleSessionConfig()` for the `"Explore"` type and asserts the returned `SessionConfig` shape: `effectiveCwd`, `systemPrompt`, `toolNames`, `extensions: false`, `noSkills: true`, `disallowedSet: undefined`.
+   Mock `agent-types`, `prompts`, `memory`, `skill-loader` at the module level.
+   This fails because `session-config.ts` does not exist yet.
+   Commit: `test: add session-config assembler test for default agent type`
+
+2. **Green: implement `assembleSessionConfig()` core path.**
+   Create `src/session-config.ts` with `AssemblerContext`, `AssemblerOptions`, `SessionConfig` interfaces and the `assembleSessionConfig()` function.
+   Implement the happy path: resolve config, compute effectiveCwd, resolve extensions/skills, build extras, build system prompt, compute toolNames, compute disallowedSet, resolve noSkills.
+   Tests go green.
+   Commit: `feat: add assembleSessionConfig in session-config.ts`
+
+3. **Red→Green: model resolution fallback chain.**
+   Add tests for: explicit option model wins, config model string resolves via registry, invalid config model falls back to parent, no model returns undefined.
+   Move `resolveDefaultModel()` from `agent-runner.ts` to `session-config.ts` (internal).
+   Commit: `test: model resolution fallback chain in session-config`
+
+4. **Red→Green: skill preloading paths.**
+   Add tests for: `skills: string[]` populates `extras.skillBlocks`, `skills: false` skips, `skills: true` skips preloading (loaded by resource loader instead), `isolated: true` forces skip.
+   Commit: `test: skill preloading paths in session-config`
+
+5. **Red→Green: memory block selection.**
+   Add tests for: agent with memory + write tools → read-write block, agent with memory + read-only tools → read-only block, agent with memory + denied write tools → read-only block, agent without memory → no block.
+   Commit: `test: memory block selection in session-config`
+
+6. **Red→Green: isolated mode, unknown type fallback, thinking level.**
+   Add tests for: `isolated: true` forces `extensions: false` and `noSkills: true`, unknown type falls back to general-purpose config, thinking level resolves from option > config > undefined.
+   Commit: `test: isolated mode, unknown type fallback, thinking level`
+
+7. **Refactor: wire `assembleSessionConfig` into `runAgent()`.**
+   Replace the configuration assembly block in `runAgent()` with a call to `assembleSessionConfig()`.
+   Use the returned `SessionConfig` fields to construct `DefaultResourceLoader`, `createAgentSession` opts, and `filterActiveTools` args.
+   Remove `resolveDefaultModel()` from `agent-runner.ts` (already moved in step 3).
+   Run full test suite — all existing `agent-runner.test.ts` tests pass unchanged.
+   Commit: `refactor: wire assembleSessionConfig into runAgent (#71)`
+
+8. **Verify acceptance criteria and clean up.**
+   Confirm `runAgent()` is ≤200 lines.
+   Confirm assembler tests run without mocking `AgentSession`, `ExtensionContext`, or Pi SDK types.
+   Confirm full test suite passes with no regressions.
+   Remove any dead imports.
+   Run `pnpm run check` for type safety.
+   Commit: `refactor: finalize session-config extraction (#71)`
+
+## Risks and Mitigations
+
+| Risk                                                                                                                            | Mitigation                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Assembly logic has subtle ordering dependencies (e.g., tool names must be computed before memory block selection)               | The assembler mirrors the exact order from `runAgent()` today; tests verify each dependency chain explicitly.                                                                                                                                                           |
+| Moving `resolveDefaultModel` changes import paths for any external consumer                                                     | `resolveDefaultModel` is not exported from the package — it is internal to `agent-runner.ts` today and internal to `session-config.ts` after the move. No external impact.                                                                                              |
+| Existing `agent-runner.test.ts` tests break when assembly is delegated                                                          | The tests mock `agent-types`, `prompts`, `memory`, `skill-loader` — the assembler calls the same functions through the same module paths, so existing mocks continue to intercept.                                                                                      |
+| `Model<any>` import from `@earendil-works/pi-ai` in the new module violates "keep Pi SDK imports out of business-logic modules" | `pi-ai` provides type-only interfaces (`Model`, `ThinkingLevel`) already used in `types.ts`. The constraint targets `pi-coding-agent` SDK types (`AgentSession`, `ExtensionContext`, `DefaultResourceLoader`). The assembler imports zero types from `pi-coding-agent`. |
+| The assembler's return type becomes a wide interface (9 fields)                                                                 | All fields are consumed by `runAgent()` — none are unused. The interface represents a single cohesive concept (session configuration). No consumer uses a subset; there is no narrowing opportunity.                                                                    |
+
+## Open Questions
+
+- Should `assembleSessionConfig` also resolve `effectiveCwd` internally (trivial: `options.cwd ?? ctx.cwd`) or should the caller pre-compute it?
+  The plan assumes the assembler computes it (self-contained), but `runAgent()` also needs `effectiveCwd` for `detectEnv()` before calling the assembler.
+  Resolution: `runAgent()` computes `effectiveCwd` once, passes it as `options.cwd` (already resolved) or as a separate parameter.
+  The assembler still computes `effectiveCwd` from its inputs, which produces the same value.
+  This duplication is benign — both paths yield `options.cwd ?? ctx.cwd`.

package/docs/retro/0069-create-subagent-runtime.md

@@ -0,0 +1,43 @@
+---
+issue: 69
+issue_title: "refactor: eliminate module-scope mutable state in pi-subagents — create SubagentRuntime"
+---
+
+# Retro: #69 — create SubagentRuntime
+
+## Final Retrospective (2026-05-19T16:47:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped `SubagentRuntime` — a composition-root object that replaces module-scope mutable state in `agent-runner.ts` and closure-scoped state in `index.ts`.
+Six TDD steps completed with one deviation: `agent-tool.ts` and `agent-menu.ts` also imported the removed getter/setter exports, requiring unplanned fixes.
+Released as `pi-subagents-v5.2.0`.
+
+### Observations
+
+#### What went well
+
+- The lift-and-shift strategy (introduce `RunOptions` fields alongside module-scope fallback, wire consumers, then remove old path) kept the 460-test suite green through every intermediate commit.
+  No step broke existing tests.
+- `pnpm run check` caught the two missing downstream files (`agent-tool.ts`, `agent-menu.ts`) immediately after the removal step.
+  The typecheck-after-removal safety net worked exactly as intended.
+- The `pi-permission-system` prior art (`ExtensionRuntime` in #43) provided a clear structural template, reducing design decisions to near zero.
+
+#### What caused friction (agent side)
+
+- `missing-context` — The plan's Module-Level Changes listed `agent-runner.ts`, `agent-manager.ts`, and `index.ts` but missed `src/tools/agent-tool.ts` and `src/ui/agent-menu.ts`, both of which imported `getDefaultMaxTurns`/`setDefaultMaxTurns`/`getGraceTurns`/`setGraceTurns` from `agent-runner.ts`.
+  A grep for all importers of the removed symbols during planning would have caught this.
+  Impact: 4 extra files touched in step 5 (the two source files + their test helpers); no rework of earlier steps, but the commit scope was wider than planned. (self-identified at `pnpm run check` time)
+
+- `missing-context` — In step 3 (`agent-manager.test.ts`), checked `vi.mocked(runAgent).mock.calls[0]` without clearing the mock first.
+  The module-level `vi.mock("../src/agent-runner.js")` is shared across all describe blocks, so `calls[0]` picked up a stale invocation from an earlier test.
+  Impact: one debug cycle adding `vi.mocked(runAgent).mockClear()` after `resolvedRun()`. (self-identified)
+
+#### What caused friction (user side)
+
+- Nothing notable.
+  The plan was unambiguous, and the session ran without user intervention beyond the initial prompts.
+
+### Changes made
+
+1. `.pi/prompts/plan-issue.md` — added grep-importers rule to the Module-Level Changes bullet: when a step removes or renames an export, grep all `src/` and `test/` files for every removed symbol before finalizing the file list.

package/package.json

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

package/src/agent-runner.ts

@@ -14,19 +14,9 @@ import {
   SessionManager,
   SettingsManager,
 } from "@earendil-works/pi-coding-agent";
-import {
-  getAgentConfig,
-  getConfig,
-  getMemoryToolNames,
-  getReadOnlyMemoryToolNames,
-  getToolNamesForType,
-} from "./agent-types.js";
 import { buildParentContext, extractText } from "./context.js";
-import { DEFAULT_AGENTS } from "./default-agents.js";
 import { detectEnv } from "./env.js";
-import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
-import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
-import { preloadSkills } from "./skill-loader.js";
+import { assembleSessionConfig } from "./session-config.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
 
 /** Names of tools registered by this extension that subagents must NOT inherit. */
@@ -74,39 +64,6 @@ export function normalizeMaxTurns(n: number | undefined): number | undefined {
   return Math.max(1, n);
 }
 
-/**
- * Try to find the right model for an agent type.
- * Priority: explicit option > config.model > parent model.
- */
-function resolveDefaultModel(
-  parentModel: Model<any> | undefined,
-  registry: {
-    find(provider: string, modelId: string): Model<any> | undefined;
-    getAvailable?(): Model<any>[];
-  },
-  configModel?: string,
-): Model<any> | undefined {
-  if (configModel) {
-    const slashIdx = configModel.indexOf("/");
-    if (slashIdx !== -1) {
-      const provider = configModel.slice(0, slashIdx);
-      const modelId = configModel.slice(slashIdx + 1);
-
-      // Build a set of available model keys for fast lookup
-      const available = registry.getAvailable?.();
-      const availableKeys = available
-        ? new Set(available.map((m: any) => `${m.provider}/${m.id}`))
-        : undefined;
-      const isAvailable = (p: string, id: string) =>
-        !availableKeys || availableKeys.has(`${p}/${id}`);
-
-      const found = registry.find(provider, modelId);
-      if (found && isAvailable(provider, modelId)) return found;
-    }
-  }
-
-  return parentModel;
-}
 
 /** Info about a tool event in the subagent. */
 export interface ToolActivity {
@@ -223,96 +180,27 @@ export async function runAgent(
   prompt: string,
   options: RunOptions,
 ): Promise<RunResult> {
-  const config = getConfig(type);
-  const agentConfig = getAgentConfig(type);
-
-  // Resolve working directory: worktree override > parent cwd
+  // Resolve working directory upfront — needed for detectEnv before assembly.
   const effectiveCwd = options.cwd ?? ctx.cwd;
-
   const env = await detectEnv(options.pi, effectiveCwd);
 
-  // Get parent system prompt for append-mode agents
-  const parentSystemPrompt = ctx.getSystemPrompt();
-
-  // Build prompt extras (memory, skill preloading)
-  const extras: PromptExtras = {};
-
-  // Resolve extensions/skills: isolated overrides to false
-  const extensions = options.isolated ? false : config.extensions;
-  const skills = options.isolated ? false : config.skills;
-
-  // Skill preloading: when skills is string[], preload their content into prompt
-  if (Array.isArray(skills)) {
-    const loaded = preloadSkills(skills, effectiveCwd);
-    if (loaded.length > 0) {
-      extras.skillBlocks = loaded;
-    }
-  }
-
-  let toolNames = getToolNamesForType(type);
-
-  // Persistent memory: detect write capability and branch accordingly.
-  // Account for disallowedTools — a tool in the base set but on the denylist is not truly available.
-  if (agentConfig?.memory) {
-    const existingNames = new Set(toolNames);
-    const denied = agentConfig.disallowedTools
-      ? new Set(agentConfig.disallowedTools)
-      : undefined;
-    const effectivelyHas = (name: string) =>
-      existingNames.has(name) && !denied?.has(name);
-    const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
-
-    if (hasWriteTools) {
-      // Read-write memory: add any missing memory tool names (read/write/edit)
-      const extraNames = getMemoryToolNames(existingNames);
-      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildMemoryBlock(
-        agentConfig.name,
-        agentConfig.memory,
-        effectiveCwd,
-      );
-    } else {
-      // Read-only memory: only add read tool name, use read-only prompt
-      const extraNames = getReadOnlyMemoryToolNames(existingNames);
-      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
-      extras.memoryBlock = buildReadOnlyMemoryBlock(
-        agentConfig.name,
-        agentConfig.memory,
-        effectiveCwd,
-      );
-    }
-  }
-
-  // Build system prompt from agent config
-  let systemPrompt: string;
-  if (agentConfig) {
-    systemPrompt = buildAgentPrompt(
-      agentConfig,
-      effectiveCwd,
-      env,
-      parentSystemPrompt,
-      extras,
-    );
-  } else {
-    // Unknown type fallback: spread the canonical general-purpose config (defensive —
-    // unreachable in practice since index.ts resolves unknown types before calling runAgent).
-    const fallback = DEFAULT_AGENTS.get("general-purpose");
-    if (!fallback)
-      throw new Error(
-        `No fallback config available for unknown type "${type}"`,
-      );
-    systemPrompt = buildAgentPrompt(
-      { ...fallback, name: type },
-      effectiveCwd,
-      env,
-      parentSystemPrompt,
-      extras,
-    );
-  }
-
-  // When skills is string[], we've already preloaded them into the prompt.
-  // Still pass noSkills: true since we don't need the skill loader to load them again.
-  const noSkills = skills === false || Array.isArray(skills);
+  // Assemble session configuration (synchronous, no SDK objects).
+  const cfg = assembleSessionConfig(
+    type,
+    {
+      cwd: ctx.cwd,
+      parentSystemPrompt: ctx.getSystemPrompt(),
+      parentModel: ctx.model,
+      modelRegistry: ctx.modelRegistry,
+    },
+    {
+      cwd: options.cwd,
+      isolated: options.isolated,
+      model: options.model,
+      thinkingLevel: options.thinkingLevel,
+    },
+    env,
+  );
 
   const agentDir = getAgentDir();
 
@@ -323,56 +211,43 @@ export async function runAgent(
   // wanted, reaches the subagent via prompt_mode: append (parentSystemPrompt
   // is embedded in systemPromptOverride) or inherit_context (conversation).
   const loader = new DefaultResourceLoader({
-    cwd: effectiveCwd,
+    cwd: cfg.effectiveCwd,
     agentDir,
-    noExtensions: extensions === false,
-    noSkills,
+    noExtensions: cfg.extensions === false,
+    noSkills: cfg.noSkills,
     noPromptTemplates: true,
     noThemes: true,
     noContextFiles: true,
-    systemPromptOverride: () => systemPrompt,
+    systemPromptOverride: () => cfg.systemPrompt,
     appendSystemPromptOverride: () => [],
   });
   await loader.reload();
 
-  // Resolve model: explicit option > config.model > parent model
-  const model =
-    options.model ??
-    resolveDefaultModel(ctx.model, ctx.modelRegistry, agentConfig?.model);
-
-  // Resolve thinking level: explicit option > agent config > undefined (inherit)
-  const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
-
   const sessionOpts: Parameters<typeof createAgentSession>[0] = {
-    cwd: effectiveCwd,
+    cwd: cfg.effectiveCwd,
     agentDir,
-    sessionManager: SessionManager.inMemory(effectiveCwd),
-    settingsManager: SettingsManager.create(effectiveCwd, agentDir),
+    sessionManager: SessionManager.inMemory(cfg.effectiveCwd),
+    settingsManager: SettingsManager.create(cfg.effectiveCwd, agentDir),
     modelRegistry: ctx.modelRegistry,
-    model,
-    tools: toolNames,
+    model: cfg.model as Model<any> | undefined,
+    tools: cfg.toolNames,
     resourceLoader: loader,
   };
-  if (thinkingLevel) {
-    sessionOpts.thinkingLevel = thinkingLevel;
+  if (cfg.thinkingLevel) {
+    sessionOpts.thinkingLevel = cfg.thinkingLevel;
   }
 
   const { session } = await createAgentSession(sessionOpts);
 
-  // Build disallowed tools set from agent config
-  const disallowedSet = agentConfig?.disallowedTools
-    ? new Set(agentConfig.disallowedTools)
-    : undefined;
-
   // Filter active tools: remove our own tools to prevent nesting,
   // apply extension allowlist if specified, and apply disallowedTools denylist.
   // First pass — over built-in tools, before bindExtensions registers extension tools.
-  if (extensions !== false || disallowedSet) {
+  if (cfg.extensions !== false || cfg.disallowedSet) {
     const filtered = filterActiveTools(
       session.getActiveToolNames(),
-      toolNames,
-      extensions,
-      disallowedSet,
+      cfg.toolNames,
+      cfg.extensions,
+      cfg.disallowedSet,
     );
     session.setActiveToolsByName(filtered);
   }
@@ -396,12 +271,12 @@ export async function runAgent(
   // re-filter, the `extensions: string[]` allowlist branch never matches any
   // extension tools and `extensions: true` lets non-allowlisted denylist
   // entries slip in. Run the same filter against the post-bind active set.
-  if (extensions !== false || disallowedSet) {
+  if (cfg.extensions !== false || cfg.disallowedSet) {
     const refiltered = filterActiveTools(
       session.getActiveToolNames(),
-      toolNames,
-      extensions,
-      disallowedSet,
+      cfg.toolNames,
+      cfg.extensions,
+      cfg.disallowedSet,
     );
     session.setActiveToolsByName(refiltered);
   }
@@ -411,7 +286,7 @@ export async function runAgent(
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
   const maxTurns = normalizeMaxTurns(
-    options.maxTurns ?? agentConfig?.maxTurns ?? options.defaultMaxTurns,
+    options.maxTurns ?? cfg.agentMaxTurns ?? options.defaultMaxTurns,
   );
   let softLimitReached = false;
   let aborted = false;

package/src/session-config.ts

@@ -0,0 +1,263 @@
+/**
+ * session-config.ts — Pure configuration assembler for agent sessions.
+ *
+ * `assembleSessionConfig()` is the pure core extracted from `runAgent()`.
+ * It accepts resolved inputs (agent type, narrow context, run options, env info)
+ * and returns everything `runAgent()` needs to create the SDK session — without
+ * importing or constructing any Pi SDK types.
+ *
+ * The only async IO in the assembly phase (`detectEnv`) is handled by the caller
+ * before invoking this function, keeping the assembler synchronous.
+ */
+
+import {
+  getAgentConfig,
+  getConfig,
+  getMemoryToolNames,
+  getReadOnlyMemoryToolNames,
+  getToolNamesForType,
+} from "./agent-types.js";
+import { DEFAULT_AGENTS } from "./default-agents.js";
+import { buildMemoryBlock, buildReadOnlyMemoryBlock } from "./memory.js";
+import { buildAgentPrompt, type PromptExtras } from "./prompts.js";
+import { preloadSkills } from "./skill-loader.js";
+import type { EnvInfo, SubagentType, ThinkingLevel } from "./types.js";
+
+// ── Public interfaces ────────────────────────────────────────────────────────
+
+/**
+ * Narrow context the assembler reads from the parent session.
+ * Tests construct plain objects satisfying this interface — no SDK mocking needed.
+ *
+ * Models are treated as opaque handles: the assembler never inspects their
+ * internals, only passes them through. `getAvailable` returns just enough
+ * structural information ({ provider, id }) for the availability check in
+ * `resolveDefaultModel`.
+ */
+export interface AssemblerContext {
+  /** Parent working directory (overridable via options.cwd). */
+  cwd: string;
+  /** Parent's effective system prompt (for append-mode agents). */
+  parentSystemPrompt: string;
+  /** Parent's current model instance (fallback when agent config has no model). */
+  parentModel?: unknown;
+  /** Model registry for resolving config.model strings. */
+  modelRegistry: {
+    find(provider: string, modelId: string): unknown;
+    getAvailable?(): Array<{ provider: string; id: string }>;
+  };
+}
+
+/**
+ * Narrow slice of RunOptions consumed by the assembler.
+ * All fields are optional — callers pass only what they have.
+ */
+export interface AssemblerOptions {
+  /** Override working directory (e.g. for worktree isolation). */
+  cwd?: string;
+  /** When true, forces extensions and skills to false. */
+  isolated?: boolean;
+  /** Explicit model override — wins over agentConfig.model and parent model. */
+  model?: unknown;
+  /** Explicit thinking level — wins over agentConfig.thinking. */
+  thinkingLevel?: ThinkingLevel;
+}
+
+/**
+ * Assembled configuration returned to `runAgent()`.
+ * Contains everything needed to create the SDK session and filter tools —
+ * with no SDK object references.
+ */
+export interface SessionConfig {
+  /** Resolved working directory (`options.cwd ?? ctx.cwd`). */
+  effectiveCwd: string;
+  /** Fully-assembled system prompt string (ready for `systemPromptOverride`). */
+  systemPrompt: string;
+  /** Built-in tool names for session creation, filtering, and memory augmentation. */
+  toolNames: string[];
+  /** Disallowed tool set from agentConfig (for `filterActiveTools`). undefined when empty. */
+  disallowedSet: Set<string> | undefined;
+  /** Resolved extensions setting for resource loader and tool filtering. */
+  extensions: boolean | string[];
+  /**
+   * Resolved model instance (undefined → use parent model as passed to SDK).
+   * Opaque handle — the assembler passes it through without inspection.
+   * Caller casts to the SDK’s Model<any> at the session-creation boundary.
+   */
+  model: unknown;
+  /** Resolved thinking level (undefined → inherit from session). */
+  thinkingLevel: ThinkingLevel | undefined;
+  /** Whether to skip skill loading in the resource loader (`noSkills` flag). */
+  noSkills: boolean;
+  /** Prompt extras (memory block, preloaded skill blocks) — for transparency. */
+  extras: PromptExtras;
+  /** Per-agent configured max turns (from agentConfig.maxTurns). */
+  agentMaxTurns: number | undefined;
+}
+
+// ── Internal helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve the default model from the agent config's model string.
+ *
+ * Priority: parentModel is the fallback; if `configModel` is a "provider/modelId"
+ * string that resolves against the registry AND is in the available set, return
+ * that model instead.
+ */
+function resolveDefaultModel(
+  parentModel: unknown,
+  registry: AssemblerContext["modelRegistry"],
+  configModel?: string,
+): unknown {
+  if (configModel) {
+    const slashIdx = configModel.indexOf("/");
+    if (slashIdx !== -1) {
+      const provider = configModel.slice(0, slashIdx);
+      const modelId = configModel.slice(slashIdx + 1);
+
+      const available = registry.getAvailable?.();
+      const availableKeys = available
+        ? new Set(available.map((m) => `${m.provider}/${m.id}`))
+        : undefined;
+      const isAvailable = (p: string, id: string) =>
+        !availableKeys || availableKeys.has(`${p}/${id}`);
+
+      const found = registry.find(provider, modelId);
+      if (found && isAvailable(provider, modelId)) return found;
+    }
+  }
+  return parentModel;
+}
+
+// ── Public function ──────────────────────────────────────────────────────────
+
+/**
+ * Assemble all configuration needed to create an agent session.
+ *
+ * Synchronous and side-effect-free (beyond calling `preloadSkills` which reads
+ * the filesystem). The caller is responsible for resolving `EnvInfo` beforehand
+ * via `detectEnv()`.
+ *
+ * @param type       The subagent type name (case-insensitive registry lookup).
+ * @param ctx        Narrow context from the parent session.
+ * @param options    Per-call overrides (cwd, isolated, model, thinkingLevel).
+ * @param env        Pre-resolved environment info from `detectEnv()`.
+ */
+export function assembleSessionConfig(
+  type: SubagentType,
+  ctx: AssemblerContext,
+  options: AssemblerOptions,
+  env: EnvInfo,
+): SessionConfig {
+  const config = getConfig(type);
+  const agentConfig = getAgentConfig(type);
+
+  const effectiveCwd = options.cwd ?? ctx.cwd;
+
+  // Resolve extensions/skills: isolated overrides to false
+  const extensions = options.isolated ? false : config.extensions;
+  const skills = options.isolated ? false : config.skills;
+
+  // Build prompt extras (memory, preloaded skills)
+  const extras: PromptExtras = {};
+
+  // Skill preloading: when skills is string[], preload their content into the prompt
+  if (Array.isArray(skills)) {
+    const loaded = preloadSkills(skills, effectiveCwd);
+    if (loaded.length > 0) {
+      extras.skillBlocks = loaded;
+    }
+  }
+
+  let toolNames = getToolNamesForType(type);
+
+  // Persistent memory: detect write capability and branch accordingly.
+  // Account for disallowedTools — a tool in the base set but on the denylist
+  // is not truly available.
+  if (agentConfig?.memory) {
+    const existingNames = new Set(toolNames);
+    const denied = agentConfig.disallowedTools
+      ? new Set(agentConfig.disallowedTools)
+      : undefined;
+    const effectivelyHas = (name: string) =>
+      existingNames.has(name) && !denied?.has(name);
+    const hasWriteTools = effectivelyHas("write") || effectivelyHas("edit");
+
+    if (hasWriteTools) {
+      const extraNames = getMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
+      extras.memoryBlock = buildMemoryBlock(
+        agentConfig.name,
+        agentConfig.memory,
+        effectiveCwd,
+      );
+    } else {
+      const extraNames = getReadOnlyMemoryToolNames(existingNames);
+      if (extraNames.length > 0) toolNames = [...toolNames, ...extraNames];
+      extras.memoryBlock = buildReadOnlyMemoryBlock(
+        agentConfig.name,
+        agentConfig.memory,
+        effectiveCwd,
+      );
+    }
+  }
+
+  // Build system prompt from agent config (or general-purpose fallback for unknown types)
+  let systemPrompt: string;
+  if (agentConfig) {
+    systemPrompt = buildAgentPrompt(
+      agentConfig,
+      effectiveCwd,
+      env,
+      ctx.parentSystemPrompt,
+      extras,
+    );
+  } else {
+    // Unknown type fallback: spread the canonical general-purpose config (defensive —
+    // unreachable in practice since index.ts resolves unknown types before calling runAgent).
+    const fallback = DEFAULT_AGENTS.get("general-purpose");
+    if (!fallback) {
+      throw new Error(`No fallback config available for unknown type "${type}"`);
+    }
+    systemPrompt = buildAgentPrompt(
+      { ...fallback, name: type },
+      effectiveCwd,
+      env,
+      ctx.parentSystemPrompt,
+      extras,
+    );
+  }
+
+  // noSkills: when we've already preloaded skills into the prompt, or skills = false,
+  // tell the resource loader not to load them again.
+  const noSkills = skills === false || Array.isArray(skills);
+
+  // Disallowed tools set (for filterActiveTools in runAgent)
+  const disallowedSet = agentConfig?.disallowedTools
+    ? new Set(agentConfig.disallowedTools)
+    : undefined;
+
+  // Model resolution: explicit option > config model string > parent model
+  const model =
+    options.model ??
+    resolveDefaultModel(ctx.parentModel, ctx.modelRegistry, agentConfig?.model);
+
+  // Thinking level: explicit option > agent config > undefined (inherit)
+  const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
+
+  // Per-agent max turns (combined with options.maxTurns and defaultMaxTurns by runAgent)
+  const agentMaxTurns = agentConfig?.maxTurns;
+
+  return {
+    effectiveCwd,
+    systemPrompt,
+    toolNames,
+    disallowedSet,
+    extensions,
+    model,
+    thinkingLevel,
+    noSkills,
+    extras,
+    agentMaxTurns,
+  };
+}