Como interceptar chamadas de ferramentas do Claude Code antes de serem executadas

Agentes executam chamadas de ferramentas. A maioria delas está bem. Algumas delas excluem bancos de dados de teste, enviam e-mails para a lista de distribuição errada ou git push --force em um branch que alguém estava revisando. A lacuna entre "o modelo decidiu" e "a ferramenta foi executada" é onde a governança deve viver.

Este é um guia prático para adicionar essa lacuna, uma camada de aprovação pré-execução, ao Claude Code em cerca de 60 segundos.

A linha única

curl -fsSL https://sidclaw.com/install-hooks.mjs | node

Essa é a instalação completa. Nenhum pacote npm, nenhuma edição de .claude/settings.json, nenhum binário wrapper. O script escreve um PreToolUse hook no diretório de hooks do Claude Code, registra-o contra todas as 11 categorias de ferramentas governadas e verifica a instalação com uma chamada de auto-teste.

Homebrew, rustup e nvm usam todos esse padrão. É um modelo de confiança razoável: você pode ler o script antes de canalizá-lo (curl -fsSL https://sidclaw.com/install-hooks.mjs | less), a soma SHA-256 é publicada em /install-hooks.mjs.sha256, e a instalação é idempotente — executá-la duas vezes não fará um registro duplo.

Variáveis de ambiente

Duas variáveis, ambas obrigatórias:

export SIDCLAW_BASE_URL=https://api.sidclaw.com
export SIDCLAW_API_KEY=ai_your_key_here

As chaves do nível gratuito vêm de app.sidclaw.com/signup. O hook falha por padrão se a API estiver inacessível. Defina SIDCLAW_FAIL_MODE=open se você preferir priorizar a disponibilidade em vez da segurança (não recomendado para produção).

Opcional:

export SIDCLAW_TIMEOUT_MS=30000        # padrão 30s
export SIDCLAW_AGENT_ID=my-agent-name  # padrão para hostname

O que é interceptado

Cada chamada nessas 11 categorias passa pela avaliação de políticas antes que a ferramenta seja executada:

As políticas são YAML no painel. Você pode começar com os padrões (alinhados ao SOC2, bloqueando os perigos óbvios) e apertar a partir daí.

Demonstração: o cenário rm -rf

Sem o hook:

$ claude
> limpar os dados de teste em ./staging

# Claude executa: rm -rf ./staging
# Arquivos desaparecem. Sem confirmação. Sem registro.

Com o hook:

$ claude
> limpar os dados de teste em ./staging

[SidClaw] Chamada de ferramenta retida para aprovação: Bash
  comando: rm -rf ./staging
  risco: alto (exclusão recursiva)
  classificação: restrita
  agente: claude-code-local
  raciocínio: "usuário solicitou limpeza de dados de teste; ./staging contém fixações de teste"

Aprovação pendente... (política: operações-destrutivas-fs)

O revisor vê o cartão completo no Slack, Teams, Telegram ou no painel. Eles aprovam, negam ou editam o comando antes da execução. Cada decisão escreve uma entrada assinada na cadeia de auditoria.

Aprovar → o comando é executado, rastreamento registrado.
Negar → Claude recebe uma recusa estruturada sobre a qual pode raciocinar. Nenhum dado acessado.

Antes / depois

Antes (Claude Code padrão):

agente decide → ferramenta executa → registrado no histórico local do Claude (por sessão)

Depois (com hook):

agente decide → política SidClaw → [permitir | aprovação_requerida | negar] → ferramenta executa ou bloqueia → evento de auditoria encadeado por hash

A cadeia de auditoria é duas tabelas, ambas seladas contra adulteração com cadeias SHA-256:

• action_records — cada transição de estado (executando → pendente_aprovação → aprovado → completo, ou qualquer falha)
• audit_events — cada decisão, com o hash do evento anterior incluído na assinatura do próximo evento

Você pode verificar a cadeia offline, exportar para SIEM como JSON/CSV ou transmitir continuamente via webhook.

Solução de problemas

Erro "Sem chave API" em cada chamada de ferramenta. Você não exportou SIDCLAW_API_KEY, ou você a exportou em um shell diferente de onde o Claude Code está sendo executado. Verifique com echo $SIDCLAW_API_KEY no mesmo terminal. Se você usar um arquivo .env, o Claude Code não o carrega automaticamente — carregue-o primeiro.

Tempo limite após 30 segundos. O revisor ainda não respondeu. Aumente SIDCLAW_TIMEOUT_MS ou mude a política para assíncrona (baseada em webhook) para que o agente possa continuar em ações permitidas enquanto a chamada retida aguarda.

O hook não disparou. O Claude Code carrega hooks no início da sessão. Reinicie claude após a instalação. Verifique se o hook está registrado: claude hooks list deve mostrar sidclaw-pretooluse.

Limitado pela taxa da API. O nível gratuito é de 1.000 chamadas governadas/dia. A resposta inclui um cabeçalho de retry-after. Para volumes mais altos, app.sidclaw.com tem níveis pagos.

Mapeamento de conformidade

Isso não é um aviso. A trilha de auditoria do hook é estruturada contra requisitos regulatórios específicos:

• FINRA 2026 Regra 3110 — pontos de verificação humanos documentados para ações de IA em serviços financeiros. O cartão de aprovação É o artefato de ponto de verificação.
• EU AI Act Artigo 14 (efetivo em agosto de 2026) — supervisão humana para alto risco