Criar subagentes personalizados

Crie e use subagentes de IA especializados no Claude Code para fluxos de trabalho específicos de tarefas e gerenciamento de contexto aprimorado.

Subagentes são assistentes de IA especializados que lidam com tipos específicos de tarefas. Use um quando uma tarefa secundária inundaria sua conversa principal com resultados de pesquisa, logs ou conteúdos de arquivo que você não referenciará novamente: o subagente faz esse trabalho em seu próprio contexto e retorna apenas o resumo. Defina um subagente personalizado quando você continua gerando o mesmo tipo de worker com as mesmas instruções.

Cada subagente é executado em sua própria janela de contexto com um prompt de sistema personalizado, acesso a ferramentas específicas e permissões independentes. Ele também envia suas próprias solicitações, que contam para os mesmos limites de uso que sua conversa principal. Quando Claude encontra uma tarefa que corresponde à descrição de um subagente, ele delega para esse subagente, que funciona independentemente e retorna resultados. Para ver a economia de contexto na prática, a visualização da janela de contexto apresenta uma sessão onde um subagente lida com pesquisa em sua própria janela separada.

[!NOTE]

Subagentes funcionam dentro de uma única sessão. Para executar muitas sessões independentes em paralelo e monitorá-las de um único lugar, consulte agentes em segundo plano. Para sessões separadas que passam mensagens uma para a outra, consulte mensagens entre sessões. Para uma equipe coordenada de sessões que Claude gera e supervisiona, consulte equipes de agentes.

Subagentes ajudam você a:

• Preservar contexto mantendo exploração e implementação fora de sua conversa principal
• Aplicar restrições limitando quais ferramentas um subagente pode usar
• Reutilizar configurações entre projetos com subagentes no nível do usuário
• Especializar comportamento com prompts de sistema focados para domínios específicos
• Controlar custos roteando tarefas para modelos mais rápidos e baratos como Haiku

Claude usa a descrição de cada subagente para decidir quando delegar tarefas. Quando você cria um subagente, escreva uma descrição clara para que Claude saiba quando usá-lo.

Essas descrições ocupam contexto, então mantenha-as breves. Quando as descrições combinadas de seus subagentes, exceto os integrados, excedem 15.000 tokens, Claude Code mostra um aviso na inicialização com a contagem total de tokens. Reduza os campos description de seus subagentes e mova detalhes para o prompt de sistema de cada subagente, que é carregado apenas quando esse subagente é executado.

Subagentes integrados

Claude Code inclui subagentes integrados que Claude usa automaticamente quando apropriado. Cada um herda as permissões da conversa pai; a maioria é executada com um conjunto de ferramentas restrito.

Explore e Plan iniciam sem seus arquivos CLAUDE.md e sem o snapshot de status git para manter a pesquisa rápida e econômica. Outros subagentes integrados e subagentes personalizados carregam ambos, a menos que você defina omitClaudeMd na definição de um subagente personalizado para iniciá-lo sem os arquivos CLAUDE.md do usuário, do projeto e locais. Para o detalhamento completo do que chega a um subagente, consulte o que é carregado na inicialização.

[tab] Explore

Um agente rápido e somente leitura otimizado para pesquisar e analisar bases de código.

• Model: o modelo da conversa principal. Quando a conversa principal executa Fable, o modelo do Explore depende de como você se conecta:
  • Com uma assinatura Claude, uma conta do Anthropic Console ou um gateway de LLM acessado por meio de ANTHROPIC_BASE_URL, Explore é executado no modelo Opus para o qual o alias opus é resolvido.
  • No Amazon Bedrock, no Google Cloud's Agent Platform, no Microsoft Foundry, na Claude Platform on AWS ou em um gateway de Claude apps, Explore permanece no modelo da conversa principal.
• Tools: ferramentas somente leitura; Write e Edit são negados
• Purpose: descoberta de arquivos, pesquisa de código, exploração de base de código

Um subagente de usuário ou projeto nomeado Explore sobrescreve o integrado e mantém seu próprio campo model, portanto defina um com model: haiku para executar a exploração em um modelo de menor custo. Para forçar um único modelo em todos os subagentes, incluindo o Explore, consulte Execute cada subagente em um modelo.

Claude delega para Explore quando precisa pesquisar ou entender uma base de código sem fazer alterações. Isso mantém os resultados da exploração fora do contexto da sua conversa principal.

Ao invocar Explore, Claude especifica um nível de minuciosidade: quick para buscas direcionadas, medium para exploração equilibrada, ou very thorough para análise abrangente.

[tab] Plan

Um agente de pesquisa usado durante plan mode para reunir contexto antes de apresentar um plano.

• Model: herda da conversa principal, a menos que você defina CLAUDE_CODE_SUBAGENT_MODEL e force-o em cada subagente
• Tools: ferramentas somente leitura; Write e Edit são negados
• Purpose: pesquisa de base de código para planejamento

Quando você está em plan mode e Claude precisa entender sua base de código, ele delega a pesquisa para o subagente Plan para que a saída de exploração permaneça em uma janela de contexto separada enquanto a conversa principal permanece somente leitura.

[tab] General-purpose

Um agente capaz para tarefas complexas e multi-etapas que requerem exploração e ação.

• Model: o modelo CLAUDE_CODE_SUBAGENT_MODEL se você definir um e nada atribuir um modelo de outra forma, caso contrário o modelo da conversa principal; Escolha um modelo declara a ordem completa, e Execute cada subagente em um modelo mostra como fazer a variável substituir essas fontes
• Tools: todas as ferramentas disponíveis para subagentes
• Purpose: pesquisa complexa, operações multi-etapas, modificações de código

Claude delega para general-purpose quando a tarefa requer exploração e modificação, raciocínio complexo para interpretar resultados, ou múltiplas etapas dependentes.

[tab] Other

Claude Code inclui agentes auxiliares adicionais para tarefas específicas. Estes são normalmente invocados automaticamente, então você não precisa usá-los diretamente.

Agent	Model	When Claude uses it
claude	Nenhum próprio; segue a ordem de modelo quando Claude o gera como um subagente	Quando uma tarefa não se encaixa em um agente mais especializado. Um catch-all com todas as ferramentas disponíveis para subagentes. Também o agente padrão para uma sessão em background despachada; qual modo de permissão ele inicia depende de como a sessão foi iniciada
statusline-setup	Sonnet	Quando você executa /statusline para configurar sua linha de status
claude-code-guide	Haiku	Quando você faz perguntas sobre recursos do Claude Code

Os subagentes integrados são registrados por padrão em sessões interativas. Para restringi-los:

• Para bloquear um tipo integrado específico, adicione-o a permissions.deny conforme mostrado em Desabilitar subagentes específicos.
• Para impedir que Claude delegue a qualquer subagente, negue a ferramenta Agent em si com permissions.deny.
• Para remover apenas os subagentes integrados Explore e Plan, defina CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude lê e explora arquivos diretamente em vez de delegar para eles. Requer Claude Code v2.1.198 ou posterior.
• Em modo não interativo e no Agent SDK, defina CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 para remover todos os tipos integrados e fornecer apenas os seus próprios.

Uma chamada de ferramenta Agent que omite subagent_type falha com subagent_type is required quando a sessão não tem nenhum subagente general-purpose para recorrer.

Além desses subagentes integrados, você pode criar os seus próprios com prompts personalizados, restrições de ferramentas, modos de permissão, hooks e skills. As seções a seguir mostram como começar e personalizar subagentes.

Quickstart: criar seu primeiro subagente

Subagentes são arquivos Markdown com frontmatter YAML. Para criar um, peça ao Claude para escrevê-lo para você, ou escreva o arquivo você mesmo.

Este passo a passo cria um subagente no nível do usuário que revisa código e sugere melhorias.

1. Peça ao Claude para criar o subagente

No Claude Code, descreva o subagente que você deseja e onde salvá-lo:

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

Claude escreve o arquivo com um name, uma description, uma lista de tools, um model e um system prompt.

2. Revise o arquivo

Abra ~/.claude/agents/code-improver.md e confirme que o frontmatter corresponde ao que você pediu. O resultado se parece com isto:

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Como o arquivo está em ~/.claude/agents/, o subagente está disponível em todos os projetos em sua máquina. Para limitá-lo a um projeto, mova-o para o diretório .claude/agents/ desse projeto. Escolha o escopo do subagente compara os dois.

3. Teste-o

Peça ao Claude para delegar para o novo subagente:

Use the code-improver agent to suggest improvements in this project

Claude delega para seu novo subagente, que verifica a base de código e retorna sugestões de melhoria. Na transcrição, a delegação aparece como uma linha de chamada de ferramenta mostrando o nome do subagente seguido por uma breve descrição de tarefa, como code-improver(Suggest code improvements).

Se Claude não conseguir encontrar o novo subagente, reinicie o Claude Code e tente novamente. Isso acontece apenas quando ~/.claude/agents/ não existia antes da sessão começar, porque uma sessão em execução não detecta um diretório agents recém-criado.

Agora você tem um subagente que pode usar em qualquer projeto em sua máquina para analisar bases de código e sugerir melhorias.

Você também pode escrever arquivos de subagente manualmente, defini-los via flags CLI ou distribuí-los através de plugins. As seções a seguir cobrem todas as opções de configuração.

[!NOTE]

Executar /agents imprime um lembrete para pedir ao Claude ou editar .claude/agents/ e ~/.claude/agents/ diretamente. No Claude Code v2.1.197 e anterior, /agents abre um assistente interativo com uma aba Running que lista subagentes ativos e uma aba Library para criá-los, editá-los e deletá-los.

Configurar subagentes

O local do arquivo de um subagente determina para quem ele está disponível, e o seu frontmatter determina o que ele pode fazer. Esta seção aborda onde os arquivos de subagentes ficam e todos os campos que eles suportam.

Escolher o escopo do subagente

Armazene os arquivos de subagentes em locais diferentes dependendo do escopo. Quando vários subagentes compartilham o mesmo nome, o Claude Code usa aquele do local de maior prioridade.

Subagentes de projeto (.claude/agents/) são ideais para subagentes específicos de uma base de código. Faça commit deles no controle de versão para que sua equipe possa usá-los e aprimorá-los de forma colaborativa.

Os subagentes de projeto são descobertos subindo a partir do diretório de trabalho atual, de modo que cada .claude/agents/ entre ele e a raiz do repositório é verificado. Quando mais de um desses diretórios aninhados define o mesmo name, o Claude Code usa a definição mais próxima do diretório de trabalho.

