@tintinweb/pi-subagents 0.2.7 → 0.3.0

package/CHANGELOG.md

@@ -5,6 +5,43 @@ 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).
 
+## [0.3.0] - 2026-03-08
+
+### Added
+- **Case-insensitive agent type lookup** — `"explore"`, `"EXPLORE"`, and `"Explore"` all resolve to the same agent. LLMs frequently lowercase type names; this prevents validation failures.
+- **Unknown type fallback** — unrecognized agent types fall back to `general-purpose` with a note, instead of hard-rejecting. Matches Claude Code behavior.
+- **Dynamic tool list for general-purpose** — `builtinToolNames` is now optional in `AgentConfig`. When omitted, the agent gets all tools from `TOOL_FACTORIES` at lookup time, so new tools added upstream are automatically available.
+- **Agent source indicators in `/agents` menu** — `•` (project), `◦` (global), `✕` (disabled) with legend. Defaults are unmarked.
+- **Disabled agents visible in UI** — disabled agents now show in the "Agent types" list (marked `✕`) with an Enable action, instead of being invisible.
+- **Enable action** — re-enable a disabled agent from the `/agents` menu. Stub files are auto-cleaned.
+- **Disable action for all agent types** — custom and ejected default agents can now be disabled from the UI, not just built-in defaults.
+- `resolveType()` export — case-insensitive type name resolution for external use.
+- `getAllTypes()` export — returns all agent names including disabled (for UI listing).
+- `source` field on `AgentConfig` — tracks where an agent was loaded from (`"default"`, `"project"`, `"global"`).
+
+### Fixed
+- **Model resolver checks auth for exact matches** — `resolveModel("anthropic/claude-haiku-4-5-20251001")` now fails gracefully when no Anthropic API key is configured, instead of returning a model that errors at the API call. Explore silently falls back to the parent model on non-Anthropic setups.
+
+### Changed
+- **Unified agent registry** — built-in and custom agents now use the same `AgentConfig` type and a single registry. No more separate code paths for built-in vs custom agents.
+- **Default agents are overridable** — creating a `.md` file with the same name as a default agent (e.g. `.pi/agents/Explore.md`) overrides it.
+- **`/agents` menu** — "Agent types" list shows defaults and custom agents together with source indicators. Default agents get Eject/Disable actions; overridden defaults get Reset to default.
+- **Eject action** — export a default agent's embedded config as a `.md` file to project or personal location for customization.
+- **Model labels** — provider-agnostic: strips `provider/` prefix and `-YYYYMMDD` date suffix (e.g. `anthropic/claude-haiku-4-5-20251001` → `claude-haiku-4-5`). Works for any provider.
+- **New frontmatter fields** — `display_name` (UI display name) and `enabled` (default: true; set to false to disable).
+- **Menu navigation** — Esc in agent detail returns to agent list (not main menu).
+
+### Removed
+- **`statusline-setup` and `claude-code-guide` agents** — removed as built-in types (never spawned programmatically). Users can recreate them as custom agents if needed.
+- `BuiltinSubagentType` union type, `SUBAGENT_TYPES` array, `DISPLAY_NAMES` map, `SubagentTypeConfig` interface — replaced by unified `AgentConfig`.
+- `buildSystemPrompt()` switch statement — replaced by config-driven `buildAgentPrompt()`.
+- `HAIKU_MODEL_IDS` fallback array — Explore's haiku default is now just the `model` field in its config.
+- `BUILTIN_MODEL_LABELS` — model labels now derived from config.
+- `ALL_TOOLS` hardcoded constant — general-purpose now derives tools dynamically.
+
+### Added
+- `src/default-agents.ts` — embedded default configs for general-purpose, Explore, and Plan.
+
 ## [0.2.7] - 2026-03-08
 
 ### Fixed
@@ -130,6 +167,7 @@ Initial release.
 - **Thinking level** — per-agent extended thinking control
 - **`/agent` and `/agents` commands**
 
+[0.3.0]: https://github.com/tintinweb/pi-subagents/compare/v0.2.7...v0.3.0
 [0.2.7]: https://github.com/tintinweb/pi-subagents/compare/v0.2.6...v0.2.7
 [0.2.6]: https://github.com/tintinweb/pi-subagents/compare/v0.2.5...v0.2.6
 [0.2.5]: https://github.com/tintinweb/pi-subagents/compare/v0.2.4...v0.2.5

