@gotgenes/pi-subagents 5.3.0 → 5.4.0

package/CHANGELOG.md

@@ -5,6 +5,19 @@ 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.4.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.3.0...pi-subagents-v5.4.0) (2026-05-20)
+
+
+### Features
+
+* add resolveAgentConfig with guaranteed-non-null fallback chain ([6b676a0](https://github.com/gotgenes/pi-packages/commit/6b676a0b59ebc3598d366cb5db600a8177b301e6))
+
+
+### Documentation
+
+* plan consolidate getConfig/getAgentConfig into resolveAgentConfig ([#80](https://github.com/gotgenes/pi-packages/issues/80)) ([1c14b47](https://github.com/gotgenes/pi-packages/commit/1c14b4760fa67dff5dbf17306d04bbe992b38bce))
+* **retro:** add retro notes for issue [#71](https://github.com/gotgenes/pi-packages/issues/71) ([a70e52f](https://github.com/gotgenes/pi-packages/commit/a70e52f840cf3b2f65689987dcb7316e32dc12ff))
+
 ## [5.3.0](https://github.com/gotgenes/pi-packages/compare/pi-subagents-v5.2.0...pi-subagents-v5.3.0) (2026-05-19)
 
 

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/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.3.0",
+  "version": "5.4.0",
   "exports": {
     ".": "./src/service.ts"
   },

package/src/agent-types.ts

@@ -48,12 +48,6 @@ export function resolveType(name: string): string | undefined {
   return resolveKey(name);
 }
 
-/** Get the agent config for a type (case-insensitive). */
-export function getAgentConfig(name: string): AgentConfig | undefined {
-  const key = resolveKey(name);
-  return key ? agents.get(key) : undefined;
-}
-
 /** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
   return [...agents.entries()]
@@ -116,49 +110,29 @@ export function getToolNamesForType(type: string): string[] {
   return names;
 }
 
-/** Get config for a type (case-insensitive, returns a SubagentTypeConfig-compatible object). Falls back to general-purpose. */
-export function getConfig(type: string): {
-  displayName: string;
-  description: string;
-  builtinToolNames: string[];
-  extensions: true | string[] | false;
-  skills: true | string[] | false;
-  promptMode: "replace" | "append";
-} {
+/** Resolve agent config with guaranteed non-null return. Falls back: unknown → general-purpose → absolute fallback. */
+export function resolveAgentConfig(type: string): AgentConfig {
   const key = resolveKey(type);
   const config = key ? agents.get(key) : undefined;
-  if (config && config.enabled !== false) {
-    return {
-      displayName: config.displayName ?? config.name,
-      description: config.description,
-      builtinToolNames: config.builtinToolNames ?? BUILTIN_TOOL_NAMES,
-      extensions: config.extensions,
-      skills: config.skills,
-      promptMode: config.promptMode,
-    };
+  if (config) {
+    return config;
   }
 
-  // Fallback for unknown/disabled types — general-purpose config
+  // Fallback to general-purpose for unknown types
   const gp = agents.get("general-purpose");
-  if (gp && gp.enabled !== false) {
-    return {
-      displayName: gp.displayName ?? gp.name,
-      description: gp.description,
-      builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
-      extensions: gp.extensions,
-      skills: gp.skills,
-      promptMode: gp.promptMode,
-    };
+  if (gp) {
+    return gp;
   }
 
-  // Absolute fallback (should never happen)
+  // Absolute fallback (should never happen in practice)
   return {
+    name: type,
     displayName: "Agent",
     description: "General-purpose agent for complex, multi-step tasks",
     builtinToolNames: BUILTIN_TOOL_NAMES,
     extensions: true,
     skills: true,
+    systemPrompt: "",
     promptMode: "append",
   };
 }
-

package/src/index.ts

@@ -14,7 +14,7 @@ import { join } from "node:path";
 import { defineTool, type ExtensionAPI, getAgentDir } from "@earendil-works/pi-coding-agent";
 import { AgentManager } from "./agent-manager.js";
 import { getAgentConversation, normalizeMaxTurns, steerAgent } from "./agent-runner.js";
-import { getAgentConfig, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, } from "./agent-types.js";
+import { getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveAgentConfig, } from "./agent-types.js";
 import { loadCustomAgents } from "./custom-agents.js";
 import { type ModelRegistry, resolveModel } from "./model-resolver.js";
 import { buildEventData, createNotificationSystem } from "./notification.js";
@@ -149,14 +149,14 @@ export default function (pi: ExtensionAPI) {
     const userNames = getUserAgentNames();
 
     const defaultDescs = defaultNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      const modelSuffix = cfg?.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
-      return `- ${name}: ${cfg?.description ?? name}${modelSuffix}`;
+      const cfg = resolveAgentConfig(name);
+      const modelSuffix = cfg.model ? ` (${getModelLabelFromConfig(cfg.model)})` : "";
+      return `- ${name}: ${cfg.description}${modelSuffix}`;
     });
 
     const customDescs = userNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      return `- ${name}: ${cfg?.description ?? name}`;
+      const cfg = resolveAgentConfig(name);
+      return `- ${name}: ${cfg.description}`;
     });
 
     return [
@@ -237,8 +237,8 @@ export default function (pi: ExtensionAPI) {
     reloadCustomAgents,
     agentActivity: runtime.agentActivity,
     getModelLabel: (type, registry) => {
-      const cfg = getAgentConfig(type);
-      if (!cfg?.model) return 'inherit';
+      const cfg = resolveAgentConfig(type);
+      if (!cfg.model) return 'inherit';
       if (registry) {
         const resolved = resolveModel(cfg.model, registry as any);
         if (typeof resolved === 'string') return 'inherit';

package/src/session-config.ts

@@ -11,13 +11,11 @@
  */
 
 import {
-  getAgentConfig,
-  getConfig,
   getMemoryToolNames,
   getReadOnlyMemoryToolNames,
   getToolNamesForType,
+  resolveAgentConfig,
 } 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";
@@ -149,14 +147,13 @@ export function assembleSessionConfig(
   options: AssemblerOptions,
   env: EnvInfo,
 ): SessionConfig {
-  const config = getConfig(type);
-  const agentConfig = getAgentConfig(type);
+  const agentConfig = resolveAgentConfig(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;
+  const extensions = options.isolated ? false : agentConfig.extensions;
+  const skills = options.isolated ? false : agentConfig.skills;
 
   // Build prompt extras (memory, preloaded skills)
   const extras: PromptExtras = {};
@@ -174,7 +171,7 @@ export function assembleSessionConfig(
   // 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) {
+  if (agentConfig.memory) {
     const existingNames = new Set(toolNames);
     const denied = agentConfig.disallowedTools
       ? new Set(agentConfig.disallowedTools)
@@ -202,51 +199,34 @@ export function assembleSessionConfig(
     }
   }
 
-  // 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,
-    );
-  }
+  // Build system prompt from the resolved agent config
+  const systemPrompt = buildAgentPrompt(
+    agentConfig,
+    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
+  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);
+    resolveDefaultModel(ctx.parentModel, ctx.modelRegistry, agentConfig.model);
 
   // Thinking level: explicit option > agent config > undefined (inherit)
-  const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
+  const thinkingLevel = options.thinkingLevel ?? agentConfig.thinking;
 
   // Per-agent max turns (combined with options.maxTurns and defaultMaxTurns by runAgent)
-  const agentMaxTurns = agentConfig?.maxTurns;
+  const agentMaxTurns = agentConfig.maxTurns;
 
   return {
     effectiveCwd,

package/src/tools/agent-tool.ts

@@ -1,7 +1,7 @@
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { normalizeMaxTurns } from "../agent-runner.js";
-import { getAgentConfig, resolveType } from "../agent-types.js";
+import { resolveAgentConfig, resolveType } from "../agent-types.js";
 import { resolveAgentInvocationConfig } from "../invocation-config.js";
 import { resolveInvocationModel } from "../model-resolver.js";
 import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "../output-file.js";
@@ -370,8 +370,8 @@ Guidelines:
 
       const displayName = getDisplayName(subagentType);
 
-      // Get agent config (if any)
-      const customConfig = getAgentConfig(subagentType);
+      // Get agent config for invocation resolution
+      const customConfig = resolveAgentConfig(subagentType);
 
       const resolvedConfig = resolveAgentInvocationConfig(customConfig, params);
 

package/src/ui/agent-menu.ts

@@ -3,8 +3,9 @@ import { join } from "node:path";
 
 import {
   BUILTIN_TOOL_NAMES,
-  getAgentConfig,
   getAllTypes,
+  resolveAgentConfig,
+  resolveType,
 } from "../agent-types.js";
 import type { AgentConfig, AgentRecord } from "../types.js";
 import type { AgentActivity } from "./agent-widget.js";
@@ -152,21 +153,21 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
     };
 
     const entries = allNames.map((name) => {
-      const cfg = getAgentConfig(name);
-      const disabled = cfg?.enabled === false;
+      const cfg = resolveAgentConfig(name);
+      const disabled = cfg.enabled === false;
       const model = deps.getModelLabel(name, ctx.modelRegistry);
       const indicator = sourceIndicator(cfg);
       const prefix = `${indicator}${name} · ${model}`;
-      const desc = disabled ? "(disabled)" : (cfg?.description ?? name);
+      const desc = disabled ? "(disabled)" : cfg.description;
       return { name, prefix, desc };
     });
     const maxPrefix = Math.max(...entries.map((e) => e.prefix.length));
 
     const hasCustom = allNames.some((n) => {
-      const c = getAgentConfig(n);
-      return c && !c.isDefault && c.enabled !== false;
+      const c = resolveAgentConfig(n);
+      return !c.isDefault && c.enabled !== false;
     });
-    const hasDisabled = allNames.some((n) => getAgentConfig(n)?.enabled === false);
+    const hasDisabled = allNames.some((n) => resolveAgentConfig(n).enabled === false);
     const legendParts: string[] = [];
     if (hasCustom) legendParts.push("• = project  ◦ = global");
     if (hasDisabled) legendParts.push("✕ = disabled");
@@ -184,7 +185,7 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
       .split(" · ")[0]
       .replace(/^[•◦✕\s]+/, "")
       .trim();
-    if (getAgentConfig(agentName)) {
+    if (resolveType(agentName) != null) {
       await showAgentDetail(ctx, agentName);
       await showAllAgentsList(ctx);
     }
@@ -245,11 +246,11 @@ export function createAgentsMenuHandler(deps: AgentMenuDeps) {
   }
 
   async function showAgentDetail(ctx: MenuContext, name: string) {
-    const cfg = getAgentConfig(name);
-    if (!cfg) {
+    if (resolveType(name) == null) {
       ctx.ui.notify(`Agent config not found for "${name}".`, "warning");
       return;
     }
+    const cfg = resolveAgentConfig(name);
 
     const file = findAgentFile(name);
     const isDefault = cfg.isDefault === true;

package/src/ui/agent-widget.ts

@@ -7,7 +7,7 @@
 
 import { truncateToWidth } from "@earendil-works/pi-tui";
 import type { AgentManager } from "../agent-manager.js";
-import { getConfig } from "../agent-types.js";
+import { resolveAgentConfig } from "../agent-types.js";
 import type { AgentInvocation, SubagentType } from "../types.js";
 import { getLifetimeTotal, getSessionContextPercent, type LifetimeUsage, type SessionLike } from "../usage.js";
 
@@ -144,12 +144,13 @@ export function formatDuration(startedAt: number, completedAt?: number): string
 
 /** Get display name for any agent type (built-in or custom). */
 export function getDisplayName(type: SubagentType): string {
-  return getConfig(type).displayName;
+  const config = resolveAgentConfig(type);
+  return config.displayName ?? config.name;
 }
 
 /** Short label for prompt mode: "twin" for append, nothing for replace (the default). */
 export function getPromptModeLabel(type: SubagentType): string | undefined {
-  const config = getConfig(type);
+  const config = resolveAgentConfig(type);
   return config.promptMode === "append" ? "twin" : undefined;
 }