Quando você adiciona um diretório com --add-dir ou /add-dir, o Claude Code também carrega a pasta .claude/agents/ dele, junto com os seus subagentes de projeto. Consulte Diretórios adicionais para saber quais outros tipos de configuração são carregados a partir de --add-dir. Para compartilhar subagentes entre projetos sem --add-dir, use ~/.claude/agents/ ou um plugin.

Subagentes de usuário (~/.claude/agents/) são subagentes pessoais disponíveis em todos os seus projetos.

O Claude Code verifica .claude/agents/ e ~/.claude/agents/ recursivamente, então você pode organizar as definições em subpastas como agents/review/ ou agents/research/. O caminho do subdiretório não afeta como um subagente é identificado ou invocado, porque a identidade vem apenas do campo name do frontmatter.

Mantenha os valores de name únicos em toda a árvore: se dois arquivos sob o mesmo diretório .claude/agents/, incluindo suas subpastas, declararem o mesmo nome, o Claude Code carrega apenas um deles, escolhido pela ordem de leitura do sistema de arquivos, e não por uma precedência documentada. Entre diretórios de projeto aninhados, a definição mais próxima do diretório de trabalho prevalece, conforme descrito acima. A verificação de configuração /doctor informa arquivos no mesmo diretório que compartilham um nome e propõe renomear ou remover todos, exceto um.

Os diretórios agents/ de plugins também são verificados recursivamente. Diferentemente dos escopos de projeto e de usuário, uma subpasta dentro do diretório agents/ de um plugin passa a fazer parte do identificador com escopo: um arquivo em agents/review/security.md no plugin my-plugin é registrado como my-plugin:review:security.

Subagentes definidos via CLI são passados como JSON ao iniciar o Claude Code. Eles existem apenas naquela sessão e não são salvos em disco, o que os torna úteis para testes rápidos ou scripts de automação. Você pode definir vários subagentes em uma única chamada --agents:

[tab] macOS, Linux, WSL

claude --agents '{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}'

[tab] Windows PowerShell

claude --agents @'
{
  "code-reviewer": {
    "description": "Expert code reviewer. Use proactively after code changes.",
    "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
    "tools": ["Read", "Grep", "Glob", "Bash"],
    "model": "sonnet"
  },
  "debugger": {
    "description": "Debugging specialist for errors and test failures.",
    "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
  }
}
'@

No modo não interativo, --agents também aceita o caminho para um arquivo JSON contendo o mesmo objeto, para definições grandes demais para passar na linha de comando. Por exemplo, claude -p --agents ./agents.json "Review my changes" lê as definições desse arquivo. Em uma sessão interativa, o Claude Code recusa um caminho de arquivo. O formato de arquivo requer o Claude Code v2.1.281 ou posterior.

Cada chave de nível superior no JSON é o nome de um agente, e seu valor é a definição desse agente. Não comece um nome com -. Uma definição aceita estes campos:

• prompt: o system prompt do agente, equivalente ao corpo em markdown nos subagentes baseados em arquivo. prompt pode estar vazio. Se você selecionar um agente com prompt vazio e sem campo memory como o agente da sessão com --agent, o system prompt da sessão permanece inalterado. Um prompt vazio requer o Claude Code v2.1.281 ou posterior.
• Campos do frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd e isolation.
• Campos ignorados: color e experimental não são aceitos aqui e são ignorados em vez de rejeitados.

Para saber o que o Claude Code faz com um valor que não consegue carregar, e as flags e a variável de ambiente que ignoram essa verificação, consulte Invalid --agents configuration.

Subagentes gerenciados são implantados por administradores da organização. Coloque arquivos markdown em .claude/agents/ dentro do diretório de configurações gerenciadas, usando o mesmo formato de frontmatter dos subagentes de projeto e de usuário. As definições gerenciadas têm precedência sobre subagentes de projeto e de usuário com o mesmo nome.

Subagentes de plugin vêm de plugins que você instalou. Eles são carregados automaticamente junto com seus subagentes personalizados e aparecem no preenchimento automático de @-menção sob seu nome com escopo. Consulte a referência de componentes de plugin para detalhes sobre como criar subagentes de plugin.

[!NOTE]

Por motivos de segurança, subagentes de plugin não suportam os campos de frontmatter hooks, mcpServers ou permissionMode. Esses campos são ignorados ao carregar agentes de um plugin. Se você precisar deles, copie o arquivo do agente para .claude/agents/ ou ~/.claude/agents/. Você também pode adicionar regras a permissions.allow em settings.json ou settings.local.json, mas essas regras se aplicam à sessão inteira, não apenas ao subagente do plugin.

Se você é o autor do plugin, distribua os hooks no hooks/hooks.json do plugin e os servidores MCP no seu .mcp.json. Eles se aplicam sempre que o plugin está habilitado, e não apenas dentro do subagente.

Você também pode reutilizar uma definição de subagente como colega de uma equipe de agentes: nomeie o tipo de subagente quando pedir ao Claude para criar o colega, e o Claude Code aplica partes dessa definição a ele. Usar definições de subagentes para colegas informa quais escopos e quais partes se aplicam em cada modo de exibição.

Escrever arquivos de subagentes

Os arquivos de subagentes usam frontmatter YAML para configuração, seguido pelo system prompt em Markdown:

[!NOTE]

O Claude Code monitora ~/.claude/agents/ e .claude/agents/. Quando você adiciona ou edita um arquivo de subagente em disco, ou pede ao Claude para escrever um para você, o Claude Code detecta a alteração em poucos segundos e a próxima delegação usa a definição atualizada, sem necessidade de reiniciar.

Três casos ainda exigem reinicialização:

• O monitoramento cobre apenas diretórios que existiam quando a sessão começou, portanto, após criar o primeiro arquivo de agente de um escopo em um novo diretório agents, reinicie para carregá-lo.
• O Claude Code não monitora .claude/agents/ dentro de diretórios adicionados com --add-dir ou /add-dir, portanto, após adicionar ou editar um subagente ali, reinicie para carregar a alteração.
• Sessões iniciadas com --disable-slash-commands não monitoram esses diretórios de forma alguma.

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

O frontmatter define os metadados e a configuração do subagente. O corpo se torna o system prompt que orienta o comportamento do subagente. Os subagentes recebem apenas esse system prompt mais detalhes básicos do ambiente, como o diretório de trabalho, e não o system prompt do Claude Code.

No modo não interativo, passe --append-subagent-system-prompt para acrescentar seu texto ao final do system prompt de cada subagente, incluindo subagentes aninhados, exceto um subagente bifurcado, que reutiliza o próprio prompt da conversa. Requer o Claude Code v2.1.205 ou posterior. Se o seu texto for longo demais para passar na linha de comando, salve-o em um arquivo e passe o caminho com --append-subagent-system-prompt-file. A flag de arquivo requer o Claude Code v2.1.261 ou posterior.

Um subagente começa no diretório de trabalho atual da conversa principal. Dentro de um subagente, comandos cd não persistem entre chamadas das ferramentas Bash ou PowerShell e não afetam o diretório de trabalho da conversa principal. Para dar ao subagente uma cópia isolada do repositório, defina isolation: worktree.

Um subagente com isolation: worktree executa seus comandos Bash e PowerShell dentro do seu worktree. Um comando cujo diretório de trabalho resolve para o seu checkout principal, por exemplo porque o diretório do worktree foi removido enquanto o subagente estava em execução, falha com um erro.

Essa verificação de diretório de trabalho abrange todo o repositório que contém o diretório a partir do qual você iniciou o Claude Code. Quando sua sessão é executada em um worktree vinculado próprio, a verificação também abrange o checkout principal ao qual esse worktree está vinculado.

Para comandos Bash, o Claude Code também verifica o próprio comando de duas maneiras:

• Ele bloqueia um comando que redireciona o git para o checkout principal.
• Ele recusa um comando quando não consegue verificar, a partir do texto do comando, que qualquer git executado pelo comando permanece dentro do worktree, por exemplo quando o nome do comando é calculado em tempo de execução.

Os vetores de redirecionamento e as regras de formato estão listados em Como o Claude Code aplica o isolamento. Comandos PowerShell recebem apenas a verificação de diretório de trabalho.

Comandos do Monitor passam pelas mesmas verificações de diretório de trabalho e de conteúdo do comando que os comandos Bash.

Quando a própria conversa principal é executada isolada em um worktree, o Claude Code aplica as mesmas verificações à sessão e a cada subagente que ela cria, incluindo subagentes sem isolation: worktree; consulte Como o Claude Code aplica o isolamento.

Referência do frontmatter

Configure um subagente com frontmatter YAML entre marcadores --- no topo do arquivo e escreva seu system prompt em Markdown após o --- de fechamento. Apenas name e description são obrigatórios.

Nomes de campos com várias palavras usam camelCase, como maxTurns e disallowedTools, e devem corresponder exatamente à tabela: o Claude Code ignora um campo que não reconhece sem relatar um erro.

• Para encontrar um campo com erro de digitação em um subagente que foi carregado, execute claude --debug no seu shell e pesquise does not recognize or apply no log de depuração em ~/.claude/debug/<session-id>.txt. O log de depuração nomeia até cinco campos de nível superior no arquivo do subagente que o Claude Code não reconhece, com o nome provavelmente pretendido quando um campo suportado é semelhante. Requer o Claude Code v2.1.296 ou posterior.
• Para descobrir por que um arquivo de subagente não foi carregado, consulte Arquivos de subagentes que o Claude Code ignora.

Escreva cacheTtl dentro do mapa experimental, não no nível superior do frontmatter.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Arquivos de subagentes que o Claude Code ignora

O Claude Code ignora um arquivo em um diretório agents de projeto, de usuário ou gerenciado, ou em um sob um diretório que você adiciona com --add-dir, sem relatá-lo na sessão, quando o frontmatter tem algum destes problemas:

• Sem name: o Claude Code trata o arquivo como documentação mantida ao lado dos seus agentes.
• Um --- de abertura que não está na primeira linha do arquivo: o Claude Code lê o arquivo como se não tivesse frontmatter e o trata como documentação.
• Um name que começa com -, contém : ou tem mais de 256 caracteres: o Claude Code ignora o arquivo e grava um erro no log de depuração.
• Um name mas sem description: o Claude Code ignora o arquivo e grava o motivo no log de depuração.
• YAML que não pode ser analisado: o Claude Code não lê nenhum campo do arquivo, ignora-o e grava o erro de análise no log de depuração.

Para ver o log de depuração, execute o Claude Code com --debug.

Um subagente de plugin cujo frontmatter não tem name ou não pode ser analisado ainda é carregado, sob o nome do seu arquivo.

