Skip to main content
Claude Code tem acesso a um conjunto de ferramentas integradas que o ajudam a entender e modificar sua base de código. Os nomes das ferramentas são as strings exatas que você usa em regras de permissão, listas de ferramentas de subagentes e correspondências de hooks. Para controlar quais ferramentas Claude pode usar e quando ele pede primeiro, configure regras de permissão em suas configurações, hooks ou lista de ferramentas de um subagente. Veja Configurar ferramentas com regras de permissão e hooks para cada local que aceita um nome de ferramenta. Para adicionar ferramentas personalizadas, conecte um servidor MCP. Para estender Claude com fluxos de trabalho baseados em prompts reutilizáveis, escreva uma skill, que é executada através da ferramenta Skill existente em vez de adicionar uma nova entrada de ferramenta.
Em modo automático, um classificador decide a maioria dos prompts de permissão em vez de você. A coluna Permission required mostra se a ferramenta solicita em Modo Manual para caminhos dentro do diretório de trabalho. Ferramentas de acesso a arquivos marcadas como Não, incluindo Read, Grep e Glob, ainda solicitam para caminhos fora do diretório de trabalho e diretórios adicionais. Bash é marcado como Sim, mas executa um conjunto integrado de comandos somente leitura sem solicitar.

​
Configure ferramentas com regras de permissão e hooks

Na maioria dos casos, Claude decide quando usar essas ferramentas e você não precisa nomeá-las você mesmo ao interagir com Claude. Você referencia nomes de ferramentas diretamente ao definir permissões e outras configurações: Todos esses aceitam o mesmo formato de regra, ToolName(specifier). O especificador depende da ferramenta, e várias ferramentas compartilham um formato: Ferramentas não listadas aqui, como ExitPlanMode ou ShareOnboardingGuide, aceitam apenas o nome da ferramenta sem especificador. Uma regra de permissão Edit(...) também concede acesso de leitura ao mesmo caminho, portanto você não precisa de uma regra Read(...) correspondente. Uma regra de negação Read(...) também bloqueia as ferramentas Edit e Write no mesmo caminho, incluindo a criação de um novo arquivo lá, porque ambas as ferramentas alteram conteúdo que Claude precisa ser capaz de ler novamente. A verificação de negação Read requer Claude Code v2.1.208 ou posterior em edições, e v2.1.228 ou posterior em escritas. Os campos matcher do Hook usam nomes de ferramentas simples, não o formato entre parênteses. Veja padrões de matcher para as regras de correspondência. Para os nomes de campo que cada ferramenta passa para tool_input em hooks, veja a referência de entrada PreToolUse.

​
Comportamento da ferramenta Agent

A ferramenta Agent cria um subagente em uma janela de contexto separada. O subagente trabalha através de sua tarefa autonomamente, depois retorna seu resultado para a conversa pai. O pai não vê as chamadas de ferramentas intermediárias ou saídas do subagente, apenas esse resultado final. Com agent teams ativados, uma chamada que carrega um name pode iniciar um teammate, que relata através de mensagens de equipe em vez de retornar um resultado. Para limitar quantas voltas um subagente executa, defina maxTurns na definição do subagente. Quando o subagente atinge o limite, Claude Code marca o resultado retornado como saída parcial, e Claude pode retomar o subagente para continuar. A mesma ferramenta Agent também inicia subagentes bifurcados onde fork mode está ativado. Uma bifurcação herda a conversa pai completa em vez de começar do zero, executa em segundo plano além dos casos que permanecem em primeiro plano, e ainda exibe prompts de permissão em seu terminal. O resto desta seção descreve subagentes não-bifurcados. Quais ferramentas um subagente não-bifurcado pode usar depende dos campos tools e disallowedTools na definição do subagente:
  • Nenhum campo definido: o subagente herda todas as ferramentas disponíveis para subagentes.
  • Apenas tools: o subagente obtém apenas as ferramentas listadas.
  • Apenas disallowedTools: o subagente obtém todas as ferramentas pai, exceto as listadas.
  • Ambos definidos: disallowedTools tem precedência. Uma ferramenta listada em ambos é removida.
Em todos os casos, o conjunto resolvido é limitado às ferramentas disponíveis para subagentes: uma ferramenta que não está disponível para subagentes nunca é concedida, mesmo quando listada em tools. Onde as condições na entrada da tabela de ferramentas SubagentHandback se mantêm, Claude Code também fornece ao subagente essa ferramenta, mesmo se você a deixar de fora de tools ou a listar em disallowedTools. Se cada entrada na lista tools de um subagente falhar em corresponder a uma ferramenta utilizável, a ferramenta Agent geralmente retorna um erro nomeando as entradas em vez de iniciar o subagente; veja Agent would be spawned with zero tools para a mensagem e como corrigir cada entrada. Iniciar o subagente não solicita permissão por si só. Claude Code verifica as chamadas de ferramentas do próprio subagente contra suas regras de permissão conforme executa. Onde você vê os prompts de permissão de um subagente depende se ele executa em primeiro plano ou em segundo plano. Claude Code executa subagentes em segundo plano por padrão, além dos casos que executam em primeiro plano.
  • Subagentes em primeiro plano mostram os mesmos prompts de permissão que você veria na conversa principal, no momento em que cada chamada de ferramenta acontece.
  • Subagentes em segundo plano exibem prompts de permissão em sua sessão principal. O prompt nomeia qual subagente está solicitando, e pressionar Esc nega essa chamada de ferramenta sem parar o subagente.
Para limitar o que um subagente pode alcançar em primeiro lugar, restrinja seu campo tools, por exemplo deixando Bash fora da lista, ou defina regras de negação em suas configurações.

​
Comportamento da ferramenta AskUserQuestion

Claude usa AskUserQuestion para fazer perguntas de múltipla escolha quando precisa de uma decisão ou esclarecimento. Responda escolhendo uma opção ou digite seu próprio texto através da linha Other ou do campo de notas. Quando você responde digitando seu próprio texto, Claude Code retransmite a resposta com redação neutra para que Claude siga o que você escreveu, incluindo uma solicitação para aguardar ou explicar primeiro.

​
Timeout de continuação automática de perguntas

As perguntas permanecem abertas até que você as responda. Se você quiser que uma pergunta que deixar sem resposta eventualmente feche e permita que Claude continue sem você, defina a configuração askUserQuestionTimeout como 60s, 5m ou 10m, seja no seu settings.json do usuário ou na linha Question auto-continue timeout em /config. Depois que uma pergunta fica tanto tempo sem entrada, o diálogo fecha automaticamente: ele envia todas as opções que você já havia selecionado e diz a Claude que você pode estar longe do teclado, então Claude procede com seu próprio julgamento e pode fazer perguntas novamente mais tarde. Você vê uma contagem regressiva nos últimos 20 segundos. Pressione qualquer tecla para reiniciar o temporizador. Enquanto seu terminal relatar que a janela dele está em foco, o temporizador não faz a contagem regressiva. O temporizador nunca é iniciado para uma pergunta que Claude faz em uma sessão em segundo plano, no modo de leitor de tela ou enquanto a sessão está conectada ao Remote Control. Essas perguntas aguardam até que você as responda. O timeout se aplica apenas às perguntas de múltipla escolha do AskUserQuestion; prompts de permissão, incluindo aprovação de plano, nunca se resolvem automaticamente quando inativo.

​
Comportamento da ferramenta Bash

A ferramenta Bash executa cada comando em um processo separado.

