Your Claude Code Explore subagent might be running on Opus without you asking

Open a Claude Code session, switch to Opus because the task in front of you actually needs it, then ask Claude to "find where the retry logic lives." That lookup gets delegated to the built-in Explore subagent, and if you learned Claude Code's model behavior more than a few releases ago, you are probably picturing that delegation running on Haiku, quietly and cheaply, the way it always used to.

As of Claude Code v2.1.198, that is no longer how Explore works. It now inherits the main conversation's model — capped at Opus on the Claude API, so it never runs more expensive than your session, but it also no longer defaults to something cheap. A session on Opus means Explore runs on Opus too. A session on Sonnet means Explore runs on Sonnet. The cap only stops it from going higher than whatever you are already paying for.

That is a real behavior change, not a hypothetical. It is documented directly in the subagents reference: "A user or project subagent named Explore overrides the built-in and keeps its own model field, so define one with model: haiku to keep exploration on a lower-cost model." Anthropic is telling you, in the docs, that the override is something you now have to do yourself if you want it.

Why this actually costs something

Per Anthropic's current API pricing (verified against platform.claude.com/docs/en/about-claude/pricing as of this writing):

Model	Input	Output
Claude Opus 4.8	$5 / MTok	$25 / MTok
Claude Sonnet 5	$2 / MTok	$10 / MTok
Claude Haiku 4.5	$1 / MTok	$5 / MTok

An Explore delegation inheriting Opus costs 5x the input tokens and 5x the output tokens of the same delegation pinned to Haiku. A session that fires a dozen Explore calls while you build a feature — locating a function, checking every caller, confirming a config key exists — pays that 5x multiplier a dozen times over, on work that never needed frontier reasoning in the first place. Exploration is grep with judgment, not the hard part of the task.

The fix, scoped to just Explore

Define a project or user-level subagent literally named Explore. Because Claude Code resolves same-named subagents by scope priority, your definition overrides the built-in one — and unlike the built-in, yours keeps whatever model you set instead of inheriting.

Project-scoped (checked into the repo, shared with your team):

---
name: Explore
description: Fast, read-only search agent for locating code. Use for grep-style lookups, file discovery, and codebase search — not modification.
tools: Read, Grep, Glob, Bash
model: haiku
---

You are a fast, read-only code search agent. Locate files, symbols, and
patterns. Report what you find. Do not modify anything.

Save it as .claude/agents/Explore.md for one project, or ~/.claude/agents/Explore.md to apply it everywhere you run Claude Code. Restart the session if ~/.claude/agents/ did not already exist — the file watcher only picks up new files inside a directory that existed when the session started.

This is a one-time, ten-minute change. After it, your main session can sit on Opus for the reasoning-heavy part of a task while every Explore delegation underneath it runs on Haiku, regardless of what the parent session is doing.

The single lever for everything, when you need it

Sometimes you want every subagent in a session — Explore, general-purpose, and any custom ones you have defined — capped at a cheap model at once, without editing files. That is what CLAUDE_CODE_SUBAGENT_MODEL is for:

CLAUDE_CODE_SUBAGENT_MODEL=haiku claude

Claude Code resolves a subagent's model in this order: the CLAUDE_CODE_SUBAGENT_MODEL environment variable first, then a per-invocation model parameter, then the subagent's own frontmatter, then inherit from the main conversation. The environment variable wins over all of it — including a custom subagent you explicitly pinned to sonnet or opus for a reason.

That makes it the right tool for a specific situation: a big fan-out pass where you are spinning up ten or twenty subagents to search or summarize in parallel, and none of them need to reason hard. It is the wrong tool to leave set permanently, because it will silently downgrade a subagent you deliberately pinned to a stronger model — an architecture-review agent, a debugger, anything where the frontmatter model: opus was a real decision, not a default. Set it for the session that needs it, then unset it.

The other lever: fewer tool definitions, not just a cheaper model

Every tool a subagent has access to — including every tool from every connected MCP server — adds its schema to that subagent's context on every turn, whether or not the subagent ever calls it. If a subagent only ever reads and greps, an MCP server full of ticketing or deployment tools sitting in its tool list is pure overhead.

disallowedTools accepts MCP server-level patterns, not just individual tool names:

---
name: safe-researcher
description: Read-only research agent, no external service access
disallowedTools: mcp__github, mcp__linear
---

mcp__<server> strips every tool from that server; mcp__* strips every MCP tool from every server. Combine this with a haiku model pin on a research-only subagent and you have cut both sides of the cost: cheaper tokens, and fewer of them per turn.

Where to actually spend the reasoning

None of this is an argument for running everything on Haiku. It is an argument for matching the model to the step. The pattern that holds up in practice:

1. Fan-out on the cheap model. Exploration, file discovery, "does X exist," "what calls Y" — Haiku via the Explore override or a custom read-only subagent.
2. Synthesis on the model that is actually thinking. The subagent (or your main session) that reads the fan-out summaries and decides what to do next stays on Sonnet or Opus, because that is where the judgment call actually happens.
3. CLAUDE_CODE_SUBAGENT_MODEL for one-off bulk passes only. Set it, run the pass, unset it. Do not leave it exported in a shell profile where it will quietly cap a subagent you meant to run at full strength.

The docs frame the model field as a cost-control knob, but most sessions never touch it because the default behavior used to make that unnecessary. It no longer does. Checking whether you have an Explore override today, and adding one if you do not, is the kind of five-minute fix that keeps paying back on every session after it.

For more on getting a terminal coding agent set up well in the first place, see installing CLI coding agents and CLI workflows.