Verificar um diretório agents antes de uma sessão

Para encontrar arquivos em um diretório agents cujo frontmatter não pode ser analisado, execute claude plugin validate no diretório, por exemplo .claude/agents ou ~/.claude/agents. O Claude Code verifica apenas o diretório que você nomeia e não sinaliza um arquivo cujo frontmatter é analisado, mas não tem name. Requer o Claude Code v2.1.233 ou posterior.

Escolher um modelo

O campo model controla qual modelo o subagente usa:

• Alias de modelo: use um dos aliases disponíveis: sonnet, opus, haiku ou fable
• ID de modelo completo: use um ID de modelo completo como claude-opus-5-5 ou claude-sonnet-5. Aceita os mesmos valores que a flag --model
• inherit: use o mesmo modelo da conversa principal

Quando o Claude invoca um subagente, ele também pode passar um parâmetro model para aquela invocação específica. Em uma chamada da ferramenta Agent, esse parâmetro aceita um alias de modelo: sonnet, opus, haiku ou fable. O Claude não pode passar um ID de modelo completo nem inherit nessa chamada. O Claude Code resolve o modelo do subagente nesta ordem:

1. O parâmetro model por invocação
2. O frontmatter model da definição do subagente, em que inherit seleciona o modelo da conversa principal
3. A variável de ambiente CLAUDE_CODE_SUBAGENT_MODEL, quando você a define como um alias de modelo ou ID de modelo
4. O modelo da conversa principal

Se um mod instalado definir um modelo no seu hook agent.spawn, o Claude Code usa esse modelo no lugar do parâmetro por invocação.

Em dois casos, um alias de família como opus no parâmetro por invocação ou no frontmatter resolve para o modelo da conversa principal em vez da versão para a qual o alias aponta:

• O modelo da conversa principal pertence a essa família: o subagente é executado no modelo exato da conversa principal, incluindo qualquer sufixo [1m], de modo que recebe a mesma janela de contexto estendido da conversa principal.
• O Claude Code não consegue identificar a família do modelo da conversa principal, em um provedor diferente da API da Anthropic: isso pode acontecer com um ARN de perfil de inferência de aplicação no Amazon Bedrock que o Claude Code não resolveu para um modelo subjacente. Este caso abrange apenas o alias opus e não se aplica quando você define ANTHROPIC_DEFAULT_OPUS_MODEL, pois opus então resolve para o modelo que você definiu.

Um alias em CLAUDE_CODE_SUBAGENT_MODEL sempre resolve para a versão para a qual o alias aponta, mesmo quando nomeia a família da conversa principal. Definir a variável como inherit é o mesmo que deixá-la sem definição.

Definir CLAUDE_CODE_SUBAGENT_MODEL sozinha não altera o modelo em que os subagentes integrados Explore e Plan são executados. Para alterá-lo, consulte Executar todos os subagentes em um único modelo.

Antes da v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL vinha primeiro nesta ordem e sobrescrevia tanto o parâmetro por invocação quanto o frontmatter, incluindo model: inherit.

O Claude Code verifica os valores do parâmetro por invocação, do frontmatter e da variável de ambiente em relação à allowlist availableModels da sua organização. Para um valor bloqueado, ele substitui por outro modelo:

• Quando o valor bloqueado é um alias de família como opus, o Claude Code executa o subagente na versão mais recente dessa família que a allowlist permite, seguindo as mesmas regras de substituição e escopo de provedor que o /model. Antes da v2.1.222, o Claude Code também executava o subagente no modelo herdado para um alias de família bloqueado.
• Para qualquer outro valor bloqueado, em provedores onde essa substituição não opera, ou quando a allowlist não permite nenhuma versão da família, o Claude Code executa o subagente no modelo herdado. Se você definir CLAUDE_CODE_SUBAGENT_MODEL, o Claude Code tenta esse modelo primeiro, sob essas mesmas regras.

Em sessões interativas, o Claude Code mostra um aviso nomeando o modelo solicitado e o modelo em que o subagente é executado, para qualquer uma das substituições.

Para verificar em qual modelo um subagente está sendo executado, execute /tasks. O Claude Code nomeia o modelo na linha do subagente e adiciona o nível de esforço definido para esse subagente, se houver. Requer o Claude Code v2.1.242 ou posterior.

Um parâmetro model por invocação também se aplica quando o subagente é retomado ou recebe uma mensagem de acompanhamento, de modo que o subagente permanece nesse modelo.

A partir da v2.1.198, os subagentes também herdam a configuração de pensamento estendido da conversa principal: se o pensamento estiver ativado na sua sessão, ele estará ativado para o subagente e, se estiver desativado, permanecerá desativado. Não há configuração de pensamento por subagente. Antes da v2.1.198, os subagentes eram executados com o pensamento estendido desativado, independentemente da configuração da conversa principal.

Executar todos os subagentes em um único modelo

CLAUDE_CODE_SUBAGENT_MODEL é um padrão, então a definição de um subagente ou um modelo que o Claude passa ainda tem precedência sobre ela. Para aplicar um único modelo a todos os subagentes, colegas e agentes de workflow, defina também CLAUDE_CODE_SUBAGENT_MODEL_FORCE como 1. Requer o Claude Code v2.1.257 ou posterior.

• Se você definir ambas as variáveis, os subagentes são executados no modelo em CLAUDE_CODE_SUBAGENT_MODEL.
• Se você definir apenas CLAUDE_CODE_SUBAGENT_MODEL_FORCE, os subagentes são executados no modelo da conversa principal, exceto que o subagente integrado Explore é executado no modelo listado para ele em Subagentes integrados.

Por exemplo, para executar todos os subagentes no Haiku, defina ambas as variáveis no bloco env de um arquivo de configurações:

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

Para verificar se a configuração entrou em vigor, execute /tasks enquanto um subagente estiver em execução. A linha do subagente mostra o modelo em que ele é executado.

Enquanto CLAUDE_CODE_SUBAGENT_MODEL_FORCE estiver ativada, o Claude Code ignora o campo model nas definições de subagentes, e o Claude não pode passar um modelo ao iniciar um subagente. Estes subagentes ainda são executados no modelo da conversa principal:

• Um fork
• Uma skill executada em um subagente com model: inherit

Escolher um nível de esforço

Para executar um subagente em seu próprio nível de esforço, defina o campo effort na sua definição.

Quando você pede ao Claude para executar um subagente que não seja um fork em um nível de esforço específico, ele também pode passar um parâmetro effort para essa invocação. O parâmetro sobrescreve o campo effort e permanece em vigor quando o subagente é retomado. A variável de ambiente CLAUDE_CODE_EFFORT_LEVEL tem precedência sobre ambos. O parâmetro por invocação requer o Claude Code v2.1.292 ou posterior.

Controlar as capacidades dos subagentes

Você pode controlar o que os subagentes podem fazer por meio do acesso a ferramentas, dos modos de permissão e de regras condicionais.

Ferramentas disponíveis

Os subagentes herdam as ferramentas integradas e as ferramentas MCP disponíveis na conversa principal, reduzidas por dois filtros: o primeiro remove uma pequena lista de ferramentas de todos os subagentes, e o segundo reduz o conjunto de ferramentas integradas para subagentes executados em segundo plano, que é o padrão. No macOS, Linux e WSL, um subagente também pode receber as ferramentas Glob e Grep quando a conversa principal não as tem, conforme descrito em Comportamento da ferramenta Glob. Os forks ignoram ambos os filtros e recebem exatamente o conjunto de ferramentas da conversa principal. O primeiro filtro remove estas ferramentas, mesmo quando listadas no campo tools:

• Agent, quando o subagente está no limite de profundidade; em um fork, a ferramenta permanece listada, mas retorna um erro em vez de criar um subagente
• AskUserQuestion
• EndConversation, que só pode encerrar a conversa principal; consulte Comportamento da ferramenta EndConversation
• EnterPlanMode
• ExitPlanMode, a menos que o permissionMode do subagente seja plan
• ScheduleWakeup
• WaitForMcpServers
• Workflow

O segundo filtro se aplica a subagentes executados em segundo plano. Exceto Agent e ExitPlanMode, que seguem as condições do primeiro filtro onde quer que o subagente seja executado, um subagente em segundo plano mantém todas as ferramentas MCP, mas apenas estas ferramentas integradas: Read, Grep, Glob, LSP, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage e Artifact, além de SubagentHandback para um subagente que faz seus relatos por meio dela. O Claude Code remove todas as outras ferramentas integradas de um subagente em segundo plano, sejam herdadas ou listadas no campo tools, de modo que a mesma definição pode resolver para ferramentas diferentes em primeiro plano e em segundo plano. A remoção não relata nenhum erro, a menos que deixe a lista tools resolvendo para nada.

Antes da v2.1.280, os subagentes em segundo plano não podiam usar LSP.

ListAgents segue esses filtros como qualquer ferramenta integrada: um subagente em primeiro plano a herda em sessões onde a troca de mensagens entre sessões está habilitada, e um subagente em segundo plano não a mantém.

Os colegas em equipes de agentes mantêm adicionalmente as ferramentas de tarefas e de cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete e CronList. Em uma sessão sem as ferramentas Task, o Claude Code também não fornece as ferramentas de tarefas aos subagentes, mesmo quando o subagente executa um modelo diferente. Um colega em processo segue a sua sessão da mesma forma. Para descobrir se um colega em painel dividido tem as ferramentas de tarefas, consulte Disponibilidade da ferramenta Task.

Restringir quais ferramentas um subagente pode usar

Para restringir ferramentas, use o campo tools como allowlist ou o campo disallowedTools como denylist. Se ambos estiverem definidos, disallowedTools é aplicado primeiro e, em seguida, tools é resolvido em relação ao conjunto restante. Uma ferramenta listada em ambos é removida.

Este exemplo usa tools para permitir apenas Read, Grep, Glob e Bash. O subagente não pode editar arquivos, escrever arquivos nem usar ferramentas MCP:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Este exemplo usa disallowedTools para herdar o conjunto de ferramentas do subagente, exceto Write e Edit. O subagente mantém Bash, as ferramentas MCP e o restante do seu conjunto:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Quando nada na lista tools resolve para uma ferramenta, por exemplo porque todas as entradas estão com erro de digitação ou nomeiam uma ferramenta que não está disponível para subagentes, o Claude Code geralmente se recusa a iniciar o subagente e a ferramenta Agent retorna um erro nomeando as entradas não resolvidas; consulte Agent would be spawned with zero tools para ver a mensagem e como corrigir cada entrada.