​
O que persiste entre comandos

  • Quando Claude executa cd na sessão principal, o novo diretório de trabalho é mantido para comandos Bash posteriores, desde que permaneça dentro do diretório do projeto ou de um diretório de trabalho adicional que você adicionou com --add-dir, /add-dir, ou additionalDirectories nas configurações. Isso inclui comandos que Claude executa em resposta às suas mensagens posteriores.
    • Sessões de subagentes nunca mantêm mudanças de diretório de trabalho.
    • Se cd sair desses diretórios, Claude Code redefine para o diretório do projeto e anexa Shell cwd was reset to <dir> ao resultado da ferramenta.
    • Para desabilitar esse carregamento de forma que cada comando Bash comece no diretório do projeto, defina CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1.
  • Variáveis de ambiente não persistem. Um export em um comando não estará disponível no próximo.
  • Aliases e funções de shell definidas no seu arquivo de inicialização de shell estão disponíveis. No início da sessão, Claude Code carrega ~/.zshrc, ~/.bashrc, ou ~/.profile dependendo do seu shell, captura os aliases, funções e opções de shell resultantes e os aplica a cada comando Bash.
Ative seu virtualenv ou ambiente conda antes de iniciar Claude Code. Para fazer variáveis de ambiente persistirem entre comandos Bash, defina CLAUDE_ENV_FILE para um script de shell antes de iniciar Claude Code, ou use um hook SessionStart para preenchê-lo dinamicamente.

​
Limites de timeout e saída

Cada comando é executado sob um timeout, e Claude o gerencia: quando precisa de mais tempo do que o padrão para um comando, ele passa o parâmetro timeout com essa chamada. Você nunca define um timeout por comando. Duas variáveis de ambiente controlam o que Claude obtém para um comando que é executado em primeiro plano:
  • BASH_DEFAULT_TIMEOUT_MS — o padrão quando Claude não passa timeout; dois minutos por padrão
  • BASH_MAX_TIMEOUT_MS — com o padrão, define o limite máximo que limita o que Claude solicita: o limite efetivo é o maior dos dois, dez minutos por padrão
Em uma sessão que tem um limite de tempo para comandos em segundo plano, timeout em um comando que Claude inicia em segundo plano define, em vez disso, por quanto tempo o comando pode ser executado lá, com o padrão e o máximo separados desse limite. A ferramenta PowerShell segue as mesmas regras de timeout e lê as mesmas duas variáveis.

​
Limites de saída

