Support custom model aliases for subagent spawning via Task tool

Problem Statement

The Task tool's model parameter is hardcoded to an enum of ["sonnet", "opus", "haiku"]. There is no way to register additional model aliases that Claude can select when spawning subagents.

Users who route Claude Code through a proxy (LiteLLM, OpenRouter, 9router, custom gateways) and have access to non-Anthropic models (Gemini, GPT, GLM, DeepSeek, etc.) cannot make these models visible to Claude as options when it decides which model to use for a subagent.

Why this matters

The current workaround — hijacking opus/sonnet/haiku aliases via ANTHROPIC_DEFAULT_*_MODEL env vars — only gives 3 slots and Claude has no awareness of what model it's actually selecting. It thinks it's picking "opus" when it might be routing to Gemini.

The ideal behavior: Claude sees a list like [opus, sonnet, haiku, gemini-reasoning, gpt-codex] and can intelligently choose the best model per subagent based on task characteristics (reasoning-heavy → gemini-reasoning, fast code generation → gpt-codex, etc.).

Current limitations

• Task tool model enum is hardcoded to 3 values
• Custom agent .md files accept model: frontmatter but only the same 3 aliases
• CLAUDE_CODE_SUBAGENT_MODEL is a single value, not a list
• No plugin, hook, or MCP mechanism can extend the model alias registry
• availableModels in settings restricts models but cannot add new ones

Workaround — claude-alias-patch

I built a patch that solves this: claude-alias-patch

It modifies 6 locations in cli.js to dynamically register model aliases from ANTHROPIC_DEFAULT_*_MODEL env vars. A single install script does everything — run it locally and it auto-patches your Claude instance.

It works. After running the script, all I had to do was open a new Claude session and ask Claude to list the models it can use — it listed all my custom aliases alongside the built-in ones. Then I asked it to spawn an agent with a custom model alias and send a test message to it — the agent spawned, used the correct model, and responded successfully.

No need to re-patch when you add or remove models — just edit ~/.claude/settings.json and restart Claude.

Proposed Native Solution

Add a customModels (or modelAliases) configuration in settings.json that:

1. Registers additional model aliases beyond the built-in three
2. Makes them available in the Task tool's model parameter
3. Makes them selectable via /model picker
4. Maps each alias to the actual model name sent to the API endpoint

{
  "customModels": {
    "gemini-reasoning": {
      "name": "Gemini 3.1 Pro",
      "modelId": "google/gemini-3.1-pro",
      "description": "Best for complex reasoning tasks"
    },
    "gpt-codex": {
      "name": "GPT 5.4 Codex",
      "modelId": "openai/gpt-5.4",
      "description": "Optimized for code generation"
    }
  }
}

The proxy at ANTHROPIC_BASE_URL handles the actual routing — Claude Code just needs to pass the model name through.

Related Issues

• #2480 — "Is it possible to define multiple custom models to choose from in /model?" (auto-closed, 19 👍, zero Anthropic response)
• #12386 — Custom model aliases in settings.json for Bedrock (closed as dup of #2480)
• #10169 — Custom Bedrock models not discoverable in /model
• #5772 — Built-in agents fail on Bedrock, can't use model: inherit
• #18873 — Task tool model parameter returns 404
• #24668 — Model parameter ignored with team_name
• #5456 — Sub-agents don't inherit model configuration
• #4377 — Feature request: add optional model parameter to sub-agents

Environment

• Claude Code latest
• Using custom proxy at ANTHROPIC_BASE_URL
• Platform: Linux