Módulo 1.4 — A Caixa de Ferramentas: 40+ Ferramentas

📋 O Padrão Universal — ~30 métodos por ferramenta

O Claude Code tem mais de 40 ferramentas, e cada uma delas segue o mesmo modelo universal. Uma ferramenta é um objeto com cerca de 30 métodos que definem o que ela faz, como validar entradas, quem pode executá-la e o que acontece se você interrompê-la.

O modelo universal de ferramentas e as 12 ferramentas mais importantes.

Um Padrão Para Todas

● Cada ferramenta é um objeto TypeScript com ~30 métodos padronizados

● O padrão garante consistência: toda ferramenta se comporta de forma previsível

● Novas ferramentas são criadas seguindo o mesmo template

● O sistema de execução não precisa conhecer detalhes internos — só a interface

● É um exemplo de design por contrato (Design by Contract) em produção

📊 As 12 Ferramentas Mais Usadas

● Read — Lê arquivos do sistema

● Edit — Edita arquivos com substituição de strings

● Write — Cria/sobrescreve arquivos

● Bash — Executa comandos shell

● Glob — Busca arquivos por padrão (*.ts, **/*.json)

● Grep — Busca conteúdo dentro de arquivos

● Agent — Cria subagentes para tarefas paralelas

● WebFetch — Busca conteúdo da web

● WebSearch — Pesquisa na internet

● NotebookEdit — Edita Jupyter notebooks

● TodoRead/TodoWrite — Gerencia lista de tarefas

● ToolSearch — Busca ferramentas sob demanda

⚙️ Anatomia de uma Ferramenta — call(), inputSchema, checkPermissions

Vamos abrir uma ferramenta e ver suas entranhas. Cada método tem um propósito claro e bem definido.

Os Métodos Essenciais

● call() — Executa a ação principal (ler arquivo, rodar comando, etc.)

● inputSchema — Define e valida as entradas usando Zod (biblioteca de validação TypeScript)

● checkPermissions() — Decide: permitir automaticamente, negar ou perguntar ao usuário

● isConcurrencySafe() — Esta ferramenta pode rodar em paralelo com outras?

● isReadOnly() — Se true, é seguro aprovar automaticamente

● interruptBehavior — O que acontece se você pressionar Ctrl+C no meio da execução

● shouldDefer — Carrega sob demanda via ToolSearch para manter a lista enxuta

💡 Zod para Validação

Toda entrada é validada com Zod antes da execução. Se você passar um parâmetro inválido, a ferramenta rejeita antes mesmo de tentar executar. Isso previne erros cascata e protege o sistema de inputs malformados.

🔐 Sistema de Permissões — allow, deny, ask

Cada ferramenta tem um sistema de permissões de três níveis que equilibra autonomia com segurança. Você pode configurar para que ações seguras sejam automáticas e ações perigosas peçam confirmação.

Os Três Níveis

● Allow (Permitir): A ferramenta executa automaticamente sem perguntar. Exemplo: ler arquivos

● Deny (Negar): A ferramenta é bloqueada. Exemplo: comandos destrutivos em produção

● Ask (Perguntar): O sistema pede sua confirmação antes de executar. Exemplo: editar um arquivo

💡 Configurando Permissões Automáticas

O problema mais comum é o sistema pedir confirmação o tempo todo. A solução: configurar wildcards no settings.json:

● Permitir todos os comandos git

● Permitir edições em determinada pasta

● Permitir leituras em todo o projeto

Resultado: menos interrupção e mais automação.

✅ Fazer

● Configurar permissões automáticas para ações seguras e repetitivas

● Manter ask para ações destrutivas

● Revisar settings.json periodicamente

❌ Evitar

● Aprovar tudo automaticamente sem pensar

● Negar tudo e ser interrompido a cada ação

● Ignorar o sistema de permissões

🔀 Concorrência e Paralelismo — isConcurrencySafe e execução paralela

O Claude Code pode executar múltiplas ferramentas simultaneamente — mas só quando é seguro. O método isConcurrencySafe() é o guardião que decide o que pode rodar em paralelo.

Paralelo vs Exclusivo

● Ferramentas concurrency-safe: Read, Glob, Grep, WebFetch — podem rodar em paralelo

● Ferramentas exclusivas: Edit, Write, Bash — rodam uma de cada vez

● A decisão é por ferramenta, não global

● Ferramentas read-only são automaticamente concurrency-safe

● O executor gerencia filas e prioridades transparentemente

📊 Impacto Real

● Buscar 10 arquivos em paralelo vs sequencial: até 10x mais rápido

● O paralelismo é transparente — o modelo simplesmente chama várias ferramentas e o executor decide

● Cache de prompt é compartilhado entre execuções paralelas, reduzindo custo

● Na prática, o Claude Code frequentemente lê múltiplos arquivos de uma vez ao explorar código

🛡️ BashTool — A mais protegida: 23+ verificações

A BashTool é a ferramenta mais poderosa e mais protegida do Claude Code. Ela executa comandos shell — e por isso tem mais de 23 verificações de segurança que bloqueiam padrões perigosos.

23+ Verificações de Segurança

A BashTool bloqueia:

● Substituição de comando: $() e crases — previne injeção

● Comandos Zsh perigosos: zmodload, sysopen, syswrite

● Flags ofuscadas: Flags que escondem comportamento real

● Injeção de IFS: Manipulação do separador de campos

● Unicode tricks: Caracteres Unicode que parecem espaço mas não são

● Caracteres de controle: Bytes invisíveis que alteram comportamento

● Comandos compostos: cmd1 && cmd2 são divididos e cada parte é verificada independentemente

⚠️ Por Que Tanta Proteção?

Execução de shell é o maior vetor de ataque em agentes de IA. Um comando malicioso pode: deletar arquivos, instalar malware, exfiltrar dados, comprometer credenciais. As 23+ verificações são a diferença entre um agente útil e um vetor de ataque.

💡 Classificador de ML Opcional

Além das verificações baseadas em regras, existe um classificador de machine learning opcional que pode aprovar ou negar comandos automaticamente com base na compreensão semântica — não apenas em padrões de texto.

🔎 ToolSearch e Deferimento — Carregamento sob demanda

Com 40+ ferramentas, listar todas de uma vez sobrecarregaria o contexto do modelo. A solução? Carregamento sob demanda via ToolSearch — ferramentas são carregadas apenas quando necessárias.

Lazy Loading de Ferramentas

● O método shouldDefer marca ferramentas para carregamento diferido

● Ferramentas diferidas aparecem apenas pelo nome — sem schema de parâmetros

● Quando o modelo quer usar uma ferramenta diferida, chama ToolSearch

● ToolSearch retorna o schema completo, permitindo a chamada

● Resultado: contexto enxuto + acesso completo quando necessário

📊 Eficiência de Contexto

● 40+ schemas de ferramentas consumiriam milhares de tokens do contexto

● Com deferimento, apenas ~12 ferramentas essenciais são carregadas por padrão

● As demais ficam disponíveis via ToolSearch sob demanda

● Economia estimada: centenas de tokens por mensagem, acumulando ao longo da conversa

✅ Fazer

● Confiar no sistema de carregamento automático

● Usar ToolSearch quando precisar de ferramentas específicas

● Entender que nem todas as ferramentas aparecem na lista inicial

❌ Evitar

● Tentar listar todas as ferramentas de uma vez

● Ignorar que existem ferramentas além das visíveis

● Forçar o carregamento de ferramentas desnecessárias

📋 Resumo do Módulo

✓ 40+ ferramentas seguem um padrão universal com ~30 métodos

✓ call(), inputSchema (Zod), checkPermissions() são o núcleo

✓ Permissões em 3 níveis: allow, deny, ask — configuráveis via settings.json

✓ Ferramentas read-only rodam em paralelo, modificações são exclusivas

✓ BashTool tem 23+ verificações — a mais protegida do sistema

✓ ToolSearch permite carregamento sob demanda para manter contexto enxuto

Próxima Trilha:

Trilha 2 - Núcleo: Arquitetura Profunda do Claude Code

← Voltar para Trilha Próxima Trilha: Núcleo →