Claude Code transmite a saída de um comando para um arquivo de trabalho enquanto o comando é executado; um comando cuja saída ultrapassa 5 GB é interrompido. Quando o comando termina, Claude Code lê a saída de volta desse arquivo, até a janela de releitura descrita abaixo. Quanto da saída chega a Claude inline depende se Claude Code trata o resultado como uma falha: Um comando que sai com código 1 conta como um resultado válido para a ferramenta Bash apenas quando Claude Code reconhece o código de saída 1 como um resultado benigno para esse comando: grep, rg, egrep, fgrep, find, diff, test, e [, mais git diff e git grep. Todo outro comando que sai com código 1 conta como uma falha, mesmo quando o código de saída 1 é um resultado informacional benigno: sem correspondências para pgrep e jq -e, arquivos que diferem para cmp. BASH_MAX_OUTPUT_LENGTH define quantos caracteres de saída Claude Code relê do arquivo de trabalho para o resultado de um comando: 30.000 por padrão, até um limite máximo de 150.000. Aumente quando seus comandos rotineiramente ultrapassarem essa janela, como um build verboso ou um log de suite de testes completo. Aumentá-lo amplia a janela de releitura, que também é a janela de onde um trecho de comando com falha é cortado. Não aumenta os limites inline: um resultado válido acima do limite inline chega como um caminho de arquivo mais visualização independentemente dessa variável. Para alterar quanto de um resultado válido Claude recebe inline, defina a configuração bashOutputMaxChars em vez disso, até 128.000 caracteres. Ele dimensiona o limite inline e a janela de releitura juntos, e Claude Code então ignora BASH_MAX_OUTPUT_LENGTH. Requer Claude Code v2.1.261 ou posterior.

​
Comandos em segundo plano

Para processos de longa duração, como servidores de desenvolvimento ou builds de observação, Claude pode definir run_in_background: true para iniciar o comando como uma tarefa em segundo plano e continuar trabalhando enquanto é executado. Liste e interrompa tarefas em segundo plano com /tasks. Depois de interromper uma lá, ou de um cliente conectado como o aplicativo de desktop, Claude continua em vez de esperar. Se um subagente iniciou o comando, é esse subagente que continua.

​
Quando um comando em segundo plano para

Um comando que um subagente em primeiro plano iniciou para quando a execução desse subagente termina, quer tenha terminado, falhado ou sido interrompido. Um comando que a conversa principal ou um subagente em segundo plano iniciou continua sendo executado após uma resposta final, até sair, ser interrompido ou atingir seu limite de tempo. Enquanto um comando que a conversa principal iniciou ainda está em execução, uma execução no modo não interativo com a flag -p permanece aberta após seu resultado até que esse comando saia ou atinja seu limite de tempo. Um comando que um subagente em segundo plano iniciou é interrompido quando a execução sai.

​
Limite de tempo para comandos em segundo plano

Em uma sessão executada sem supervisão, como uma execução com a flag -p, uma aplicação do Agent SDK, um job de CI ou uma sessão na nuvem, comandos Bash e PowerShell em segundo plano têm um limite de tempo. Uma sessão local em que você trabalha a partir de um terminal, do aplicativo de desktop ou da extensão do VS Code não tem limite de tempo para comandos em segundo plano. O limite de tempo requer Claude Code v2.1.285 ou posterior. Antes da v2.1.288, ele se aplicava em todas as sessões. O limite de tempo é contado a partir do momento em que o comando entra em segundo plano:
  • Um comando que Claude inicia em segundo plano obtém 30 minutos, ou o timeout que Claude passa com run_in_background, até um máximo de 2 horas
  • Um comando que começa em primeiro plano e depois se move para segundo plano, por exemplo em seu timeout, obtém 30 minutos a partir da mudança
Em uma execução com a flag -p cujo prompt você passa como texto em vez de com --input-format stream-json, ambos os padrões são de 10 minutos em vez de 30, porque a execução aguarda os comandos em segundo plano após seu resultado. Quando um comando em segundo plano atinge seu limite de tempo, Claude Code o interrompe e diz a Claude por quê, e Claude pode iniciar o comando novamente com um timeout mais longo se o trabalho ainda precisar. O aviso de parada lê Background command "<description>" was stopped after reaching its background time limit.

​
Aumente o limite de tempo para comandos em segundo plano

Duas variáveis de ambiente aumentam esses limites, para comandos Bash e PowerShell igualmente. Ambas usam milissegundos, e nenhuma pode encurtar um limite: um valor mais baixo deixa os padrões e o máximo de 2 horas em vigor.
  • Defina BASH_DEFAULT_TIMEOUT_MS acima de 1800000 para substituir o padrão de 30 minutos por esse valor, tanto para comandos que Claude inicia sem um timeout quanto para comandos movidos. Em uma execução -p cujo prompt você passa como texto, qualquer valor acima de 600000 substitui seu padrão de 10 minutos
  • Defina BASH_MAX_TIMEOUT_MS acima de 7200000 para aumentar o máximo de 2 horas para esse valor. Definir BASH_DEFAULT_TIMEOUT_MS acima de 7200000 aumenta o máximo da mesma forma

​
Comandos em primeiro plano que se movem para segundo plano

Quando um comando em primeiro plano atinge seu timeout sem terminar, Claude Code o move para segundo plano em vez de interrompê-lo, a menos que o comando comece com sleep. O limite de tempo de um comando movido é contado a partir da mudança, e um comando movido de um subagente em primeiro plano ainda para quando a execução desse subagente termina. Definir CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 ou executar no modo bare desabilita o auto-backgrounding junto com o resto da funcionalidade de tarefas em segundo plano, de modo que um comando que atinge seu timeout é interrompido. O resultado de um comando movido para segundo plano declara o que aconteceu:
  • Quando o timeout dispara a mudança, o resultado relata explicitamente: Command did not complete within its 120s timeout and was moved to the background, com os segundos correspondendo ao timeout que se aplicava, seguido pela ID da tarefa e o caminho do arquivo para o qual a saída está sendo escrita.
  • Um cd, pushd, popd, ou chdir dentro de um comando que é movido para segundo plano nunca é mantido: o resultado declara Session cwd remains <dir>; directory changes made by the backgrounded command do not apply to subsequent commands., então Claude não age em uma mudança de diretório que não aconteceu.

​
Limite de memória no Linux e WSL

No Linux e WSL, defina CLAUDE_CODE_TOOL_MEMORY_LIMIT para um tamanho como 4G para limitar a memória que comandos Bash, PowerShell e Monitor podem usar, para que um build descontrolado não consuma a memória que o resto da sessão precisa. Requer Claude Code v2.1.233 ou posterior. Antes de v2.1.246, comandos da ferramenta Monitor eram executados fora do limite.
  • Escreva o tamanho como um número de bytes ou com um sufixo K, M, G, ou T. Defina 0, off, false, no, ou none para desativar o limite. Claude Code ignora qualquer outro valor que não consiga ler como um tamanho, como 4e9.
  • Claude Code conta todos os comandos Bash, PowerShell e Monitor de uma sessão contra o único limite, não cada comando por si só.
  • Claude Code aplica o limite com um cgroup de memória. Quando não consegue configurar o cgroup, comandos são executados sem um limite, e o log de depuração de claude --debug diz por quê.
  • Depois que o primeiro processo que Claude Code inicia ativou o limite, ou o desativou por causa de um valor off ou uma configuração de cgroup falhada, Claude Code mantém esse resultado até você relançar. Para aplicar um valor alterado ou removido, ou uma configuração corrigida, inicie claude novamente.
  • Quando comandos não conseguem ficar sob o limite, o kernel mata um comando, e nada em seu resultado nomeia o limite.
Claude Code também pode contar outros tipos de processos que inicia contra o mesmo limite. Defina CLAUDE_CODE_TOOL_MEMORY_CGROUP_EXCLUDE para uma lista separada por vírgulas dos tipos a isentar do limite; Claude Code aplica o limite a cada tipo não em sua lista. Defina para none para limitar cada tipo, ou para all-new para limitar apenas comandos Bash, PowerShell e Monitor tool. Requer Claude Code v2.1.246 ou posterior. Os tipos que você pode nomear: Seja qual for sua lista, estas regras se aplicam:
  • Nomes desconhecidos: Claude Code ignora nomes que não reconhece
  • Variável não definida: Claude Code pega o conjunto de outros tipos limitados da configuração que Anthropic entrega do servidor, e esse conjunto pode mudar ao longo do tempo, então defina a variável quando precisar de um conjunto que não mude
  • Hooks com permissão: mesmo com cada tipo limitado, Claude Code exclui do limite um hook que pode bloquear ou alterar o resultado de uma ação, e qualquer servidor MCP que tal hook chama, então o kernel matando um hook com permissão não pode permitir a ação que estava bloqueando

​
Comportamento da ferramenta Edit

A ferramenta Edit realiza substituição exata de strings. Ela recebe uma old_string e uma new_string e substitui a primeira pela segunda. Ela não usa regex ou correspondência aproximada. Estas verificações devem passar para que uma edição seja aplicada. Antes de qualquer uma delas, um caminho correspondido por uma regra de negação Read é recusado, incluindo a criação de um novo arquivo lá. A recusa requer Claude Code v2.1.208 ou posterior.
  • Read-before-edit: Claude lê o arquivo na conversa atual antes de editá-lo, e uma leitura interrompida com um aviso PARTIAL view não conta. Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura. Modelos mais novos podem editar um arquivo não lido quando a leitura não precisaria de um prompt de permissão e a ferramenta Read está disponível.
  • Match: old_string deve aparecer no arquivo exatamente como escrito. Uma única diferença de caractere de espaço em branco ou indentação é suficiente para não corresponder.
  • Uniqueness: old_string deve aparecer exatamente uma vez. Quando aparece mais de uma vez, Claude fornece uma string mais longa com contexto circundante suficiente para identificar uma ocorrência, ou define replace_all: true para substituir todas elas.
Um arquivo que mudou no disco depois que Claude o leu pela última vez ainda pode ser editado quando old_string corresponde ao conteúdo atual exatamente e sem ambiguidade e Claude Code pode ler o arquivo sem solicitar. Corresponder contra o conteúdo atual do arquivo mantém isso seguro, e o resultado observa que o arquivo contém outras alterações para que Claude o releia antes de edições que dependem do conteúdo circundante. Em qualquer outro caso, como uma old_string desatualizada ou uma que corresponde mais de uma vez sem replace_all, Claude lê o arquivo novamente antes de editar. O tratamento relaxado de arquivos não lidos e alterados requer Claude Code v2.1.208 ou posterior; antes disso, Claude Code recusava qualquer edição em um arquivo que não havia lido na conversa ou que mudou no disco após a leitura. Claude também pode editar um arquivo sem um Read separado depois de visualizá-lo com um comando Bash como cat ou grep. Esses comandos são cat, nl, bat, batcat, head, tail, sed -n 'X,Yp', grep, egrep, fgrep e rg, cada um executado em um único arquivo sem pipes ou redirecionamentos. Uma busca que não exibe nenhuma correspondência não conta como leitura, nem qualquer comando fora desta lista. Quando Claude visualiza um arquivo dessa forma, Claude Code também carrega qualquer CLAUDE.md de subdiretório e regras com escopo de caminho que se aplicam a esse arquivo. Consulte Regras de permissão Read e Edit para saber quais comandos Bash suas regras de negação Read e Edit cobrem.

​
Arquivos não UTF-8

Claude não pode usar NotebookEdit em um arquivo que não seja UTF-8 válido. O mesmo vale para Edit, a menos que o arquivo comece com uma marca de ordem de bytes UTF-16 little-endian. Quando Claude tenta, a ferramenta recusa a alteração e deixa o arquivo intacto. Os arquivos recusados incluem texto não ASCII salvo em uma codificação legada como Windows-1252 ou Shift-JIS, arquivos binários e UTF-8 com uma sequência de bytes inválida. As ferramentas recusam porque salvam o arquivo inteiro de volta como UTF-8, o que substituiria cada byte que não conseguem decodificar pelo caractere de substituição U+FFFD. Em vez disso, o erro que Claude recebe instrui a fazer a alteração com um comando de shell que mantém a codificação do arquivo, ou a perguntar a você sobre convertê-lo para UTF-8 primeiro. Claude ainda pode substituir esse arquivo com Write, a menos que o novo conteúdo contenha U+FFFD, o caractere que Read mostra a Claude no lugar de bytes que não consegue decodificar. Essa proteção impede que Claude grave de volta o texto corrompido que leu. Quando Write substitui o arquivo, ele salva o novo conteúdo como UTF-8, de modo que a codificação original do arquivo é perdida.

​
Comportamento da ferramenta EndConversation

A ferramenta EndConversation encerra a sessão atual. Claude a utiliza apenas em duas situações:
  • como último recurso contra entrada abusiva sustentada, após tentativas de redirecionar a conversa terem falhado e após um aviso claro em uma mensagem anterior
  • quando você solicita explicitamente ver a ferramenta demonstrada e confirma que deseja encerrar a sessão
Frustração geral, profanidade ou uma tarefa correndo mal não se qualificam, assim como solicitações de conteúdo prejudicial, que Claude recusa em vez de encerrar a sessão. Claude Code segue a mesma abordagem que claude.ai, que pode encerrar um subconjunto raro de chats. Depois que Claude encerra uma sessão interativa, a sessão é bloqueada. Novos prompts e a maioria dos comandos retornam Claude ended this conversation. Start a new session (or /clear) to continue., e apenas /clear, /resume, /help, /exit e /feedback ainda funcionam. Claude Code registra o encerramento na transcrição da sessão, portanto retomar uma sessão encerrada restaura o bloqueio; o histórico da sessão não é excluído. Retomar uma sessão encerrada em modo não interativo com a flag -p gera erro e sai com código 1, portanto um script não lê a execução encerrada como um sucesso. A ferramenta nunca solicita permissão, e hooks PreToolUse não são executados para ela. Enquanto qualquer outra ferramenta permanecer, você também não pode bloqueá-la: regras de negação e solicitação nomeando EndConversation não têm efeito, e nem --disallowedTools nem uma lista --tools podem removê-la. A isenção é deliberada: a ferramenta não faz nada além de encerrar a conversa, nunca lendo ou modificando arquivos ou dados, e uma salvaguarda desse tipo só funciona se a sessão à qual se aplica não puder desativá-la. Quando suas regras de negação removem todas as outras ferramentas e também correspondem a EndConversation, como "*" faz, Claude Code a remove também em vez de deixá-la como a única ferramenta, a menos que uma regra de permissão nomeie EndConversation explicitamente. Uma lista de negação que remove todas as outras ferramentas sem corresponder a EndConversation a deixa em vigor. Subagentes nunca recebem a ferramenta. Tarefas em segundo plano que compartilham a lista de ferramentas da conversa principal a veem, mas chamá-la lá não encerra nada. A ferramenta aparece apenas quando todos os itens a seguir se aplicam:
  • Versão: Claude Code v2.1.213 ou posterior.
  • Modelo: o modelo da sessão é Claude Opus 4.8, Claude Sonnet 5, Claude Fable 5 ou uma versão posterior de uma dessas famílias.
  • Superfície: uma sessão de terminal interativa, incluindo uma sessão claude no terminal integrado de um IDE, que é como o plugin JetBrains a executa. Outras superfícies não incluem a ferramenta, como:
  • Modo de inicialização: não uma sessão --bare. O modo bare carrega apenas ferramentas de shell e arquivo, portanto a ferramenta nunca é registrada lá.
  • Provedor: não disponível em Amazon Bedrock, Claude Platform on AWS, Google Cloud’s Agent Platform ou Microsoft Foundry, ou em sessões conectadas através de um cloud gateway.

​
Comportamento da ferramenta Glob

A ferramenta Glob encontra arquivos por padrão de nome. No Windows, ela faz parte do conjunto de ferramentas padrão. No macOS, Linux e WSL, Claude Code deixa Glob e Grep fora do conjunto de ferramentas padrão, e Claude pesquisa com find e grep através da ferramenta Bash. No shell do Claude, esses dois comandos executam versões incorporadas de bfs e ugrep, e as pesquisas alcançam seus hooks e regras de permissão como chamadas Bash. No macOS, Linux e WSL, você recupera as ferramentas Glob e Grep nestes casos:
  • Você nomeia Glob ou Grep em --tools ou --allowedTools quando inicia a sessão, ou nas opções equivalentes do Agent SDK. Com --tools você obtém os que lista, e nomear qualquer ferramenta em --allowedTools restaura ambas. Uma regra de permissão em um arquivo de configurações não tem esse efeito.
  • Uma regra de negação de permissões, o sinalizador --disallowedTools, ou --restricted remove Bash da sessão.
  • Um subagente lista Glob ou Grep em seu campo tools e deixa Bash de fora. As ferramentas listadas voltam apenas para esse subagente, ou para toda a sessão quando é executado como o agente de sessão principal através de --agent ou da configuração agent.
Glob suporta sintaxe glob padrão, incluindo ** para correspondência recursiva de diretórios:
  • **/*.js corresponde a todos os arquivos .js em qualquer profundidade
  • src/**/*.ts corresponde a todos os arquivos .ts sob src/
  • *.{json,yaml} corresponde a arquivos .json e .yaml no diretório atual
Os resultados são classificados por tempo de modificação e limitados a 100 arquivos. Se o limite for atingido, Claude vê um sinalizador de truncamento no resultado e pode estreitar o padrão. Glob não respeita .gitignore por padrão, portanto encontra arquivos ignorados pelo git junto com os rastreados. Isso difere de Grep, que ignora arquivos gitignored. Para fazer Glob respeitar .gitignore, defina CLAUDE_CODE_GLOB_NO_IGNORE=false antes de iniciar Claude Code. Claude Code decide a permissão para uma chamada Glob antes de verificar se o diretório de pesquisa existe. Ele ainda executa a verificação de permissão de leitura para um path ausente fora dos diretórios de trabalho, portanto um prompt de permissão para um caminho não significa que o caminho existe. Um valor pattern ou path que contém um byte nulo retorna um erro pedindo a Claude para removê-lo.

​
Comportamento da ferramenta Grep

A ferramenta Grep pesquisa padrões no conteúdo dos arquivos. Enquanto Glob encontra arquivos por nome, Grep encontra linhas dentro deles. No macOS, Linux e WSL, Grep está ausente por padrão sob as mesmas condições que Glob. Veja Comportamento da ferramenta Glob para quando ambas as ferramentas estão disponíveis. Grep é construído em ripgrep e usa a sintaxe regex do ripgrep, não grep POSIX. Padrões que incluem metacaracteres regex precisam ser escapados. Por exemplo, encontrar interface{} em código Go requer o padrão interface\{\}. Um padrão, glob ou tipo de arquivo que ripgrep rejeita retorna um erro que inclui o diagnóstico do ripgrep, para que Claude possa corrigir a entrada e pesquisar novamente. Antes da v2.1.208, Claude Code relatava uma entrada rejeitada como No files found em vez de um erro, mesmo quando o texto pesquisado existia nos arquivos de destino. Três modos de saída controlam o que é retornado:
  • files_with_matches: apenas caminhos de arquivo, sem conteúdo de linha. Este é o padrão.
  • content: linhas correspondentes com arquivo e número de linha. Quando o parâmetro offset da ferramenta aponta para além da última correspondência de um padrão que tem correspondências, Grep retorna No entries at this offset, para que Claude amplie ou redefina o offset em vez de concluir que o padrão não corresponde.
  • count: contagem de correspondências por arquivo, seguida por um total em todos os arquivos correspondentes. O total cobre cada correspondência mesmo quando os parâmetros head_limit ou offset da ferramenta truncam as entradas listadas por arquivo. Antes da v2.1.208, o total apenas somava as entradas listadas.
Claude pode escopar resultados por arquivo com o parâmetro glob, como **/*.tsx, ou por linguagem com o parâmetro type, como py ou rust. Por padrão, padrões correspondem dentro de uma única linha. Claude pode definir multiline: true para corresponder através de limites de linha. Grep respeita .gitignore, portanto arquivos ignorados pelo git são ignorados. Para pesquisar um arquivo ignorado pelo git, Claude passa seu caminho diretamente. Claude Code decide permissão para uma chamada Grep antes de verificar se o path da pesquisa existe. Ele ainda executa a verificação de permissão de leitura para um path ausente fora dos diretórios de trabalho, portanto um prompt de permissão para um caminho não significa que o caminho existe.

​
Comportamento da ferramenta LSP

A ferramenta LSP fornece ao Claude inteligência de código de um servidor de linguagem em execução. Após cada edição de arquivo, ela relata automaticamente erros de tipo e avisos para que Claude possa corrigir problemas sem uma etapa de compilação separada. Claude também pode chamá-la diretamente para navegar no código:
  • Ir para a definição de um símbolo
  • Encontrar todas as referências a um símbolo
  • Obter informações de tipo em uma posição
  • Listar símbolos em um arquivo
  • Pesquisar um símbolo por nome em todo o workspace
  • Encontrar implementações de uma interface
  • Rastrear hierarquias de chamadas
Claude Code mantém a ferramenta inativa até que você instale um plugin de inteligência de código para sua linguagem. Em sessões na nuvem, Claude Code não inicia servidores de linguagem de plugin, portanto a ferramenta LSP permanece inativa lá. Claude Code obtém a configuração do servidor de linguagem do plugin, e você instala o binário do servidor você mesmo. Claude Code retorna um resultado de erro para cada chamada LSP em um arquivo cujo servidor de linguagem não consegue iniciar.

​
Ferramenta Monitor

A ferramenta Monitor permite que Claude observe algo em segundo plano e reaja quando muda, sem pausar a conversa. Peça a Claude para:
  • Monitorar um arquivo de log e sinalizar erros conforme aparecem
  • Pesquisar um PR ou trabalho de CI e relatar quando seu status muda
  • Observar um diretório para mudanças de arquivo
  • Rastrear saída de qualquer script de longa duração que você apontar
  • Conectar a um feed WebSocket e relatar cada mensagem conforme chega
Para a maioria das observações, Claude escreve um pequeno script, o executa em segundo plano e recebe cada linha de saída conforme chega. Para um servidor que já envia eventos, Claude pode abrir uma WebSocket em vez de executar um script. Você continua trabalhando na mesma sessão e Claude intervém quando um evento chega. Cada observação que Claude inicia tem um prazo: 5 minutos por padrão, no máximo 30 minutos, e no máximo 10 minutos em uma execução não interativa com um único prompt com -p. No prazo, a observação termina. Claude recebe um aviso, para que possa iniciar a observação novamente se ainda for necessária. Interrompa um monitor pedindo a Claude para cancelá-lo ou encerrando a sessão. Quando você interrompe um subagente que iniciou monitors, por exemplo de /tasks, esses monitors param com ele. Quando Monitor executa um comando, ele usa as mesmas regras de permissão que Bash, portanto os padrões allow e deny que você definiu para Bash também se aplicam aqui. Enquanto o modo auto está ativo, Claude Code deixa de lado as regras allow que nomeiam o próprio Monitor, junto com as outras regras allow amplas que ele descarta, portanto o classificador revisa comandos Monitor da mesma forma que revisa comandos Bash. A fonte WebSocket tem seu próprio prompt de aprovação, que o classificador também decide no modo auto. A ferramenta não está disponível no Amazon Bedrock, na Agent Platform do Google Cloud ou no Microsoft Foundry. Também não está disponível quando DISABLE_TELEMETRY ou CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC está definido. No Windows, a ferramenta está disponível apenas quando o Git Bash está instalado. Plugins podem declarar monitors que iniciam automaticamente quando o plugin está ativo, em vez de pedir a Claude para iniciá-los. Veja plugin monitors.

​
Fonte WebSocket

Quando um servidor já envia eventos por WebSocket, Claude pode se conectar diretamente em vez de escrever um script de pesquisa. Cada tipo de atividade de socket se torna um evento ou encerra a observação:
  • Mensagens de texto: cada uma se torna um evento, mesmo quando a mensagem abrange várias linhas.
  • Mensagens binárias: não são passadas. Claude recebe uma linha de espaço reservado como [binary frame, 512 bytes].
  • Mensagens maiores que 1 MiB: a observação termina, portanto inscreva-se em um feed filtrado onde existe um.
  • Fechamento de socket: a observação termina e Claude recebe o código de fechamento.
Uma observação WebSocket usa uma entrada ws no lugar de command, e uma única chamada Monitor não pode combinar os dois. A entrada ws tem dois campos: O prazo timeout_ms também se aplica a uma observação WebSocket: a observação termina no prazo, e TaskStop a cancela antecipadamente. Abrir uma WebSocket solicita aprovação; no modo auto o classificador decide em vez disso. O prompt não oferece uma opção para pular prompts futuros para o mesmo host. Claude Code nega URLs que apontam para um endereço privado, link-local ou de metadados de nuvem, incluindo nomes de host que resolvem para um. Também nega hosts em sandbox.network.deniedDomains, e quando allowManagedDomainsOnly está definido em configurações gerenciadas, qualquer host fora da allowlist gerenciada.

​
Comportamento da ferramenta NotebookEdit

NotebookEdit modifica um notebook Jupyter uma célula por vez, direcionando células por seu cell_id. Ela não realiza substituição de string em todo o notebook da forma que Edit faz em arquivos simples. Três modos de edição controlam o que acontece com a célula alvo:
  • replace: sobrescreve a fonte da célula. Este é o padrão.
  • insert: adiciona uma nova célula após a alvo. Sem cell_id, a nova célula vai no início do notebook. Requer cell_type definido como code ou markdown.
  • delete: remove a célula alvo.
NotebookEdit recusa um arquivo de notebook que não seja decodificado como UTF-8, sob a mesma regra que Edit, e não grava nada. Regras de permissão usam o formato de caminho Edit(...). Uma regra como Edit(notebooks/**) cobre chamadas NotebookEdit em arquivos nesse diretório.

​
Ferramenta PowerShell

A ferramenta PowerShell permite que Claude execute comandos PowerShell nativamente. No Windows, isso significa que os comandos são executados no PowerShell em vez de serem roteados através do Git Bash. Como a ferramenta fica disponível depende da sua plataforma:
  • Windows sem Git Bash: a ferramenta é ativada automaticamente.
  • Windows com Git Bash instalado: a ferramenta está ativada por padrão para contas claude.ai e Console; defina CLAUDE_CODE_USE_POWERSHELL_TOOL=1 para ativá-la em sessões do Amazon Bedrock, Google Cloud’s Agent Platform e Microsoft Foundry, ou 0 para desativá-la.
  • Linux, macOS e WSL: a ferramenta é opcional.
Seus hooks PreToolUse recebem a string de comando da ferramenta em tool_input.command, com os mesmos campos que a ferramenta Bash. Combine Bash|PowerShell em hooks que inspecionam comandos de shell; a seção de entrada do hook PowerShell explica por que combinar apenas Bash não é suficiente.

​
Ativar a ferramenta PowerShell

Defina CLAUDE_CODE_USE_POWERSHELL_TOOL=1 em seu ambiente ou em settings.json:
No Windows, defina a variável como 0 para desativar a ferramenta. No Linux, macOS e WSL, a ferramenta requer PowerShell 7 ou posterior: instale pwsh e certifique-se de que está em seu PATH. No Windows, Claude Code detecta automaticamente pwsh.exe para PowerShell 7+ com fallback para powershell.exe para PowerShell 5.1. Quando a ferramenta está ativada, Claude trata PowerShell como o shell principal. A ferramenta Bash permanece disponível para scripts POSIX quando Git Bash está instalado. Claude Code inicia PowerShell com -ExecutionPolicy Bypass apenas no escopo do processo, portanto scripts .ps1 e importações de módulos funcionam em instalações padrão do Windows sem alterar a política da máquina. O bypass no escopo do processo não substitui a Group Policy MachinePolicy ou UserPolicy, portanto as políticas corporativas ainda se aplicam. Para respeitar a política de execução efetiva da máquina, defina CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1.

​
Regras de negação do Bash também desativam a ferramenta PowerShell

No Windows com Git Bash instalado, negar o Bash também desativa a ferramenta PowerShell para a sessão. Isso se aplica a regras com escopo, como Bash(git push *), bem como a um Bash simples, e a regras de um dos seus arquivos de configuração ou de --disallowedTools. Claude Code faz isso porque uma regra Bash não restringe a ferramenta PowerShell, que tem suas próprias regras de permissão. Com o PowerShell ativado, Claude poderia executar nele o que sua regra nega no Bash. Para manter a ferramenta PowerShell ativada junto com uma regra de negação do Bash, faça uma destas opções: Sem uma dessas opções, uma regra de negação do Bash com escopo deixa a ferramenta Bash disponível, e Claude Code desativa o PowerShell sem aviso. Uma regra que remove a ferramenta Bash inteira deixa Claude sem nenhuma ferramenta de shell para a sessão.

​
Seleção de shell em configurações, hooks e skills

Três configurações adicionais controlam onde PowerShell é usado:
  • "defaultShell": "powershell" em settings.json: roteia comandos interativos ! através do PowerShell. Requer que a ferramenta PowerShell esteja ativada.
  • "shell": "powershell" em hooks de comando individuais: executa esse hook no PowerShell. Os hooks iniciam PowerShell diretamente, portanto isso funciona independentemente de CLAUDE_CODE_USE_POWERSHELL_TOOL.
  • shell: powershell em frontmatter de skill: executa blocos !`command` no PowerShell. Requer que a ferramenta PowerShell esteja ativada.
Os comandos PowerShell seguem o mesmo comportamento de redefinição de diretório de trabalho da sessão principal que os comandos Bash, incluindo a variável de ambiente CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR. Os comandos PowerShell também recebem as variáveis que os hooks persistem através de CLAUDE_ENV_FILE, nas condições descritas em Variáveis persistidas em comandos PowerShell. Requer Claude Code v2.1.296 ou posterior. O código de saída 1 de grep, rg, egrep, fgrep, findstr e git grep significa nenhuma correspondência. O código de saída 1 de git diff significa que existem diferenças. Nenhum resultado é relatado ao Claude como uma falha de comando. Para robocopy, códigos de saída de 0 a 7 são resultados informativos, como arquivos copiados ou arquivos extras detectados. Códigos de saída de 8 ou superior contam como falhas.

​
Codificação do Windows e códigos de saída

No Windows, os seguintes comportamentos de codificação e código de saída do PowerShell requerem Claude Code v2.1.214 ou posterior:
  • Redirecionamento com > e >> escreve arquivos UTF-8 no PowerShell 5.1
  • Claude Code codifica texto canalizado para a entrada padrão de um comando nativo como UTF-8
  • Claude Code captura saída de erro sem sequências de escape ANSI
  • Um comando cujo processo filho aguarda na entrada padrão recebe fim de arquivo em vez de travar
  • O código de saída 1 de where.exe significa nenhuma correspondência, e de fc.exe e diff.exe significa que os arquivos diferem, portanto quando o comando produz saída, Claude Code trata esse código de saída como uma resposta negativa válida em vez de um erro de comando. Claude Code ainda relata uma forma silenciada, como where.exe /Q ou um redirecionamento para $null, como uma falha no código de saída 1
Antes da v2.1.214, > no PowerShell 5.1 escrevia arquivos UTF-16LE, entrada não-ASCII canalizada chegava como ?, e scripts Python poderiam falhar com um UnicodeEncodeError ao imprimir caracteres não-ASCII.

​
Limitações de visualização

A ferramenta PowerShell tem as seguintes limitações conhecidas durante a visualização:
  • Perfis do PowerShell não são carregados
  • No Windows, sandboxing não é suportado

​
Comportamento da ferramenta Read

A ferramenta Read recebe um caminho de arquivo e retorna o conteúdo com números de linha. Claude é instruído a sempre passar caminhos absolutos. Ler um arquivo vazio retorna um aviso de que o arquivo existe mas seu conteúdo está vazio, e um offset além da última linha retorna um aviso informando a contagem de linhas do arquivo. Antes da v2.1.208, ler um arquivo vazio retornava o aviso past-the-end em vez disso. Read lida com vários tipos de arquivo além de texto simples:
  • Imagens: PNG, JPG e outros formatos de imagem são retornados como conteúdo visual que Claude pode ver, não como bytes brutos. Claude Code redimensiona e recompacta imagens grandes para se adequarem aos limites de tamanho de imagem do modelo antes de enviá-las, então Claude pode ver uma versão reduzida de uma captura de tela grande. Uma imagem que ainda é maior que 500KB após esse redimensionamento é re-codificada como JPEG com qualidade reduzida com suas dimensões de pixel inalteradas. Se Claude perder detalhes de nível de pixel fino em uma imagem grande, peça-lhe para cortar a região de interesse primeiro, por exemplo com ImageMagick via Bash.
  • PDFs: Claude lê arquivos .pdf curtos por inteiro. Para PDFs com mais de 10 páginas, ele lê em intervalos com um parâmetro pages, como "1-5", até 20 páginas por vez. Leituras de intervalo de páginas renderizam páginas com pdftoppm do poppler-utils, então instale-o com brew install poppler no macOS ou apt-get install poppler-utils no Debian e Ubuntu. No Windows e outras plataformas, instale uma compilação do poppler que coloque pdftoppm no seu PATH. Sem ele, uma leitura de intervalo de páginas falha com pdftoppm is not installed.
  • Notebooks Jupyter: arquivos .ipynb retornam todas as células com suas saídas, incluindo código, markdown e visualizações. Um notebook cujas células somam mais de 256 KB, ou mais do que o limite de tokens, retorna um erro em vez disso. Claude Code recusa-se a ler um arquivo de notebook com mais de 100 MB; o erro informa a Claude como ler uma porção do notebook em vez disso, como uma fatia de células, com um comando shell.
Read apenas lê arquivos, não diretórios. Claude lista o conteúdo do diretório com um comando shell como ls.

​
Arquivos grandes

Claude pode ler um arquivo de texto maior do que uma única chamada de Read retorna. Por padrão, uma chamada retorna no máximo 25.000 tokens, ou o valor que você definir em CLAUDE_CODE_FILE_READ_MAX_OUTPUT_TOKENS, e recusa um arquivo inteiro com mais de 256 KB, então Claude lê um arquivo maior em páginas com offset e limit. No Claude Code v2.1.296 ou posterior, ele pode, em vez disso, ler o arquivo inteiro, ou um intervalo longo de linhas, em uma única chamada definindo allow_large: true quando precisar, por exemplo porque você pediu o arquivo inteiro. Essa leitura é dimensionada de acordo com o espaço restante na janela de contexto da sessão em vez dos limites padrão. Imagens, PDFs e notebooks mantêm seus limites. O que Claude recebe quando uma leitura ultrapassa os limites padrão:
  • Arquivo inteiro acima do limite de tokens: a primeira página do arquivo, com um aviso de PARTIAL view informando quanto do arquivo foi recebido e como ler mais com offset e limit
  • Arquivo inteiro acima de 256 KB, ou uma leitura com offset ou limit acima do limite de tokens: um erro informando para ler uma porção com offset e limit, ou para procurar conteúdo específico com Grep em vez disso

​
Comportamento da ferramenta SendFeedback

O feedback redigido pelo Claude é um relatório de feedback sobre o Claude Code que o Claude escreve para você. Ele requer o Claude Code v2.1.238 ou posterior. O Claude Code salva cada rascunho na sua máquina em ~/.claude/feedback/drafts/, e nada chega à Anthropic até que você o envie. O Claude redige um com a ferramenta SendFeedback quando:
  • Uma ferramenta ou comando continua falhando
  • Ele não consegue ajudar com algo que você pediu
  • Você aponta um erro que ele cometeu, ou ele percebe um
  • Você pede que ele registre um feedback

​
O que você vê quando o Claude redige

Depois que o Claude coloca um rascunho na fila, você vê um cartão acima do seu prompt com o título do rascunho. Pressione 1 para revisar o rascunho, pressione 2 duas vezes para enviá-lo como está escrito ou pressione 0 para dispensar o cartão. Um rascunho dispensado permanece na sua fila. Depois que você dispensa um cartão, o Claude Code pergunta se deseja desativar o feedback redigido pelo Claude. Ele para de perguntar depois que você recusar duas vezes. Por padrão, você vê no máximo três cartões em uma sessão; a Anthropic pode ajustar esse limite pelo servidor sem uma nova versão. Após o limite, e sempre que você definir feedbackDrafts como quiet, você vê apenas uma contagem de rascunhos na fila no rodapé do prompt.

​
Revisar e editar um rascunho

Execute /feedback sem argumento para abrir sua fila. Ela lista todos os rascunhos na fila de todas as suas sessões, incluindo rascunhos cujos cartões você dispensou ou nunca viu. Selecione um rascunho para abri-lo para revisão, onde você pode:
  • Editar o título, a área e os detalhes
  • Definir Send transcript como yes ou no. Quando a transcrição da sessão em que o Claude colocou o rascunho na fila ainda está disponível, o valor começa como yes, o que envia essa conversa à Anthropic; no envia apenas o relatório
  • Enviar o rascunho, descartá-lo ou deixá-lo na fila para depois
Para escrever um relatório você mesmo, pressione w para abrir a caixa de diálogo de feedback padrão. /feedback seguido de texto, e /bug, abrem essa caixa de diálogo diretamente.

​
Enviar um rascunho

Quando você envia um rascunho, o Claude Code o envia da mesma forma que um relatório de /feedback, com a mesma retenção, e exclui o rascunho da sua máquina. Quando você envia pelo cartão, ele mostra ✓ Sent; quando você envia pela fila, ela se fecha com um ID de recibo. O relatório contém:
  • Seu título, área e detalhes
  • Informações do ambiente, como sua versão do Claude Code, sistema operacional e modelo
  • Os IDs das requisições recentes de API
  • A transcrição da conversa, quando você deixou Send transcript como yes na tela de revisão. O envio pelo cartão nunca inclui a transcrição
O Claude Code mantém seu diretório de trabalho no rascunho local para poder encontrar a transcrição, e não envia o diretório. Em organizações com Zero Data Retention, e em organizações com a configuração HIPAA aplicada, o Claude Code deixa a ferramenta de fora, assim como faz com /feedback. Se uma sessão em uma organização com Zero Data Retention ainda oferecer a ferramenta, os rascunhos permanecem na sua máquina e o envio falha com Feedback collection is not available for organizations with custom data retention policies.

​
Descartar ou manter um rascunho

Quando você descarta um rascunho, o Claude Code o exclui da sua máquina. Um rascunho que você deixa na fila expira após 30 dias, ou após cleanupPeriodDays quando esse período for menor. A fila comporta 10 rascunhos entre todas as suas sessões e, quando o Claude coloca um décimo primeiro na fila, o Claude Code exclui o mais antigo. Quando você executa /exit com rascunhos da sessão ainda na fila, o Claude Code pergunta se deseja revisá-los ou descartá-los antes de sair.

​
Desativar o feedback redigido pelo Claude

Defina Claude-drafted feedback como off em /config, o que grava a configuração feedbackDrafts, ou defina CLAUDE_CODE_SEND_FEEDBACK=0 para uma sessão. Com qualquer uma das opções, o Claude não pode colocar rascunhos na fila. Para manter a redação ativada sem cartões, defina feedbackDrafts como quiet. Administradores podem definir feedbackDrafts nas configurações gerenciadas, que têm precedência sobre sua própria configuração.

​
Sessões sem feedback redigido pelo Claude

O Claude Code inclui a ferramenta em sessões interativas de terminal na sua própria máquina que usam a Claude API em vez de um provedor de nuvem. Ele deixa a ferramenta de fora de:

​
Disponibilidade da ferramenta Task

As ferramentas de rastreamento de tarefas, TaskCreate, TaskGet, TaskUpdate, TaskList e TodoWrite, estão disponíveis por padrão apenas no Opus 4.7, Sonnet 4.6, Haiku 4.5 e em modelos anteriores. Sempre que as ferramentas estão disponíveis, você obtém as quatro ferramentas Task, ou TodoWrite quando você define CLAUDE_CODE_ENABLE_TASKS=0. Em todos os outros modelos, Claude Code deixa as ferramentas de fora a menos que você opte por usá-las. O mesmo se aplica a um ID de modelo que Claude Code não reconhece, como um nome de modelo personalizado servido através de um gateway LLM. Em modelos mais novos, Claude acompanha o trabalho em várias etapas sem uma lista de verificação escrita, e as definições e lembretes das ferramentas ocupam contexto. Sem as ferramentas, Claude não adiciona nada à lista de tarefas enquanto trabalha. Se você gostaria de usar essas ferramentas em um modelo que não as possui por padrão, faça um dos seguintes:
  • Exporte CLAUDE_CODE_ENABLE_TODO_TOOLS=1 antes de iniciar Claude Code, por exemplo CLAUDE_CODE_ENABLE_TODO_TOOLS=1 claude. Claude Code então fornece as mesmas ferramentas em todos os modelos e todos os provedores
  • Nomeie uma das ferramentas em --allowedTools, por exemplo claude --allowedTools TaskCreate
  • Liste as ferramentas em --tools, que restringe as ferramentas integradas da sessão àquelas que ela nomeia. Inclua as ferramentas que você deseja junto com as outras ferramentas integradas que você usa
  • No Agent SDK, as opções allowedTools e tools funcionam da mesma forma que os dois sinalizadores
Em sessões em segundo plano e em sessões na nuvem, Claude Code fornece as mesmas ferramentas em todos os modelos, listados ou não. Claude Code fornece a um suagente as ferramentas apenas quando sua sessão as possui, mesmo quando o suagente executa um modelo diferente. Um colega de equipe de agentes em processo segue sua sessão da mesma forma, enquanto um colega em seu próprio painel dividido é executado como um processo Claude Code separado, portanto seu próprio modelo decide. Sem as ferramentas Task, um agente coordena com sua equipe através de mensagens em vez da lista de tarefas compartilhada. O conjunto padrão descrito aqui se aplica no Claude Code v2.1.268 e posterior.

​
Comportamento da ferramenta WebFetch

WebFetch recebe uma URL e um prompt descrevendo o que extrair. Ele busca a página e converte a resposta para Markdown quando o servidor retorna HTML. Para a maioria das buscas, ele então executa o prompt contra o conteúdo em uma chamada de modelo separada, e Claude recebe o resultado dessa chamada em vez da página bruta. A etapa de conversão não é configurável. Isso torna WebFetch lossy por design. O prompt de extração determina o que chega a Claude, então um resultado que diz que uma página não menciona algo pode apenas significar que o prompt não perguntou sobre isso. Peça a Claude para buscar novamente com um prompt mais específico, ou use curl via Bash para a página não processada. Alguns comportamentos moldam a resposta que Claude recebe:
  • WebFetch recusa localhost e qualquer outro nome de host sem um ponto, como um nome de intranet simples, antes de fazer uma solicitação. O erro que retorna diz a Claude para alcançar servidores locais com curl através do Bash.
  • URLs HTTP são automaticamente atualizadas para HTTPS.
  • WebFetch lê até 100.000 caracteres do conteúdo de uma página por chamada. No Claude Code v2.1.290 ou posterior, o resultado para uma página mais longa informa a Claude quanto ficou sem ser lido, para que Claude possa buscar a próxima parte.
  • WebFetch armazena em cache cada resposta por 15 minutos por padrão, então buscas repetidas da mesma URL retornam rapidamente. No Claude Code v2.1.233 ou posterior, defina CLAUDE_CODE_WEBFETCH_CACHE_TTL_MS para alterar quanto tempo WebFetch mantém cada resposta.
  • Uma página que não terminou de fazer download em cinco minutos, incluindo qualquer redirecionamento que WebFetch segue, falha com um erro de deadline. No Claude Code v2.1.268 ou posterior, defina CLAUDE_CODE_WEBFETCH_DEADLINE_MS para alterar o limite, ou para 0 para removê-lo.
  • Quando uma URL redireciona para um host diferente, WebFetch retorna um resultado de texto que nomeia a URL original e o alvo de redirecionamento em vez de segui-lo. Claude então busca a nova URL com uma segunda chamada WebFetch.
  • Quando a etapa de extração atinge uma API sobrecarregada, Claude Code tenta novamente com backoff; uma busca que ainda falha retorna um resultado de erro. Antes da v2.1.212, o texto de erro da API poderia chegar a Claude como se fosse o conteúdo da página extraída.
Nos modos Manual e acceptEdits permission modes, WebFetch solicita antes de buscar, exceto para domínios que suas permission rules já permitem ou negam e um conjunto integrado de domínios de documentação pré-aprovados que buscam sem um prompt. Qualquer que seja suas regras permitam, uma busca também passa pela WebFetch domain safety check primeiro; essa seção cobre o que a verificação envia e a configuração que a ignora. O prompt oferece três opções:
  • Yes: aprova apenas esta busca. A próxima chamada WebFetch solicita novamente, mesmo para o mesmo domínio.
  • Yes, and don’t ask again for <domain>: aprova a busca e salva uma regra de permissão WebFetch(domain:...) para esse domínio em .claude/settings.local.json para esse repositório. Veja como as aprovações salvas persistem. Quando sua organização define allowManagedPermissionRulesOnly, Claude Code oculta essa opção.
  • No, and tell Claude what to do differently: rejeita a busca.
Para permitir um domínio antecipadamente sem um prompt, adicione uma regra de permissão como WebFetch(domain:example.com); WebFetch(domain:*) permite todos os domínios. Os modos de permissão auto e bypassPermissions permission modes ignoram o prompt, exceto para um domínio que uma regra ask explícita corresponde. Uma regra WebFetch(domain:...) explícita em deny, ask ou allow tem precedência sobre o conjunto pré-aprovado, então você pode bloquear um domínio pré-aprovado ou exigir um prompt para ele. Quando a URL é um link de artefato do claude.ai, Claude Code também pode pedir aprovação para ler o próprio artefato. Para os casos em que ele pede, consulte Ler um artefato compartilhado com você. WebFetch define um cabeçalho User-Agent começando com Claude-User, e um cabeçalho Accept que prefere Markdown sobre HTML para que servidores que suportam negociação de conteúdo possam retornar Markdown diretamente. Comandos em sandbox não herdam o conjunto integrado de domínios de documentação pré-aprovados do WebFetch. Para permitir que um comando em sandbox alcance um domínio sem um prompt, adicione o domínio a allowedDomains ou permita-o com uma regra WebFetch(domain:...), que o sandbox também honra. WebFetch nunca lê a lista de permissões do sandbox em troca, então adicionar um domínio a um sandbox ou lista de permissões de rede da organização não impede que WebFetch solicite por ele.

​
Disponibilidade do WebFetch

No Claude Code v2.1.285 ou posterior, defina CLAUDE_CODE_DISABLE_WEB_FETCH para 1 para desativar WebFetch. Se você entrar com uma conta Team ou Enterprise claude.ai e não se conectar através de um LLM gateway, WebFetch também depende da política da sua organização, que Claude Code solicita de api.anthropic.com quando uma sessão é iniciada. O mesmo vale para uma sessão cuja plano Claude Code não consegue determinar, como uma executada sob um token claude.ai que outro aplicativo forneceu. Se WebFetch estiver faltando em uma sessão, execute /status na sessão. Se sua linha Organization policy relatar que a política não foi carregada e nomear web fetch entre os recursos que aguardam por ela, Claude Code está retendo WebFetch até que possa confirmar que sua organização permite. Fora de uma sessão, claude doctor faz sua própria solicitação e imprime a mesma linha. Assim que uma política que permite WebFetch for carregada, a ferramenta retorna sem uma reinicialização.

​
Comportamento da ferramenta WebSearch

WebSearch executa uma consulta no backend de web search da Anthropic e retorna títulos e URLs dos resultados. Ele não busca as páginas de resultados. Para ler uma página que Claude encontra nos resultados de busca, ele faz um acompanhamento com WebFetch. A ferramenta pode emitir até oito buscas de backend por chamada, refinando a busca internamente antes de retornar resultados. Claude pode delimitar resultados com allowed_domains para incluir apenas certos hosts, ou blocked_domains para excluí-los. As duas listas não podem ser combinadas em uma única chamada. Quando a solicitação de busca atinge uma API sobrecarregada, Claude Code tenta novamente com backoff; uma chamada que ainda falha retorna um resultado de erro. Antes da v2.1.212, o texto de erro da API poderia chegar a Claude como se fossem resultados de busca. As regras de permissão do WebSearch não usam especificador. Uma entrada WebSearch simples em allow ou deny é a única forma. O backend de busca não é configurável. Para buscar com um provedor diferente, adicione um servidor MCP que exponha uma ferramenta de busca.
WebSearch está disponível na Claude API, na Claude Platform on AWS e no Microsoft Foundry. Na Agent Platform do Google Cloud, funciona com Opus 4, Sonnet 4, Haiku 4.5 e modelos posteriores. Amazon Bedrock não expõe a ferramenta de web search do lado do servidor.

​
Limite de busca da sessão

Uma sessão interativa no terminal tem um limite de 200 chamadas do WebSearch. As buscas da conversa principal e de subagentes, como um fan-out de pesquisa paralela, contam contra o mesmo limite. O limite requer Claude Code v2.1.212 ou posterior. Enquanto uma sessão está no limite, as buscas aparecem na conversa como chamadas que não fizeram nada. Claude recebe um aviso dizendo a ele para continuar com as informações que já reuniu e, se precisar de mais buscas, para pedir que você aumente o limite. Para obter mais buscas, aumente o limite, aguarde o limite ser reabastecido ou inicie uma nova conversa:
  • Aumentar o limite: defina a variável de ambiente CLAUDE_CODE_MAX_WEB_SEARCHES_PER_SESSION com um número inteiro positivo, como 500. O limite pode ser aumentado, mas não desativado.
  • Aguardar o reabastecimento: no Claude Code v2.1.290 ou posterior, o limite de uma sessão interativa no terminal é reabastecido a cerca de 100 chamadas por hora. Para alterar a taxa, defina CLAUDE_CODE_WEB_SEARCH_REFILLS_PER_HOUR com um número de chamadas por hora, como 50.
  • Iniciar uma nova conversa: executar /clear no prompt do Claude Code também redefine a contagem. Se o trabalho que ainda pode gerar subagentes sobreviver à limpeza, como um fluxo de trabalho em execução, a contagem é mantida.

​
Comportamento da ferramenta Write

A ferramenta Write cria um novo arquivo ou sobrescreve um existente com o conteúdo completo fornecido. Ela não anexa ou mescla. A Write também sobrescreve um arquivo existente cujos bytes não podem ser decodificados e salva o novo conteúdo como UTF-8, conforme descrito em arquivos não UTF-8. Se Claude deve ler um arquivo existente na conversa atual antes de sobrescrevê-lo depende do modelo e do arquivo:
  • Claude Opus 4.6, Claude Haiku 4.5 e modelos mais antigos sempre exigem a leitura, portanto uma Write para um arquivo existente não lido falha com um erro.
  • Modelos mais novos podem sobrescrever um arquivo que nunca leram nesta sessão sob as mesmas condições que read-before-edit: lê-lo não precisaria de um prompt de permissão e a ferramenta Read está disponível.
  • Notebooks Jupyter e arquivos que Claude leu apenas parcialmente com um aviso PARTIAL view exigem a leitura em todos os modelos.
Esta restrição não se aplica a novos arquivos. Antes da v2.1.228, todos os modelos exigiam a leitura antes de sobrescrever um arquivo existente. Visualizar o arquivo com Bash também satisfaz este requisito sob as mesmas regras descritas em Comportamento da ferramenta Edit. Para alterações parciais em um arquivo existente, Claude usa Edit em vez de Write.

​
Verificar quais ferramentas estão disponíveis

Seu conjunto exato de ferramentas depende do seu provedor, plataforma e configurações. Para verificar o que está carregado em uma sessão em execução, pergunte a Claude diretamente:
Claude fornece um resumo conversacional. Para nomes exatos de ferramentas MCP, execute /mcp.
A ferramenta advisor é uma ferramenta de servidor que a API executa, em vez de uma ferramenta que Claude Code implementa. Ela não tem um nome que você possa referenciar em regras de permissão ou correspondências de hook.

​
Veja também

  • Servidores MCP: adicione ferramentas personalizadas conectando servidores externos
  • Permissões: sistema de permissões, sintaxe de regras e padrões específicos de ferramentas
  • Subagents: configure o acesso a ferramentas para subagents
  • Hooks: execute comandos personalizados antes ou depois da execução da ferramenta