Qual modelo cada subagente usa no Claude Code

Downshift por Tiago Vilas Boas. Atualizado em 19 de outubro de 2026

Este Downshift é uma ferramenta em Go para agentes de código com IA, não a biblioteca React downshift de autocomplete.

Resumo

Para saber qual modelo cada subagente usa, a documentação da Anthropic define esta ordem: o subagente toma o modelo primeiro do parâmetro da chamada, depois do frontmatter, depois de CLAUDE_CODE_SUBAGENT_MODEL e, por fim, do modelo da conversa principal. Essas configurações escolhem um modelo para um agente inteiro, então não distinguem um rename de uma revisão de arquitetura.

Qual modelo cada subagente usa: a ordem de precedência

Esta é a ordem na documentação de sub-agents em 2026-10-19. O texto oficial está em inglês.

Prioridade	Origem	Observação
1	O parâmetro model que o Claude passa ao iniciar o subagente	Escolhido a cada chamada
2	O campo model na definição do subagente	inherit seleciona o modelo da conversa principal
3	CLAUDE_CODE_SUBAGENT_MODEL	Um alias ou um id completo de modelo
4	O modelo da conversa principal	O último recurso

A ordem mudou na v2.1.251. Antes, a variável de ambiente vinha primeiro e vencia o parâmetro da chamada e o frontmatter. Guias mais antigos ainda descrevem essa ordem.

O campo model no frontmatter

O campo aceita os aliases sonnet, opus, haiku e fable, um id completo como claude-opus-5-5, ou inherit. A página de custos da Anthropic sugere model: haiku para tarefas simples de subagente.

---
name: leitor-de-logs
description: Lê logs e relata erros
model: haiku
---

A variável CLAUDE_CODE_SUBAGENT_MODEL e o FORCE

A variável define um modelo para todo subagente que nada mais configure. Desde a v2.1.257, acrescentar CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 aplica esse modelo a todos os subagentes, passando por cima das definições e das escolhas por chamada. Com o FORCE ligado, o Claude não consegue passar um modelo.

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

Subagentes embutidos: Explore e Plan

O Explore é somente leitura. O modelo dele é o da conversa principal, com exceções quando o modelo principal é o Fable. Para rodá-lo em um modelo mais barato, defina um subagente chamado Explore com model: haiku. Configurar só CLAUDE_CODE_SUBAGENT_MODEL não muda o Explore.
O Plan também é somente leitura e herda o modelo principal, a menos que a variável com FORCE o substitua.
O general-purpose usa CLAUDE_CODE_SUBAGENT_MODEL, se definida e se nada mais atribuir um modelo. Caso contrário, usa o modelo principal.

Esforço é outra configuração

A definição do subagente pode fixar effort em low, medium, high, xhigh ou max, e os níveis disponíveis dependem do modelo. A partir da v2.1.292, o Claude também pode passar o esforço por chamada. A variável CLAUDE_CODE_EFFORT_LEVEL vence as duas formas.

Por que o subagente ainda usa o modelo da sessão

Nada atribui um modelo, então vale a regra 4.
O CLAUDE_CODE_SUBAGENT_MODEL_FORCE está ligado, ou a variável aponta para um modelo diferente do esperado.
O Explore embutido segue a própria regra, não a variável de ambiente.

Há também relatos que essas regras não explicam. A issue 43869 diz que todos os mecanismos resolvem para o modelo pai, e a issue 100082 relata o campo model ignorado, com 1.149 de 1.371 subagentes rodando no Opus da sessão. Ambas estavam abertas em 2026-10-19. São relatos de usuários, e não afirmo a causa deles.

Para a pergunta de quando vale a pena usar Haiku nos subagentes, há um artigo em português no blog horadecodar.com.br. Este guia responde a outra pergunta: qual modelo o subagente de fato recebe.

Escolha fixa ou por tarefa

Frontmatter e variável de ambiente são estáticos: uma resposta por agente ou por sessão. Um rename e uma revisão de arquitetura que passam pelo mesmo agente recebem o mesmo modelo. Um hook PreToolUse pode definir o modelo por chamada, e aí ele pode variar por tarefa. O Downshift faz isso no Claude Code e, em uma sessão, o efeito foi observado em dois spawns.