Os campos tools e disallowedTools também aceitam entradas para um servidor MCP inteiro:

Este exemplo remove todas as ferramentas do servidor MCP github, mantendo as ferramentas de outros servidores e as ferramentas integradas no conjunto do subagente:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Uma entrada de disallowedTools com especificador, como Bash(git push *), ainda remove a ferramenta inteira do subagente, e não apenas os comandos correspondentes. Para manter o Bash e bloquear comandos específicos, adicione uma regra de negação do Bash, como Bash(git push *), a permissions.deny nas suas configurações. A regra se aplica à conversa principal e aos subagentes.

Nomes de servidores MCP que contêm um sublinhado duplo

Se um subagente não recebe nenhuma das ferramentas de um servidor MCP cujo nome contém __, como reports__v2, verifique as entradas mcp__ do subagente:

• Em tools: escreva mcp__ seguido do nome completo do servidor e __*, como em mcp__reports__v2__*. Sem o __* final, mcp__reports__v2 não corresponde a nenhuma das ferramentas desse servidor.
• Em disallowedTools: procure mcp__reports ou mcp__reports__*, as entradas que retêm um servidor chamado reports. Com qualquer uma dessas entradas, o subagente também perde todas as ferramentas de reports__v2, porque esses nomes de ferramentas também começam com mcp__reports__. Para reter apenas as ferramentas do servidor reports, liste-as uma a uma, como mcp__reports__run_query.

Restringir quais subagentes podem ser criados

Quando um agente é executado como thread principal com claude --agent, ele pode criar subagentes usando a ferramenta Agent. Para restringir quais tipos de subagentes ele pode criar, use a sintaxe Agent(agent_type) no campo tools.

[!NOTE]

Na versão 2.1.63, a ferramenta Task foi renomeada para Agent. As referências Task(...) existentes em configurações e definições de agentes ainda funcionam como aliases.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Isto é uma allowlist: apenas os subagentes worker e researcher podem ser criados. Se o agente tentar criar qualquer outro tipo, a requisição falha e o agente vê apenas os tipos permitidos no seu prompt. Para bloquear agentes específicos enquanto permite todos os outros, use permissions.deny.

Para permitir a criação de qualquer subagente sem restrições, use Agent sem parênteses:

tools: Agent, Read, Bash

Se você omitir Agent totalmente da lista tools, o agente não poderá criar nenhum subagente com a ferramenta Agent.

A sintaxe de allowlist Agent(agent_type) se aplica apenas a um agente executado como thread principal com claude --agent. Em uma definição de subagente, listar Agent em tools permite que esse subagente crie seus próprios subagentes enquanto o limite de profundidade permitir, mas qualquer lista de tipos dentro dos parênteses é ignorada.

Restringir servidores MCP a um subagente

Use o campo mcpServers para dar a um subagente acesso a servidores MCP que não estão disponíveis na conversa principal. Os servidores inline definidos aqui são conectados quando o subagente é iniciado, sujeitos à regra de confiança para a pasta do arquivo do agente, e desconectados quando ele termina. As referências por string compartilham a conexão da sessão pai.

[!NOTE]

O campo mcpServers se aplica em ambos os contextos em que um arquivo de agente pode ser executado:

• Como subagente, criado por meio da ferramenta Agent ou de uma @-menção
• Como sessão principal, iniciada com --agent ou a configuração agent

Quando o agente é a sessão principal, as definições de servidores inline se conectam na inicialização junto com os servidores de .mcp.json e dos arquivos de configurações, sob a mesma regra de confiança para a pasta do arquivo do agente. No /mcp, um servidor remoto (HTTP ou SSE) que você já usou pode mostrar o status cached; o Claude Code o conecta quando o Claude chama uma de suas ferramentas pela primeira vez.

Cada entrada na lista é uma definição de servidor inline ou uma string que referencia um servidor MCP já configurado na sua sessão:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

As definições inline usam o mesmo esquema das entradas de servidor do .mcp.json, indexadas pelo nome do servidor, e suportam os tipos stdio, http, sse e ws.

Para manter um servidor MCP totalmente fora da conversa principal e evitar que as descrições de suas ferramentas consumam contexto ali, defina-o inline aqui em vez de no .mcp.json. O subagente recebe as ferramentas; a conversa pai não.

As restrições de MCP que se aplicam à sessão principal também abrangem os servidores declarados no frontmatter do subagente:

• --strict-mcp-config e --bare
• Configuração de MCP gerenciada corporativa
• Políticas allowedMcpServers e deniedMcpServers

Quando uma delas bloqueia um servidor, o Claude Code o ignora e mostra um aviso nomeando os servidores bloqueados.

As restrições das configurações gerenciadas se aplicam a todos os subagentes, independentemente de como são definidos. --strict-mcp-config não filtra servidores que você passa inline via --agents ou a opção agents do SDK, pois essas são entradas explícitas de quem faz a chamada.

Confiança exigida para servidores MCP inline

O Claude Code carrega um servidor MCP inline de um arquivo de agente no diretório .claude/agents/ do seu projeto, ou no .claude/agents/ de um diretório --add-dir, somente depois que você confia na pasta de onde o arquivo do agente veio. Antes da v2.1.238, o Claude Code carregava esses servidores sem verificar a confiança.

• Confiança que não conta: a confiança de uma pasta pai e a confiança automática que uma sessão -p ou do SDK recebe para hooks em arquivos de configurações
• Até então: o Claude Code ignora todos os servidores inline nesse arquivo de agente e grava a chave exata projects["<path>"].hasTrustDialogAccepted para ~/.claude.json no log de depuração
• Diretórios --add-dir: um diretório fora do repositório do seu workspace confiável precisa de sua própria entrada de confiança, pois seus arquivos .claude/agents/ não herdam a confiança do seu workspace

O Claude Code carrega dois tipos de servidor sem verificar a confiança da pasta de onde o arquivo do agente veio:

• Um nome que referencia um servidor que você já configurou
• Um servidor inline em um arquivo de agente de ~/.claude/agents/, em um que você passa com --agents ou a opção agents do SDK, ou em um que as configurações gerenciadas fornecem

Modos de permissão

Defina permissionMode para escolher o modo de permissão em que um subagente é executado. Use os valores de configuração dos modos; assim, o modo Manual é default. Se você deixá-lo sem definição, o subagente herda o modo de permissão da conversa principal.

O modo de permissão da conversa principal decide se o Claude Code usa o valor que você definiu:

• Quando a conversa principal está em bypassPermissions, acceptEdits ou no modo auto, o subagente é executado nesse mesmo modo e o Claude Code ignora o permissionMode que você definiu. No modo auto, o classificador avalia as chamadas de ferramenta do subagente com as regras de bloqueio e de permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes que o relatório seja entregue, conforme descrito em Como o modo auto lida com subagentes.
• Quando a conversa principal está no modo plan, o subagente permanece no modo de planejamento independentemente do permissionMode que você definir, a menos que seja executado como colega de uma equipe de agentes sob as regras de equipes de agentes. Se você definir dontAsk, o subagente também não solicita sua confirmação: uma ação que o modo de planejamento pediria para você aprovar é negada.
• Quando a conversa principal está no modo default ou dontAsk, o subagente é executado no modo de permissão que você definiu. Em vez disso, ele mantém o modo de permissão da conversa principal nestes casos:
  • Você define bypassPermissions. A exceção de bypassPermissions requer o Claude Code v2.1.267 ou posterior.
  • Você define auto e o modo auto não está disponível para o subagente, como quando um arquivo de configurações define disableAutoMode ou o modelo do subagente não suporta o modo auto.

permissionMode aceita estes valores, e manual como alias para default:

Pré-carregar skills em subagentes

Use o campo skills para injetar o conteúdo de skills no contexto de um subagente na inicialização. Isso dá ao subagente conhecimento de domínio sem exigir que ele descubra e carregue skills durante a execução.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização, até os primeiros 32 nomes distintos da lista. Este campo controla quais skills são pré-carregadas, e não quais skills o subagente pode acessar: sem ele, o subagente ainda pode descobrir e invocar skills de projeto, de usuário e de plugin por meio da ferramenta Skill durante a execução. Para impedir totalmente que um subagente invoque skills, omita Skill da lista tools ou adicione-a a disallowedTools.

Você não pode pré-carregar skills que definem disable-model-invocation: true, pois o pré-carregamento usa o mesmo conjunto de skills que o Claude pode invocar. Isso inclui a skill integrada /verify, que o Claude não pode executar por conta própria.

Se uma skill listada estiver ausente ou desabilitada, por exemplo pela política da sua organização, o Claude Code a ignora e registra um aviso no log de depuração.

[!NOTE]

Isto é o inverso de executar uma skill em um subagente. Com skills em um subagente, o subagente controla o system prompt e carrega o conteúdo da skill. Com context: fork em uma skill, o conteúdo da skill é injetado no agente que você especificar. Em ambos os casos, o subagente começa sem o histórico da sua conversa.

Habilitar memória persistente

O campo memory dá ao subagente um diretório persistente que sobrevive entre conversas. O subagente usa esse diretório para acumular conhecimento ao longo do tempo, como padrões da base de código, insights de depuração e decisões arquiteturais.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Escolha um escopo com base em quão amplamente a memória deve se aplicar:

A memória do subagente faz parte da memória automática: se você desativar a memória automática, com a configuração autoMemoryEnabled ou CLAUDE_CODE_DISABLE_AUTO_MEMORY, o campo memory não tem efeito e o subagente é iniciado sem as instruções de memória ou o acesso às ferramentas de memória descritos abaixo.

Quando a memória está habilitada:

• O system prompt do subagente inclui instruções para ler e gravar no diretório de memória.
• O system prompt do subagente também inclui as primeiras 200 linhas ou 25KB de MEMORY.md no diretório de memória, o que ocorrer primeiro, com instruções para organizar o MEMORY.md se ele exceder esse limite.
• As ferramentas Read, Write e Edit são habilitadas automaticamente para que o subagente possa gerenciar seus arquivos de memória.

Dicas de memória persistente

• project é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão.

• Peça ao subagente para consultar sua memória antes de começar o trabalho: "Revise este PR e verifique sua memória em busca de padrões que você já viu antes."

• Peça ao subagente para atualizar sua memória após concluir uma tarefa: "Agora que você terminou, salve o que aprendeu na sua memória." Com o tempo, isso cria uma base de conhecimento que torna o subagente mais eficaz.

• Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:

  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

Regras condicionais com hooks