package/README.md

@@ -19,6 +19,7 @@ https://github.com/user-attachments/assets/5d1331e8-6d02-420b-b30a-dcbf838b1660
 - **Mid-run steering** — inject messages into running agents to redirect their work without restarting
 - **Session resume** — pick up where an agent left off, preserving full conversation context
 - **Graceful turn limits** — agents get a "wrap up" warning before hard abort, producing clean partial results instead of cut-off output
+- **Case-insensitive agent types** — `"explore"`, `"Explore"`, `"EXPLORE"` all work. Unknown types fall back to general-purpose with a note
 - **Fuzzy model selection** — specify models by name (`"haiku"`, `"sonnet"`) instead of full IDs, with automatic filtering to only available/configured models
 - **Context inheritance** — optionally fork the parent conversation into a sub-agent so it knows what's been discussed
 
@@ -75,21 +76,21 @@ Individual agent results render Claude Code-style in the conversation:
 
 Completed results can be expanded (ctrl+o in pi) to show the full agent output inline.
 
-## Built-in Agent Types
+## Default Agent Types
 
-| Type | Tools | Description |
-|------|-------|-------------|
-| `general-purpose` | all 7 | Full read/write access for complex multi-step tasks |
-| `Explore` | read, bash, grep, find, ls | Fast codebase exploration (read-only, defaults to haiku) |
-| `Plan` | read, bash, grep, find, ls | Software architect for implementation planning (read-only) |
-| `statusline-setup` | read, edit | Configuration editor |
-| `claude-code-guide` | read, grep, find | Documentation and help queries |
+| Type | Tools | Model | Description |
+|------|-------|-------|-------------|
+| `general-purpose` | all 7 | inherit | Full read/write access for complex multi-step tasks |
+| `Explore` | read, bash, grep, find, ls | haiku (falls back to inherit) | Fast codebase exploration (read-only) |
+| `Plan` | read, bash, grep, find, ls | inherit | Software architect for implementation planning (read-only) |
+
+Default agents can be **overridden** by creating a `.md` file with the same name (e.g. `.pi/agents/Explore.md`), or **disabled** per-project by creating a `.md` file with `enabled: false` frontmatter.
 
 ## Custom Agents
 
-Define custom agent types by creating `.md` files. The filename becomes the agent type name.
+Define custom agent types by creating `.md` files. The filename becomes the agent type name. Any name is allowed — using a default agent's name overrides it.
 
-Custom agents are discovered from two locations (higher priority wins):
+Agents are discovered from two locations (higher priority wins):
 
 | Priority | Location | Scope |
 |----------|----------|-------|
@@ -131,16 +132,18 @@ All fields are optional — sensible defaults for everything.
 | Field | Default | Description |
 |-------|---------|-------------|
 | `description` | filename | Agent description shown in tool listings |
+| `display_name` | — | Display name for UI (e.g. widget, agent list) |
 | `tools` | all 7 | Comma-separated built-in tools: read, bash, edit, write, grep, find, ls. `none` for no tools |
 | `extensions` | `true` | Inherit MCP/extension tools. `false` to disable |
 | `skills` | `true` | Inherit skills from parent |
-| `model` | inherit parent | Model as `provider/modelId` |
+| `model` | inherit parent | Model — `provider/modelId` or fuzzy name (`"haiku"`, `"sonnet"`) |
 | `thinking` | inherit | off, minimal, low, medium, high, xhigh |
 | `max_turns` | 50 | Max agentic turns before graceful shutdown |
 | `prompt_mode` | `replace` | `replace`: body is the full system prompt. `append`: body appended to default prompt |
 | `inherit_context` | `false` | Fork parent conversation into agent |
 | `run_in_background` | `false` | Run in background by default |
 | `isolated` | `false` | No extension/MCP tools, only built-in |
+| `enabled` | `true` | Set to `false` to disable an agent (useful for hiding a default agent per-project) |
 
 Frontmatter sets defaults. Explicit `Agent` parameters always override them.
 
