Boucle

Hooks do Claude Code que realmente impõem suas regras. 7 hooks independentes, mais enforce-hooks para políticas do CLAUDE.md, ferramentas de auditoria, mais de 1.900 testes e um corpus pesquisável de lacunas do Claude Code com classificações de gravidade e soluções alternativas.

Links rápidos: Verifique sua configuração · Instale os hooks · Limitações conhecidas · Exportação JSON · Início rápido · Triagem · Lista de verificação de atualização · Evidências de suporte seguro · Exemplos de suporte · Auditorias somente leitura · Hooks individuais · Suporte a plataformas · Versão recomendada do Claude Code · Solução de problemas · Boucle Framework (opcional, para agentes autônomos)

Hooks do Claude Code

As regras do CLAUDE.md do Claude Code são lidas, mas não aplicadas — elas funcionam no início da sessão e degradam conforme o contexto cresce. O sistema de permissões tem lacunas conhecidas — curingas não correspondem a comandos compostos, regras de negação não verificam segmentos de pipe e podem ser contornadas com comentários multilinha. Esses hooks aplicam limites que regras de texto e permissões não conseguem.

O que acontece quando um hook bloqueia um comando perigoso:``` Claude tries: rm -rf ~/projects bash-guard: bash-guard: rm -rf targeting a critical system path. This would cause irreversible data loss. Claude sees: ⚠ Hook blocked this action. Suggesting safer alternative...

Sem solicitações, sem diálogos de "tem a certeza?". O comando nunca é executado.

<a id="check-your-setup"></a>

**Verifique a sua configuração atual:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash

Execute isto a partir da mesma raiz do projeto onde você inicia o Claude Code. Os hooks do projeto são resolvidos a partir do diretório atual, portanto, um lançamento em um subdiretório pode não encontrar .claude/settings.json na raiz do repositório. Se você já estiver em algum lugar dentro de um git checkout:```sh cd "$(git rev-parse --show-toplevel)" curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash

Avalia sua configuração de segurança do Claude Code de A a F e mostra correções de uma linha para cada lacuna. Adicione `--verify` para enviar payloads de teste a cada hook e confirmar que eles realmente bloqueiam:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify

Para CI ou uma verificação de workstation por script, falhe quando a verificação encontrar um hook FAIL-OPEN, arquivos de hook quebrados, verificações PreToolUse ignoradas, nenhum hook ou nenhuma verificação de payload:```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --strict

Use o [guia de verificações com script](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/CI.md) para GitHub Actions,
verificações em estações de trabalho de desenvolvedores, códigos de saída e os limites do que o CI pode provar.

Verifica a instalação de hooks, a saúde dos hooks (scripts ausentes/não executáveis), verificação ao vivo (envia `rm -rf /` para bash-guard, `git push --force` para git-safe, etc. e confirma que eles bloqueiam), regras enforce-hooks e `@enforced` do CLAUDE.md, problemas de ambiente (IS_DEMO, configurações JSONC, dependências jq/python3, confiabilidade de hooks no Windows) e regressões conhecidas de versões de CLI. Examina tanto as configurações de nível do usuário (`~/.claude/settings.json`) quanto as de nível do projeto (`.claude/settings.json`), com um inventário de hooks que mostra hooks personalizados/de terceiros junto com hooks do framework. O resumo conta 8 slots de hooks do framework porque inclui o hook de política `enforce-hooks`; `install.sh all` instala os 7 hooks independentes listados abaixo. Também alerta quando regras de negação são configuradas sem bash-guard, já que padrões de negação [podem ser contornados](https://github.com/anthropics/claude-code/issues/38119) por comandos compostos e scripts multilinha. Nenhuma instalação de hook é necessária para a auditoria. Coberto por centenas de testes.

Para um caminho de 10 minutos da auditoria até hooks verificados, veja o [início rápido do safety-check](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/QUICKSTART.md).
Se precisar de ajuda, use o [guia de evidências de suporte seguro](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/safety-check/SUPPORT_EVIDENCE.md)
para compartilhar o bloco de resumo sem expor configurações privadas ou segredos. Para
imprimir apenas esse bloco público delimitado, execute:```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/safety-check/check.sh | bash -s -- --verify --summary-only

Para exemplos de relatórios públicos seguros e trechos inseguros a evitar, consulte safe support examples.

Para lacunas de permissões e hooks do Claude Code de upstream, use a página de limitações pesquisável, a exportação JSON legível por máquina, ou o feed Atom.

Requisitos para macOS / Linux: bash, python3 e jq. O instalador usa python3 para gerenciar o settings.json do Claude Code, o safety-check usa python3 para sua auditoria, e a maioria dos hooks de shell autônomos usa jq para analisar os payloads de hooks do Claude Code.

Comece com o essencial (bash-guard + git-safe + file-guard):```sh curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- recommended

Esses três hooks formam a rede de segurança que todo usuário do Claude Code deve ter: bloquear comandos perigosos, prevenir operações destrutivas do git e proteger arquivos sensíveis. Após a instalação, execute a verificação de segurança acima com `--verify` para confirmar que cada hook bloqueia o que deveria.

**Se a instalação for bem-sucedida, mas os hooks não bloquearem nada:**