[FEATURE] Add per-built-in-agent model/effort override (settings.json), without forking the prompt

Open 💬 0 comments Opened Jul 2, 2026 by flesheatinggames

Preflight Checklist

  • [x] I have searched existing requests and this feature hasn't been requested yet
  • [x] This is a single feature request (not multiple features)

Problem Statement

Problem

Built-in Explore now inherits the main session's model. On an Opus session, exploration runs on Opus — expensive and slow for basic grep-style work that _absolutely_ does not require Opus. There's no supported way to pin a built-in subagent to a specific model/effort.

Current behavior

  • Same-name override (~/.claude/agents/Explore.md) is rejected — built-ins are baked into the binary.
  • CLAUDE_CODE_SUBAGENT_MODEL doesn't override built-ins.
  • permissions.deny: ["Agent(Explore)"] blocks Explore but doesn't force delegation — the main agent just explores inline on the session model or delegates to general-purpose.
  • Forking into a custom-named agent loses the built-in prompt and doesn't reliably auto-trigger.

Why it matters

In an engineering organization with many developers using Claude Code all day, Exploration costs are skyrocketing and will quickly render Claude Code unfeasible for continued use. The logical setup — Opus for main reasoning, cheap model for exploration — is currently impossible for the built-in Explore without forking its prompt. Model resolution already has a priority chain (env > invocation > frontmatter > parent); this slots in cleanly.

Prior art

Requested in #25546, #21348 (both closed without a shipped override).

Proposed Solution

Request

A settings.json map to override model/effort per built-in agent, preserving its prompt:

{ "agentOverrides": { "Explore": { "model": "sonnet", "effort": "low" } } }

Or per-agent env vars (CLAUDE_CODE_EXPLORE_MODEL), or make CLAUDE_CODE_SUBAGENT_MODEL apply to built-ins.

Alternative Solutions

_No response_

Priority

High - Significant impact on productivity

Feature Category

Configuration and settings

Use Case Example

_No response_

Additional Context

_No response_

View original on GitHub ↗