Running Sonnet or Opus in the main session and Haiku 5.5 in subagents that look up files and extract logs is a division of labor worth evaluating. When you set it up, keep two things apart: assigning a model to one custom subagent, and forcing every subagent onto the same model. Setting only CLAUDE_CODE_SUBAGENT_MODEL does not guarantee that the built-in Explore subagent changes with it.
Below, we first build a read-only subagent, then cover the global settings and how to verify them. The information was checked on October 10, 2026. The examples are based on the official documentation and were not run on a paid account, so they do not represent measured savings or confirmed successful calls.
Check your version, access method, and model permissions first
Run claude --version to see your version. The official model configuration docs require v2.1.293 or later to call Haiku 5.5. To upgrade, run claude update. For maintenance rules specific to your installation method, follow the prompt your installation shows.Model configuration docs
Confirm that your provider offers claude-haiku-5-5. The fixed model ID in the official API is not the same as the haiku alias in the tool: aliases change with the version, provider, and configuration. If you plan to reproduce an experiment, the full ID makes it easier to confirm the model.
If you haven't connected Claude Code yet, first finish the Anthropic Messages configuration for your provider. If you use an API relay that supports multiple models, see AICodeWith's Claude Code setup docs. There, ANTHROPIC_BASE_URL takes the root address, and you can't simply carry over a standard OpenAI /v1 configuration. The subagent settings later in this article are still controlled by Claude Code.
Create a read-only subagent that explicitly uses Haiku 5.5
Create .claude/agents/log-triage.md inside your project. If you want to share it across projects, put it in ~/.claude/agents/ in your user directory. On Windows, the equivalent is .claude\agents\ under your user directory. Project-level definitions are easy to share with a team. Don't put API keys in the file.
---
name: log-triage
description: 分析测试失败日志,提取失败测试、相关文件和证据;不修改代码。
tools: Read, Grep, Glob
model: claude-haiku-5-5
effort: medium
---
只读取与本次任务有关的日志和文件。
逐项返回失败测试名称、文件位置、错误原文和可能相关的代码。
将直接证据与推测分开;没有证据时明确说明。
不修改文件,不执行修复,不发起其他子任务。
Download this example source file (TXT, line breaks and indentation preserved)
model pins the model, tools restricts it to read-only file search, and effort sets the thinking effort. The value of medium here is a starting point for evaluation, not a guarantee of the lowest cost or highest accuracy. Tool permissions are still governed by the session and organization rules.Subagent definitions and tool restrictions
After saving, restart Claude Code and run /agents to check whether log-triage is recognized. Then give the main session a concrete request:
请使用 log-triage 子 Agent 读取 tests-failed.log,列出失败测试、
相关文件和错误原文。只做调查,不修改任何文件,
本次调用保留定义中的 claude-haiku-5-5 模型。
Download this example source file (TXT, line breaks and indentation preserved)
Replace the log file name with an actual file in your project. The prompt spells out the division of labor, but whether the model really runs as defined still has to be verified in the next step.
Check the model that ran, not just the config file
While the subagent is running, open /tasks and look at the model and effort shown on the task row. According to the official docs, this display requires v2.1.242 or later, which the Haiku version requirement above already covers.
Then check your provider's call logs for the request time, the actual model, input/output usage, and whether there were retries. If the platform can show the routed model, check that field first. If it only has the model the client requested, it can only prove what the client selected.
Finally, check whether the result meets the task: are the test names complete, do the file locations exist, do the citations match the log, and did any unrelated file changes appear. The task list confirms the client configuration, the call logs confirm the channel's request, and the result check confirms whether this division of labor is usable.
If the definition can't be found in /agents, check the file location, the YAML format at the top of the Markdown file, and the name field, then reopen the session. If the task appears but the model is different, work through the precedence order below.
Why a subagent still uses the main model after you set Haiku
The current official docs list the model selection order for regular subagents as:
- The model parameter passed in when that call is made.
- The
modelfield in the subagent definition. - The environment variable
CLAUDE_CODE_SUBAGENT_MODEL. - The main session's model.
So a full model ID in the definition is usually more explicit than a global default, but a parameter on a single call can still override it.model: inherit means use the main session's model. If model is omitted, the lookup continues down the order.
This order is also affected by organization restrictions such as availableModels. A restricted model may trigger a fallback model selection, and interactive sessions will show a prompt. If an installed mod rewrites the model in a agent.spawn hook, check that too. Earlier versions had a different precedence than the current one, so record your version number when troubleshooting.Model precedence and fallback rules
How to set the global default and forced mode
If you only want a default for regular subagents that don't specify their own model, merge it into the settings.json in your personal env. On macOS/Linux the path is ~/.claude/settings.json, and on Windows it is %USERPROFILE%\.claude\settings.json. To apply it to the current project only, use .claude/settings.local.json. If you create the file by hand, add an ignore rule so personal credentials don't get committed to the repository.
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-5-5"
}
}
Download this example source file (TXT, line breaks and indentation preserved)
This is a default and is overridden by higher-priority settings. The official docs also state that setting this variable alone does not change the model used by the built-in Explore and Plan.
If you've already evaluated task quality and want to override the model for subagents, teammates, and workflow agents across the board, use this forced configuration:
{
"env": {
"CLAUDE_CODE_SUBAGENT_MODEL": "claude-haiku-5-5",
"CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
}
}
Download this example source file (TXT, line breaks and indentation preserved)
Forced mode requires v2.1.257 or later. It ignores the model choice in subagent definitions and prevents callers from choosing another model. Forks and skill subagents that run with model: inherit are still exceptions. Don't describe it as "every subtask will definitely use Haiku."Forced mode details
If you only want to lower the model tier for Explore, you can also define a subagent with the same name, Explore, to override the built-in definition and set it to Haiku. This takes over the definition, so you have to maintain the prompt and tool restrictions yourself. If you only need log analysis, the log-triage above gives you tighter control over scope.
When editing an existing file, merge the env field and keep the original configuration. To undo forced mode, remove CLAUDE_CODE_SUBAGENT_MODEL_FORCE. To return to normal inheritance, also remove the default model variable, then restart and recheck with /tasks.
Which tasks tell you whether it's worth keeping
Start with work you can check directly: extracting failing logs, locating a function, or summarizing config entries in a file. Save cross-file fixes, complex root-cause analysis, and architecture decisions for a separate evaluation, so you don't switch every subagent at once.
For the same batch of tasks, record the correct items, misses, elapsed time, input/output, cache, retries, and time spent on manual fixes. A lower per-token price only reduces the cost of the requests it applies to. The cost of the main session reading subagent results, reinvestigating, and fixing still has to be counted. To get the cost per accepted task, divide the total cost of all calls in the round by the number of tasks that passed, and list manual time separately.
Start with one read-only subagent. Once you've confirmed the actual model, correct citations, and a controllable task scope, then consider widening the default setting.
Related reading
If you're still deciding which steps to hand to a smaller model, start with Haiku 5.5 coding uses and migration changes. When you need to account for long-conversation and cache costs, use the billing basis in the Haiku 5.5 API pricing guide.