@@ -193,19 +196,19 @@ The `/agents` command opens an interactive menu:
 
 ```
 Running agents (2) — 1 running, 1 done     ← only shown when agents exist
-Custom agents (3)                           ← submenu: edit or delete agents
+Agent types (6)                             ← unified list: defaults + custom
 Create new agent                            ← manual wizard or AI-generated
 Settings                                    ← max concurrency, max turns, grace turns, join mode
-
-Built-in (always available):
-  general-purpose · inherit
-  Explore         · haiku
-  Plan            · inherit
-  ...
 ```
 
-- **Custom agents submenu** — select an agent to edit (opens editor) or delete
-- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file)
+- **Agent types** — unified list with source indicators: `•` (project), `◦` (global), `✕` (disabled). Select an agent to manage it:
+  - **Default agents** (no override): Eject (export as `.md`), Disable
+  - **Default agents** (ejected/overridden): Edit, Disable, Reset to default, Delete
+  - **Custom agents**: Edit, Disable, Delete
+  - **Disabled agents**: Enable, Edit, Delete
+- **Eject** — writes the embedded default config as a `.md` file to project or personal location, so you can customize it
+- **Disable/Enable** — toggle agent availability. Disabled agents stay visible in the list (marked `✕`) and can be re-enabled
+- **Create new agent** — choose project/personal location, then manual wizard (step-by-step prompts for name, tools, model, thinking, system prompt) or AI-generated (describe what the agent should do and a sub-agent writes the `.md` file). Any name is allowed, including default agent names (overrides them)
 - **Settings** — configure max concurrency, default max turns, grace turns, and join mode at runtime
 
 ## Graceful Max Turns
