> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Referência de ferramentas
> Referência completa para as ferramentas que Claude Code pode usar, incluindo requisitos de permissão e comportamento por ferramenta.
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](/pt/permissions#tool-specific-permission-rules), [listas de ferramentas de subagent](/pt/sub-agents) e [correspondências de hooks](/pt/hooks). Para desabilitar uma ferramenta completamente, adicione seu nome ao array `deny` em suas [configurações de permissão](/pt/permissions#tool-specific-permission-rules).
Para adicionar ferramentas personalizadas, conecte um [servidor MCP](/pt/mcp). Para estender Claude com fluxos de trabalho baseados em prompts reutilizáveis, escreva uma [skill](/pt/skills), que é executada através da ferramenta `Skill` existente em vez de adicionar uma nova entrada de ferramenta.
| Ferramenta | Descrição | Permissão Necessária |
| :--------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :------------------- |
| `Agent` | Cria um [subagent](/pt/sub-agents) com sua própria janela de contexto para lidar com uma tarefa. Veja [comportamento da ferramenta Agent](#agent-tool-behavior) | Não |
| `Artifact` | Publica um arquivo HTML ou Markdown como um [artifact](/pt/artifacts): uma página privada e interativa no claude.ai que você pode compartilhar dentro de sua organização. {/* plan-availability: feature=artifacts plans=team,enterprise providers=anthropic */}Requer um plano Team ou Enterprise e autenticação `/login`; veja [Disponibilidade](/pt/artifacts#availability) | Sim |
| `AskUserQuestion` | Faz perguntas de múltipla escolha para coletar requisitos ou esclarecer ambiguidades | Não |
| `Bash` | Executa comandos de shell em seu ambiente. Veja [comportamento da ferramenta Bash](#bash-tool-behavior) | Sim |
| `CronCreate` | Agenda uma solicitação recorrente ou única dentro da sessão atual. As tarefas têm escopo de sessão e são restauradas em `--resume` ou `--continue` se não expiradas. Veja [tarefas agendadas](/pt/scheduled-tasks) | Não |
| `CronDelete` | Cancela uma tarefa agendada por ID | Não |
| `CronList` | Lista todas as tarefas agendadas na sessão | Não |
| `Edit` | Faz edições direcionadas em arquivos específicos. Veja [comportamento da ferramenta Edit](#edit-tool-behavior) | Sim |
| `EnterPlanMode` | Muda para Plan Mode para projetar uma abordagem antes de codificar | Não |
| `EnterWorktree` | Cria um [git worktree](/pt/worktrees) isolado e muda para ele. Passe um `path` para mudar para um worktree existente do repositório atual em vez de criar um novo. De dentro de uma sessão de worktree, ou de um subagent com um diretório de trabalho fixado como [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields), apenas a forma `path` está disponível e o destino deve estar sob `.claude/worktrees/` | Não |
| `ExitPlanMode` | Apresenta um plano para aprovação e sai do Plan Mode | Sim |
| `ExitWorktree` | Sai de uma sessão de worktree e retorna ao diretório original. Não disponível para subagents que já são executados em seu próprio diretório de trabalho, como com [`isolation: worktree`](/pt/sub-agents#supported-frontmatter-fields) | Não |
| `Glob` | Encontra arquivos com base em correspondência de padrões. Veja [comportamento da ferramenta Glob](#glob-tool-behavior) | Não |
| `Grep` | Pesquisa padrões no conteúdo de arquivos. Veja [comportamento da ferramenta Grep](#grep-tool-behavior) | Não |
| `ListMcpResourcesTool` | Lista recursos expostos por [servidores MCP](/pt/mcp) conectados | Não |
| `LSP` | Inteligência de código via servidores de linguagem: ir para definições, encontrar referências, relatar erros de tipo e avisos. Veja [comportamento da ferramenta LSP](#lsp-tool-behavior) | Não |
| `Monitor` | Executa um comando em segundo plano e alimenta cada linha de saída de volta para Claude, para que ele possa reagir a entradas de log, mudanças de arquivo ou status consultado no meio da conversa. Também pode abrir um WebSocket e tratar cada mensagem recebida como um evento. Veja [ferramenta Monitor](#monitor-tool) | Sim |
| `NotebookEdit` | Modifica células de notebook Jupyter. Veja [comportamento da ferramenta NotebookEdit](#notebookedit-tool-behavior) | Sim |
| `PowerShell` | Executa comandos PowerShell nativamente. Veja [ferramenta PowerShell](#powershell-tool) para disponibilidade | Sim |
| `PushNotification` | Envia uma notificação de desktop e um push de telefone quando [Remote Control](/pt/remote-control) está conectado, para que uma tarefa de longa duração ou [tarefa agendada](/pt/scheduled-tasks) possa alcançá-lo quando você se afastar. {/* plan-availability: feature=push-notifications providers=anthropic */}A entrega de push é executada através de infraestrutura hospedada pela Anthropic, que não é acessível do Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |
| `Read` | Lê o conteúdo de arquivos. Veja [comportamento da ferramenta Read](#read-tool-behavior) | Não |
| `ReadMcpResourceTool` | Lê um recurso MCP específico por URI | Não |
| `RemoteTrigger` | Cria, atualiza, executa e lista [Routines](/pt/routines) no claude.ai. Suporta o comando `/schedule`. {/* plan-availability: feature=routines plans=pro,max,team,enterprise providers=anthropic */}Routines vivem no claude.ai e requerem um plano Pro, Max, Team ou Enterprise, portanto esta ferramenta não é acessível do Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |
| `ReportFindings` | Relata descobertas de revisão de código como uma lista estruturada, com um arquivo, resumo e cenário de falha por descoberta, para que Claude Code possa renderizá-las em vez de imprimi-las como texto. Claude a chama quando instruções ativas de revisão de código dizem para fazê-lo. {/* min-version: 2.1.196 */}Requer Claude Code v2.1.196 ou posterior | Não |
| `ScheduleWakeup` | Reagenda a próxima iteração de um [`/loop` auto-paced](/pt/scheduled-tasks#let-claude-choose-the-interval). Claude chama isso no final de cada iteração para escolher quando a próxima será executada, entre um minuto e uma hora; você não a chama diretamente. O wakeup pendente aparece em `session_crons` em [Stop hook input](/pt/hooks#stop-input). {/* plan-availability: feature=loop-dynamic providers=anthropic */}Não disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry, onde um prompt `/loop` sem intervalo é executado em um cronograma fixo | Não |
| `SendMessage` | Envia uma mensagem para um [membro da equipe de agentes](/pt/agent-teams), ou [retoma um subagent](/pt/sub-agents#resume-subagents) por seu ID de agente. Subagents parados retomam automaticamente em segundo plano. Mensagens de protocolo de equipe estruturadas requerem equipes de agentes | Não |
| `SendUserFile` | Envia arquivos da sessão para você com uma legenda opcional, para que um relatório gerado, diagrama, captura de tela ou artefato construído chegue ao seu dispositivo em vez de apenas ser mencionado na transcrição. {/* min-version: 2.1.196 */}A partir de v2.1.196, a entrada `display` opcional controla a apresentação: `render` abre o arquivo inline no cliente, `attach` mostra apenas um cartão de download, e quando não definido o cliente decide pelo tipo de arquivo. Disponível quando um cliente [Remote Control](/pt/remote-control) está conectado ou a sessão é executada em um ambiente de nuvem gerenciado como [Claude Code na web](/pt/claude-code-on-the-web). A entrega é executada através de infraestrutura hospedada pela Anthropic, portanto a ferramenta não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry | Não |
| `ShareOnboardingGuide` | {/* plan-availability: feature=onboarding-guide-share plans=pro,max,team,enterprise providers=anthropic */}Carrega `ONBOARDING.md` e retorna um link de compartilhamento que colegas podem abrir no Claude Code. Chamado de `/team-onboarding` após o guia ser escrito. Disponível para assinantes do claude.ai em planos Pro, Max, Team e Enterprise | Sim |
| `Skill` | Executa uma [skill](/pt/skills#control-who-invokes-a-skill) dentro da conversa principal | Sim |
| `TaskCreate` | Cria uma nova tarefa na lista de tarefas | Não |
| `TaskGet` | Recupera detalhes completos para uma tarefa específica | Não |
| `TaskList` | Lista todas as tarefas com seu status atual | Não |
| `TaskOutput` | (Descontinuado) Recupera saída de uma tarefa em segundo plano. Prefira `Read` no caminho do arquivo de saída da tarefa | Não |
| `TaskStop` | Mata uma tarefa em segundo plano em execução por ID | Não |
| `TaskUpdate` | Atualiza status da tarefa, dependências, detalhes ou deleta tarefas | Não |
| `TodoWrite` | {/* min-version: 2.1.142 */}Gerencia a lista de verificação de tarefas da sessão. Desabilitado por padrão a partir de v2.1.142 em favor de `TaskCreate`, `TaskGet`, `TaskList` e `TaskUpdate`. Defina `CLAUDE_CODE_ENABLE_TASKS=0` para reabilitar | Não |
| `ToolSearch` | Pesquisa e carrega ferramentas diferidas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está ativada | Não |
| `WaitForMcpServers` | {/* min-version: 2.1.142 */}Aguarda um ou mais [servidores MCP](/pt/mcp) que ainda estão se conectando em segundo plano, para que uma solicitação possa usar suas ferramentas sem reiniciar a sessão. Claude a chama quando um servidor necessário ainda não está conectado. Aparece apenas quando [pesquisa de ferramentas](/pt/mcp#scale-with-mcp-tool-search) está desabilitada, já que `ToolSearch` lida com a espera quando está ativada | Não |
| `WebFetch` | Busca conteúdo de uma URL especificada. Veja [comportamento da ferramenta WebFetch](#webfetch-tool-behavior) | Sim |
| `WebSearch` | Realiza pesquisas na web. Veja [comportamento da ferramenta WebSearch](#websearch-tool-behavior) | Sim |
| `Workflow` | Executa um [fluxo de trabalho dinâmico](/pt/workflows): um script que orquestra muitos subagents em segundo plano e retorna um resultado consolidado | Sim |
| `Write` | Cria ou sobrescreve arquivos. Veja [comportamento da ferramenta Write](#write-tool-behavior) | Sim |
Na maioria dos casos, Claude decide quando usar essas ferramentas e você não precisa nomeá-las quando interage com Claude. Você referencia nomes de ferramentas diretamente ao definir permissões e outras configurações:
* em [`permissions.allow` e `permissions.deny`](/pt/settings#available-settings) em configurações e na interface `/permissions`
* nos sinalizadores CLI [`--allowedTools` e `--disallowedTools`](/pt/cli-reference)
* nas opções [`allowedTools` e `disallowedTools`](/pt/agent-sdk/permissions#allow-and-deny-rules) do Agent SDK
* no [frontmatter `tools` ou `disallowedTools`](/pt/sub-agents#supported-frontmatter-fields) de um subagent
* no frontmatter [`allowed-tools`](/pt/skills#frontmatter-reference) de uma skill
* na [condição `if`](/pt/hooks-guide#filter-by-tool-name-and-arguments-with-the-if-field) de um hook
Todos esses aceitam o mesmo formato de regra, `ToolName(specifier)`. O especificador depende da ferramenta, e várias ferramentas compartilham um formato:
| Formato de regra | Aplica-se a | Detalhes |
| :----------------------------- | :------------------------ | :------------------------------------------------------------------------------------ |
| `Bash(npm run *)` | Bash, Monitor | [Correspondência de padrão de comando](/pt/permissions#bash) |
| `PowerShell(Get-ChildItem *)` | PowerShell | [Correspondência de padrão de comando](/pt/permissions#powershell) |
| `Read(~/secrets/**)` | Read, Grep, Glob, LSP | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |
| `Edit(/src/**)` | Edit, Write, NotebookEdit | [Correspondência de padrão de caminho](/pt/permissions#read-and-edit) |
| `Skill(deploy *)` | Skill | [Correspondência de nome de skill](/pt/skills#restrict-claude%E2%80%99s-skill-access) |
| `Agent(Explore)` | Agent | [Correspondência de tipo de subagent](/pt/permissions#agent-subagents) |
| `WebFetch(domain:example.com)` | WebFetch | [Correspondência de domínio](/pt/permissions#webfetch) |
| `WebSearch` | WebSearch | Sem especificador; permitir ou negar a ferramenta como um todo |
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.
Os campos `matcher` de hooks usam nomes de ferramentas simples, não o formato de regra entre parênteses. Veja [padrões de correspondência](/pt/hooks#matcher-patterns) para as regras de correspondência. Para os nomes de campos que cada ferramenta passa para `tool_input` em hooks, veja a [referência de entrada PreToolUse](/pt/hooks#pretooluse-input).
A ferramenta Agent cria um subagent em uma janela de contexto separada. O subagent trabalha através de sua tarefa autonomamente, depois retorna um único resultado de texto para a conversa pai. O pai não vê as chamadas de ferramenta intermediárias ou saídas do subagent, apenas esse resultado final. Para limitar quantas voltas um subagent executa, defina `maxTurns` na [definição do subagent](/pt/sub-agents#supported-frontmatter-fields).
A mesma ferramenta Agent também inicia [subagents bifurcados](/pt/sub-agents#fork-the-current-conversation) quando o modo de bifurcação está ativado. Uma bifurcação herda a conversa pai completa em vez de começar do zero, sempre é executada em segundo plano e ainda exibe prompts de permissão em seu terminal. O resto desta seção descreve subagents nomeados.
Quais ferramentas um subagent nomeado pode usar depende dos campos `tools` e `disallowedTools` na [definição do subagent](/pt/sub-agents):
* **Nenhum campo definido**: o subagent herda todas as ferramentas disponíveis para o pai.
* **Apenas `tools`**: o subagent obtém apenas as ferramentas listadas.
* **Apenas `disallowedTools`**: o subagent obtém todas as ferramentas pai exceto as listadas.
* **Ambos definidos**: `disallowedTools` tem precedência. Uma ferramenta listada em ambos é removida.
Iniciar o subagent não solicita permissão por si só. As chamadas de ferramenta do subagent são verificadas contra suas regras de permissão conforme ele é executado:
* **Subagents 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.
* **Subagents em segundo plano** {/* min-version: 2.1.186 */}exibem prompts de permissão em sua sessão principal a partir da v2.1.186. O prompt indica qual subagent está solicitando, e pressionar Esc nega essa chamada de ferramenta sem parar o subagent. Antes da v2.1.186, subagents em segundo plano negavam automaticamente qualquer chamada de ferramenta que de outra forma solicitaria e continuavam sem essa ferramenta.
Para limitar o que um subagent pode alcançar em primeiro lugar, restrinja seu campo `tools`, deixe Bash fora da lista ou defina regras de negação em suas configurações, conforme descrito em [Controlar capacidades de subagent](/pt/sub-agents#control-subagent-capabilities). Para mais informações sobre como escolher entre primeiro plano e segundo plano, veja [Executar subagents em primeiro plano ou segundo plano](/pt/sub-agents#run-subagents-in-foreground-or-background).
A ferramenta Bash executa cada comando em um processo separado com o seguinte comportamento de persistência:
* 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 um [diretório de trabalho adicional](/pt/permissions#working-directories) que você adicionou com `--add-dir`, `/add-dir` ou `additionalDirectories` nas configurações. Sessões de subagent 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 ` ao resultado da ferramenta.
* Para desabilitar esse carregamento para que cada comando Bash comece no diretório do projeto, defina `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR=1`.
* As 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 em 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 as variáveis de ambiente persistirem entre comandos Bash, defina [`CLAUDE_ENV_FILE`](/pt/env-vars) para um script de shell antes de iniciar Claude Code, ou use um [hook SessionStart](/pt/hooks#persist-environment-variables) para preenchê-lo dinamicamente.
Dois limites limitam cada comando:
* **Timeout**: dois minutos por padrão. Claude pode solicitar até 10 minutos por comando com o parâmetro `timeout`. Substitua o padrão e o limite máximo com [`BASH_DEFAULT_TIMEOUT_MS` e `BASH_MAX_TIMEOUT_MS`](/pt/env-vars).
* **Comprimento de saída**: 30.000 caracteres por padrão. Quando um comando produz mais do que isso, Claude Code salva a saída completa em um arquivo no diretório da sessão e fornece a Claude o caminho do arquivo mais uma visualização curta do início. Claude lê ou pesquisa esse arquivo quando precisa do resto. Aumente o limite com [`BASH_MAX_OUTPUT_LENGTH`](/pt/env-vars), até um limite máximo de 150.000 caracteres.
Para processos de longa duração, como servidores de desenvolvimento ou compilações de observação, Claude pode definir `run_in_background: true` para iniciar o comando como uma tarefa em segundo plano e continuar trabalhando enquanto ele é executado. Liste e pare tarefas em segundo plano com `/tasks`.
A ferramenta Edit realiza substituição exata de string. Ela pega um `old_string` e um `new_string` e substitui o primeiro pelo segundo. Ela não usa regex ou correspondência difusa.
Três verificações devem passar para que uma edição seja aplicada:
* **Leitura antes da edição**: Claude deve ter lido o arquivo na conversa atual e o arquivo não deve ter mudado no disco desde essa leitura. Esta verificação é executada primeiro, antes de qualquer correspondência de string.
* **Correspondência**: `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 falhar.
* **Unicidade**: `old_string` deve aparecer exatamente uma vez. Quando aparece mais de uma vez, Claude fornece uma string mais longa com contexto circundante suficiente para fixar uma ocorrência, ou define `replace_all: true` para substituir todas.
Visualizar um arquivo com Bash também satisfaz o requisito de leitura antes da edição quando o comando é `cat`, `head`, `tail`, `sed -n 'X,Yp'`, `grep`, `egrep` ou `fgrep` em um único arquivo sem pipes ou redirecionamentos. Saída com pipe e outros comandos Bash não contam, e Claude deve usar Read antes de editar nesses casos.
Isso afeta apenas a elegibilidade de edição, não as permissões. [Regras de negação de Read e Edit](/pt/permissions#tool-specific-permission-rules) também se aplicam a comandos de arquivo que Claude Code reconhece em Bash, como `cat`, `head`, `tail`, `sed` e `grep`, mas não a subprocessos arbitrários que leem ou escrevem arquivos indiretamente, como um script Python ou Node que abre arquivos por si mesmo. O conjunto de comandos reconhecidos para regras de negação não é o mesmo que a lista de leitura antes da edição acima: por exemplo, `egrep` e `fgrep` contam para leitura antes da edição, mas não são verificados contra regras de negação de Read. Para imposição em nível de SO que cobre todos os processos, [ative o sandbox](/pt/sandboxing).
A ferramenta Glob encontra arquivos por padrão de nome. Ela suporta sintaxe glob padrão incluindo `**` para correspondência de diretório recursivo:
* `**/*.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 restringir 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](#grep-tool-behavior), que pula arquivos ignorados pelo git. Para fazer Glob respeitar `.gitignore`, defina `CLAUDE_CODE_GLOB_NO_IGNORE=false` antes de iniciar Claude Code.
A ferramenta Grep pesquisa conteúdo de arquivo por padrões. Onde [Glob](#glob-tool-behavior) encontra arquivos por nome, Grep encontra linhas dentro deles.
Grep é construído em [ripgrep](https://github.com/BurntSushi/ripgrep) e usa 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 leva o padrão `interface\{\}`.
Três modos de saída controlam o que volta:
* `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.
* `count`: contagem de correspondências por arquivo.
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 pulados. Para pesquisar um arquivo ignorado pelo git, Claude passa seu caminho diretamente.
A ferramenta LSP fornece a 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
A ferramenta fica inativa até que você instale um [plugin de inteligência de código](/pt/discover-plugins#code-intelligence) para sua linguagem. O plugin agrupa a configuração do servidor de linguagem, e você instala o binário do servidor separadamente.
A ferramenta Monitor requer Claude Code v2.1.98 ou posterior.
A ferramenta Monitor permite que Claude observe algo em segundo plano e reaja quando muda, sem pausar a conversa. Peça a Claude para:
* Acompanhar um arquivo de log e sinalizar erros conforme aparecem
* Consultar 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 de 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](#websocket-source) em vez de executar um script.
Você continua trabalhando na mesma sessão e Claude intervém quando um evento chega. Pare um monitor pedindo a Claude para cancelá-lo ou encerrando a sessão.
Quando Monitor executa um comando, ele usa as mesmas [regras de permissão que Bash](/pt/permissions#tool-specific-permission-rules), portanto os padrões `allow` e `deny` que você definiu para Bash se aplicam aqui também. A [fonte WebSocket](#websocket-source) tem seu próprio prompt de aprovação.
A ferramenta não está disponível no Amazon Bedrock, Google Vertex AI ou Microsoft Foundry. Também não está disponível quando `DISABLE_TELEMETRY` ou `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC` está definido.
Plugins podem declarar monitores que iniciam automaticamente quando o plugin está ativo, em vez de pedir a Claude para iniciá-los. Veja [monitores de plugin](/pt/plugins-reference#monitors).
Fonte WebSocket
A fonte WebSocket requer Claude Code v2.1.195 ou posterior.
Quando um servidor já envia eventos por WebSocket, Claude pode se conectar a ele diretamente em vez de escrever um script de consulta. 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 um existe.
* **Fechamento de socket**: a observação termina e Claude recebe o código de fechamento.
Uma observação de WebSocket usa uma entrada `ws` no lugar de `command`, e uma única chamada de Monitor não pode combinar os dois. A entrada `ws` tem dois campos:
| Campo | Obrigatório | Descrição |
| :---------- | :---------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `url` | Sim | O endpoint para se conectar. Deve ser uma URL `ws://` ou `wss://` sem credenciais ou espaços em branco incorporados, usando apenas caracteres ASCII |
| `protocols` | Não | Nomes de subprotocolo WebSocket para oferecer durante o handshake. Cada entrada deve ser um token de subprotocolo válido, e a lista não pode conter duplicatas |
As entradas `timeout_ms` e `persistent` se comportam da mesma forma que para um comando: a observação termina no prazo, a menos que `persistent` esteja definido, e `TaskStop` a cancela antecipadamente.
Abrir uma WebSocket solicita aprovação, e 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 em nuvem, incluindo nomes de host que resolvem para um. Também nega hosts em `sandbox.network.deniedDomains`, e quando [`allowManagedDomainsOnly`](/pt/settings#sandbox-settings) está definido nas configurações gerenciadas, qualquer host fora da lista de permissões gerenciada.
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](#edit-tool-behavior) 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.
Regras de permissão usam o formato de caminho `Edit(...)`. Uma regra como `Edit(notebooks/**)` cobre chamadas NotebookEdit em arquivos nesse diretório.
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. No Windows sem Git Bash, a ferramenta é ativada automaticamente. No Windows com Git Bash instalado, a ferramenta está sendo lançada progressivamente. No Linux, macOS e WSL, a ferramenta é opcional.
Defina `CLAUDE_CODE_USE_POWERSHELL_TOOL=1` em seu ambiente ou em `settings.json`:
```json theme={null}
{
"env": {
"CLAUDE_CODE_USE_POWERSHELL_TOOL": "1"
}
}
```
No Windows, defina a variável como `0` para desativar o lançamento. 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 primário. 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ódulo 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 os bloqueios corporativos ainda se aplicam. Para respeitar a política de execução efetiva da máquina, defina `CLAUDE_CODE_POWERSHELL_RESPECT_EXECUTION_POLICY=1`.
Seleção de shell em configurações, hooks e skills
Três configurações adicionais controlam onde PowerShell é usado:
* `"defaultShell": "powershell"` em [`settings.json`](/pt/settings#available-settings): roteia comandos `!` interativos através do PowerShell. Requer que a ferramenta PowerShell esteja ativada.
* `"shell": "powershell"` em [hooks de comando](/pt/hooks#command-hook-fields) individuais: executa esse hook em PowerShell. Hooks geram PowerShell diretamente, portanto isso funciona independentemente de `CLAUDE_CODE_USE_POWERSHELL_TOOL`.
* `shell: powershell` em [frontmatter de skill](/pt/skills#frontmatter-reference): executa blocos `` !`command` `` em PowerShell. Requer que a ferramenta PowerShell esteja ativada.
O mesmo comportamento de redefinição de diretório de trabalho da sessão principal descrito na seção da ferramenta Bash se aplica aos comandos PowerShell, incluindo a variável de ambiente `CLAUDE_BASH_MAINTAIN_PROJECT_WORKING_DIR`.
{/* min-version: 2.1.196 */}A partir da v2.1.196, a ferramenta PowerShell corresponde ao tratamento da ferramenta Bash dos códigos de saída de busca e diff. O código de saída 1 de `grep`, `egrep`, `fgrep` e `git grep` significa nenhuma correspondência, e o código de saída 1 de `git diff` significa que existem diferenças, portanto esses resultados não são relatados a Claude como falhas de comando.
Limitações da 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
A ferramenta Read pega um caminho de arquivo e retorna o conteúdo com números de linha. Claude é instruído a sempre passar caminhos absolutos.
Por padrão, Read retorna o arquivo do início. Quando uma leitura de arquivo inteiro excede o limite de tokens, Read retorna a primeira página com um aviso de `PARTIAL view` que diz a Claude quanto do arquivo ele recebeu e como ler mais com `offset` e `limit`. Uma leitura que passa um `offset` ou `limit` explícito e ainda assim excede o limite de tokens retorna um erro.
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 ajustar aos limites de tamanho de imagem do modelo antes de enviá-las, portanto Claude pode ver uma versão reduzida de uma captura de tela grande. A partir da v2.1.196, 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 inteiros. Para PDFs mais longos que 10 páginas, ele lê em intervalos com um parâmetro `pages`, como `"1-5"`, até 20 páginas por vez.
* **Notebooks Jupyter**: arquivos `.ipynb` retornam todas as células com suas saídas, incluindo código, markdown e visualizações.
Read apenas lê arquivos, não diretórios. Claude usa `ls` via a ferramenta Bash para listar conteúdo de diretório.
WebFetch pega uma URL e um prompt descrevendo o que extrair. Ela busca a página, converte a resposta para Markdown quando o servidor retorna HTML e executa o prompt contra o conteúdo usando um modelo pequeno e rápido. Para a maioria das buscas, Claude recebe a resposta desse modelo, não a página bruta. A etapa de conversão não é configurável.
Isso torna WebFetch com perda por design. O prompt de extração determina o que chega a Claude, portanto 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:
* URLs HTTP são automaticamente atualizadas para HTTPS.
* Páginas grandes são truncadas para um limite de caracteres fixo antes do processamento.
* Respostas são armazenadas em cache por 15 minutos, portanto buscas repetidas da mesma URL retornam rapidamente.
* 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.
Nos modos de permissão padrão e `acceptEdits`, WebFetch solicita a primeira vez que atinge um novo domínio, exceto por um conjunto integrado de domínios de documentação pré-aprovados que buscam sem um prompt. Para permitir outro domínio antecipadamente sem um prompt, adicione uma regra de permissão como `WebFetch(domain:example.com)`. Os modos de permissão `auto` e `bypassPermissions` [permission modes](/pt/permissions#permission-modes) pulam o prompt inteiramente.
Uma regra explícita `WebFetch(domain:...)` em `deny`, `ask` ou `allow` tem precedência sobre o conjunto pré-aprovado, portanto você pode bloquear um domínio pré-aprovado ou exigir um prompt para ele.
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. [Sandbox](/pt/sandboxing) regras de rede são configuradas separadamente, portanto um domínio que você quer que um processo em sandbox alcance ainda precisa de uma regra de permissão de sandbox explícita.
WebSearch executa uma consulta contra o backend de [pesquisa na web](https://platform.claude.com/docs/pt/agents-and-tools/tool-use/web-search-tool) da Anthropic e retorna títulos e URLs de resultados. Ela não busca as páginas de resultado. Para ler uma página que Claude encontra em resultados de pesquisa, ele segue com [WebFetch](#webfetch-tool-behavior).
A ferramenta pode emitir até oito pesquisas de backend por chamada, refinando a pesquisa internamente antes de retornar resultados. Claude pode escopar 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.
O backend de pesquisa não é configurável. Para pesquisar com um provedor diferente, adicione um [servidor MCP](/pt/mcp) que exponha uma ferramenta de pesquisa.
Regras de permissão WebSearch não levam especificador. Uma entrada `WebSearch` simples em `allow` ou `deny` é a única forma.
WebSearch está disponível na Claude API e Microsoft Foundry. No Google Cloud Vertex AI funciona com modelos Claude 4, incluindo Opus, Sonnet e Haiku. Amazon Bedrock não expõe a ferramenta de pesquisa na web do lado do servidor.
A ferramenta Write cria um novo arquivo ou sobrescreve um existente com o conteúdo completo fornecido. Ela não anexa ou mescla.
Se o caminho alvo já existe, Claude deve ter lido esse arquivo pelo menos uma vez na conversa atual antes de sobrescrevê-lo. Uma Write para um arquivo existente não lido falha com um erro. Esta restrição não se aplica a novos arquivos.
Visualizar o arquivo com Bash também satisfaz este requisito sob as mesmas regras descritas em [comportamento da ferramenta Edit](#edit-tool-behavior).
Para mudanças parciais em um arquivo existente, Claude usa Edit em vez de Write.
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:
```text theme={null}
What tools do you have access to?
```
Claude fornece um resumo conversacional. Para nomes exatos de ferramentas MCP, execute `/mcp`.
A [ferramenta advisor](/pt/advisor) é uma [ferramenta de servidor](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool) 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](/pt/mcp): adicione ferramentas personalizadas conectando servidores externos
* [Permissões](/pt/permissions): sistema de permissões, sintaxe de regras e padrões específicos de ferramentas
* [Subagents](/pt/sub-agents): configure o acesso a ferramentas para subagents
* [Hooks](/pt/hooks-guide): execute comandos personalizados antes ou depois da execução da ferramenta