Para um controle mais dinâmico sobre o uso de ferramentas, use hooks PreToolUse para validar operações antes que sejam executadas. Isso é útil quando você precisa permitir algumas operações de uma ferramenta enquanto bloqueia outras.

Este exemplo cria um subagente que permite apenas consultas de banco de dados somente leitura. O hook PreToolUse executa o script especificado em command antes de cada comando Bash ser executado:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

O Claude Code passa a entrada do hook como JSON via stdin para os comandos de hook. O script de validação lê esse JSON, extrai o comando Bash e sai com código 2 para bloquear operações de escrita:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

No macOS e no Linux, torne o script executável, caso contrário o hook falha em vez de bloquear algo:

chmod +x ./scripts/validate-readonly-query.sh

Para testar a regra, peça ao subagente para executar uma instrução UPDATE: o script sai com código 2, o Claude Code bloqueia o comando e o subagente vê a mensagem Blocked: Only SELECT queries are allowed.

Consulte Entrada do hook para o esquema de entrada completo e códigos de saída para saber como os códigos de saída afetam o comportamento. No Windows, escreva scripts de hook em PowerShell e adicione shell: powershell à entrada do hook, conforme mostrado em executar hooks no PowerShell.

Desabilitar subagentes específicos

Você pode impedir que o Claude use subagentes específicos adicionando-os ao array deny nas suas configurações. Use o formato Agent(subagent-name), em que subagent-name corresponde ao campo name do subagente.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Isso funciona tanto para subagentes integrados quanto personalizados. Você também pode usar a flag de CLI --disallowedTools:

claude --disallowedTools "Agent(Explore)"

Consulte a documentação de permissões para mais detalhes sobre regras de permissão.

Definir hooks para subagentes

Os subagentes podem definir hooks que são executados durante o ciclo de vida do subagente. Há duas maneiras de configurar hooks:

• No frontmatter do subagente: defina hooks que são executados apenas enquanto esse subagente está ativo
• Em settings.json: defina hooks de toda a sessão que também disparam dentro dos subagentes. Eventos de ferramentas como PreToolUse e PostToolUse disparam para as chamadas de ferramenta do subagente da mesma forma que na conversa principal, e SubagentStart e SubagentStop disparam quando um subagente começa ou termina

Os hooks de arquivos de configurações, configurações de política gerenciada e plugins se aplicam todos dentro dos subagentes, de modo que um hook PreToolUse em settings.json também é executado antes de cada ferramenta que um subagente usa.

Hooks no frontmatter do subagente

Defina hooks diretamente no arquivo markdown do subagente. Esses hooks são executados apenas enquanto aquele subagente específico está ativo e são removidos quando ele termina.

[!NOTE]

Os hooks do frontmatter disparam quando o agente é criado como subagente por meio da ferramenta Agent ou de uma @-menção, e quando o agente é executado como sessão principal via --agent ou a configuração agent. No caso da sessão principal, eles são executados junto com quaisquer hooks definidos em settings.json.

Para permitir que os hooks do frontmatter de um subagente de nível de projeto sejam executados, aceite a caixa de diálogo de confiança do workspace para a pasta que contém o arquivo do agente. Os hooks de subagentes de nível de usuário em ~/.claude/agents/ e de definições que você passa com --agents são executados sem essa etapa. Se você adicionou uma pasta com --add-dir de fora do repositório do seu workspace confiável, confie nessa pasta separadamente: os hooks do seu .claude/agents/ não herdam a concessão do workspace.

Até que você confie na pasta, o subagente ainda é executado, mas o Claude Code ignora seus hooks de frontmatter e registra no log de depuração um erro explicando como confiar na pasta. Esta é uma regra mais rigorosa do que a dos hooks em arquivos de configurações: confiar em uma pasta pai não é suficiente, e uma sessão -p não conta como confiável. O que é executado antes de você confiar em uma pasta compara as duas.

Todos os eventos de hook são suportados. Os eventos mais comuns para subagentes são:

Este exemplo valida comandos Bash com o hook PreToolUse e executa um linter após edições de arquivos com PostToolUse:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Quando o agente é invocado como subagente, os hooks Stop no frontmatter são convertidos automaticamente em eventos SubagentStop.

Hooks de nível de projeto para eventos de subagentes

Configure hooks em settings.json que respondem a eventos do ciclo de vida de subagentes na sessão principal.

Ambos os eventos suportam matchers para direcionar tipos de agentes específicos pelo nome. O valor do matcher é o name do frontmatter do agente para subagentes de nível de projeto e de nível de usuário, ou o identificador com escopo de plugin, como my-plugin:db-agent, para subagentes de plugin. Um nome com escopo contém dois-pontos, então é avaliado como uma expressão regular não ancorada; ancore-o com ^ e $, como em ^my-plugin:db-agent$, para corresponder apenas a esse agente.

Este exemplo executa um script de configuração apenas quando o subagente db-agent é iniciado, e um script de limpeza quando qualquer subagente para:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Consulte Hooks para o formato completo de configuração de hooks.

Trabalhar com subagentes

Entender delegação automática

Claude delega tarefas automaticamente com base na descrição da tarefa em sua solicitação, no campo description nas configurações de subagentes e no contexto atual. Para incentivar delegação proativa, inclua frases como "use proativamente" no campo de descrição do seu subagente.

Mantenha as descrições breves: Claude Code mostra um aviso de inicialização quando as descrições combinadas de seus subagentes ultrapassam o limite de 15.000 tokens, e ainda carrega todos os subagentes.

Se o subagente é fornecido em um plugin, você pode medir o quão confiável Claude delega a ele em prompts realistas em vez de verificar um de cada vez: claude plugin eval executa cada prompt com e sem o plugin e pontua os resultados.

Invocar subagentes explicitamente

Quando a delegação automática não é suficiente, você pode solicitar um subagente você mesmo. Três padrões escalam de uma sugestão única para um padrão em toda a sessão:

• Linguagem natural: nomeie o subagente em seu prompt; Claude decide se deve delegar
• @-mention: garante que o subagente seja executado para uma tarefa
• Em toda a sessão: toda a sessão é executada como esse subagente via flag --agent ou configuração agent

Para linguagem natural, não há sintaxe especial. Nomeie o subagente e Claude normalmente delega:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-mention o subagente. Digite @ e escolha o subagente na lista de sugestões, da mesma forma que você @-menciona arquivos. Isso garante que esse subagente específico seja executado em vez de deixar a escolha para Claude:

@"code-reviewer (agent)" look at the auth changes

Sua mensagem completa ainda vai para Claude, que escreve o prompt de tarefa do subagente com base no que você pediu. O @-mention controla qual subagente Claude invoca, não qual prompt ele recebe.

Subagentes fornecidos por um plugin habilitado aparecem na lista de sugestões sob seu nome com escopo, como my-plugin:code-reviewer ou my-plugin:review:security quando o plugin organiza agentes em subpastas. Subagentes em segundo plano nomeados atualmente em execução na sessão também aparecem na lista de sugestões, mostrando seu status ao lado do nome.

Você também pode digitar a menção manualmente sem usar o seletor: @agent-<name> para subagentes locais, ou @agent- seguido pelo nome com escopo para subagentes de plugin, por exemplo @agent-my-plugin:code-reviewer. Enquanto você digita este formulário, a lista de sugestões mostra correspondências de arquivo em vez de agentes. A menção do agente ainda é resolvida quando você envia.

Execute toda a sessão como um subagente. Passe --agent <name> para iniciar uma sessão onde o thread principal em si assume as restrições de ferramentas e o modelo desse subagente:

claude --agent code-reviewer

A menos que o prompt do agente esteja vazio, o system prompt de um subagente personalizado substitui completamente o system prompt padrão do Claude Code, da mesma forma que --system-prompt faz. Os arquivos CLAUDE.md e a memória do projeto ainda são carregados através do fluxo de mensagens normal, mesmo quando a definição do agente define omitClaudeMd. Se você executar a sessão com -p como um agente personalizado que tem seu próprio prompt, ela também inicia sem o snapshot de status do git.

O nome do agente aparece como @<name> no cabeçalho de inicialização para que você possa confirmar que está ativo.

Isso funciona com subagentes integrados e personalizados, e a escolha persiste quando você retoma a sessão: Claude Code restaura as restrições de ferramentas e o modelo do agente junto com a conversa. Se o agente não existir mais quando você retomar, a sessão continua com as ferramentas padrão e mostra um aviso nomeando o agente. Para o system prompt em ambos os casos, consulte Flags de system prompt em conversas retomadas.

Para um subagente fornecido por plugin, você pode passar apenas o nome do agente e Claude Code o encontra:

claude --agent security-reviewer

Se vários plugins fornecerem agentes com o mesmo nome, passe o nome com escopo para desambiguar:

claude --agent my-plugin:security-reviewer

Se o plugin colocar o agente em uma subpasta de seu diretório agents/, inclua a subpasta no nome com escopo, por exemplo claude --agent my-plugin:review:security.

Para torná-lo o padrão para cada sessão em um projeto, defina agent em .claude/settings.json:

{
  "agent": "code-reviewer"
}

A flag da CLI sobrescreve a configuração se ambas estiverem presentes.

Executar subagentes em primeiro plano ou segundo plano

Subagentes podem ser executados em primeiro plano ou segundo plano:

• Subagentes em primeiro plano bloqueiam a conversa principal até a conclusão. Prompts de permissão são passados para você conforme surgem.
• Subagentes em segundo plano são executados simultaneamente enquanto você continua trabalhando. Quando um subagente em segundo plano atinge uma chamada de ferramenta que precisa de permissão, Claude Code exibe o prompt em sua sessão principal e nomeia o subagente que está pedindo. Aprove para deixar o subagente continuar, ou pressione Esc para negar essa chamada de ferramenta sem parar o subagente.

Quais subagentes são executados em segundo plano

Sem nada configurado, um subagente que Claude gera a partir da sua conversa principal inicia em segundo plano.

• claude -p e o Agent SDK: Claude pode aguardar, por seu próprio julgamento ou quando você pede.
• Sessão interativa no terminal, VS Code e sessões do aplicativo desktop na sua máquina: para deixar Claude aguardar um subagente, desative o modo fork, que está ativado por padrão.

Para uma skill com context: fork, Claude Code segue as regras em Executar skills em um subagente, independentemente de o modo fork estar ativado.

Deixar Claude aguardar um subagente

1. Desative o modo fork definindo CLAUDE_CODE_FORK_SUBAGENT como 0, por exemplo em settings.json:

   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   

2. Execute claude novamente a partir do seu shell, ou abra uma nova conversa no VS Code.

