@gotgenes/pi-subagents 5.2.0 → 5.4.0

package/docs/plans/0080-consolidate-agent-config-lookup.md

@@ -0,0 +1,247 @@
+---
+issue: 80
+issue_title: "refactor: consolidate getConfig / getAgentConfig into a single resolution path"
+---
+
+# Consolidate agent config lookup into resolveAgentConfig
+
+## Problem Statement
+
+`agent-types.ts` exports two overlapping lookup functions:
+
+- `getConfig(type)` — returns a narrow shape (`displayName`, `description`, `builtinToolNames`, `extensions`, `skills`, `promptMode`) with a guaranteed-non-null fallback chain (unknown → general-purpose → absolute fallback).
+- `getAgentConfig(type)` — returns the full `AgentConfig | undefined`.
+
+Every field `getConfig()` returns also exists on `AgentConfig`.
+Callers that need both must call both and keep them in sync:
+
+```typescript
+const config = getConfig(type);
+const agentConfig = getAgentConfig(type);
+```
+
+This showed up concretely in `session-config.ts` (extracted in #71), where the assembler calls both, then handles the `agentConfig === undefined` fallback separately — duplicating the same fallback chain that `getConfig()` already handles internally.
+Test mocks must also set up both `mockGetConfig` and `mockGetAgentConfig` with compatible values, which is error-prone.
+
+## Goals
+
+- Add a single `resolveAgentConfig(type): AgentConfig` function that returns a guaranteed-non-null `AgentConfig`, handling the fallback chain internally (unknown → general-purpose → absolute fallback).
+- Migrate all callers of `getConfig()` and `getAgentConfig()` to `resolveAgentConfig()`.
+- Remove `getConfig()` and `getAgentConfig()`.
+- Simplify test mocks from two compatible stubs to one.
+
+This is a pure internal refactor — no behavior change, no public API impact (the package's `exports` only expose `service.ts`).
+
+## Non-Goals
+
+- Changing the `AgentConfig` type shape.
+- Refactoring `getToolNamesForType()` (it has its own lookup logic and is a separate concern).
+- Modifying the public API surface (`service.ts`).
+- Changing the fallback semantics (the chain stays: type → general-purpose → absolute fallback).
+
+## Background
+
+### Relevant modules
+
+| Module                | Role                                                                                                                  |
+| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `agent-types.ts`      | Unified agent type registry — owns `getConfig`, `getAgentConfig`, `resolveType`, `getToolNamesForType`, `isValidType` |
+| `session-config.ts`   | Pure configuration assembler — calls both `getConfig` + `getAgentConfig`                                              |
+| `ui/agent-widget.ts`  | Widget rendering — calls `getConfig` via `getDisplayName()` and `getPromptModeLabel()` helpers                        |
+| `index.ts`            | Extension entry point — calls `getAgentConfig` (3 sites) for type listing and model label                             |
+| `tools/agent-tool.ts` | Agent tool handler — calls `getAgentConfig` (1 site) after `resolveType()`                                            |
+| `ui/agent-menu.ts`    | Agent menu UI — calls `getAgentConfig` (5 sites) for listing, detail, and existence checks                            |
+
+### Current caller inventory
+
+Source files that import `getConfig` or `getAgentConfig`:
+
+| File                  | `getConfig` calls | `getAgentConfig` calls | Notes                                         |
+| --------------------- | ----------------- | ---------------------- | --------------------------------------------- |
+| `session-config.ts`   | 1                 | 1                      | Primary motivation; dual-call pattern         |
+| `ui/agent-widget.ts`  | 2 (via helpers)   | 0                      | `getDisplayName()`, `getPromptModeLabel()`    |
+| `index.ts`            | 0                 | 3                      | Iterates known names; `?.` is defensive       |
+| `tools/agent-tool.ts` | 0                 | 1                      | After `resolveType()` — guaranteed to exist   |
+| `ui/agent-menu.ts`    | 0                 | 5                      | 3 iterate known names; 2 are existence guards |
+
+Test files that mock `agent-types.js` with both functions:
+
+| Test file                              | Mocks `getConfig` | Mocks `getAgentConfig` |
+| -------------------------------------- | ----------------- | ---------------------- |
+| `session-config.test.ts`               | ✓                 | ✓                      |
+| `agent-runner.test.ts`                 | ✓                 | ✓                      |
+| `agent-runner-extension-tools.test.ts` | ✓                 | ✓                      |
+
+### Caller migration notes
+
+- **`session-config.ts`**: Replace both calls with one `resolveAgentConfig(type)`.
+  Read `extensions` and `skills` directly from the returned `AgentConfig` instead of the narrow shape.
+  The prompt-building fallback (`agentConfig` null → use `DEFAULT_AGENTS.get("general-purpose")`) collapses into the single call since `resolveAgentConfig` already handles the fallback.
+- **`ui/agent-widget.ts`**: `getDisplayName()` becomes `resolveAgentConfig(type).displayName ?? resolveAgentConfig(type).name` (or cache the result).
+  `getPromptModeLabel()` reads `.promptMode` from the resolved config.
+- **`index.ts`**: All 3 call sites iterate names from `getDefaultAgentNames()` or `getUserAgentNames()` — configs are guaranteed to exist.
+  Direct replacement with `resolveAgentConfig()`.
+- **`tools/agent-tool.ts`**: Called after `resolveType()` — config guaranteed.
+  Direct replacement.
+- **`ui/agent-menu.ts`**: 3 of 5 calls iterate `getAllTypes()` — configs guaranteed.
+  The 2 defensive existence guards (lines 187, 248) switch to `resolveType(name) != null` checks, then use `resolveAgentConfig()` for the config.
+
+### Constraints from AGENTS.md
+
+- Keep modules focused and composable (one concern per file).
+- Prefer explicit configuration over hidden behavior.
+- Use `vi.hoisted()` for module-level mocks, `.mockClear()` when the factory provides a default.
+- Run `pnpm run check` after interface changes.
+
+## Design Overview
+
+### `resolveAgentConfig` semantics
+
+```typescript
+export function resolveAgentConfig(type: string): AgentConfig
+```
+
+1. Case-insensitive key lookup via `resolveKey(type)`.
+2. If found and `enabled !== false`, return the `AgentConfig`.
+3. Fallback to `general-purpose` (if present and enabled).
+4. Absolute fallback: a synthetic `AgentConfig` with safe defaults (same values as today's `getConfig` absolute fallback, plus the missing `AgentConfig` fields like `name`, `systemPrompt`).
+
+The function is pure (reads from the module-level `agents` map) and deterministic.
+
+### Absolute fallback shape
+
+The absolute fallback is a complete `AgentConfig` synthesized inline, matching the current `getConfig` absolute fallback values plus required `AgentConfig` fields:
+
+```typescript
+{
+  name: type,
+  displayName: "Agent",
+  description: "General-purpose agent for complex, multi-step tasks",
+  builtinToolNames: BUILTIN_TOOL_NAMES,
+  extensions: true,
+  skills: true,
+  systemPrompt: "",
+  promptMode: "append",
+}
+```
+
+### session-config.ts simplification
+
+Before (two calls, two variables, null-check branching):
+
+```typescript
+const config = getConfig(type);
+const agentConfig = getAgentConfig(type);
+// ...
+const extensions = options.isolated ? false : config.extensions;
+const skills = options.isolated ? false : config.skills;
+// ...
+if (agentConfig) {
+  systemPrompt = buildAgentPrompt(agentConfig, ...);
+} else {
+  const fallback = DEFAULT_AGENTS.get("general-purpose");
+  systemPrompt = buildAgentPrompt({ ...fallback, name: type }, ...);
+}
+```
+
+After (one call, no null checks):
+
+```typescript
+const agentConfig = resolveAgentConfig(type);
+// ...
+const extensions = options.isolated ? false : agentConfig.extensions;
+const skills = options.isolated ? false : agentConfig.skills;
+// ...
+systemPrompt = buildAgentPrompt(agentConfig, ...);
+```
+
+The `DEFAULT_AGENTS` import in `session-config.ts` becomes unnecessary.
+
+## Module-Level Changes
+
+### `src/agent-types.ts`
+
+- **Add** `resolveAgentConfig(type: string): AgentConfig` — guaranteed-non-null lookup with fallback chain.
+- **Remove** `getConfig(type)` — replaced by `resolveAgentConfig`.
+- **Remove** `getAgentConfig(type)` — replaced by `resolveAgentConfig`.
+
+### `src/session-config.ts`
+
+- **Change** imports: replace `getConfig`, `getAgentConfig` with `resolveAgentConfig`.
+- **Remove** `DEFAULT_AGENTS` import (no longer needed for the unknown-type fallback prompt path).
+- **Simplify** `assembleSessionConfig()`: one `resolveAgentConfig(type)` call replaces two; remove the `if (agentConfig)` / `else` branch for prompt building.
+
+### `src/ui/agent-widget.ts`
+
+- **Change** import: replace `getConfig` with `resolveAgentConfig`.
+- **Update** `getDisplayName()`: `const config = resolveAgentConfig(type); return config.displayName ?? config.name;`.
+- **Update** `getPromptModeLabel()`: read `promptMode` from resolved config.
+
+### `src/index.ts`
+
+- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`.
+- **Update** 3 call sites: direct replacement (all iterate known names).
+
+### `src/tools/agent-tool.ts`
+
+- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`.
+- **Update** 1 call site: direct replacement (type already resolved via `resolveType()`).
+
+### `src/ui/agent-menu.ts`
+
+- **Change** import: replace `getAgentConfig` with `resolveAgentConfig`, add `resolveType` if not already imported.
+- **Update** 5 call sites: 3 are direct replacements; 2 existence guards switch to `resolveType(name) != null` before calling `resolveAgentConfig()`.
+
+### Test files
+
+- **`test/agent-types.test.ts`**: Add tests for `resolveAgentConfig`; remove tests for `getConfig` and `getAgentConfig`.
+- **`test/session-config.test.ts`**: Replace `mockGetConfig` + `mockGetAgentConfig` with a single `mockResolveAgentConfig`; remove all `mockGetConfig` usages.
+- **`test/agent-runner.test.ts`**: Update `vi.mock("../src/agent-types.js")` factory: replace `getConfig` + `getAgentConfig` with `resolveAgentConfig`.
+- **`test/agent-runner-extension-tools.test.ts`**: Same mock update as above.
+
+## Test Impact Analysis
+
+1. **New unit tests enabled**: `resolveAgentConfig` gets focused tests for the fallback chain (unknown → general-purpose → absolute fallback), case-insensitive lookup, and disabled-type fallback.
+   These replace the scattered `getConfig` fallback tests in `agent-types.test.ts`.
+2. **Redundant tests**: `getConfig`-specific tests (return shape, fallback, extension allowlist) become redundant since `resolveAgentConfig` returns the full `AgentConfig` directly.
+   Remove them.
+3. **Tests that must stay**: `agent-types.test.ts` tests for `registerAgents`, `resolveType`, `isValidType`, `getAvailableTypes`, `getAllTypes`, `getToolNamesForType`, `getMemoryToolNames`, `getReadOnlyMemoryToolNames` are unaffected.
+   `session-config.test.ts` tests all stay — they test assembler behavior, just with a simpler mock setup.
+
+## TDD Order
+
+1. **Add `resolveAgentConfig` with tests** — add the function to `agent-types.ts` alongside existing functions.
+   Tests: known type returns config; unknown type falls back to general-purpose; disabled type falls back; absolute fallback when general-purpose is missing; case-insensitive lookup.
+   Commit: `feat: add resolveAgentConfig with guaranteed-non-null fallback chain`.
+
+2. **Migrate `session-config.ts` and its tests** — replace `getConfig` + `getAgentConfig` imports with `resolveAgentConfig`; remove `DEFAULT_AGENTS` import; simplify the assembler body (one call, no null-check branch).
+   Update `session-config.test.ts`: replace `mockGetConfig` + `mockGetAgentConfig` with single `mockResolveAgentConfig`; update all test setups.
+   Commit: `refactor: migrate session-config to resolveAgentConfig`.
+
+3. **Migrate `agent-widget.ts`** — update `getDisplayName()` and `getPromptModeLabel()` to use `resolveAgentConfig`.
+   Commit: `refactor: migrate agent-widget to resolveAgentConfig`.
+
+4. **Migrate remaining source callers** — update `index.ts` (3 sites), `tools/agent-tool.ts` (1 site), `ui/agent-menu.ts` (5 sites, including 2 existence-guard rewrites).
+   Commit: `refactor: migrate remaining callers to resolveAgentConfig`.
+
+5. **Update transitive test mocks** — update `agent-runner.test.ts` and `agent-runner-extension-tools.test.ts` mock factories to export `resolveAgentConfig` instead of `getConfig` + `getAgentConfig`.
+   Commit: `test: update agent-runner test mocks for resolveAgentConfig`.
+
+6. **Remove `getConfig` and `getAgentConfig`** — delete both functions from `agent-types.ts`; remove their tests from `agent-types.test.ts`.
+   Run `pnpm run check` to verify no remaining references.
+   Commit: `refactor: remove getConfig and getAgentConfig`.
+
+## Risks and Mitigations
+
+| Risk                                                                     | Mitigation                                                                                                                                      |
+| ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Overlooked caller of removed functions                                   | Grep all `src/` and `test/` files for `getConfig` and `getAgentConfig` before the removal step; `pnpm run check` catches any remaining imports. |
+| `agent-menu.ts` existence guards behave differently with `resolveType()` | `resolveType()` is already the canonical existence check used by `agent-tool.ts`; the guard semantics are identical.                            |
+| Absolute fallback `AgentConfig` shape drift                              | The absolute fallback is a single inline literal — any future `AgentConfig` field additions will cause a type error at the definition site.     |
+| Test mock compatibility during migration                                 | Lift-and-shift: `resolveAgentConfig` coexists with old functions until all callers are migrated; each step leaves tests green.                  |
+
+## Open Questions
+
+- `getToolNamesForType()` does its own lookup with similar fallback logic.
+  It could be simplified to delegate to `resolveAgentConfig()`, but that is out of scope for this issue.
+  Consider a follow-up if the duplication becomes a maintenance concern.

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/docs/retro/0071-extract-session-config-assembler.md

@@ -0,0 +1,60 @@
+---
+issue: 71
+issue_title: "refactor: extract pure agent-session assembler from agent-runner.ts"
+---
+
+# Retro: #71 - extract session-config assembler
+
+## Final Retrospective (2026-05-19T22:15:00Z)
+
+### Session summary
+
+Planned, implemented, and shipped `assembleSessionConfig()` - a pure configuration assembler extracted from `runAgent()` in `agent-runner.ts`.
+Eight TDD steps completed across three phases (plan, implement, ship), adding 33 new tests in `test/session-config.test.ts` and reducing `runAgent()` from ~390 lines to ~198.
+Released as `pi-subagents-v5.3.0`.
+Filed follow-up #80 (consolidate `getConfig`/`getAgentConfig`) and updated the architecture roadmap.
+
+### Observations
+
+#### What went well
+
+- The user's redirecting question ("Do we need more decomposition?
+  Are there any seams we can exploit?") at the `as any` fix point was perfectly timed.
+  It shifted the approach from mechanical casting (8 `as any` casts) to a structural fix: `unknown` for opaque model handles, `Array<{ provider: string; id: string }>` for the availability check.
+  The final design removed the `@earendil-works/pi-ai` import from `session-config.ts` entirely - cleaner than the plan's original specification of `Model<any>`.
+- The prior art from `pi-permission-system` (`evaluate()` extraction) provided a clear template for the pure-core-from-IO-shell pattern.
+  Design decisions were minimal.
+- All 451 existing tests stayed green through every intermediate commit.
+  The mock-at-module-boundary strategy (`vi.mock("../src/agent-types.js")` etc.) meant existing `agent-runner.test.ts` mocks continued to intercept the same module paths even after the assembler delegated to them.
+
+#### What caused friction (agent side)
+
+- `premature-convergence` - When `pnpm run check` surfaced 10 type errors from `Model<any>` in `SessionConfig`, the first fix attempt was adding `as any` casts to the `vi.fn` factory return values and all test model objects (8 casts total).
+  This partially addressed the symptom but created new `never[]` inference errors and left a fundamentally wrong interface.
+  The user's first pushback ("Can we find a real type?") prompted a proper analysis of `Model<TApi>`'s ~10 required fields, leading to the `unknown` solution.
+  Impact: ~20 minutes of rework across 3 attempts (the `as any` factory cast, diagnosing the residual `never[]` errors, and the final `unknown` rewrite). (user-caught)
+
+- `missing-context` - The plan omitted `agentMaxTurns` from the `SessionConfig` return type.
+  `runAgent()`'s turn-limit resolution reads `agentConfig?.maxTurns`, which is no longer available after the assembly delegation.
+  Caught during step 7 (wiring) when the code wouldn't compile without it.
+  Impact: added one field to `SessionConfig` and `assembleSessionConfig`; no rework of earlier steps, but the commit body noted the deviation. (self-identified at implementation time)
+
+- `missing-context` - The `vi.fn(() => [])` → `never[]` TypeScript inference issue wasn't anticipated.
+  Five mock factories (`mockGetMemoryToolNames`, `mockGetReadOnlyMemoryToolNames`, `mockPreloadSkills`, `mockRegistry.find`, `mockRegistry.getAvailable`) needed explicit return-type annotations.
+  Impact: one debug cycle to diagnose, then a second to fix with `import type` annotations. (self-identified during `pnpm run check`)
+
+#### What caused friction (user side)
+
+- The user's second pushback ("Do we need more decomposition?") was the highest-leverage intervention in the session.
+  Without it, the `as any` approach would have landed and the `pi-ai` import would have stayed in `session-config.ts` - defeating the goal of a SDK-free business-logic module.
+  The pattern of catching design-level issues through "is there a better seam?"
+  questions is worth preserving.
+
+#### Design observations (not actionable as rules)
+
+- The `cfg.model as Model<any> | undefined` cast in `agent-runner.ts` is a legitimate interim cost — it's one line at the SDK boundary and will be resolved when #66 (replace `as any` casts with proper SDK types) and #72 (AgentManager DI) refine the interface contracts.
+  Codifying “use `unknown` + boundary cast” as a general pattern would normalize something that should feel uncomfortable and motivate further interface refinement.
+
+### Changes made
+
+1. `.pi/skills/testing/SKILL.md` — added `vi.fn()` return-type annotation rule under “Vitest mock patterns”: annotate factories that return empty arrays or narrow literals to prevent `never[]` inference.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gotgenes/pi-subagents",
-  "version": "5.2.0",
+  "version": "5.4.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;