@@ -250,13 +253,14 @@ When background agents complete, they notify the main agent. The **join mode** c
 ```
 src/
   index.ts            # Extension entry: tool/command registration, rendering
-  types.ts            # Type definitions (SubagentType, AgentRecord, configs)
-  agent-types.ts      # Agent type registry (built-in + custom), tool factories
+  types.ts            # Type definitions (AgentConfig, AgentRecord, etc.)
+  default-agents.ts   # Embedded default agent configs (general-purpose, Explore, Plan)
+  agent-types.ts      # Unified agent registry (defaults + user), tool factories
   agent-runner.ts     # Session creation, execution, graceful max_turns, steer/resume
   agent-manager.ts    # Agent lifecycle, concurrency queue, completion notifications
   group-join.ts       # Group join manager: batched completion notifications with timeout
-  custom-agents.ts    # Load custom agents from .pi/agents/*.md
-  prompts.ts          # System prompts per agent type
+  custom-agents.ts    # Load user-defined agents from .pi/agents/*.md
+  prompts.ts          # Config-driven system prompt builder
   context.ts          # Parent conversation context for inherit_context
   env.ts              # Environment detection (git, platform)
   ui/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.2.7",
+  "version": "0.3.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -21,9 +21,9 @@
     "autonomous"
   ],
   "dependencies": {
-    "@mariozechner/pi-ai": "latest",
-    "@mariozechner/pi-coding-agent": "latest",
-    "@mariozechner/pi-tui": "latest",
+    "@mariozechner/pi-ai": "^0.57.1",
+    "@mariozechner/pi-coding-agent": "^0.57.1",
+    "@mariozechner/pi-tui": "^0.57.1",
     "@sinclair/typebox": "latest"
   },
   "scripts": {

package/src/agent-runner.ts

@@ -13,8 +13,8 @@ import {
 } from "@mariozechner/pi-coding-agent";
 import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
 import type { Model } from "@mariozechner/pi-ai";
-import { getToolsForType, getConfig, getCustomAgentConfig } from "./agent-types.js";
-import { buildSystemPrompt } from "./prompts.js";
+import { getToolsForType, getConfig, getAgentConfig } from "./agent-types.js";
+import { buildAgentPrompt } from "./prompts.js";
 import { buildParentContext, extractText } from "./context.js";
 import { detectEnv } from "./env.js";
 import type { SubagentType, ThinkingLevel } from "./types.js";
@@ -38,47 +38,34 @@ export function getGraceTurns(): number { return graceTurns; }
 /** Set the grace turns value (minimum 1). */
 export function setGraceTurns(n: number): void { graceTurns = Math.max(1, n); }
 
-/** Haiku model IDs to try for Explore agents (in preference order). */
-const HAIKU_MODEL_IDS = [
-  "claude-haiku-4-5-20251001",
-  "claude-3-5-haiku-20241022",
-];
-
 /**
  * Try to find the right model for an agent type.
- * Priority: explicit option > custom agent model > type-specific default > parent model.
+ * Priority: explicit option > config.model > parent model.
  */
 function resolveDefaultModel(
-  type: SubagentType,
   parentModel: Model<any> | undefined,
   registry: { find(provider: string, modelId: string): Model<any> | undefined; getAvailable?(): Model<any>[] },
-  customModel?: string,
+  configModel?: string,
 ): Model<any> | undefined {
-  // 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 = (provider: string, modelId: string) =>
-    !availableKeys || availableKeys.has(`${provider}/${modelId}`);
-
-  // Custom agent model from frontmatter
-  if (customModel) {
-    const slashIdx = customModel.indexOf("/");
+  if (configModel) {
+    const slashIdx = configModel.indexOf("/");
     if (slashIdx !== -1) {
-      const provider = customModel.slice(0, slashIdx);
-      const modelId = customModel.slice(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;
     }
   }
 
-  if (type !== "Explore") return parentModel;
-
-  for (const modelId of HAIKU_MODEL_IDS) {
-    const found = registry.find("anthropic", modelId);
-    if (found && isAvailable("anthropic", modelId)) return found;
-  }
   return parentModel;
 }
 
@@ -152,17 +139,60 @@ export async function runAgent(
   options: RunOptions,
 ): Promise<RunResult> {
   const config = getConfig(type);
-  const customConfig = getCustomAgentConfig(type);
+  const agentConfig = getAgentConfig(type);
   const env = await detectEnv(options.pi, ctx.cwd);
 
-  // Build system prompt: custom override > custom append > built-in
+  // Build system prompt: custom override > custom append > config-driven
   let systemPrompt: string;
   if (options.systemPromptOverride) {
     systemPrompt = options.systemPromptOverride;
   } else if (options.systemPromptAppend) {
-    systemPrompt = buildSystemPrompt(type, ctx.cwd, env) + "\n\n" + options.systemPromptAppend;
+    // Build a default prompt and append to it
+    const defaultConfig = agentConfig ?? {
+      name: type,
+      description: "",
+      builtinToolNames: [],
+      extensions: true,
+      skills: true,
+      systemPrompt: "",
+      promptMode: "replace" as const,
+      inheritContext: false,
+      runInBackground: false,
+      isolated: false,
+    };
+    systemPrompt = buildAgentPrompt(defaultConfig, ctx.cwd, env) + "\n\n" + options.systemPromptAppend;
+  } else if (agentConfig) {
+    systemPrompt = buildAgentPrompt(agentConfig, ctx.cwd, env);
   } else {
-    systemPrompt = buildSystemPrompt(type, ctx.cwd, env);
+    // Unknown type — use a minimal general-purpose prompt
+    systemPrompt = buildAgentPrompt({
+      name: type,
+      description: "General-purpose agent",
+      builtinToolNames: [],
+      extensions: true,
+      skills: true,
+      systemPrompt: `# Role
+You are a general-purpose coding agent for complex, multi-step tasks.
+You have full access to read, write, edit files, and execute commands.
+Do what has been asked; nothing more, nothing less.
+
+# Tool Usage
+- Use the read tool instead of cat/head/tail
+- Use the edit tool instead of sed/awk
+- Use the write tool instead of echo/heredoc
+- Use the find tool instead of bash find/ls for file search
+- Use the grep tool instead of bash grep/rg for content search
+- Make independent tool calls in parallel
+
+# Output
+- Use absolute file paths
+- Do not use emojis
+- Be concise but complete`,
+      promptMode: "replace",
+      inheritContext: false,
+      runInBackground: false,
+      isolated: false,
+    }, ctx.cwd, env);
   }
 
   const tools = getToolsForType(type, ctx.cwd);
@@ -182,13 +212,13 @@ export async function runAgent(
   });
   await loader.reload();
 
-  // Resolve model: explicit option > custom agent config > type-specific default > parent model
+  // Resolve model: explicit option > config.model > parent model
   const model = options.model ?? resolveDefaultModel(
-    type, ctx.model, ctx.modelRegistry, customConfig?.model,
+    ctx.model, ctx.modelRegistry, agentConfig?.model,
   );
 
-  // Resolve thinking level: explicit option > custom agent config > undefined (inherit)
-  const thinkingLevel = options.thinkingLevel ?? customConfig?.thinking;
+  // Resolve thinking level: explicit option > agent config > undefined (inherit)
+  const thinkingLevel = options.thinkingLevel ?? agentConfig?.thinking;
 
   const sessionOpts: Record<string, unknown> = {
     cwd: ctx.cwd,
@@ -225,7 +255,7 @@ export async function runAgent(
 
   // Track turns for graceful max_turns enforcement
   let turnCount = 0;
-  const maxTurns = options.maxTurns ?? customConfig?.maxTurns ?? defaultMaxTurns;
+  const maxTurns = options.maxTurns ?? agentConfig?.maxTurns ?? defaultMaxTurns;
   let softLimitReached = false;
   let aborted = false;
 

package/src/agent-types.ts

@@ -1,7 +1,8 @@
 /**
- * agent-types.ts — Agent type registry: tool sets and configs per subagent type.
+ * agent-types.ts — Unified agent type registry.
  *
- * Supports both built-in types and custom agents loaded from .pi/agents/*.md.
+ * Merges embedded default agents with user-defined agents from .pi/agents/*.md.
+ * User agents override defaults with the same name. Disabled agents are kept but excluded from spawning.
  */
 
 import {
@@ -14,7 +15,8 @@ import {
   createLsTool,
 } from "@mariozechner/pi-coding-agent";
 import type { AgentTool } from "@mariozechner/pi-agent-core";
-import type { BuiltinSubagentType, SubagentType, SubagentTypeConfig, CustomAgentConfig } from "./types.js";
+import type { AgentConfig } from "./types.js";
+import { DEFAULT_AGENTS } from "./default-agents.js";
 
 type ToolFactory = (cwd: string) => AgentTool<any>;
 
@@ -31,107 +33,145 @@ const TOOL_FACTORIES: Record<string, ToolFactory> = {
 /** All known built-in tool names, derived from the factory registry. */
 export const BUILTIN_TOOL_NAMES = Object.keys(TOOL_FACTORIES);
 
-const BUILTIN_CONFIGS: Record<BuiltinSubagentType, SubagentTypeConfig> = {
-  "general-purpose": {
-    displayName: "Agent",
-    description: "General-purpose agent for complex, multi-step tasks",
-    builtinToolNames: BUILTIN_TOOL_NAMES,
-    extensions: true,
-    skills: true,
-  },
-  "Explore": {
-    displayName: "Explore",
-    description: "Fast codebase exploration agent (read-only)",
-    builtinToolNames: ["read", "bash", "grep", "find", "ls"],
-    extensions: true,
-    skills: true,
-  },
-  "Plan": {
-    displayName: "Plan",
-    description: "Software architect for implementation planning (read-only)",
-    builtinToolNames: ["read", "bash", "grep", "find", "ls"],
-    extensions: true,
-    skills: true,
-  },
-  "statusline-setup": {
-    displayName: "Config",
-    description: "Configuration editor (read + edit only)",
-    builtinToolNames: ["read", "edit"],
-    extensions: false,
-    skills: false,
-  },
-  "claude-code-guide": {
-    displayName: "Guide",
-    description: "Documentation and help queries",
-    builtinToolNames: ["read", "grep", "find"],
-    extensions: false,
-    skills: false,
-  },
-};
+/** Unified runtime registry of all agents (defaults + user-defined). */
+const agents = new Map<string, AgentConfig>();
 
-/** Runtime registry of custom agent configs. */
-const customAgents = new Map<string, CustomAgentConfig>();
+/**
+ * Register agents into the unified registry.
+ * Starts with DEFAULT_AGENTS, then overlays user agents (overrides defaults with same name).
+ * Disabled agents (enabled === false) are kept in the registry but excluded from spawning.
+ */
+export function registerAgents(userAgents: Map<string, AgentConfig>): void {
+  agents.clear();
+
+  // Start with defaults
+  for (const [name, config] of DEFAULT_AGENTS) {
+    agents.set(name, config);
+  }
+
+  // Overlay user agents (overrides defaults with same name)
+  for (const [name, config] of userAgents) {
+    agents.set(name, config);
+  }
+}
 
-/** Register custom agents into the runtime registry. */
-export function registerCustomAgents(agents: Map<string, CustomAgentConfig>): void {
-  customAgents.clear();
-  for (const [name, config] of agents) {
-    customAgents.set(name, config);
+/** Case-insensitive key resolution. */
+function resolveKey(name: string): string | undefined {
+  if (agents.has(name)) return name;
+  const lower = name.toLowerCase();
+  for (const key of agents.keys()) {
+    if (key.toLowerCase() === lower) return key;
   }
+  return undefined;
+}
+
+/** Resolve a type name case-insensitively. Returns the canonical key or undefined. */
+export function resolveType(name: string): string | undefined {
+  return resolveKey(name);
 }
 
-/** Get the custom agent config if it exists. */
-export function getCustomAgentConfig(name: string): CustomAgentConfig | undefined {
-  return customAgents.get(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 available type names (built-in + custom). */
+/** Get all enabled type names (for spawning and tool descriptions). */
 export function getAvailableTypes(): string[] {
-  return [...Object.keys(BUILTIN_CONFIGS), ...customAgents.keys()];
+  return [...agents.entries()]
+    .filter(([_, config]) => config.enabled !== false)
+    .map(([name]) => name);
 }
 
-/** Get all custom agent names. */
-export function getCustomAgentNames(): string[] {
-  return [...customAgents.keys()];
+/** Get all type names including disabled (for UI listing). */
+export function getAllTypes(): string[] {
+  return [...agents.keys()];
 }
 
-/** Check if a type is valid (built-in or custom). */
+/** Get names of default agents currently in the registry. */
+export function getDefaultAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault === true)
+    .map(([name]) => name);
+}
+
+/** Get names of user-defined agents (non-defaults) currently in the registry. */
+export function getUserAgentNames(): string[] {
+  return [...agents.entries()]
+    .filter(([_, config]) => config.isDefault !== true)
+    .map(([name]) => name);
+}
+
+/** Check if a type is valid and enabled (case-insensitive). */
 export function isValidType(type: string): boolean {
-  return type in BUILTIN_CONFIGS || customAgents.has(type);
+  const key = resolveKey(type);
+  if (!key) return false;
+  return agents.get(key)?.enabled !== false;
 }
 
-/** Get built-in tools for a type. Works for both built-in and custom agents. */
-export function getToolsForType(type: SubagentType, cwd: string): AgentTool<any>[] {
-  const config = BUILTIN_CONFIGS[type as BuiltinSubagentType];
-  if (config) {
-    return config.builtinToolNames.map((n) => TOOL_FACTORIES[n](cwd));
-  }
-  const custom = customAgents.get(type);
-  if (custom) {
-    return custom.builtinToolNames
-      .filter((n) => n in TOOL_FACTORIES)
-      .map((n) => TOOL_FACTORIES[n](cwd));
-  }
-  // Fallback: all tools
-  return BUILTIN_TOOL_NAMES.map((n) => TOOL_FACTORIES[n](cwd));
+/** Get built-in tools for a type (case-insensitive). */
+export function getToolsForType(type: string, cwd: string): AgentTool<any>[] {
+  const key = resolveKey(type);
+  const raw = key ? agents.get(key) : undefined;
+  const config = raw?.enabled !== false ? raw : undefined;
+  const toolNames = config?.builtinToolNames?.length ? config.builtinToolNames : BUILTIN_TOOL_NAMES;
+  return toolNames.filter((n) => n in TOOL_FACTORIES).map((n) => TOOL_FACTORIES[n](cwd));
 }
 
-/** Get config for a type. Works for both built-in and custom agents. */
-export function getConfig(type: SubagentType): SubagentTypeConfig {
-  const builtin = BUILTIN_CONFIGS[type as BuiltinSubagentType];
-  if (builtin) return builtin;
+/** 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;
+} {
+  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,
+    };
+  }
 
-  const custom = customAgents.get(type);
-  if (custom) {
+  // Fallback for unknown/disabled types — general-purpose config
+  const gp = agents.get("general-purpose");
+  if (gp && gp.enabled !== false) {
     return {
-      displayName: custom.name,
-      description: custom.description,
-      builtinToolNames: custom.builtinToolNames,
-      extensions: custom.extensions,
-      skills: custom.skills,
+      displayName: gp.displayName ?? gp.name,
+      description: gp.description,
+      builtinToolNames: gp.builtinToolNames ?? BUILTIN_TOOL_NAMES,
+      extensions: gp.extensions,
+      skills: gp.skills,
     };
   }
 
-  // Fallback for unknown types — general-purpose config
-  return BUILTIN_CONFIGS["general-purpose"];
+  // Absolute fallback (should never happen)
+  return {
+    displayName: "Agent",
+    description: "General-purpose agent for complex, multi-step tasks",
+    builtinToolNames: BUILTIN_TOOL_NAMES,
+    extensions: true,
+    skills: true,
+  };
+}
+
+// ---- Backwards-compatible aliases ----
+
+/** @deprecated Use registerAgents instead */
+export const registerCustomAgents = registerAgents;
+
+/** @deprecated Use getAgentConfig instead */
+export function getCustomAgentConfig(name: string): AgentConfig | undefined {
+  const key = resolveKey(name);
+  return key ? agents.get(key) : undefined;
+}
+
+/** @deprecated Use getUserAgentNames instead */
+export function getCustomAgentNames(): string[] {
+  return getUserAgentNames();
 }

package/src/custom-agents.ts

@@ -6,7 +6,7 @@ import { parseFrontmatter } from "@mariozechner/pi-coding-agent";
 import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, basename } from "node:path";
 import { homedir } from "node:os";
-import { SUBAGENT_TYPES, type CustomAgentConfig, type ThinkingLevel } from "./types.js";
+import type { AgentConfig, ThinkingLevel } from "./types.js";
 import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
 
 /**
@@ -16,19 +16,20 @@ import { BUILTIN_TOOL_NAMES } from "./agent-types.js";
  *   2. Global:  ~/.pi/agent/agents/*.md
  *
  * Project-level agents override global ones with the same name.
+ * Any name is allowed — names matching defaults (e.g. "Explore") override them.
  */
-export function loadCustomAgents(cwd: string): Map<string, CustomAgentConfig> {
+export function loadCustomAgents(cwd: string): Map<string, AgentConfig> {
   const globalDir = join(homedir(), ".pi", "agent", "agents");
   const projectDir = join(cwd, ".pi", "agents");
 
-  const agents = new Map<string, CustomAgentConfig>();
-  loadFromDir(globalDir, agents);   // lower priority
-  loadFromDir(projectDir, agents);  // higher priority (overwrites)
+  const agents = new Map<string, AgentConfig>();
+  loadFromDir(globalDir, agents, "global");   // lower priority
+  loadFromDir(projectDir, agents, "project");  // higher priority (overwrites)
   return agents;
 }
 
 /** Load agent configs from a directory into the map. */
-function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void {
+function loadFromDir(dir: string, agents: Map<string, AgentConfig>, source: "project" | "global"): void {
   if (!existsSync(dir)) return;
 
   let files: string[];
@@ -40,7 +41,6 @@ function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void
 
   for (const file of files) {
     const name = basename(file, ".md");
-    if ((SUBAGENT_TYPES as readonly string[]).includes(name)) continue;
 
     let content: string;
     try {
@@ -53,6 +53,7 @@ function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void
 
     agents.set(name, {
       name,
+      displayName: str(fm.display_name),
       description: str(fm.description) ?? name,
       builtinToolNames: csvList(fm.tools, BUILTIN_TOOL_NAMES),
       extensions: inheritField(fm.extensions ?? fm.inherit_extensions),
@@ -65,6 +66,8 @@ function loadFromDir(dir: string, agents: Map<string, CustomAgentConfig>): void
       inheritContext: fm.inherit_context === true,
       runInBackground: fm.run_in_background === true,
       isolated: fm.isolated === true,
+      enabled: fm.enabled !== false,  // default true; explicitly false disables
+      source,
     });
   }
 }