Use Haiku 5.5 for Read-Only Claude Code Subagents—and Verify the Model

The safest pattern is not to move the entire Claude Code session to a small model. Give Haiku 5.5 only the work that is bounded, read-only, and easy to verify: finding symbol references, tracing imports, locating configuration, or summarizing a defined set of files. Keep Sonnet or Opus in the main conversation for judgment, edits, tests, and final sign-off.

A successful configuration needs more evidence than “use Haiku” in a prompt or model: haiku in a file. Check three layers: the explicit model in the agent definition, the model Claude Code shows for the running task, and the actual Model ID in the provider’s request record. Treat the run as verified only when those layers agree.

Decide what can be delegated

Anthropic positions Haiku 5.5 for quick, repetitive workloads such as summaries, compaction, database queries, and classification, and specifically describes it as a coding subagent alongside Sonnet 5.5 or Opus 5.5. Anthropic still recommends larger models for complex agentic coding. See the Haiku 5.5 announcement.

Use this split as a starting point:

Task	Recommended owner	Why
Find every reference to a class, function, or setting	Read-only small-model subagent	The input, output, and stopping rule are clear
Summarize the responsibilities of files in one directory	Read-only small-model subagent	It requires reading and synthesis, not changes
Trace a request from an entry point to a database call	Read-only small-model subagent	You can verify it with file paths and line numbers
Choose an architecture, migration strategy, or security boundary	Sonnet/Opus main agent	It needs cross-context trade-offs and higher-stakes judgment
Modify code, run migrations, update dependencies, or change permissions	Sonnet/Opus main agent	It changes the workspace and needs stricter review
Decide and implement the final fix after research	Sonnet/Opus main agent	It must combine evidence and own the outcome

A useful test is whether you can state, in one sentence, what to find, what to return, and when to stop—and whether the task can finish without writing files. If not, keep it in the main conversation.

Understand four different model controls

Claude Code has several model controls that are easy to confuse:

1. Main conversation model: selected with /model, a startup flag, or settings.
2. The subagent frontmatter model: applies to that agent definition.
3. Alias versus full Model ID: haiku is an alias whose resolution can change by provider and version; claude-haiku-5-5 is Anthropic’s published full ID.
4. One-role override versus global override: a custom agent named Explore replaces only built-in Explore, while CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 affects almost every subagent.

The current official subagent documentation resolves a model in this order: a per-invocation model, the agent definition’s model, CLAUDE_CODE_SUBAGENT_MODEL, and finally the main conversation model. Therefore, CLAUDE_CODE_SUBAGENT_MODEL alone is only a default; it does not guarantee that the agent definition or invocation cannot override it. See the Claude Code subagent documentation.

For this workflow, start with one explicitly named read-only agent. Do not begin with a global forced override, because it can also move Plan, general-purpose, teammate, or workflow agents onto the small model.

Step 1: check your Claude Code version and provider IDs

Check the client version first:

claude --version

The version changes both the interface and the available verification path:

• In Claude Code v2.1.198 and later, /agents no longer opens the creation wizard. It reminds you to ask Claude to create a file or edit .claude/agents/ or ~/.claude/agents/ directly.
• In v2.1.197 and earlier, /agents opens the interactive wizard with Running and Library tabs.
• In v2.1.242 and later, /tasks shows the model on the running subagent row. On older versions, rely more heavily on the provider’s request record.
• Use CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 only when you deliberately want one model on all subagents. That behavior requires v2.1.257 or later.

Next, confirm which exact IDs your provider accepts:

• On the Anthropic Claude API, the official Haiku 5.5 Model ID is claude-haiku-5-5. See the official model page.
• On a cloud platform or third-party gateway, do not assume the same ID is already available. The provider may use a deployment name, its own alias, or a curated catalog.
• At the time this guide was checked on October 10, 2026, BetterToken’s public catalog listed claude-haiku-4-5-20251001, claude-sonnet-5-5, and claude-opus-5-5, but not claude-haiku-5-5. When using BetterToken, choose an ID that actually appears in the current catalog instead of copying the new Anthropic ID. See the current BetterToken catalog.

“Anthropic has released the model” and “my gateway serves the model” are separate facts. Do not infer support from a verbal instruction or a family alias when the ID is absent from the provider catalog.

Step 2: create a project-level read-only subagent

Project agents live in .claude/agents/ and can be maintained with the repository. User agents in ~/.claude/agents/ are available across your projects.

Create the project directory from the repository root:

mkdir -p .claude/agents

Create .claude/agents/repo-researcher.md. With the Anthropic Claude API, use this definition:

---
name: repo-researcher
description: Finds symbols, traces call paths, and summarizes selected files before code changes. Use only for bounded read-only repository research.
tools: Read, Grep, Glob
model: claude-haiku-5-5
---

You are a read-only repository researcher.

For each task:
1. Search only the scope named by the caller.
2. Do not edit, create, delete, or rename files.
3. Return file paths and line numbers for every important finding.
4. Separate direct evidence from inference.
5. Stop when the requested question is answered; do not propose unrelated refactors.

Return:
- Findings
- Evidence: file:line
- Uncertainties
- Suggested next check for the main agent

Three details matter:

• tools allows only Read, Grep, and Glob; it does not grant Write, Edit, or Bash.
• description explains when delegation is appropriate, reducing the chance that the main agent sends modification work to it.
• model uses a full ID accepted by the provider, not merely a sentence asking for Haiku.

When Claude Code is connected through BetterToken, the small Claude model present in the checked catalog is:

model: claude-haiku-4-5-20251001

