159 Configurar subagentes159 Configurar subagentes
160</h2>160</h2>
161 161
162A localização do arquivo de um subagente determina quem tem acesso a ele, e seu frontmatter determina o que ele pode fazer. Esta seção aborda onde os arquivos de subagente residem e cada campo que eles suportam.162O 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.
163 163
164<h3 id="choose-the-subagent-scope">164<h3 id="choose-the-subagent-scope">
165 Escolher o escopo do subagente165 Escolher o escopo do subagente
166</h3>166</h3>
167 167
168Armazene arquivos de subagente em locais diferentes dependendo do escopo. Quando múltiplos subagentes compartilham o mesmo nome, Claude Code usa o que está no local de prioridade mais alta.168Armazene 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.
169 169
170| Location | Scope | Priority | How to create |170| Local | Escopo | Prioridade | Como criar |
171| :- | :- | :- | :- |171| :- | :- | :- | :- |
172| Managed settings | Organization-wide | 1 (highest) | Deployed via [managed settings](/docs/pt/settings) |172| Configurações gerenciadas | Toda a organização | 1 (mais alta) | Implantado via [configurações gerenciadas](/docs/pt/settings) |
173| `--agents` CLI flag | Current session | 2 | Pass JSON when launching Claude Code |173| Flag de CLI `--agents` | Sessão atual | 2 | Passe JSON ao iniciar o Claude Code |
174| `.claude/agents/` | Current project | 3 | Ask Claude, or create the file manually |174| `.claude/agents/` | Projeto atual | 3 | Peça ao Claude ou crie o arquivo manualmente |
175| `~/.claude/agents/` | All your projects | 4 | Ask Claude, or create the file manually |175| `~/.claude/agents/` | Todos os seus projetos | 4 | Peça ao Claude ou crie o arquivo manualmente |
176| Plugin's `agents/` directory | Where plugin is enabled | 5 (lowest) | Installed with [plugins](/docs/pt/plugins/overview) |176| Diretório `agents/` do plugin | Onde o plugin está habilitado | 5 (mais baixa) | Instalado com [plugins](/docs/pt/plugins/overview) |
177 177
178**Subagentes de projeto** (`.claude/agents/`) são ideais para subagentes específicos de uma base de código. Verifique-os no controle de versão para que sua equipe possa usá-los e melhorá-los colaborativamente.178**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.
179 179
180Subagentes de projeto são descobertos caminhando para cima a partir do diretório de trabalho atual, portanto cada `.claude/agents/` entre lá e a raiz do repositório é verificado. Quando mais de um desses diretórios aninhados define o mesmo `name`, Claude Code usa a definição mais próxima do diretório de trabalho.180Os 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.
181 181
182Quando você adiciona um diretório com `--add-dir` ou `/add-dir`, Claude Code também carrega sua pasta `.claude/agents/`, junto com seus subagentes de projeto. Veja [Diretórios adicionais](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) para quais outros tipos de configuração carregam de `--add-dir`. Para compartilhar subagentes entre projetos sem `--add-dir`, use `~/.claude/agents/` ou um [plugin](/docs/pt/plugins/overview).182Quando 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](/docs/pt/permissions#additional-directories-grant-file-access-not-configuration) 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](/docs/pt/plugins/overview).
183 183
184**Subagentes de usuário** (`~/.claude/agents/`) são subagentes pessoais disponíveis em todos os seus projetos.184**Subagentes de usuário** (`~/.claude/agents/`) são subagentes pessoais disponíveis em todos os seus projetos.
185 185
186Claude Code verifica `.claude/agents/` e `~/.claude/agents/` recursivamente, para que você possa organizar 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.186O 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.
187 187
188Mantenha valores de `name` únicos em toda a árvore: se dois arquivos sob o mesmo diretório `.claude/agents/`, incluindo suas subpastas, declaram o mesmo nome, Claude Code carrega apenas um deles, escolhido pela ordem de leitura do sistema de arquivos em vez de uma precedência documentada. Entre diretórios de projeto aninhados, a definição mais próxima do diretório de trabalho vence, conforme descrito acima. O verificador de configuração [`/doctor`](/docs/pt/commands#all-commands) relata arquivos no mesmo diretório que compartilham um nome e propõe renomear ou remover todos exceto um. Antes da v2.1.205, `/doctor` abria uma tela de diagnósticos que listava duplicatas e mostrava qual definição estava ativa.188Mantenha 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`](/docs/pt/commands#all-commands) informa arquivos no mesmo diretório que compartilham um nome e propõe renomear ou remover todos, exceto um. Antes da v2.1.205, o `/doctor` abria uma tela de diagnóstico que listava duplicatas e mostrava qual definição estava ativa.
189 189
190Diretórios `agents/` de plugin também são verificados recursivamente. Diferentemente dos escopos de projeto e usuário, uma subpasta dentro do diretório `agents/` de um plugin se torna parte do [identificador com escopo](#invoke-subagents-explicitly): um arquivo em `agents/review/security.md` no plugin `my-plugin` se registra como `my-plugin:review:security`.190Os 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](#invoke-subagents-explicitly): um arquivo em `agents/review/security.md` no plugin `my-plugin` é registrado como `my-plugin:review:security`.
191 191
192**Subagentes definidos por CLI** são passados como JSON ao iniciar Claude Code. Eles existem apenas para essa sessão e não são salvos em disco, tornando-os úteis para testes rápidos ou scripts de automação. Você pode definir múltiplos subagentes em uma única chamada `--agents`:192**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`:
193 193
194<Tabs>194<Tabs>
195 <Tab title="macOS, Linux, WSL">195 <Tab title="macOS, Linux, WSL">
229 </Tab>229 </Tab>
230</Tabs>230</Tabs>
231 231
232Em [modo não interativo](/docs/pt/headless), `--agents` também aceita o caminho para um arquivo JSON contendo o mesmo objeto, para definições muito grandes para passar na linha de comando. Por exemplo, `claude -p --agents ./agents.json "Review my changes"` lê as definições daquele arquivo. Em uma sessão interativa, Claude Code recusa um caminho de arquivo. O formulário de arquivo requer Claude Code v2.1.281 ou posterior.232No [modo não interativo](/docs/pt/headless), `--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.
233 233
234Cada chave de nível superior no JSON é o nome de um agente, e seu valor é a definição daquele agente. Não comece um nome com `-`. Uma definição leva estes campos:234Cada 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:
235 235
236* **`prompt`**: o prompt de sistema do agente, equivalente ao corpo markdown em subagentes baseados em arquivo. `prompt` pode estar vazio. Se você selecionar um agente com um `prompt` vazio e nenhum campo `memory` como o agente da sessão com `--agent`, o prompt de sistema da sessão é deixado inalterado. Um `prompt` vazio requer Claude Code v2.1.281 ou posterior.236* **`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.
237* **[Campos de frontmatter](#supported-frontmatter-fields)**: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `omitClaudeMd` e `isolation`.237* **[Campos do frontmatter](#supported-frontmatter-fields)**: `description`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `omitClaudeMd` e `isolation`.
238* **Campos ignorados**: `color` e `experimental` não são aceitos aqui e são ignorados em vez de rejeitados.238* **Campos ignorados**: `color` e `experimental` não são aceitos aqui e são ignorados em vez de rejeitados.
239 239
240Para o que Claude Code faz com um valor que não consegue carregar, e os flags e variável de ambiente que pulam essa verificação, veja [`Invalid --agents configuration`](/docs/pt/errors#invalid-agents-configuration).240Para 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`](/docs/pt/errors#invalid-agents-configuration).
241 241
242**Subagentes gerenciados** são implantados por administradores da organização. Coloque arquivos markdown em `.claude/agents/` dentro do [diretório de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms), usando o mesmo formato de frontmatter que subagentes de projeto e usuário. Definições gerenciadas têm precedência sobre subagentes de projeto e usuário com o mesmo nome.242**Subagentes gerenciados** são implantados por administradores da organização. Coloque arquivos markdown em `.claude/agents/` dentro do [diretório de configurações gerenciadas](/docs/pt/managed-settings#delivery-mechanisms), 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.
243 243
244**Subagentes de plugin** vêm de [plugins](/docs/pt/plugins/overview) que você instalou. Eles carregam automaticamente junto com seus subagentes personalizados e aparecem na digitação de @-menção sob seu nome com escopo. Veja a [referência de componentes de plugin](/docs/pt/plugins/components#agents) para detalhes sobre como criar subagentes de plugin.244**Subagentes de plugin** vêm de [plugins](/docs/pt/plugins/overview) 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](/docs/pt/plugins/components#agents) para detalhes sobre como criar subagentes de plugin.
245 245
246<Note>246<Note>
247 Por razões de segurança, subagentes de plugin não suportam os campos de frontmatter `hooks`, `mcpServers` ou `permissionMode`. Estes 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`](/docs/pt/settings-reference#permissions-allow) em `settings.json` ou `settings.local.json`, mas estas regras se aplicam a toda a sessão, não apenas ao subagente do plugin.247 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`](/docs/pt/settings-reference#permissions-allow) em `settings.json` ou `settings.local.json`, mas essas regras se aplicam à sessão inteira, não apenas ao subagente do plugin.
248 248
249 Se você é o autor do plugin, inclua os hooks no [`hooks/hooks.json`](/docs/pt/plugins/components#hooks) do plugin e os servidores MCP no seu [`.mcp.json`](/docs/pt/plugins/components#mcp-servers) em vez disso. Eles se aplicam sempre que o plugin está habilitado, e não apenas dentro do subagente.249 Se você é o autor do plugin, distribua os hooks no [`hooks/hooks.json`](/docs/pt/plugins/components#hooks) do plugin e os servidores MCP no seu [`.mcp.json`](/docs/pt/plugins/components#mcp-servers). Eles se aplicam sempre que o plugin está habilitado, e não apenas dentro do subagente.
250</Note>250</Note>
251 251
252Você também pode reutilizar uma definição de subagente como um colega de trabalho de uma [equipe de agentes](/docs/pt/agent-teams): nomeie o tipo de subagente quando pedir a Claude para gerar o colega de trabalho, e Claude Code aplica partes dessa definição a ele. [Usar definições de subagente para colegas de trabalho](/docs/pt/agent-teams#use-subagent-definitions-for-teammates) indica quais escopos e quais partes se aplicam em cada modo de exibição.252Você também pode reutilizar uma definição de subagente como colega de uma [equipe de agentes](/docs/pt/agent-teams): 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](/docs/pt/agent-teams#use-subagent-definitions-for-teammates) informa quais escopos e quais partes se aplicam em cada modo de exibição.
253 253
254<h3 id="write-subagent-files">254<h3 id="write-subagent-files">
255 Escrever arquivos de subagente255 Escrever arquivos de subagentes
256</h3>256</h3>
257 257
258Arquivos de subagente usam frontmatter YAML para configuração, seguido pelo prompt de sistema em Markdown:258Os arquivos de subagentes usam frontmatter YAML para configuração, seguido pelo system prompt em Markdown:
259 259
260<Note>260<Note>
261 Claude Code observa `~/.claude/agents/` e `.claude/agents/`. Quando você adiciona ou edita um arquivo de subagente no disco, ou pede a Claude para escrever um para você, Claude Code detecta a alteração em alguns segundos e a próxima delegação usa a definição atualizada, sem necessidade de reinicialização.261 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.
262 262
263 Três casos ainda precisam de uma reinicialização:263 Três casos ainda exigem reinicialização:
264 264
265 * O observador 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.265 * 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.
266 * Claude Code não observa `.claude/agents/` dentro de diretórios adicionados com `--add-dir` ou `/add-dir`, portanto após adicionar ou editar um subagente lá, reinicie para carregar a alteração.266 * 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.
267 * Sessões iniciadas com `--disable-slash-commands` não observam esses diretórios.267 * Sessões iniciadas com `--disable-slash-commands` não monitoram esses diretórios de forma alguma.
268</Note>268</Note>
269 269
270```markdown .claude/agents/code-reviewer.md theme={null}270```markdown .claude/agents/code-reviewer.md theme={null}
279specific, actionable feedback on quality, security, and best practices.279specific, actionable feedback on quality, security, and best practices.
280```280```
281 281
282O frontmatter define os metadados e configuração do subagente. O corpo se torna o prompt de sistema que guia o comportamento do subagente. Subagentes recebem apenas este prompt de sistema mais detalhes básicos de ambiente como diretório de trabalho, não o prompt de sistema do Claude Code.282O 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.
283 283
284Em [modo não interativo](/docs/pt/headless), passe [`--append-subagent-system-prompt`](/docs/pt/cli-reference#cli-flags) para anexar seu texto ao final do prompt de sistema de cada subagente, incluindo subagentes aninhados, exceto um [subagente bifurcado](#fork-the-current-conversation), que reutiliza o prompt da conversa. Requer Claude Code v2.1.205 ou posterior. Se seu texto for muito longo para passar na linha de comando, salve-o em um arquivo e passe o caminho com `--append-subagent-system-prompt-file` em vez disso. O flag de arquivo requer Claude Code v2.1.261 ou posterior.284No [modo não interativo](/docs/pt/headless), passe [`--append-subagent-system-prompt`](/docs/pt/cli-reference#cli-flags) para acrescentar seu texto ao final do system prompt de cada subagente, incluindo subagentes aninhados, exceto um [subagente bifurcado](#fork-the-current-conversation), 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.
285 285
286Um subagente começa no diretório de trabalho atual da conversa principal. Dentro de um subagente, comandos `cd` não persistem entre chamadas de 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 em vez disso, defina [`isolation: worktree`](#supported-frontmatter-fields).286Um 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`](#supported-frontmatter-fields).
287 287
288Um subagente com `isolation: worktree` executa seus comandos Bash e PowerShell dentro de seu worktree. Um comando cujo diretório de trabalho se resolve para seu checkout principal, por exemplo porque o diretório worktree foi removido enquanto o subagente estava em execução, falha com um erro. Antes da v2.1.203, tal comando poderia ser executado no checkout principal.288Um 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. Antes da v2.1.203, tal comando podia ser executado no checkout principal.
289 289
290Esta verificação de diretório de trabalho cobre todo o repositório contendo o diretório a partir do qual você iniciou Claude Code. Quando sua sessão é executada em um [worktree](/docs/pt/worktrees) vinculado de sua própria, a verificação também cobre o checkout principal do qual esse worktree está vinculado. Antes da v2.1.210, a verificação cobria apenas o diretório de inicialização em si. Um comando cujo diretório de trabalho se resolveu em outro lugar no mesmo repositório, como a raiz do repositório quando você iniciou Claude Code a partir de um subdiretório de monorepo, era executado lá em vez de falhar.290Essa 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](/docs/pt/worktrees) vinculado próprio, a verificação também abrange o checkout principal ao qual esse worktree está vinculado. Antes da v2.1.210, a verificação abrangia apenas o próprio diretório de inicialização. Um comando cujo diretório de trabalho resolvia para outro lugar no mesmo repositório, como a raiz do repositório quando você iniciava o Claude Code a partir de um subdiretório de um monorepo, era executado ali em vez de falhar.
291 291
292Para comandos Bash, Claude Code também verifica o comando em si de duas maneiras:292Para comandos Bash, o Claude Code também verifica o próprio comando de duas maneiras:
293 293
294* Ele bloqueia um comando que redireciona git para o checkout principal.294* Ele bloqueia um comando que redireciona o git para o checkout principal.
295* Ele recusa um comando quando não consegue verificar a partir do texto do comando que qualquer git que o comando executa permanece dentro do worktree, por exemplo quando o nome do comando é calculado em tempo de execução.295* 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.
296 296
297Os vetores de redirecionamento e as regras de forma estão listados em [Como Claude Code impõe isolamento](/docs/pt/worktrees#how-claude-code-enforces-isolation). Comandos PowerShell recebem apenas a verificação de diretório de trabalho.297Os vetores de redirecionamento e as regras de formato estão listados em [Como o Claude Code aplica o isolamento](/docs/pt/worktrees#how-claude-code-enforces-isolation). Comandos PowerShell recebem apenas a verificação de diretório de trabalho.
298 298
299Comandos [Monitor](/docs/pt/tools-reference#monitor-tool) passam pelas mesmas verificações de diretório de trabalho e conteúdo de comando que comandos Bash.299Comandos do [Monitor](/docs/pt/tools-reference#monitor-tool) passam pelas mesmas verificações de diretório de trabalho e de conteúdo do comando que os comandos Bash.
300 300
301Quando a conversa principal em si é executada isolada em um worktree, Claude Code aplica as mesmas verificações à sessão e a cada subagente que ela gera, incluindo subagentes sem `isolation: worktree`; veja [Como Claude Code impõe isolamento](/docs/pt/worktrees#how-claude-code-enforces-isolation).301Quando 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](/docs/pt/worktrees#how-claude-code-enforces-isolation).
302 302
303<h3 id="supported-frontmatter-fields">303<h3 id="supported-frontmatter-fields">
304 Referência de frontmatter304 Referência do frontmatter
305</h3>305</h3>
306 306
307Configure um subagente com [frontmatter](/docs/pt/glossary#frontmatter) YAML entre marcadores `---` no topo de seu arquivo, e escreva seu prompt de sistema como Markdown após o `---` de fechamento. Apenas `name` e `description` são obrigatórios.307Configure um subagente com [frontmatter](/docs/pt/glossary#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.
308 308
309Nomes de campo com múltiplas palavras usam camelCase, como `maxTurns` e `disallowedTools`, e devem corresponder à tabela exatamente: Claude Code ignora um campo que não reconhece sem relatar um erro. Para descobrir por que um arquivo de subagente não carregou, veja [Arquivos de subagente que Claude Code pula](#subagent-files-claude-code-skips).309Nomes 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 descobrir por que um arquivo de subagente não foi carregado, consulte [Arquivos de subagentes que o Claude Code ignora](#subagent-files-claude-code-skips).
310 310
311| Field | Required | Description |311| Campo | Obrigatório | Descrição |
312| :- | :- | :- |312| :- | :- | :- |
313| `name` | Yes | Identificador único, como `code-reviewer` ou `reviewer-v2`. [Hooks](/docs/pt/hooks#subagentstart) recebem este valor como `agent_type`. O nome do arquivo não precisa corresponder. Nomes não podem conter `:`, que é reservado para [identificadores com escopo de plugin](/docs/pt/plugins/overview) como `my-plugin:reviewer`. Claude Code não carrega um arquivo cujo nome contém um e registra um erro no log de debug. Antes da v2.1.218, tais nomes eram aceitos |313| `name` | Sim | Identificador único, como `code-reviewer` ou `reviewer-v2`. Os [hooks](/docs/pt/hooks#subagentstart) recebem esse valor como `agent_type`. O nome do arquivo não precisa corresponder. Os nomes não podem conter `:`, que é reservado para [identificadores com escopo de plugin](/docs/pt/plugins/overview) como `my-plugin:reviewer`. O Claude Code não carrega um arquivo cujo nome contenha esse caractere e registra um erro no log de depuração. Antes da v2.1.218, esses nomes eram aceitos |
314| `description` | Yes | Quando Claude deve delegar para este subagente |314| `description` | Sim | Quando o Claude deve delegar a este subagente |
315| `tools` | No | [Ferramentas](#available-tools) que o subagente pode usar, como uma string separada por vírgulas como `Read, Grep, Bash` ou uma lista YAML. Herda todas as ferramentas disponíveis para subagentes se omitido. Se nenhuma entrada na lista se resolver para uma ferramenta, o subagente geralmente [falha ao iniciar](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) com um erro nomeando as entradas. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |315| `tools` | Não | [Ferramentas](#available-tools) que o subagente pode usar, como uma string separada por vírgulas, como `Read, Grep, Bash`, ou uma lista YAML. Herda todas as ferramentas disponíveis para subagentes se omitido. Se nenhuma entrada da lista resolver para uma ferramenta, o subagente geralmente [falha ao iniciar](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) com um erro que nomeia as entradas. Para pré-carregar Skills no contexto, use o campo `skills` em vez de listar `Skill` aqui |
316| `disallowedTools` | No | Ferramentas a negar, removidas da lista herdada ou especificada. Mesmo formato que `tools`. Uma entrada com um especificador, como `Bash(git push *)`, ainda [remove a ferramenta inteira](#available-tools) |316| `disallowedTools` | Não | Ferramentas a negar, removidas da lista herdada ou especificada. Mesmo formato de `tools`. Uma entrada com especificador, como `Bash(git push *)`, ainda [remove a ferramenta inteira](#available-tools) |
317| `model` | No | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, `fable`, um ID de modelo completo como `claude-opus-5-5`, ou `inherit`. Quando você omite, Claude Code escolhe o modelo na [ordem de modelo de subagente](#choose-a-model) |317| `model` | Não | [Modelo](#choose-a-model) a usar: `sonnet`, `opus`, `haiku`, `fable`, um ID de modelo completo como `claude-opus-5-5`, ou `inherit`. Quando você o omite, o Claude Code escolhe o modelo na [ordem de modelos de subagentes](#choose-a-model) |
318| `permissionMode` | No | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, ou `manual` como um alias para `default`. O alias `manual` requer Claude Code v2.1.200 ou posterior. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |318| `permissionMode` | Não | [Modo de permissão](#permission-modes): `default`, `acceptEdits`, `auto`, `dontAsk`, `bypassPermissions`, `plan`, ou `manual` como alias para `default`. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |
319| `maxTurns` | No | Número máximo de turnos de agente antes do subagente parar. Quando o subagente atinge o limite, Claude Code retorna sua saída marcada como parcial, e Claude pode [retomá-lo](#resume-subagents) para continuar. A marcação parcial requer Claude Code v2.1.246 ou posterior |319| `maxTurns` | Não | Número máximo de turnos agênticos antes de o subagente parar. Quando o subagente atinge o limite, o Claude Code retorna sua saída marcada como parcial, e o Claude pode [retomá-lo](#resume-subagents) para continuar. A marcação parcial requer o Claude Code v2.1.246 ou posterior |
320| `skills` | No | [Skills](/docs/pt/skills) a pré-carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas a descrição. Subagentes ainda podem invocar skills de projeto, usuário e plugin não listadas através da ferramenta Skill |320| `skills` | Não | [Skills](/docs/pt/skills) a pré-carregar no contexto do subagente na inicialização. O conteúdo completo da skill é injetado, não apenas a descrição. Os subagentes ainda podem invocar skills de projeto, de usuário e de plugin não listadas por meio da ferramenta Skill |
321| `mcpServers` | No | [MCP servers](/docs/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor referenciando um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de MCP server](/docs/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |321| `mcpServers` | Não | [Servidores MCP](/docs/pt/mcp) disponíveis para este subagente. Cada entrada é um nome de servidor que referencia um servidor já configurado (por exemplo, `"slack"`) ou uma definição inline com o nome do servidor como chave e uma [configuração completa de servidor MCP](/docs/pt/mcp#installing-mcp-servers) como valor. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |
322| `hooks` | No | [Lifecycle hooks](#define-hooks-for-subagents) com escopo para este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |322| `hooks` | Não | [Hooks de ciclo de vida](#define-hooks-for-subagents) restritos a este subagente. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |
323| `memory` | No | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project`, ou `local`. Habilita aprendizado entre sessões |323| `memory` | Não | [Escopo de memória persistente](#enable-persistent-memory): `user`, `project` ou `local`. Permite aprendizado entre sessões |
324| `background` | No | Defina como `true` para manter este subagente em background mesmo quando Claude pede para executá-lo em foreground. Onde [fork mode](#turn-fork-mode-on-or-off) está ativado, Claude Code já executa os subagentes que Claude gera [em background](#run-subagents-in-foreground-or-background) |324| `background` | Não | Defina como `true` para manter este subagente em segundo plano mesmo quando o Claude pedir para executá-lo em primeiro plano. Onde o [modo fork](#turn-fork-mode-on-or-off) está ativado, o Claude Code já executa os subagentes que o Claude cria [em segundo plano](#run-subagents-in-foreground-or-background) |
325| `omitClaudeMd` | No | Defina como `true` para iniciar este subagente sem os arquivos CLAUDE.md de usuário, projeto e local; [arquivos de política gerenciada](/docs/pt/memory#how-claude-md-files-load) ainda carregam, exceto para [subagentes gerenciados](#choose-the-subagent-scope). Use-o para subagentes que pegam tudo que precisam do [prompt de delegação](#what-loads-at-startup). Ignorado quando o agente é executado como o agente da sessão principal via `--agent` ou a configuração `agent`. Requer Claude Code v2.1.271 ou posterior |325| `omitClaudeMd` | Não | Defina como `true` para iniciar este subagente sem os arquivos CLAUDE.md de usuário, de projeto e locais; os [arquivos de política gerenciada](/docs/pt/memory#how-claude-md-files-load) ainda são carregados, exceto para [subagentes gerenciados](#choose-the-subagent-scope). Use-o para subagentes que obtêm tudo de que precisam do [prompt de delegação](#what-loads-at-startup). Ignorado quando o agente é executado como agente da sessão principal via `--agent` ou a configuração `agent`. Requer o Claude Code v2.1.271 ou posterior |
326| `effort` | No | Nível de esforço quando este subagente está ativo. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo |326| `effort` | Não | Nível de esforço quando este subagente está ativo. Sobrescreve o nível de esforço da sessão. Padrão: herda da sessão. Opções: `low`, `medium`, `high`, `xhigh`, `max`; os níveis disponíveis dependem do modelo |
327| `isolation` | No | Defina como `worktree` para executar o subagente em um [git worktree](/docs/pt/worktrees) temporário, dando-lhe uma cópia isolada do repositório ramificada por padrão a partir de sua [branch padrão](/docs/pt/worktrees#choose-the-base-branch) em vez do `HEAD` da sessão pai. O worktree é automaticamente limpo se o subagente não fizer alterações |327| `isolation` | Não | Defina como `worktree` para executar o subagente em um [git worktree](/docs/pt/worktrees) temporário, dando a ele uma cópia isolada do repositório criada por padrão a partir do seu [branch padrão](/docs/pt/worktrees#choose-the-base-branch), e não do `HEAD` da sessão pai. O worktree é limpo automaticamente se o subagente não fizer alterações |
328| `color` | No | Cor de exibição para o subagente na lista de tarefas e transcrição. Aceita `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, ou `cyan` |328| `color` | Não | Cor de exibição do subagente na lista de tarefas e na transcrição. Aceita `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink` ou `cyan` |
329| `initialPrompt` | No | Auto-enviado como o primeiro turno do usuário quando este agente é executado como o agente da sessão principal (via `--agent` ou a configuração `agent`). [Comandos](/docs/pt/commands) e [skills](/docs/pt/skills) são processados. Preposto a qualquer prompt fornecido pelo usuário. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |329| `initialPrompt` | Não | Enviado automaticamente como o primeiro turno do usuário quando este agente é executado como agente da sessão principal (via `--agent` ou a configuração `agent`). [Comandos](/docs/pt/commands) e [skills](/docs/pt/skills) são processados. Adicionado antes de qualquer prompt fornecido pelo usuário. Ignorado para [subagentes de plugin](#choose-the-subagent-scope) |
330| `experimental` | No | Mapa de opções experimentais. Defina sua chave `cacheTtl` como `5m` ou `1h` para escolher o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#choose-the-ttl-yourself) para as solicitações deste subagente, no lugar da [precedência de tempo de vida do cache](/docs/pt/prompt-caching#choose-the-ttl-yourself). Claude Code ignora qualquer outro valor, ignora `1h` enquanto sua assinatura Claude está usando créditos de uso, e lê o campo apenas de arquivos de subagente. Requer Claude Code v2.1.248 ou posterior |330| `experimental` | Não | Mapa de opções experimentais. Defina sua chave `cacheTtl` como `5m` ou `1h` para escolher o [tempo de vida do cache de prompt](/docs/pt/prompt-caching#choose-the-ttl-yourself) para as requisições deste subagente, na posição do frontmatter na [precedência do tempo de vida do cache](/docs/pt/prompt-caching#choose-the-ttl-yourself). O Claude Code ignora qualquer outro valor, ignora `1h` enquanto sua assinatura do Claude estiver usando créditos de uso e lê o campo apenas de arquivos de subagentes. Requer o Claude Code v2.1.248 ou posterior |
331 331
332Escreva `cacheTtl` dentro do mapa `experimental`, não no nível superior do frontmatter.332Escreva `cacheTtl` dentro do mapa `experimental`, não no nível superior do frontmatter.
333 333
341```341```
342 342
343<h4 id="subagent-files-claude-code-skips">343<h4 id="subagent-files-claude-code-skips">
344 Arquivos de subagente que Claude Code pula344 Arquivos de subagentes que o Claude Code ignora
345</h4>345</h4>
346 346
347Claude Code pula um arquivo em um diretório `agents` de projeto, 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 qualquer um desses problemas:347O 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:
348 348
349* **Sem `name`**: Claude Code trata o arquivo como documentação mantida ao lado de seus agentes.349* **Sem `name`**: o Claude Code trata o arquivo como documentação mantida ao lado dos seus agentes.
350* **Um `---` de abertura que não é a primeira linha do arquivo**: Claude Code lê o arquivo como não tendo frontmatter e o trata como documentação.350* **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.
351* **Um `name` que começa com `-` ou contém `:`**: Claude Code pula o arquivo e escreve um erro no log de debug. Veja a linha `name` na tabela acima.351* **Um `name` que começa com `-` ou contém `:`**: o Claude Code ignora o arquivo e grava um erro no log de depuração. Consulte a linha `name` na tabela acima.
352* **Um `name` mas sem `description`**: Claude Code pula o arquivo e escreve o motivo no log de debug.352* **Um `name` mas sem `description`**: o Claude Code ignora o arquivo e grava o motivo no log de depuração.
353* **YAML que não analisa**: Claude Code não lê campos do arquivo, o pula e escreve o erro de análise no log de debug.353* **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.
354 354
355Para ver o log de debug, execute Claude Code com `--debug`.355Para ver o log de depuração, execute o Claude Code com `--debug`.
356 356
357Um [subagente de plugin](/docs/pt/plugins/components#agents) cujo frontmatter não tem `name` ou não analisa ainda carrega, sob seu nome de arquivo.357Um [subagente de plugin](/docs/pt/plugins/components#agents) cujo frontmatter não tem `name` ou não pode ser analisado ainda é carregado, sob o nome do seu arquivo.
358 358
359<h5 id="check-an-agents-directory-before-a-session">359<h5 id="check-an-agents-directory-before-a-session">
360 Verificar um diretório `agents` antes de uma sessão360 Verificar um diretório `agents` antes de uma sessão
361</h5>361</h5>
362 362
363Para encontrar arquivos em um diretório `agents` cujo frontmatter não analisa, execute `claude plugin validate` contra o diretório, por exemplo `.claude/agents` ou `~/.claude/agents`. Claude Code verifica apenas [o diretório que você nomeia](/docs/pt/plugins/cli-reference#validate-a-directory), e não sinaliza um arquivo cujo frontmatter analisa mas não tem `name`. Requer Claude Code v2.1.233 ou posterior.363Para 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](/docs/pt/plugins/cli-reference#validate-a-directory) e não sinaliza um arquivo cujo frontmatter é analisado, mas não tem `name`. Requer o Claude Code v2.1.233 ou posterior.
364 364
365<h3 id="choose-a-model">365<h3 id="choose-a-model">
366 Escolher um modelo366 Escolher um modelo
368 368
369O campo `model` controla qual modelo o subagente usa:369O campo `model` controla qual modelo o subagente usa:
370 370
371* **Alias de modelo**: use um dos aliases disponíveis: `sonnet`, `opus`, `haiku`, ou `fable`371* **Alias de modelo**: use um dos aliases disponíveis: `sonnet`, `opus`, `haiku` ou `fable`
372* **ID de modelo completo**: use um ID de modelo completo como `claude-opus-5-5` ou `claude-sonnet-5`. Aceita os mesmos valores que o flag `--model`372* **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`
373* **inherit**: use o mesmo modelo que a conversa principal373* **inherit**: use o mesmo modelo da conversa principal
374 374
375Quando Claude invoca um subagente, ele também pode passar um parâmetro `model` para essa invocação específica. Claude Code resolve o modelo do subagente nesta ordem:375Quando o Claude invoca um subagente, ele também pode passar um parâmetro `model` para aquela invocação específica. O Claude Code resolve o modelo do subagente nesta ordem:
376 376
3771. O parâmetro `model` por invocação3771. O parâmetro `model` por invocação
3782. O frontmatter `model` da definição do subagente, onde `inherit` seleciona o modelo da conversa principal3782. O frontmatter `model` da definição do subagente, em que `inherit` seleciona o modelo da conversa principal
3793. A variável de ambiente [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/pt/model-config#environment-variables), quando você a define para um alias de modelo ou ID de modelo3793. A variável de ambiente [`CLAUDE_CODE_SUBAGENT_MODEL`](/docs/pt/model-config#environment-variables), quando você a define como um alias de modelo ou ID de modelo
3804. O modelo da conversa principal3804. O modelo da conversa principal
381 381
382Em dois casos, um alias de família como `opus` no parâmetro por invocação ou no frontmatter se resolve para o modelo da conversa principal em vez da [versão para a qual o alias aponta](/docs/pt/model-config#model-aliases):382Em 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](/docs/pt/model-config#model-aliases):
383 383
384* **O modelo da conversa principal pertence a essa família**: o subagente é executado no modelo exato da conversa principal, incluindo qualquer sufixo `[1m]`, portanto obtém a mesma janela de [contexto estendido](/docs/pt/model-config#extended-context) que a conversa principal.384* **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](/docs/pt/model-config#extended-context) da conversa principal.
385* **Claude Code não consegue dizer a família do modelo da conversa principal, em [um provedor diferente da API Anthropic](/docs/pt/third-party-integrations)**: isso pode acontecer com um [ARN de perfil de inferência de aplicação](/docs/pt/amazon-bedrock#iam-configuration) no Amazon Bedrock que Claude Code não resolveu para um modelo de suporte. Este caso cobre apenas o alias `opus`, e não se aplica quando você define [`ANTHROPIC_DEFAULT_OPUS_MODEL`](/docs/pt/model-config#environment-variables), já que `opus` então se resolve para o modelo que você definiu.385* **O Claude Code não consegue identificar a família do modelo da conversa principal, em [um provedor diferente da API da Anthropic](/docs/pt/third-party-integrations)**: isso pode acontecer com um [ARN de perfil de inferência de aplicação](/docs/pt/amazon-bedrock#iam-configuration) 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`](/docs/pt/model-config#environment-variables), pois `opus` então resolve para o modelo que você definiu.
386 386
387Um alias em `CLAUDE_CODE_SUBAGENT_MODEL` sempre se resolve para a versão para a qual o alias aponta, mesmo quando nomeia a família da conversa principal.387Um 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.
388 388
389Definir `CLAUDE_CODE_SUBAGENT_MODEL` por si só não muda o modelo em que os subagentes Explore e Plan integrados são executados. Para mudá-lo, veja [Executar cada subagente em um modelo](#run-every-subagent-on-one-model).389Definir `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](#run-every-subagent-on-one-model).
390 390
391Antes 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`.391Antes 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`.
392 392
393Definir a variável para `inherit` é o mesmo que deixá-la indefinida. Antes da v2.1.196, esse valor forçava subagentes para o modelo da conversa principal e ignorava as outras fontes.393Definir a variável como `inherit` é o mesmo que deixá-la sem definição. Antes da v2.1.196, esse valor forçava os subagentes a usar o modelo da conversa principal e ignorava as outras fontes.
394 394
395Claude Code verifica o parâmetro por invocação, frontmatter e valores de variável de ambiente contra a lista de permissões [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização. Para um valor bloqueado, ele substitui outro modelo:395O Claude Code verifica os valores do parâmetro por invocação, do frontmatter e da variável de ambiente em relação à allowlist [`availableModels`](/docs/pt/model-config#restrict-model-selection) da sua organização. Para um valor bloqueado, ele substitui por outro modelo:
396 396
397* Quando o valor bloqueado é um alias de família como `opus`, Claude Code executa o subagente na versão mais recente dessa família que a lista de permissões permite, seguindo as mesmas [regras de substituição e escopo de provedor](/docs/pt/model-config#restrict-model-selection) que `/model`. Antes da v2.1.222, Claude Code executava o subagente no modelo herdado para um alias de família bloqueado também.397* 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](/docs/pt/model-config#restrict-model-selection) 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.
398* Para qualquer outro valor bloqueado, em provedores onde essa substituição não opera, ou quando a lista de permissões não permite nenhuma versão da família, Claude Code executa o subagente no modelo herdado em vez disso. Se você definir `CLAUDE_CODE_SUBAGENT_MODEL`, Claude Code tenta esse modelo primeiro, sob essas mesmas regras.398* 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.
399 399
400Em sessões interativas, Claude Code mostra um aviso nomeando o modelo solicitado e o modelo em que o subagente é executado, para qualquer substituição.400Em 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.
401 401
402Para verificar qual modelo um subagente está executando, execute [`/tasks`](/docs/pt/commands). Claude Code nomeia o modelo na linha do subagente, e adiciona o [nível de esforço](/docs/pt/model-config#adjust-effort-level) quando a definição do subagente, ou a skill da qual ele se bifurcou, define [`effort`](#supported-frontmatter-fields). Requer Claude Code v2.1.242 ou posterior.402Para verificar em qual modelo um subagente está sendo executado, execute [`/tasks`](/docs/pt/commands). O Claude Code nomeia o modelo na linha do subagente e adiciona o [nível de esforço](/docs/pt/model-config#adjust-effort-level) quando a definição do subagente, ou a skill da qual ele foi bifurcado, define [`effort`](#supported-frontmatter-fields). Requer o Claude Code v2.1.242 ou posterior.
403 403
404Um parâmetro `model` por invocação também se aplica quando o subagente é [retomado ou enviado uma mensagem de acompanhamento](#resume-subagents), portanto o subagente permanece nesse modelo. Antes da v2.1.211, retomar descartava o valor por invocação e o subagente revertia para o campo `model` de sua definição ou, sem um, o modelo da conversa principal.404Um parâmetro `model` por invocação também se aplica quando o subagente é [retomado ou recebe uma mensagem de acompanhamento](#resume-subagents), de modo que o subagente permanece nesse modelo. Antes da v2.1.211, a retomada descartava o valor por invocação e o subagente voltava ao campo `model` da sua definição ou, na ausência dele, ao modelo da conversa principal.
405 405
406A partir da v2.1.198, subagentes também herdam a configuração de [pensamento estendido](/docs/pt/model-config#extended-thinking) da conversa principal: se o pensamento está ativado em sua sessão, está ativado para o subagente, e se está desativado, permanece desativado. Não há configuração de pensamento por subagente. Antes da v2.1.198, subagentes eram executados com pensamento estendido desabilitado independentemente da configuração da conversa principal.406A partir da v2.1.198, os subagentes também herdam a configuração de [pensamento estendido](/docs/pt/model-config#extended-thinking) 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.
407 407
408<h4 id="run-every-subagent-on-one-model">408<h4 id="run-every-subagent-on-one-model">
409 Executar cada subagente em um modelo409 Executar todos os subagentes em um único modelo
410</h4>410</h4>
411 411
412`CLAUDE_CODE_SUBAGENT_MODEL` é um padrão, portanto a definição de um subagente ou um modelo que Claude passa ainda tem precedência sobre ele. Para aplicar um modelo a cada subagente, [colega de trabalho](/docs/pt/agent-teams#specify-teammates-and-models) e [agente de workflow](/docs/pt/workflows), também defina `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` para `1`. Requer Claude Code v2.1.257 ou posterior.412`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](/docs/pt/agent-teams#specify-teammates-and-models) e [agentes de workflow](/docs/pt/workflows), defina também `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` como `1`. Requer o Claude Code v2.1.257 ou posterior.
413 413
414* Se você definir ambas as variáveis, subagentes são executados no modelo em `CLAUDE_CODE_SUBAGENT_MODEL`.414* Se você definir ambas as variáveis, os subagentes são executados no modelo em `CLAUDE_CODE_SUBAGENT_MODEL`.
415* Se você definir apenas `CLAUDE_CODE_SUBAGENT_MODEL_FORCE`, subagentes são executados no modelo da conversa principal, exceto que o subagente Explore integrado é executado no [modelo listado para ele em Subagentes integrados](#built-in-subagents).415* 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](#built-in-subagents).
416 416
417Por exemplo, para executar cada subagente em Haiku, defina ambas as variáveis no bloco `env` de um [arquivo de configurações](/docs/pt/settings):417Por exemplo, para executar todos os subagentes no Haiku, defina ambas as variáveis no bloco `env` de um [arquivo de configurações](/docs/pt/settings):
418 418
419```json theme={null}419```json theme={null}
420{420{
425}425}
426```426```
427 427
428Para verificar que a configuração entrou em vigor, execute [`/tasks`](/docs/pt/commands) enquanto um subagente está em execução. A linha do subagente mostra o modelo em que ele é executado.428Para verificar se a configuração entrou em vigor, execute [`/tasks`](/docs/pt/commands) enquanto um subagente estiver em execução. A linha do subagente mostra o modelo em que ele é executado.
429 429
430Enquanto `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` está [ativado](/docs/pt/env-vars), Claude Code ignora o campo `model` nas definições de subagente, e Claude não pode passar um modelo quando inicia um subagente. Estes subagentes ainda são executados no modelo da conversa principal:430Enquanto `CLAUDE_CODE_SUBAGENT_MODEL_FORCE` estiver [ativada](/docs/pt/env-vars), 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:
431 431
432* Uma [bifurcação](#fork-the-current-conversation)432* Um [fork](#fork-the-current-conversation)
433* Uma [skill que é executada em um subagente](/docs/pt/skills#run-skills-in-a-subagent) com `model: inherit`433* Uma [skill executada em um subagente](/docs/pt/skills#run-skills-in-a-subagent) com `model: inherit`
434 434
435<h3 id="control-subagent-capabilities">435<h3 id="control-subagent-capabilities">
436 Controlar capacidades do subagente436 Controlar as capacidades dos subagentes
437</h3>437</h3>
438 438
439Você pode controlar o que subagentes podem fazer através de acesso a ferramentas, modos de permissão e regras condicionais.439Você pode controlar o que os subagentes podem fazer por meio do acesso a ferramentas, dos modos de permissão e de regras condicionais.
440 440
441<h4 id="available-tools">441<h4 id="available-tools">
442 Ferramentas disponíveis442 Ferramentas disponíveis
443</h4>443</h4>
444 444
445Subagentes herdam as [ferramentas integradas](/docs/pt/tools-reference) e ferramentas MCP disponíveis na conversa principal, reduzidas por dois filtros: o primeiro remove uma lista curta de ferramentas de cada subagente, e o segundo reduz o conjunto de ferramentas integradas para subagentes que são executados em [background](#run-subagents-in-foreground-or-background), que é o padrão. Em 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](/docs/pt/tools-reference#glob-tool-behavior). [Bifurcações](#fork-the-current-conversation) pulam ambos os filtros e recebem o pool de ferramentas exato da conversa principal. O primeiro filtro remove essas ferramentas, mesmo quando listadas no campo `tools`:445Os subagentes herdam as [ferramentas integradas](/docs/pt/tools-reference) 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](#run-subagents-in-foreground-or-background), 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](/docs/pt/tools-reference#glob-tool-behavior). Os [forks](#fork-the-current-conversation) 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`:
446 446
447* `Agent`, quando o subagente está no [limite de profundidade](#let-subagents-spawn-their-own-subagents); em uma [bifurcação](#fork-the-current-conversation) a ferramenta permanece listada mas retorna um erro em vez de gerar447* `Agent`, quando o subagente está no [limite de profundidade](#let-subagents-spawn-their-own-subagents); em um [fork](#fork-the-current-conversation), a ferramenta permanece listada, mas retorna um erro em vez de criar um subagente
448* `AskUserQuestion`448* `AskUserQuestion`
449* `EndConversation`, que pode encerrar apenas a conversa principal; veja [comportamento da ferramenta EndConversation](/docs/pt/tools-reference#endconversation-tool-behavior)449* `EndConversation`, que só pode encerrar a conversa principal; consulte [Comportamento da ferramenta EndConversation](/docs/pt/tools-reference#endconversation-tool-behavior)
450* `EnterPlanMode`450* `EnterPlanMode`
451* `ExitPlanMode`, a menos que o [`permissionMode`](#permission-modes) do subagente seja `plan`451* `ExitPlanMode`, a menos que o [`permissionMode`](#permission-modes) do subagente seja `plan`
452* `ScheduleWakeup`452* `ScheduleWakeup`
453* `WaitForMcpServers`453* `WaitForMcpServers`
454* `Workflow`454* `Workflow`
455 455
456O segundo filtro se aplica a subagentes em execução em background. Além de `Agent` e `ExitPlanMode`, que seguem as condições do primeiro filtro onde quer que o subagente seja executado, um subagente em background mantém cada ferramenta MCP mas apenas essas 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`](/docs/pt/tools-reference) para um subagente que relata através dele. Claude Code remove todas as outras ferramentas integradas de um subagente em background, seja herdadas ou listadas no campo `tools`, portanto a mesma definição pode se resolver para ferramentas diferentes em foreground e background. A remoção não relata erro a menos que deixe a lista `tools` [se resolvendo para nada](/docs/pt/errors#agent-would-be-spawned-with-zero-tools).456O 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`](/docs/pt/tools-reference) 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](/docs/pt/errors#agent-would-be-spawned-with-zero-tools).
457 457
458Antes da v2.1.280, subagentes em background não podiam usar `LSP`.458Antes da v2.1.280, os subagentes em segundo plano não podiam usar `LSP`.
459 459
460[`ListAgents`](/docs/pt/cross-session-messaging) segue esses filtros como qualquer ferramenta integrada: um subagente em foreground a herda em sessões onde mensagens entre sessões estão habilitadas, e um subagente em background não a mantém.460[`ListAgents`](/docs/pt/cross-session-messaging) 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.
461 461
462Colegas de trabalho em [equipes de agentes](/docs/pt/agent-teams) adicionalmente mantêm as ferramentas de tarefa e ferramentas cron: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete` e `CronList`.462Os colegas em [equipes de agentes](/docs/pt/agent-teams) mantêm adicionalmente as ferramentas de tarefas e de cron: `TaskCreate`, `TaskGet`, `TaskList`, `TaskUpdate`, `CronCreate`, `CronDelete` e `CronList`.
463 463
464Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), Claude Code não fornece as ferramentas de tarefa a subagentes também, mesmo quando o subagente executa um modelo diferente. Um colega de trabalho em processo segue sua sessão da mesma forma, enquanto um colega de trabalho em seu próprio [painel dividido](/docs/pt/agent-teams#choose-a-display-mode) é executado como um processo Claude Code separado, portanto seu próprio modelo decide.464Em uma [sessão sem as ferramentas Task](/docs/pt/tools-reference#task-tool-availability), 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, enquanto um colega em seu próprio [painel dividido](/docs/pt/agent-teams#choose-a-display-mode) é executado como um processo separado do Claude Code, então é o seu próprio modelo que decide.
465 465
466Para restringir ferramentas, use o campo `tools` como uma lista de permissões ou o campo `disallowedTools` como uma lista de negação. Este exemplo usa `tools` para permitir apenas Read, Grep, Glob e Bash. O subagente não pode editar arquivos, escrever arquivos ou usar qualquer ferramenta MCP:466Para restringir ferramentas, use o campo `tools` como allowlist ou o campo `disallowedTools` como denylist. 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:
467 467
468```yaml theme={null}468```yaml theme={null}
469---469---
473---473---
474```474```
475 475
476Este exemplo usa `disallowedTools` para herdar o pool de ferramentas do subagente exceto Write e Edit. O subagente mantém Bash, ferramentas MCP e o resto de seu pool:476Este 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:
477 477
478```yaml theme={null}478```yaml theme={null}
479---479---
483---483---
484```484```
485 485
486Se ambos forem definidos, `disallowedTools` é aplicado primeiro, depois `tools` é resolvido contra o pool restante. Uma ferramenta listada em ambos é removida.486Se ambos estiverem definidos, `disallowedTools` é aplicado primeiro e, em seguida, `tools` é resolvido em relação ao conjunto restante. Uma ferramenta listada em ambos é removida.
487 487
488Quando nada na lista `tools` se resolve para uma ferramenta, por exemplo porque cada entrada está com erro de digitação ou nomeia uma ferramenta que não está disponível para subagentes, Claude Code geralmente recusa iniciar o subagente e a ferramenta Agent retorna um erro nomeando as entradas não resolvidas; veja [Agent would be spawned with zero tools](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) para a mensagem e como corrigir cada entrada. Antes da v2.1.208, esse subagente era iniciado sem ferramentas e poderia retornar um resultado vazio ou confuso.488Quando 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](/docs/pt/errors#agent-would-be-spawned-with-zero-tools) para ver a mensagem e como corrigir cada entrada. Antes da v2.1.208, esse subagente era iniciado sem ferramentas e podia retornar um resultado vazio ou confuso.
489 489
490Ambos os campos aceitam padrões de nível de servidor MCP além de nomes de ferramentas exatos: `mcp__<server>` ou `mcp__<server>__*` concede ou remove todas as ferramentas do servidor nomeado. Em `disallowedTools`, `mcp__*` também remove todas as ferramentas MCP de qualquer servidor. Este exemplo remove todas as ferramentas do servidor MCP `github` enquanto mantém ferramentas de outros servidores e as ferramentas integradas em seu pool:490Ambos os campos aceitam padrões no nível do servidor MCP, além de nomes exatos de ferramentas: `mcp__<server>` ou `mcp__<server>__*` concede ou remove todas as ferramentas do servidor nomeado. Em `disallowedTools`, `mcp__*` também remove todas as ferramentas MCP de qualquer servidor. Este exemplo remove todas as ferramentas do servidor MCP `github`, mantendo as ferramentas de outros servidores e as ferramentas integradas no seu conjunto:
491 491
492```yaml theme={null}492```yaml theme={null}
493---493---
497---497---
498```498```
499 499
500Uma entrada `disallowedTools` com um especificador, como `Bash(git push *)`, ainda remove a ferramenta inteira do subagente, não apenas os comandos correspondentes. Para manter Bash e bloquear comandos específicos, adicione uma [regra de negação Bash](/docs/pt/permissions#bash) como `Bash(git push *)` a `permissions.deny` em suas configurações. A regra se aplica à conversa principal e aos subagentes.500Uma 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](/docs/pt/permissions#bash), como `Bash(git push *)`, a `permissions.deny` nas suas configurações. A regra se aplica à conversa principal e aos subagentes.
501 501
502<h4 id="restrict-which-subagents-can-be-spawned">502<h4 id="restrict-which-subagents-can-be-spawned">
503 Restringir quais subagentes podem ser gerados503 Restringir quais subagentes podem ser criados
504</h4>504</h4>
505 505
506Quando um agente é executado como thread principal com `claude --agent`, ele pode gerar subagentes usando a ferramenta Agent. Para restringir quais tipos de subagente ele pode gerar, use a sintaxe `Agent(agent_type)` no campo `tools`.506Quando 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`.
507 507
508<Note>Na versão 2.1.63, a ferramenta Task foi renomeada para Agent. Referências existentes de `Task(...)` em configurações e definições de agente ainda funcionam como aliases.</Note>508<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.</Note>
509 509
510```yaml theme={null}510```yaml theme={null}
511---511---
515---515---
516```516```
517 517
518Esta é uma lista de permissões: apenas os subagentes `worker` e `researcher` podem ser gerados. Se o agente tentar gerar qualquer outro tipo, a solicitação falha e o agente vê apenas os tipos permitidos em seu prompt. Para bloquear agentes específicos enquanto permite todos os outros, use [`permissions.deny`](#disable-specific-subagents) em vez disso.518Isto é 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`](#disable-specific-subagents).
519 519
520Para permitir gerar qualquer subagente sem restrições, use `Agent` sem parênteses:520Para permitir a criação de qualquer subagente sem restrições, use `Agent` sem parênteses:
521 521
522```yaml theme={null}522```yaml theme={null}
523tools: Agent, Read, Bash523tools: Agent, Read, Bash
524```524```
525 525
526Se `Agent` for omitido da lista `tools` inteiramente, o agente não pode gerar nenhum subagente com a ferramenta Agent.526Se você omitir `Agent` totalmente da lista `tools`, o agente não poderá criar nenhum subagente com a ferramenta Agent.
527 527
528A sintaxe de lista de permissões `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 gere subagentes de sua própria conta enquanto o [limite de profundidade](#let-subagents-spawn-their-own-subagents) permite, mas qualquer lista de tipo dentro dos parênteses é ignorada.528A 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](#let-subagents-spawn-their-own-subagents) permitir, mas qualquer lista de tipos dentro dos parênteses é ignorada.
529 529
530<h4 id="scope-mcp-servers-to-a-subagent">530<h4 id="scope-mcp-servers-to-a-subagent">
531 Escopo de MCP servers para um subagente531 Restringir servidores MCP a um subagente
532</h4>532</h4>
533 533
534Use o campo `mcpServers` para dar a um subagente acesso a [MCP](/docs/pt/mcp) servers que não estão disponíveis na conversa principal. Servidores inline definidos aqui são conectados quando o subagente inicia, sujeitos à [regra de confiança para a pasta do arquivo do agente](#inline-server-trust), e desconectados quando termina. Referências de string compartilham a conexão da sessão pai.534Use o campo `mcpServers` para dar a um subagente acesso a servidores [MCP](/docs/pt/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](#inline-server-trust), e desconectados quando ele termina. As referências por string compartilham a conexão da sessão pai.
535 535
536<Note>536<Note>
537 O campo `mcpServers` se aplica em ambos os contextos onde um arquivo de agente pode ser executado:537 O campo `mcpServers` se aplica em ambos os contextos em que um arquivo de agente pode ser executado:
538 538
539 * Como um subagente, gerado através da ferramenta Agent ou uma @-menção539 * Como subagente, criado por meio da ferramenta Agent ou de uma @-menção
540 * Como a sessão principal, iniciada com [`--agent`](#invoke-subagents-explicitly) ou a configuração `agent`540 * Como sessão principal, iniciada com [`--agent`](#invoke-subagents-explicitly) ou a configuração `agent`
541 541
542 Quando o agente é a sessão principal, definições de servidor inline se conectam na inicialização junto com servidores de [`.mcp.json`](/docs/pt/mcp) e arquivos de configurações, sob a mesma [regra de confiança para a pasta do arquivo do agente](#inline-server-trust). Em `/mcp`, um servidor remoto (HTTP ou SSE) que você usou antes pode mostrar o status [`cached`](/docs/pt/mcp#managing-your-servers) em vez disso; Claude Code o conecta quando Claude primeiro chama uma de suas ferramentas.542 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`](/docs/pt/mcp) e dos arquivos de configurações, sob a mesma [regra de confiança para a pasta do arquivo do agente](#inline-server-trust). No `/mcp`, um servidor remoto (HTTP ou SSE) que você já usou pode mostrar o [status `cached`](/docs/pt/mcp#managing-your-servers); o Claude Code o conecta quando o Claude chama uma de suas ferramentas pela primeira vez.
543</Note>543</Note>
544 544
545Cada entrada na lista é uma definição de servidor inline ou uma string referenciando um MCP server já configurado em sua sessão:545Cada entrada na lista é uma definição de servidor inline ou uma string que referencia um servidor MCP já configurado na sua sessão:
546 546
547```yaml theme={null}547```yaml theme={null}
548---548---
561Use the Playwright tools to navigate, screenshot, and interact with pages.561Use the Playwright tools to navigate, screenshot, and interact with pages.
562```562```
563 563
564Definições inline usam o mesmo schema que entradas de servidor `.mcp.json`, com chave pelo nome do servidor, e suportam os tipos `stdio`, `http`, `sse` e `ws`.564As 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`.
565 565
566Para manter um MCP server fora da conversa principal inteiramente e evitar que suas descrições de ferramentas consumam contexto lá, defina-o inline aqui em vez de em `.mcp.json`. O subagente obtém as ferramentas; a conversa pai não.566Para 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.
567 567
568As restrições de MCP que se aplicam à sessão principal também cobrem servidores declarados no frontmatter do subagente:568As restrições de MCP que se aplicam à sessão principal também abrangem os servidores declarados no frontmatter do subagente:
569 569
570* [`--strict-mcp-config`](/docs/pt/cli-reference) e [`--bare`](/docs/pt/cli-reference)570* [`--strict-mcp-config`](/docs/pt/cli-reference) e [`--bare`](/docs/pt/cli-reference)
571* [Configuração de MCP gerenciada pela empresa](/docs/pt/managed-mcp)571* [Configuração de MCP gerenciada corporativa](/docs/pt/managed-mcp)
572* [Políticas `allowedMcpServers` e `deniedMcpServers`](/docs/pt/managed-mcp#policy-based-control-with-allowlists-and-denylists)572* [Políticas `allowedMcpServers` e `deniedMcpServers`](/docs/pt/managed-mcp#policy-based-control-with-allowlists-and-denylists)
573 573
574Quando uma destas bloqueia um servidor, Claude Code o ignora e mostra um aviso nomeando os servidores bloqueados.574Quando uma delas bloqueia um servidor, o Claude Code o ignora e mostra um aviso nomeando os servidores bloqueados.
575 575
576Restrições de configurações gerenciadas se aplicam a cada subagente independentemente de como ele é definido. `--strict-mcp-config` não filtra servidores que você passa inline via `--agents` ou a opção `agents` do SDK, já que esses são entrada explícita do chamador.576As 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.
577 577
578<h4 id="inline-server-trust">578<h4 id="inline-server-trust">
579 Confiança necessária para servidores MCP inline579 Confiança exigida para servidores MCP inline
580</h4>580</h4>
581 581
582Claude Code carrega um [servidor MCP inline](#scope-mcp-servers-to-a-subagent) de um arquivo de agente no diretório `.claude/agents/` do seu projeto, ou no `.claude/agents/` de um diretório adicionado com `--add-dir`, apenas depois que você [confia na pasta de onde o arquivo do agente veio](/docs/pt/permissions#what-runs-before-you-trust-a-folder). Antes da v2.1.238, Claude Code carregava esses servidores sem verificar confiança.582O Claude Code carrega um [servidor MCP inline](#scope-mcp-servers-to-a-subagent) 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](/docs/pt/permissions#what-runs-before-you-trust-a-folder). Antes da v2.1.238, o Claude Code carregava esses servidores sem verificar a confiança.
583 583
584* **Confiança que não conta**: confiança de uma pasta pai, e a confiança automática que uma sessão `-p` ou SDK obtém para [hooks em arquivos de configurações](/docs/pt/permissions#what-runs-before-you-trust-a-folder)584* **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](/docs/pt/permissions#what-runs-before-you-trust-a-folder)
585* **Até então**: Claude Code pula cada servidor inline naquele arquivo de agente e escreve a chave exata `projects["<path>"].hasTrustDialogAccepted` para `~/.claude.json` no log de debug585* **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
586* **Diretórios `--add-dir`**: um diretório fora do repositório do espaço de trabalho confiável de sua organização precisa de sua própria entrada de confiança, já que seus arquivos `.claude/agents/` não herdam a confiança do seu espaço de trabalho586* **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
587 587
588Claude Code carrega dois tipos de servidor sem verificar confiança para a pasta de onde o arquivo do agente veio:588O Claude Code carrega dois tipos de servidor sem verificar a confiança da pasta de onde o arquivo do agente veio:
589 589
590* Um nome que referencia um servidor que você já configurou590* Um nome que referencia um servidor que você já configurou
591* 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 fornecem591* 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
594 Modos de permissão594 Modos de permissão
595</h4>595</h4>
596 596
597Defina `permissionMode` para escolher o modo de permissão em que um subagente é executado. Use os valores de configuração dos modos, portanto o modo Manual é `default`. Se você deixar indefinido, o subagente herda o [modo de permissão](/docs/pt/permission-modes) da conversa principal.597Defina `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](/docs/pt/permission-modes) da conversa principal.
598 598
599O modo de permissão da conversa principal decide se Claude Code usa o valor que você definiu:599O modo de permissão da conversa principal decide se o Claude Code usa o valor que você definiu:
600 600
601* Quando a conversa principal está em `bypassPermissions`, `acceptEdits`, ou [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), o subagente é executado nesse mesmo modo e Claude Code ignora o `permissionMode` que você definiu. Sob modo auto, o classificador avalia as chamadas de ferramentas do subagente com as regras de bloqueio e permissão da conversa principal. Quando o subagente termina, o classificador também revisa seu trabalho e seu relatório final antes do relatório ser entregue, conforme [Como o modo auto lida com subagentes](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode) descreve.601* Quando a conversa principal está em `bypassPermissions`, `acceptEdits` ou no [modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode), 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](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode).
602* Quando a conversa principal está em `default`, `dontAsk`, ou modo `plan`, o subagente é executado no modo de permissão que você definiu, exceto `bypassPermissions`. Um subagente que declara `bypassPermissions` mantém o modo da conversa principal em vez disso. A exceção `bypassPermissions` requer Claude Code v2.1.267 ou posterior.602* Quando a conversa principal está no modo `default`, `dontAsk` ou `plan`, o subagente é executado no modo de permissão que você definiu, exceto `bypassPermissions`. Um subagente que declara `bypassPermissions` mantém, em vez disso, o modo da conversa principal. A exceção de `bypassPermissions` requer o Claude Code v2.1.267 ou posterior.
603 603
604`permissionMode` aceita estes valores, e `manual` como um alias para `default`:604`permissionMode` aceita estes valores, e `manual` como alias para `default`:
605 605
606| Mode | Behavior |606| Modo | Comportamento |
607| :- | :- |607| :- | :- |
608| `default` | Modo Manual: solicita permissão |608| `default` | Modo Manual: solicita permissão |
609| `acceptEdits` | Auto-aceitar edições de arquivo e comandos comuns do sistema de arquivos para caminhos no diretório de trabalho ou `additionalDirectories` |609| `acceptEdits` | Aceita automaticamente edições de arquivos e comandos comuns do sistema de arquivos para caminhos no diretório de trabalho ou em `additionalDirectories` |
610| `auto` | [Modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): um classificador de IA revisa comandos e escritas em diretório protegido |610| `auto` | [Modo auto](/docs/pt/permission-modes#eliminate-prompts-with-auto-mode): um classificador em segundo plano revisa comandos e gravações em diretórios protegidos |
611| `dontAsk` | Auto-negar prompts de permissão. Ferramentas explicitamente permitidas ainda funcionam; `AskUserQuestion`, ferramentas MCP marcadas [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool), e ferramentas de conector [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega a Claude Code são negadas mesmo se você as permitiu |611| `dontAsk` | Nega automaticamente os prompts de permissão. Ferramentas explicitamente permitidas ainda funcionam; `AskUserQuestion`, ferramentas MCP marcadas com [`requiresUserInteraction`](/docs/pt/mcp#require-approval-for-a-specific-tool) e ferramentas de conectores que [sua organização definiu como `ask`](/docs/pt/mcp#organization-controls-on-connector-tools) em sessões onde essa configuração chega ao Claude Code são negadas mesmo que você as tenha permitido |
612| `bypassPermissions` | [Pular prompts de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode). Um subagente é executado neste modo apenas quando a conversa principal o faz |612| `bypassPermissions` | [Ignora os prompts de permissão](/docs/pt/permission-modes#skip-all-checks-with-bypasspermissions-mode). Um subagente é executado neste modo somente quando a conversa principal também está |
613| `plan` | Plan mode (exploração somente leitura) |613| `plan` | Modo de planejamento (exploração somente leitura) |
614 614
615<h4 id="preload-skills-into-subagents">615<h4 id="preload-skills-into-subagents">
616 Pré-carregar skills em subagentes616 Pré-carregar skills em subagentes
617</h4>617</h4>
618 618
619Use o campo `skills` para injetar conteúdo de skill 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.619Use 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.
620 620
621```yaml theme={null}621```yaml theme={null}
622---622---
630Implement API endpoints. Follow the conventions and patterns from the preloaded skills.630Implement API endpoints. Follow the conventions and patterns from the preloaded skills.
631```631```
632 632
633O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização. Este campo controla quais skills são pré-carregadas, não quais skills o subagente pode acessar: sem ele, o subagente ainda pode descobrir e invocar skills de projeto, usuário e plugin através da ferramenta Skill durante a execução. Para impedir que um subagente invoque skills inteiramente, omita `Skill` da lista [`tools`](#available-tools) ou adicione-o a `disallowedTools`.633O conteúdo completo de cada skill listada é injetado no contexto do subagente na inicialização. 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`](#available-tools) ou adicione-a a `disallowedTools`.
634 634
635Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/docs/pt/skills#control-who-invokes-a-skill), já que o pré-carregamento extrai do mesmo conjunto de skills que Claude pode invocar. Isso inclui a skill `/verify` integrada, que Claude não pode executar por conta própria.635Você não pode pré-carregar skills que definem [`disable-model-invocation: true`](/docs/pt/skills#control-who-invokes-a-skill), 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.
636 636
637Se uma skill listada estiver faltando ou desabilitada, por exemplo pela política de sua organização, Claude Code a ignora e registra um aviso no log de debug.637Se 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.
638 638
639<Note>639<Note>
640 Isto é o inverso de [executar uma skill em um subagente](/docs/pt/skills#run-skills-in-a-subagent). Com `skills` em um subagente, o subagente controla o prompt de sistema e carrega conteúdo de skill. Com `context: fork` em uma skill, o conteúdo de skill é injetado no agente que você especificar. Em ambos os casos o subagente começa sem seu histórico de conversa.640 Isto é o inverso de [executar uma skill em um subagente](/docs/pt/skills#run-skills-in-a-subagent). 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.
641</Note>641</Note>
642 642
643<h4 id="enable-persistent-memory">643<h4 id="enable-persistent-memory">
644 Habilitar memória persistente644 Habilitar memória persistente
645</h4>645</h4>
646 646
647O campo `memory` dá ao subagente um diretório persistente que sobrevive entre conversas. O subagente usa este diretório para construir conhecimento ao longo do tempo, como padrões de base de código, insights de debugging e decisões arquiteturais.647O 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.
648 648
649```yaml theme={null}649```yaml theme={null}
650---650---
657patterns, conventions, and recurring issues you discover.657patterns, conventions, and recurring issues you discover.
658```658```
659 659
660Escolha um escopo baseado em quão amplamente a memória deve se aplicar:660Escolha um escopo com base em quão amplamente a memória deve se aplicar:
661 661
662| Scope | Location | Use when |662| Escopo | Local | Use quando |
663| :- | :- | :- |663| :- | :- | :- |
664| `user` | `~/.claude/agent-memory/<name-of-agent>/` | o subagente deve lembrar aprendizados entre todos os projetos |664| `user` | `~/.claude/agent-memory/<name-of-agent>/` | o subagente deve lembrar aprendizados em todos os projetos |
665| `project` | `.claude/agent-memory/<name-of-agent>/` | o conhecimento do subagente é específico do projeto e compartilhável via controle de versão |665| `project` | `.claude/agent-memory/<name-of-agent>/` | o conhecimento do subagente é específico do projeto e pode ser compartilhado via controle de versão |
666| `local` | `.claude/agent-memory-local/<name-of-agent>/` | o conhecimento do subagente é específico do projeto mas não deve ser verificado no controle de versão |666| `local` | `.claude/agent-memory-local/<name-of-agent>/` | o conhecimento do subagente é específico do projeto, mas não deve ser incluído no controle de versão |
667 667
668A memória do subagente faz parte da [memória automática](/docs/pt/memory#auto-memory): 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 à ferramenta de memória descrito abaixo.668A memória do subagente faz parte da [memória automática](/docs/pt/memory#auto-memory): 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.
669 669
670Quando a memória está habilitada:670Quando a memória está habilitada:
671 671
672* O prompt de sistema do subagente inclui instruções para ler e escrever no diretório de memória.672* O system prompt do subagente inclui instruções para ler e gravar no diretório de memória.
673* O prompt de sistema do subagente também inclui as primeiras 200 linhas ou 25KB de `MEMORY.md` no diretório de memória, o que for menor, com instruções para curar `MEMORY.md` se exceder esse limite.673* 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.
674* Ferramentas Read, Write e Edit são automaticamente habilitadas para que o subagente possa gerenciar seus arquivos de memória.674* As ferramentas Read, Write e Edit são habilitadas automaticamente para que o subagente possa gerenciar seus arquivos de memória.
675 675
676<h5 id="persistent-memory-tips">676<h5 id="persistent-memory-tips">
677 Dicas de memória persistente677 Dicas de memória persistente
678</h5>678</h5>
679 679
680* `project` é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão.680* `project` é o escopo padrão recomendado. Ele torna o conhecimento do subagente compartilhável via controle de versão.
681* Peça ao subagente para consultar sua memória antes de começar o trabalho: "Review this PR, and check your memory for patterns you've seen before."681* 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."
682* Peça ao subagente para atualizar sua memória após completar uma tarefa: "Now that you're done, save what you learned to your memory." Ao longo do tempo, isso constrói uma base de conhecimento que torna o subagente mais eficaz.682* 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.
683* Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:683* Inclua instruções de memória diretamente no arquivo markdown do subagente para que ele mantenha proativamente sua própria base de conhecimento:
684 684
685 ```markdown theme={null}685 ```markdown theme={null}
693 Regras condicionais com hooks693 Regras condicionais com hooks
694</h4>694</h4>
695 695
696Para controle mais dinâmico sobre uso de ferramentas, use hooks `PreToolUse` para validar operações antes de serem executadas. Isso é útil quando você precisa permitir algumas operações de uma ferramenta enquanto bloqueia outras.696Para 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.
697 697
698Este exemplo cria um subagente que apenas permite consultas de banco de dados somente leitura. O hook `PreToolUse` executa o script especificado em `command` antes de cada comando Bash ser executado:698Este 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:
699 699
700```yaml theme={null}700```yaml theme={null}
701---701---
711---711---
712```712```
713 713
714Claude Code [passa entrada de hook como JSON](/docs/pt/hooks#pretooluse-input) via stdin para comandos de hook. O script de validação lê este JSON, extrai o comando Bash e [sai com código 2](/docs/pt/hooks#exit-code-2-behavior-per-event) para bloquear operações de escrita:714O Claude Code [passa a entrada do hook como JSON](/docs/pt/hooks#pretooluse-input) 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](/docs/pt/hooks#exit-code-2-behavior-per-event) para bloquear operações de escrita:
715 715
716```bash theme={null}716```bash theme={null}
717#!/bin/bash717#!/bin/bash
729exit 0729exit 0
730```730```
731 731
732Em macOS e Linux, torne o script executável, ou o hook falha em vez de bloquear qualquer coisa:732No macOS e no Linux, torne o script executável, caso contrário o hook falha em vez de bloquear algo:
733 733
734```bash theme={null}734```bash theme={null}
735chmod +x ./scripts/validate-readonly-query.sh735chmod +x ./scripts/validate-readonly-query.sh
736```736```
737 737
738Para testar a regra, peça ao subagente para executar uma instrução `UPDATE`: o script sai com código 2, Claude Code bloqueia o comando, e o subagente vê a mensagem `Blocked: Only SELECT queries are allowed`.738Para 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`.
739 739
740Veja [Hook input](/docs/pt/hooks#pretooluse-input) para o schema de entrada completo e [exit codes](/docs/pt/hooks#exit-code-output) para como códigos de saída afetam o comportamento. No Windows, escreva scripts de hook em PowerShell e adicione `shell: powershell` à entrada de hook conforme mostrado em [executando hooks em PowerShell](/docs/pt/hooks#windows-powershell-tool).740Consulte [Entrada do hook](/docs/pt/hooks#pretooluse-input) para o esquema de entrada completo e [códigos de saída](/docs/pt/hooks#exit-code-output) 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](/docs/pt/hooks#windows-powershell-tool).
741 741
742<h4 id="disable-specific-subagents">742<h4 id="disable-specific-subagents">
743 Desabilitar subagentes específicos743 Desabilitar subagentes específicos
744</h4>744</h4>
745 745
746Você pode impedir que Claude use subagentes específicos adicionando-os ao array `deny` em suas [configurações](/docs/pt/settings-reference#permission-settings). Use o formato `Agent(subagent-name)` onde `subagent-name` corresponde ao campo name do subagente.746Você pode impedir que o Claude use subagentes específicos adicionando-os ao array `deny` nas suas [configurações](/docs/pt/settings-reference#permission-settings). Use o formato `Agent(subagent-name)`, em que `subagent-name` corresponde ao campo name do subagente.
747 747
748```json theme={null}748```json theme={null}
749{749{
753}753}
754```754```
755 755
756Isso funciona para subagentes integrados e personalizados. Você também pode usar o flag CLI `--disallowedTools`:756Isso funciona tanto para subagentes integrados quanto personalizados. Você também pode usar a flag de CLI `--disallowedTools`:
757 757
758```bash theme={null}758```bash theme={null}
759claude --disallowedTools "Agent(Explore)"759claude --disallowedTools "Agent(Explore)"
760```760```
761 761
762Veja [documentação de Permissões](/docs/pt/permissions#tool-specific-permission-rules) para mais detalhes sobre regras de permissão.762Consulte a [documentação de permissões](/docs/pt/permissions#tool-specific-permission-rules) para mais detalhes sobre regras de permissão.
763 763
764<h3 id="define-hooks-for-subagents">764<h3 id="define-hooks-for-subagents">
765 Definir hooks para subagentes765 Definir hooks para subagentes
766</h3>766</h3>
767 767
768Subagentes podem definir [hooks](/docs/pt/hooks) que são executados durante o ciclo de vida do subagente. Existem duas formas de configurar hooks:768Os subagentes podem definir [hooks](/docs/pt/hooks) que são executados durante o ciclo de vida do subagente. Há duas maneiras de configurar hooks:
769 769
770* **No frontmatter do subagente**: defina hooks que são executados apenas enquanto esse subagente específico está ativo770* **No frontmatter do subagente**: defina hooks que são executados apenas enquanto esse subagente está ativo
771* **Em `settings.json`**: defina hooks em toda a sessão que também disparam dentro de subagentes. Eventos de ferramentas como `PreToolUse` e `PostToolUse` disparam para as chamadas de ferramentas do subagente da mesma forma que na conversa principal, e `SubagentStart` e `SubagentStop` disparam quando um subagente inicia ou termina771* **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
772 772
773Hooks de [arquivos de configurações, configurações de política gerenciada e plugins](/docs/pt/hooks#hook-locations) todos se aplicam dentro de subagentes, portanto um hook `PreToolUse` em `settings.json` também é executado antes de cada ferramenta que um subagente usa.773Os hooks de [arquivos de configurações, configurações de política gerenciada e plugins](/docs/pt/hooks#hook-locations) 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.
774 774
775<h4 id="hooks-in-subagent-frontmatter">775<h4 id="hooks-in-subagent-frontmatter">
776 Hooks no frontmatter do subagente776 Hooks no frontmatter do subagente
777</h4>777</h4>
778 778
779Defina hooks diretamente no arquivo markdown do subagente. Estes hooks são executados apenas enquanto esse subagente específico está ativo e são limpos quando termina.779Defina 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.
780 780
781<Note>781<Note>
782 Hooks de frontmatter disparam quando o agente é gerado como um subagente através da ferramenta Agent ou uma @-menção, e quando o agente é executado como a sessão principal via [`--agent`](#invoke-subagents-explicitly) ou a configuração `agent`. No caso de sessão principal, eles são executados junto com qualquer hook definido em [`settings.json`](/docs/pt/hooks).782 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`](#invoke-subagents-explicitly) ou a configuração `agent`. No caso da sessão principal, eles são executados junto com quaisquer hooks definidos em [`settings.json`](/docs/pt/hooks).
783</Note>783</Note>
784 784
785Para permitir que os hooks de frontmatter de um subagente no nível do projeto sejam executados, aceite o [diálogo de confiança do espaço de trabalho](/docs/pt/permissions#project-allow-rules-and-workspace-trust) para a pasta que contém o arquivo do agente. Hooks de subagentes no nível do usuário em `~/.claude/agents/` e de definições que você passa com `--agents` são executados sem esta etapa. Se você adicionou uma pasta com `--add-dir` de fora do repositório do espaço de trabalho confiável de sua organização, confie nessa pasta separadamente: seus hooks `.claude/agents/` não herdam a confiança do espaço de trabalho.785Para 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](/docs/pt/permissions#project-allow-rules-and-workspace-trust) 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.
786 786
787Até que você confie na pasta, o subagente ainda é executado, mas Claude Code pula seus hooks de frontmatter e registra um erro no log de debug explicando como confiar na pasta. Esta é uma regra mais rigorosa do que a para 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](/docs/pt/permissions#what-runs-before-you-trust-a-folder) compara os dois. Antes da v2.1.218, hooks de frontmatter podiam ser executados de pastas que você não tinha confiado, incluindo em sessões não interativas.787Até 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](/docs/pt/permissions#what-runs-before-you-trust-a-folder) compara as duas. Antes da v2.1.218, os hooks do frontmatter podiam ser executados a partir de pastas em que você não havia confiado, inclusive em sessões não interativas.
788 788
789Todos os [eventos de hook](/docs/pt/hooks#hook-events) são suportados. Os eventos mais comuns para subagentes são:789Todos os [eventos de hook](/docs/pt/hooks#hook-events) são suportados. Os eventos mais comuns para subagentes são:
790 790
791| Event | Matcher input | When it fires |791| Evento | Entrada do matcher | Quando dispara |
792| :- | :- | :- |792| :- | :- | :- |
793| `PreToolUse` | Nome da ferramenta | Antes do subagente usar uma ferramenta |793| `PreToolUse` | Nome da ferramenta | Antes de o subagente usar uma ferramenta |
794| `PostToolUse` | Nome da ferramenta | Depois do subagente usar uma ferramenta |794| `PostToolUse` | Nome da ferramenta | Depois de o subagente usar uma ferramenta |
795| `Stop` | (nenhum) | Quando o subagente termina (convertido para `SubagentStop` em tempo de execução) |795| `Stop` | (nenhuma) | Quando o subagente termina (convertido em `SubagentStop` em tempo de execução) |
796 796
797Este exemplo valida comandos Bash com o hook `PreToolUse` e executa um linter após edições de arquivo com `PostToolUse`:797Este exemplo valida comandos Bash com o hook `PreToolUse` e executa um linter após edições de arquivos com `PostToolUse`:
798 798
799```yaml theme={null}799```yaml theme={null}
800---800---
814---814---
815```815```
816 816
817Quando o agente é invocado como um subagente, hooks `Stop` no frontmatter são automaticamente convertidos para eventos `SubagentStop`.817Quando o agente é invocado como subagente, os hooks `Stop` no frontmatter são convertidos automaticamente em eventos `SubagentStop`.
818 818
819<h4 id="project-level-hooks-for-subagent-events">819<h4 id="project-level-hooks-for-subagent-events">
820 Hooks no nível do projeto para eventos de subagente820 Hooks de nível de projeto para eventos de subagentes
821</h4>821</h4>
822 822
823Configure hooks em `settings.json` que respondem a eventos de ciclo de vida de subagente na sessão principal.823Configure hooks em `settings.json` que respondem a eventos do ciclo de vida de subagentes na sessão principal.
824 824
825| Event | Matcher input | When it fires |825| Evento | Entrada do matcher | Quando dispara |
826| :- | :- | :- |826| :- | :- | :- |
827| `SubagentStart` | Nome do tipo de agente | Quando um subagente começa a execução |827| `SubagentStart` | Nome do tipo de agente | Quando um subagente inicia a execução |
828| `SubagentStop` | Nome do tipo de agente | Quando um subagente completa |828| `SubagentStop` | Nome do tipo de agente | Quando um subagente é concluído |
829 829
830Ambos os eventos suportam matchers para direcionar tipos de agente específicos por nome. O valor do matcher é o `name` do frontmatter do agente para subagentes no nível de projeto e usuário, ou o identificador com escopo de plugin como `my-plugin:db-agent` para [subagentes de plugin](/docs/pt/plugins/components#agents). Um nome com escopo contém dois-pontos, portanto é avaliado como uma [expressão regular sem âncora](/docs/pt/hooks#matcher-patterns); ancorá-lo com `^` e `$`, como em `^my-plugin:db-agent$`, para corresponder apenas a esse agente.830Ambos 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](/docs/pt/plugins/components#agents). Um nome com escopo contém dois-pontos, então é avaliado como uma [expressão regular não ancorada](/docs/pt/hooks#matcher-patterns); ancore-o com `^` e `$`, como em `^my-plugin:db-agent$`, para corresponder apenas a esse agente.
831 831
832Este exemplo executa um script de configuração apenas quando o subagente `db-agent` inicia, e um script de limpeza quando qualquer subagente para:832Este exemplo executa um script de configuração apenas quando o subagente `db-agent` é iniciado, e um script de limpeza quando qualquer subagente para:
833 833
834```json theme={null}834```json theme={null}
835{835{
853}853}
854```854```
855 855
856Veja [Hooks](/docs/pt/hooks) para o formato de configuração de hook completo.856Consulte [Hooks](/docs/pt/hooks) para o formato completo de configuração de hooks.
857 857
858<h2 id="work-with-subagents">858<h2 id="work-with-subagents">
859 Trabalhar com subagentes859 Trabalhar com subagentes
988 988
989Um 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:989Um 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:
990 990
991* **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`](/docs/pt/errors#agent-terminated-early-due-to-an-api-error), seguido pelo detalhe do erro. Na v2.1.199, um rate limit, sobrecarga ou erro de servidor que interrompeu a forma de chamadas de ferramenta apenas retornou um resultado parcial vazio contendo apenas a nota de interrupção.991* **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`](/docs/pt/errors#agent-terminated-early-due-to-an-api-error), seguido pelo detalhe do erro.
992* **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.992* **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.
993 993
994Quando você configura uma [cadeia de modelo de fallback](/docs/pt/model-config#fallback-model-chains) 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.994Quando você configura uma [cadeia de modelo de fallback](/docs/pt/model-config#fallback-model-chains) 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.