Há dois limites. O Downshift trata um modelo fixado como escolha explícita e não mexe nele, então só roteia subagentes sem modelo fixado. E, com o FORCE ligado, a Anthropic diz que o Claude não consegue passar um modelo, então espero que uma reescrita não prevaleça. Não testei isso.

Como conferir o que rodou

O /tasks mostra o modelo de cada subagente e o esforço, se houver (v2.1.242 em diante). O comando downshift try "<tarefa>" mostra a decisão do Downshift antes de um spawn, e downshift session --tree lista os subagentes da sessão com o custo, no Claude Code.

Como fica uma escolha por tarefa

Saídas reais do downshift try, capturadas em 2026-10-19, com claude-opus-5-5 como modelo atual. As tarefas aparecem como foram digitadas, duas delas em português. A diferença é uma estimativa a preço de tabela para uma chamada entre dois modelos, não uma economia de sessão ou de mês. Held significa que o modelo pedido continua rodando.

Tarefa	Tier	Troca de modelo	Diferença estimada	Resultado	Motivo
renomeie a variável userId para accountId	small	opus -> haiku	~75% cheaper (est.)	Rewritten	trivial task, no risk, confident
refactor the checkout module	mid	opus -> sonnet	~50% cheaper (est.)	Rewritten	medium task, no risk, confident
migre o webhook de pagamento para o novo esquema de autenticação	frontier	stays on opus	none	Stays on frontier	complex task, touches a risk area, confident

O webhook de pagamento fica no opus porque toca uma área de risco. As outras duas descem um ou dois níveis.

Fonte: downshift try output, captured 2026-10-19 (reproduce with the command shown)

Perguntas frequentes

O model: haiku do frontmatter vence o CLAUDE_CODE_SUBAGENT_MODEL?

Desde a v2.1.251, sim, a menos que CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1 esteja definido. Antes dessa versão, a variável de ambiente vencia.

O Downshift sobrescreve um modelo que fixei no arquivo do agente?

Não. Um modelo fixado é uma escolha explícita, e model: inherit se comporta como ausência de modelo. Omita o campo se quiser roteamento por tarefa.

Por que o meu subagente ainda roda no Opus?

Confira, nesta ordem: o campo model, a variável e o FORCE, e se o agente é um embutido como o Explore. Se tudo estiver limpo e ele ainda seguir a sessão, a issue 43869 mostra que você não está sozinho.

Instalar

Rode downshift setup --dry-run antes para ver cada alteração. downshift setup --undo restaura os backups.

curl -fsSL https://raw.githubusercontent.com/tiagovilasboas/downshift/main/install.sh | sh && downshift setup

Plugin do Claude Code

/plugin install downshift --marketplace tiagovilasboas/downshift

Comece com o Downshift GitHub

Guias relacionados

Fontes

Anthropic docsmedido
code.claude.com/docs/en/sub-agents
ordem de resolução, FORCE, agentes embutidos, esforço; os últimos 11.177 caracteres da página não foram lidos (fetched 2026-10-19)
Anthropic docsmedido
code.claude.com/docs/en/costs
model: haiku para subagentes simples (fetched 2026-10-19)
GitHub issuesmedido
github.com/anthropics/claude-code/issues/43869
aberta em 2026-10-19; relato de usuário, causa não estabelecida
GitHub issuesmedido
github.com/anthropics/claude-code/issues/100082
aberta em 2026-10-19; relato de usuário, causa não estabelecida
Downshift repomedido
docs/guides/subagents.md
subagente só é roteável sem modelo fixado
Downshift repomedido
docs/evidence/claude-code-rewrite-honored-2026-10-06.md
reescrita observada, uma sessão, dois spawns
horadecodar.com.brnão verificado
artigo sobre Haiku em subagentes
Downshift CLI outputmedido
downshift try and downshift dci output, captured 2026-10-19 (reproduce with the commands shown)
decisões de roteamento