That is a current-catalog example, not a permanent promise. Recheck the catalog or Model Plaza before changing the mapping. BetterToken’s Claude Code documentation says to use an exact Model ID and set ANTHROPIC_BASE_URL to https://bettertoken.ai without appending /v1. See the BetterToken Claude Code setup guide.

If .claude/agents/ did not exist when the current session started and Claude Code cannot see the new agent, restart Claude Code once. The official documentation notes that a running watcher does not discover the first agents directory when that directory was absent at session start.

Step 3: keep the main agent on Sonnet or Opus

Choose the main conversation model separately. For example:

/model sonnet

or:

/model opus

With a gateway, the final model behind an alias depends on the gateway and its mapping. Use a full provider ID when you need a pinned version, then confirm it in the provider record.

Do not set a global force variable merely to put one research agent on a small model. The following configuration has a much broader effect:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Use it only when you intentionally want Plan, general-purpose subagents, teammates, and workflow agents to follow the same model. If you want to change only automatic code exploration, define a project or user agent named Explore and give that definition its own model. That replaces built-in Explore without changing every other subagent.

Step 4: trigger the agent with a test you can audit

Do not begin with “understand the whole repository.” Use a narrow task whose answer can be checked manually:

Use the repo-researcher agent to find every call site of PaymentService.createCharge.
Return file:line, the caller's purpose, and the path from the public entry point.
Do not edit files. Stop after covering this symbol and its direct callers.

After the run, check four things:

1. The main transcript contains a delegation row for repo-researcher; the main agent did not silently perform the search itself.
2. The subagent returned file paths and line numbers and separated evidence from inference.
3. The working tree is unchanged:

git status --short

4. The main agent, not the research agent, owns the later judgment and any code changes.

If the research is worth preserving, review it in the main conversation first. Then let the main agent save the accepted result to project documentation or an issue. Do not add write access to the research agent merely to persist its output.

Step 5: verify the model that actually ran

1. Inspect the agent definition—but do not stop there

Confirm that .claude/agents/repo-researcher.md contains the intended full ID. This proves only the static configuration. A per-invocation model, organization policy, or gateway mapping may still alter the request.

2. Inspect /tasks while the agent is running

Run:

/tasks

Claude Code v2.1.242 and later shows the model on the subagent row. If it differs from the file, check whether:

• Claude passed a different model for this invocation;
• CLAUDE_CODE_SUBAGENT_MODEL_FORCE is enabled;
• an organization availableModels policy substituted an allowed model;
• your client version follows an older precedence rule.

3. Match the provider request record

Find the request in the same time window and inspect its actual Model ID. This is especially important with a third-party gateway, because an alias shown by the client may be mapped again by the gateway.

BetterToken presents model, token counts, final charge, and status in one request record. For this workflow, use only the model and status fields as verification; do not turn the record into an unsupported savings claim. Match the request timestamp to the subagent’s run window before attributing it to that agent.

Use a small acceptance table:

Checkpoint	Expected evidence	If it differs
Agent file	Exact Model ID	Correct the ID, then reload or restart if needed
/tasks	Target subagent and running model	Check invocation settings, force variables, and organization policy
Provider record	Actual Model ID and successful status in the same time window	Check catalog, alias mapping, routing, and account access
git status --short	No unexpected file changes	Restrict tools, revert changes, and rerun the test

Record “model switch verified” only when the model evidence agrees across the first three checkpoints. A prompt mentioning Haiku, an agent name in the interface, or a completed answer is not sufficient by itself.

Troubleshooting

The agent is not invoked

Confirm that the file is in .claude/agents/ or ~/.claude/agents/, the frontmatter has both name and description, and the YAML parses. Restart Claude Code if this is the first agent directory created after the session began. If it still does not load, run Claude Code with --debug and inspect the loading error.

/agents does not show a creation wizard

That is normally expected, not a failure. In v2.1.198 and later, /agents prints guidance to edit agent files directly. The interactive wizard belongs to v2.1.197 and earlier. Follow the documentation for the version you actually run rather than an older screenshot.

model: haiku does not prove Haiku 5.5

haiku is an alias, not a pinned version. Its target can change with the Claude Code version, provider, or gateway mapping. For auditable routing, use a full ID present in the current provider catalog and verify both /tasks and the provider record.

The gateway returns model not found, 403, or silently falls back

First check that the ID is in the gateway’s live catalog and that the account is allowed to use it. If the catalog does not contain claude-haiku-5-5, do not keep retrying that string; choose a suitable listed model or wait for the gateway to add it. An organization allowlist can also substitute another model while the task continues, so inspect the runtime evidence.

Every subagent moved to the small model

Check for and remove CLAUDE_CODE_SUBAGENT_MODEL_FORCE. To pin only one agent, put the full ID in that agent’s frontmatter. To change only automatic exploration, override Explore instead.

The research agent changed files

Use git status --short to identify the scope, then revert unintended changes. Restrict tools to Read, Grep, Glob and repeat the read-only boundary in the system prompt. Removing write-capable tools is more reliable than a prompt that merely says “do not edit.”

A minimal rollout

Start with five steps:

1. Upgrade Claude Code and run claude --version.
2. Copy a real, currently available full Model ID from your provider catalog.
3. Create one repo-researcher agent limited to Read, Grep, and Glob.
4. Trigger it with a task limited to one symbol or directory.
5. Compare /tasks, the provider request record, and git status --short.

The goal is not to send every task to the smallest model. It is to establish an auditable division of labor: a small model gathers verifiable read-only evidence, while the Sonnet or Opus main agent owns high-impact decisions and changes. Verify one narrow task first, then expand the pattern only where the same acceptance criteria still work.