3. Peça a Claude para aguardar quando você precisar de um resultado primeiro, por exemplo "execute o subagente revisor e aguarde o relatório dele".

Para continuar trabalhando enquanto Claude aguarda, pressione Ctrl+B no terminal ou clique em Run in background no VS Code.

Se você definir a variável de ambiente CLAUDE_CODE_DISABLE_BACKGROUND_TASKS como 1 em vez de desativar o modo fork, Claude aguarda os subagentes terminarem antes de continuar. Os comandos em segundo plano também ficam desativados, e Ctrl+B não move nada para o segundo plano.

Ferramentas, permissões e resultados de subagentes em segundo plano

Subagentes em segundo plano são executados com um conjunto de ferramentas integradas menor do que subagentes em primeiro plano, exceto para forks de conversa e subagentes em primeiro plano retomados.

Subagentes em segundo plano exibem cada prompt de permissão em sua sessão principal. Quando você responde um desses prompts com uma escolha que dura além dessa chamada de ferramenta, como uma concessão que dura o resto da sessão, Claude Code aplica sua resposta a toda a sessão, incluindo sua conversa principal.

Um subagente em segundo plano pode deixar um comando Bash ou PowerShell em segundo plano em execução após o final de seu turno. Quando esse comando termina, Claude Code envia ao subagente uma notificação.

Os resultados de um subagente em segundo plano chegam a Claude como uma notificação de conclusão em um turno posterior. Claude aguarda essa notificação antes de relatar os resultados do subagente, e se você perguntar sobre o progresso primeiro, ele relata que o subagente ainda está em execução.

Subagentes concluídos no painel e na lista de tarefas

Claude Code limpa a linha de um subagente em segundo plano do painel de subagentes abaixo da entrada de prompt de uma de duas maneiras, dependendo de como o subagente terminou:

• Quando um subagente termina com sucesso, Claude Code remove sua linha imediatamente e, exceto no modo leitor de tela, mostra /tasks to see subagents no rodapé por 30 segundos. Durante esses 30 segundos, execute /tasks e pressione Enter no subagente para abrir sua transcrição. Antes da v2.1.232, Claude Code mantinha a linha por 30 segundos após o subagente terminar, o mesmo que um com falha, e não mostrava dica de rodapé.
• Quando um subagente falha ou você o para, Claude Code mantém sua linha por 30 segundos. Para limpar a linha mais cedo, selecione-a e pressione x.

Um subagente em segundo plano que é concluído permanece listado em /tasks, marcado como concluído e classificado abaixo do trabalho em execução, pelos mesmos 30 segundos que a dica de rodapé. Sua visualização de detalhes permanece aberta quando o subagente termina. Subagentes que falham ou que você para saem da lista. Antes da v2.1.208, um subagente concluído saía da lista no momento em que terminava e sua visualização de detalhes fechava.

Nomes de subagentes

Se você iniciar uma sessão com equipes de agentes habilitadas, Claude pode dar um nome a um subagente passando um parâmetro name na chamada da ferramenta Agent. Ele pode fazer isso por conta própria, sem pedir a você primeiro. O nome torna o subagente endereçável: Claude pode mensagear ou retomá-lo pelo nome após terminar.

Em uma sessão interativa com equipes de agentes habilitadas, um subagente que Claude gera da conversa principal com um name é lançado como um colega, a menos que a chamada seja um fork ou passe isolation na chamada em si. Um valor isolation no frontmatter do subagente não o impede, e o colega então é executado no diretório de trabalho da sessão principal. Consulte Como Claude inicia equipes de agentes.

Erros de API em subagentes

Quando algo interrompe a resposta de um subagente no meio do fluxo, e a resposta parcial contém texto mas nenhuma chamada de ferramenta, Claude Code solicita ao subagente que continue em vez de encerrar a execução. Isso também acontece em sessões interativas. A execução termina no erro apenas uma vez que essas continuações são usadas.

Um subagente cuja execução termina em um erro de API, como um limite de uso ou um erro de servidor repetido, relata essa falha de volta a Claude. O que Claude recebe depende de onde o subagente foi executado:

• Primeiro plano: se um rate limit, sobrecarga ou erro de servidor interromper um subagente que já produziu saída de texto, a ferramenta Agent retorna essa saída parcial com uma nota de que o subagente foi interrompido e não completou sua tarefa. Um subagente que não produziu nada, ou cuja única saída foram chamadas de ferramenta, falha com Agent terminated early due to an API error, seguido pelo detalhe do erro.
• Segundo plano: o subagente é marcado como com falha, e a mensagem que Claude recebe quando termina nomeia o erro de API e inclui a última saída do subagente, para que o trabalho parcial não seja perdido.

Se o relatório de um subagente começar com a linha a seguir, o subagente terminou em um modelo de fallback:

⚠ This agent switched to <model> because its earlier model could not be used.

Quando você configura uma cadeia de modelo de fallback e um subagente encontra uma falha que a cadeia cobre, como seu modelo estar indisponível, Claude Code muda o subagente para o primeiro modelo na cadeia que aceita a requisição. O subagente continua trabalhando em vez de terminar no erro.

Uma vez que o erro de API subjacente seja resolvido, peça a Claude para tentar novamente a tarefa ou retomar o subagente.

Verificação de saída de subagente

Claude Code verifica o relatório final de cada subagente antes de Claude lê-lo. Um subagente pode ter lido arquivos, páginas da web ou saída de comando que você nunca revisou, e texto dessas fontes pode carregar instruções destinadas à conversa principal. A verificação nunca remove ou reformula nada; ela faz dois tipos de mudança que você pode notar em um relatório:

• Inserção de barra invertida: a verificação insere uma barra invertida em texto que imita a própria saída do Claude Code, como uma tag <system-reminder> ou uma linha começando com Human: ou Assistant:, para que a imitação seja lida como texto comum em vez de ser confundida com parte da conversa.
• Linha de marcador: a verificação prepara uma linha começando com [harness: subagent output matched instruction-shaped pattern(s): quando o relatório imita uma tag como <system-reminder> ou menciona configurações de permissão como bypassPermissions ou --dangerously-skip-permissions. Menções de configuração de permissão recebem a linha de marcador, mas o texto em si permanece como escrito.

A verificação não julga se o conteúdo é malicioso, e não muda o que uma instrução em um relatório pode fazer: uma chamada de ferramenta que o relatório leva Claude a fazer ainda passa pelas verificações de permissão e sandboxing da sessão. Não é um substituto para restringir o que um subagente pode alcançar.

Um relatório que retorna a Claude como o resultado do subagente também chega sob um cabeçalho marcando-o como saída de subagente. O cabeçalho afirma que instruções ou reivindicações de aprovação dentro do relatório são as palavras do subagente e não carregam autoridade de você.

Um relatório de subagente em segundo plano chega dentro de uma notificação de conclusão, que é marcada como um evento automatizado em vez de uma mensagem de você.

Padrões comuns

Isolar operações de alto volume

Um dos usos mais eficazes para subagentes é isolar operações que produzem grandes quantidades de saída. Executar testes, buscar documentação ou processar arquivos de log pode consumir contexto significativo. Ao delegar isso a um subagente, a saída detalhada permanece no contexto do subagente enquanto apenas o resumo relevante retorna à sua conversa principal.

Use a subagent to run the test suite and report only the failing tests with their error messages

Executar pesquisa paralela

Para investigações independentes, gere vários subagentes para trabalhar simultaneamente:

Research the authentication, database, and API modules in parallel using separate subagents

Cada subagente explora sua área independentemente, então Claude sintetiza as descobertas. Isso funciona melhor quando os caminhos de pesquisa não dependem um do outro.

[!WARNING]

Quando subagentes são concluídos, seus resultados retornam à sua conversa principal. Executar muitos subagentes que cada um retorna resultados detalhados pode consumir contexto significativo, e cada subagente gasta tokens de seu próprio enquanto é executado.

Para trabalho que precisa continuar em paralelo ou não caberá em uma janela de contexto, execute-o em sessões separadas e deixe Claude passar descobertas entre elas.

Encadear subagentes

Para fluxos de trabalho de várias etapas, peça a Claude para usar subagentes em sequência. Cada subagente completa sua tarefa e retorna resultados a Claude, que então passa contexto relevante para o próximo subagente.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Escolher entre subagentes e conversa principal

Use a conversa principal quando:

• A tarefa precisa de frequente ida e volta ou refinamento iterativo
• Múltiplas fases compartilham contexto significativo, como planejamento, implementação e testes
• Você está fazendo uma mudança rápida e direcionada
• A latência importa. Um subagente que não é um fork começa do zero e pode precisar de tempo para reunir contexto

Use subagentes quando:

• A tarefa produz saída detalhada que você não precisa em seu contexto principal
• Você quer impor restrições de ferramentas ou permissões específicas
• O trabalho é autossuficiente e pode retornar um resumo

Considere Skills em vez disso quando você quer prompts ou fluxos de trabalho reutilizáveis que são executados no contexto da conversa principal em vez de contexto de subagente isolado.

Para uma pergunta sobre algo já em sua conversa, use /btw em vez de um subagente. Ele vê seu contexto completo mas não tem acesso a ferramentas, e a resposta não é adicionada ao histórico.

Deixar subagentes gerar seus próprios subagentes

Por padrão, um subagente pode gerar subagentes de seu próprio, até três camadas abaixo da conversa principal. No limite de profundidade, Claude Code retém a ferramenta Agent de cada subagente, exceto um fork, para que um subagente no limite faça seu trabalho delegado em si e retorne um resumo. Um fork no limite mantém Agent em sua lista de ferramentas herdada, mas a ferramenta retorna um erro em vez de gerar.

Subagentes aninhados são adequados para uma tarefa delegada que em si se divide em subtarefas paralelas, como um subagente revisor que despacha um verificador por descoberta. Por padrão, o subagente que gera aguarda o relatório de cada subagente aninhado:

• Sessão interativa no terminal: apenas o resumo do subagente de nível superior retorna para você, porque um subagente que lança subagentes em segundo plano aguarda seus resultados antes de terminar.
• claude -p e o Agent SDK: o subagente que gera aguarda enquanto o modo fork está ativado. Se você desativar o modo fork, os subagentes aninhados iniciam em segundo plano em vez disso. O subagente que gera não aguarda um subagente aninhado em segundo plano, que relata à sua conversa principal se durar mais que o subagente que o gerou.

Para alterar o limite, defina CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH para o número de camadas de subagente que você quer abaixo de sua conversa principal. Por exemplo, esta entrada em settings.json limita o aninhamento a duas camadas:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Com este valor, seus subagentes podem delegar a uma segunda camada de seus próprios, e essa segunda camada não pode delegar mais. Defina 1 para desativar o aninhamento.

Um subagente aninhado é configurado da mesma forma que um de nível superior e é resolvido dos mesmos escopos. Para manter um subagente de gerar enquanto o aninhamento está ativado, como um revisor que deve permanecer somente leitura, omita Agent de sua lista tools ou adicione-o a disallowedTools.

No terminal, Claude Code mostra subagentes aninhados como uma árvore no painel de subagentes abaixo da entrada de prompt e marca cada linha que ainda tem descendentes no painel com uma contagem (+N) deles. Abra uma linha para ver os irmãos e filhos diretos desse subagente com um caminho de volta para main.

Limite de subagente concorrente

Dois limites controlam o uso de subagentes, cada um com sua própria variável: este impede que Claude gere mais subagentes enquanto muitos estão em execução, e o limite de profundidade limita o quão profundamente os subagentes se aninham. Não há limite no número total de subagentes que Claude pode gerar ao longo de uma sessão.

Por padrão, quando 20 subagentes estão em execução em uma sessão, gerar outro com a ferramenta Agent falha com Concurrent subagent limit reached, e o erro diz a Claude para não tentar novamente. A geração é bem-sucedida novamente quando a contagem em execução cai abaixo do limite. Para alterar o limite, defina CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS para qualquer número inteiro positivo. Sessões com ultracode ativo estão isentas: o limite não é imposto lá. Requer Claude Code v2.1.217 ou posterior.

O limite bloqueia apenas subagentes que Claude gera com a ferramenta Agent, mas outras execuções ocupam os mesmos slots:

• Um fork em sessão que você inicia com /subtask ocupa um slot enquanto é executado e nunca é bloqueado pelo limite.
• Retomar um subagente que já terminou ocupa um slot novo sem verificar o limite, para que retomadas possam empurrar a contagem em execução além dele.

Agentes que outros recursos executam, como agentes workflow e colegas de equipe de agentes, seguem seus próprios limites em vez disso.

Gerenciar contexto de subagente

O que é carregado na inicialização

Cada subagente começa com uma janela de contexto fresca e isolada. Ele não vê seu histórico de conversa, as skills que você já invocou ou os arquivos que Claude já leu. Claude compõe uma mensagem de delegação que resume a tarefa, e o subagente trabalha a partir daí. A exceção é um fork, que herda a conversa pai em vez de começar do zero.

O contexto inicial de um subagente não-fork contém:

• System prompt: o próprio prompt do agente mais detalhes de ambiente que Claude Code acrescenta, não o system prompt do Claude Code. Subagentes personalizados definem o seu no corpo markdown ou campo prompt. Agentes integrados têm prompts predefinidos.
• Mensagem de tarefa: o prompt de delegação que Claude escreve quando passa o trabalho.
• Arquivos CLAUDE.md: cada nível da hierarquia CLAUDE.md que a conversa principal carrega, incluindo ~/.claude/CLAUDE.md, regras do projeto, CLAUDE.local.md, arquivos de política gerenciada e qualquer arquivo AGENTS.md carregado como instruções do projeto. Os agentes Explore e Plan integrados pulam isso. Um subagente cuja definição define omitClaudeMd carrega apenas os arquivos de política gerenciada, ou nenhum quando a definição vem de configurações gerenciadas.
• Status Git: um snapshot que Claude Code lê do seu repositório quando o subagente é iniciado. Para um subagente em seu próprio worktree desse repositório, o snapshot mostra o branch, o status e os commits recentes do worktree. Ausente fora de um repositório Git ou sempre que o snapshot estiver desativado; consulte includeGitInstructions. Explore e Plan o pulam de qualquer forma.
• Skills pré-carregadas: conteúdo completo de qualquer skill nomeada no campo skills do agente. Agentes integrados não pré-carregam skills.
• Roster de irmãos: um lembrete do sistema listando main e cada outro agente nomeado na sessão, cada um um valor to válido para SendMessage. O roster aparece apenas quando as ferramentas do subagente incluem SendMessage e pelo menos um outro agente tem um nome, seja Claude o nomeou ao gerá-lo ou ele é executado como um colega de equipe de agentes. É um snapshot tirado quando o subagente começa, então agentes nomeados depois não aparecem.

Para lançar um de seus próprios subagentes sem os arquivos CLAUDE.md do usuário, projeto e local, defina omitClaudeMd: true em seu frontmatter ou --agents JSON. Para Explore, Plan e subagentes com omitClaudeMd, o CLAUDE.md de um subdiretório e as regras com escopo de caminho correspondentes ainda são carregados quando o subagente trabalha com arquivos nesse local.

A conversa principal ainda tem seu CLAUDE.md completo quando lê os resultados desses subagentes, então a maioria das regras não precisa alcançar o subagente em si. Se uma regra deve, como "ignore o diretório vendor/," reafirme-a no prompt que você dá a Claude ao delegar.

Você não pode alterar quais subagentes recebem status git. Apenas Explore e Plan pulam.

Algum estado da conversa principal nunca alcança um subagente não-fork:

• Estilo de saída: um subagente executa seu próprio system prompt, então seu estilo de saída não molda suas respostas, exceto em um fork.
• Memória automática: a memória automática da conversa principal não é carregada. Para dar a um subagente memória persistente de seu próprio, use o campo memory.
• Tamanho da janela de contexto: a janela de contexto de um subagente é dimensionada por seu próprio modelo, não pelo pai. Delegar a um modelo com uma janela menor dá a esse subagente a janela menor.

Retomar subagentes

Cada invocação de subagente cria uma nova instância em vez de continuar uma anterior. Para continuar o trabalho de um subagente existente em vez de começar do zero, peça a Claude para retomá-lo.

Subagentes retomados retêm seu histórico de conversa completo, incluindo todas as chamadas de ferramenta anteriores, resultados e raciocínio. Se o subagente gerou subagentes em segundo plano de seu próprio, esse histórico inclui os resultados que entregaram enquanto era executado. Antes da v2.1.304, um subagente que Claude mensageava ou retomava logo após ele terminar podia esquecer seu trabalho mais recente.

• Quando um subagente é concluído, Claude recebe seu ID de agente.
• Os agentes Explore e Plan integrados são de uma única execução e não retornam um ID de agente, então Claude não pode retomá-los. Use general-purpose ou um subagente personalizado quando você precisa continuar o trabalho.
• Quando um subagente para em seu limite maxTurns, Claude Code marca a saída retornada como parcial, e Claude pode retomar o subagente para continuar seu trabalho.

Claude usa a ferramenta SendMessage com o ID ou nome do agente como o campo to para retomá-lo. SendMessage não requer que equipes de agentes estejam habilitadas; apenas mensagens de protocolo de equipe estruturadas como shutdown_request e plan_approval_response fazem. Além de subagentes e colegas, em sessões onde mensagens entre sessões estão habilitadas, Claude pode usar a mesma ferramenta para mensagear suas outras sessões do Claude Code, nesta máquina ou além dela.

Para retomar um subagente, peça a Claude para continuar o trabalho anterior:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Quando Claude envia a um subagente concluído uma mensagem com a ferramenta SendMessage, o subagente retoma em segundo plano sem uma nova invocação Agent. O mesmo se aplica a um subagente que Claude parou com a ferramenta TaskStop, uma vez que sua execução parada tenha saído. A execução retomada mantém o conjunto de ferramentas de onde o subagente foi executado primeiro e pode continuar lendo o cache de prompt que a execução original aqueceu.

Um subagente que tem a ferramenta SendMessage pode enviar essa mensagem também. Em uma sessão interativa, o agente retomado então relata de volta ao subagente que o retomou, não à sua conversa principal. Esse subagente aguarda o resultado antes de terminar seu próprio trabalho. Quando um subagente mensageia um agente ao qual relata, como seu próprio iniciador, Claude Code retoma esse agente sem redirecionar seus resultados.

Um subagente que você parou você mesmo, com x em /tasks ou uma requisição SDK stop_task, não retoma automaticamente. Se Claude enviar uma mensagem a ele, a mensagem é recusada e Claude é informado de que o agente foi cancelado.

Enquanto a linha desse subagente ainda está no painel de subagentes, digite em sua transcrição para retomá-lo você mesmo. Depois disso, uma mensagem de Claude pode retomá-lo automaticamente novamente.

Retomar inicia uma nova execução do agente sob o mesmo ID, então um subagente que já havia falhado ou sido concluído mostra como em execução novamente na lista de tarefas e nos eventos de tarefa do Agent SDK.

SendMessage verifica que um nome ainda se refere ao mesmo agente que alcançou anteriormente na conversa. Se um agente mais novo assumiu o nome, como um agente em segundo plano re-gerado que o reutilizou, Claude Code recusa o envio em vez de entregá-lo ao agente errado, e o erro relata qual agente o nome agora alcança para que Claude possa redirecionar. Para alcançar o agente anterior enquanto ainda está em execução, Claude o endereça pelo ID do agente que recebeu quando gerou esse agente. A verificação é restrita à conversa atual e é redefinida em /clear.

Um subagente trata mensagens do agente que o lançou como direção de tarefa normal, incluindo correções de curso no meio da tarefa, e age sobre elas dentro de suas próprias configurações de permissão. Dois limites se mantêm independentemente de quem enviou a mensagem: nenhuma mensagem de qualquer agente conta como sua aprovação para um prompt de permissão pendente, e nenhuma mensagem de agente pode alterar as configurações de permissão, CLAUDE.md ou configuração de um subagente. Apenas o sistema de permissão ou suas próprias mensagens podem conceder aprovação.

Você também pode pedir a Claude o ID do agente se quiser referenciá-lo explicitamente, ou encontrar IDs nos arquivos de transcrição em ~/.claude/projects/{project}/{sessionId}/subagents/. Cada transcrição é armazenada como agent-{agentId}.jsonl.

Transcrições de subagentes persistem independentemente da conversa principal:

• Compactação da conversa principal: quando a conversa principal é compactada, as transcrições de subagentes não são afetadas. Elas são armazenadas em arquivos separados.
• Persistência de sessão: as transcrições de subagentes persistem dentro de sua sessão. Você pode retomar um subagente após reiniciar Claude Code retomando a mesma sessão.
• Limpeza automática: Claude Code deleta transcrições de subagentes após o período de retenção cleanupPeriodDays, 30 dias por padrão, seguindo as regras de varredura de retenção.

Mensagear um subagente pelo nome após uma reinicialização

[!NOTE]

Para um subagente que foi lançado como um colega, consulte as limitações de equipes de agentes em vez disso.

Se Claude não conseguir mensagear um subagente pelo nome depois que você reiniciar Claude Code e retomar a sessão, dê a Claude o ID de agente do subagente em vez disso. Nomes que Claude deu a partir da conversa principal desde sua última compactação sobrevivem à reinicialização. Um nome de antes dessa compactação não sobrevive. Para encontrar o ID de um nome, procure esse nome nos arquivos agent-{agentId}.meta.json em ~/.claude/projects/{project}/{sessionId}/subagents/.

Após uma mensagem por ID, o nome do subagente volta a funcionar, a menos que um agente mais novo tenha assumido esse nome. Antes da v2.1.299, nenhum nome sobrevivia a uma reinicialização, e um envio por nome era recusado mesmo quando o ID do agente ainda funcionava.

Compactação automática

Subagentes suportam compactação automática. A compactação é acionada à medida que a própria janela de contexto do subagente se enche, e CLAUDE_AUTOCOMPACT_PCT_OVERRIDE se aplica a subagentes também. Consulte variáveis de ambiente para quando a substituição entra em vigor.

Eventos de compactação são registrados em arquivos de transcrição de subagentes:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

O valor preTokens mostra quantos tokens foram usados antes da compactação ocorrer.

Definir a janela de compactação automática para um subagente

Para fazer um subagente compactar mais cedo do que faria de outra forma, defina autoCompactWindow em seu frontmatter como uma contagem de tokens de 100000 a 1000000. Se você definir CLAUDE_CODE_AUTO_COMPACT_WINDOW, o subagente usa a janela dessa variável em vez disso e o campo não tem efeito, a menos que Claude Code ignore o valor da variável. Requer Claude Code v2.1.296 ou posterior.

Este frontmatter define autoCompactWindow como 200.000 tokens para um subagente que lê arquivos de log longos:

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

Escreva o valor como um inteiro simples, como 200000, porque no frontmatter Claude Code lê 200k como 200, que está fora do intervalo permitido. O subagente ainda é carregado e compacta como se o campo estivesse ausente. Para verificar se Claude Code ignorou seu valor, execute claude --debug em seu shell e procure invalid autoCompactWindow no log de depuração.

Se o valor estiver dentro do intervalo e você ainda não vir nenhuma mudança, verifique estas causas:

• O valor não está abaixo da janela de compactação automática que o subagente herdaria de outra forma: para compactar mais cedo, defina um valor abaixo dessa janela.
• Você executa toda a sessão como este subagente com --agent ou a configuração agent: o campo não tem efeito nesse caso. Para definir a janela da sessão, consulte Definir a janela de compactação automática.

Bifurcar a conversa atual

[!NOTE]

Quando a visualização de agente está desativada, /subtask não está disponível e /fork inicia o subagente bifurcado; caso contrário, /fork copia toda a sessão para uma nova sessão em background.

Uma bifurcação é um subagente que herda toda a conversa até agora em vez de começar do zero. Isso remove o isolamento de entrada que subagentes de outra forma fornecem: uma bifurcação vê o mesmo prompt de sistema, ferramentas, modelo e histórico de mensagens que a sessão principal, para que você possa entregar uma tarefa secundária sem re-explicar a situação. As chamadas de ferramentas da bifurcação ainda ficam fora de sua conversa e apenas seu resultado final volta, para que sua janela de contexto principal permaneça limpa. Use uma bifurcação quando qualquer outro subagente precisaria de muito contexto para ser útil, ou quando você quer tentar várias abordagens em paralelo a partir do mesmo ponto de partida.

Claude pode iniciar uma bifurcação por conta própria enquanto o modo de bifurcação está ativado, como está por padrão. Para impedir bifurcações, consulte Desativar o modo de bifurcação.

Você pode iniciar uma bifurcação você mesmo com /subtask seguido de uma tarefa, independentemente de o modo de bifurcação estar ativado. Claude Code nomeia a bifurcação a partir das primeiras palavras da tarefa. O exemplo a seguir bifurca a conversa para rascunhar casos de teste enquanto você continua com a implementação na sessão principal:

/subtask draft unit tests for the parser changes so far

A bifurcação aparece em um painel abaixo do seu prompt e é executada em background enquanto você continua trabalhando. Quando termina, seu resultado chega como uma mensagem em sua conversa principal. A próxima seção cobre os controles do painel para observar e orientar bifurcações enquanto são executadas.

Observar e orientar bifurcações em execução

Bifurcações em execução aparecem em um painel abaixo da entrada de prompt, com uma linha para a sessão principal e uma para cada bifurcação.

Quando uma bifurcação termina com sucesso, Claude Code remove sua linha. Claude Code mantém a linha de uma bifurcação que falhou ou que você parou por 30 segundos, o mesmo que para qualquer outro subagente em background. Antes da v2.1.232, Claude Code também mantinha a linha de uma bifurcação terminada por 30 segundos.

Use estas teclas para interagir com o painel:

Com a transcrição de uma bifurcação ou subagente aberta, mensagens de acompanhamento e skills vão para esse agente, e comandos integrados vão para sua conversa principal, com estas salvaguardas:

• /compact, /clear e /rewind atuam na conversa principal, então Claude Code pede que você confirme antes de executar um deles a partir desta visualização.
• /model e /fast definem o modelo e o modo rápido da conversa principal, não os do agente visualizado, então não são executados a partir desta visualização. Um aviso informa o motivo.

Para que o agente visualizado leia sua mensagem antes que termine o trabalho que ele está aguardando, envie-a com Ctrl+Enter ou Ctrl+X Ctrl+S. Qualquer comando de shell ou subagente que o agente está aguardando e que possa ser movido para o background é movido para lá e continua em execução. Quando o agente está escrevendo uma resposta, ou aguardando um trabalho que não pode ser movido para o background, ele continua e lê sua mensagem assim que isso terminar. Requer Claude Code v2.1.286 ou posterior.

Como bifurcações diferem de outros subagentes

Uma bifurcação herda tudo que a sessão principal tem no momento em que é gerada. Qualquer outro subagente começa do zero a partir de sua definição.

Porque o system prompt de uma bifurcação e as definições de ferramentas são idênticos aos do pai, sua primeira requisição reutiliza o cache de prompt do pai. Por causa dessa reutilização, uma bifurcação custa menos do que um subagente fresco para tarefas que precisam do mesmo contexto.

Quando Claude gera uma bifurcação através da ferramenta Agent, ele pode passar isolation: "worktree" para que as edições de arquivo da bifurcação sejam escritas em um git worktree separado em vez de seu checkout. Uma bifurcação não pode gerar bifurcações adicionais.

Desativar o modo de bifurcação

O modo de bifurcação permite que Claude inicie uma bifurcação por conta própria. Para impedir que Claude inicie bifurcações:

• Impedir apenas as bifurcações: adicione "Agent(fork)" a permissions.deny nas suas configurações.
• Desativar o modo de bifurcação: defina CLAUDE_CODE_FORK_SUBAGENT como 0, seguindo as etapas em Permitir que Claude aguarde um subagente.

Enquanto o modo de bifurcação está ativado, Claude também não pode aguardar um subagente em sessões interativas de terminal, VS Code ou desktop na sua máquina. O modo de bifurcação está ativado por padrão a partir do Claude Code v2.1.302, e em uma sessão interativa de terminal a partir da v2.1.232.

Subagentes de exemplo

Estes exemplos demonstram padrões eficazes para construir subagentes. Use-os como pontos de partida, ou gere uma versão personalizada com Claude.

[!TIP]

Melhores práticas:

• Projete subagentes focados: cada subagente deve se destacar em uma tarefa específica
• Escreva descrições que destaquem um subagente: Claude usa a descrição para decidir quando delegar. Faça cada descrição específica o suficiente para rotear para o subagente correto, e mantenha o conjunto combinado dentro do orçamento de descrição de 15.000 tokens
• Limite acesso a ferramentas: conceda apenas permissões necessárias para segurança e foco
• Verifique no controle de versão: compartilhe subagentes de projeto com sua equipe

Revisor de código

Um subagente somente leitura que revisa código sem modificá-lo. Este exemplo mostra como projetar um subagente focado com acesso limitado a ferramentas que exclui Edit e Write, e um prompt detalhado que especifica exatamente o que procurar e como formatar a saída.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Debugger

Um subagente que pode analisar e corrigir problemas. Diferentemente do revisor de código, este inclui Edit porque corrigir bugs requer modificar código. O prompt fornece um fluxo de trabalho claro de diagnóstico para verificação.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Cientista de dados

Um subagente específico de domínio para trabalho de análise de dados. Este exemplo mostra como criar subagentes para fluxos de trabalho especializados fora de tarefas de codificação típicas. Ele explicitamente define model: sonnet para análise mais capaz.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Validador de consulta de banco de dados

Um subagente que permite acesso Bash mas valida comandos para permitir apenas consultas SQL somente leitura. Este exemplo mostra como usar hooks PreToolUse para validação condicional quando você precisa de controle mais fino do que o campo tools fornece.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code passa entrada de hook como JSON via stdin para comandos de hook. O script de validação lê este JSON, extrai o comando sendo executado e o verifica contra uma lista de operações de escrita SQL. Se uma operação de escrita é detectada, o script sai com código 2 para bloquear execução e retorna uma mensagem de erro para Claude via stderr.

Crie o script de validação em qualquer lugar em seu projeto. O caminho deve corresponder ao campo command em sua configuração de hook:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

No macOS e Linux, torne o script executável:

chmod +x ./scripts/validate-readonly-query.sh

No Windows, escreva o script de validação em PowerShell e adicione shell: powershell à entrada de hook. Veja executando hooks em PowerShell.

O hook recebe JSON via stdin com o comando Bash em tool_input.command. Código de saída 2 bloqueia a operação e alimenta a mensagem de erro de volta para Claude. Veja Hooks para detalhes sobre códigos de saída e Hook input para o schema de entrada completo.

O prompt do sistema diz ao subagente para recusar solicitações de escrita, então o hook é um backstop: se o subagente tentar uma escrita mesmo assim, Claude Code bloqueia o comando e o subagente vê a mensagem Blocked: Write operations not allowed. Use SELECT queries only..

Próximos passos

Agora que você entende subagentes, explore estes recursos relacionados:

• Distribuir subagentes com plugins para compartilhar subagentes entre equipes ou projetos
• Executar Claude Code programaticamente com o Agent SDK para CI/CD e automação
• Usar MCP servers para dar aos subagentes acesso a ferramentas e dados externos