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

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

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

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:**

- Execute `install.sh check --verify --strict` primeiro no macOS/Linux (`install.ps1 verify` no Windows nativo). Uma instalação limpa não é prova de que os hooks estão sendo acionados.
- Execute `install.sh doctor` em seguida (`install.ps1 doctor` no Windows). Ele detecta arquivos ausentes, permissões incorretas, JSONC em `settings.json` e outros estados de falha silenciosa.
- No Windows, use o PowerShell 7 (`pwsh`), não o Windows PowerShell 5.
- Se você escrever hooks de negação personalizados, prefira `stderr` + `exit 2` para bloqueios rígidos. O JSON `permissionDecision: "deny"` ainda é inconsistente entre as superfícies do Claude Code.

**Instale todos os hooks de uma vez:**```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.sh | bash -s -- all

**Equivalentes do Windows** (sintaxe do PowerShell):```powershell
# List, verify, upgrade, check, uninstall, doctor, backup/restore, help
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } list"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } verify"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } upgrade"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --summary-only"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } check --verify --strict"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } doctor"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } uninstall read-once"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } backup"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } restore"
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } help"

Economiza ~2000 tokens por releitura evitada. Inclui [modo diff](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/read-once#diff-mode-opt-in) para fluxos de trabalho de edição-verificação-edição (80-95% de economia de tokens em arquivos alterados).

### [file-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/file-guard) — Proteja arquivos contra acesso ou modificação por IA```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/file-guard/install.sh | bash

Bloqueia `git push --force`, `git reset --hard`, `git checkout .`, `git checkout HEAD -- path`, `git restore`, `git clean -f`, `git branch -D`, `--no-verify` e outros comandos git destrutivos. Impede o [padrão exato](https://github.com/anthropics/claude-code/issues/37888) que destruiu 30+ arquivos apesar das 100+ regras do CLAUDE.md. Sugere alternativas mais seguras. Lista de permissões via configuração `.git-safe`. ~145 testes (88 bash + 57 PowerShell).

### [bash-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/bash-guard) — Bloqueia comandos bash perigosos```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/bash-guard/install.sh | bash

Impede commits diretos em branches protegidas (main, master, production, release). Força o fluxo de trabalho feature-branch. Personalize as branches protegidas via configuração `.branch-guard` ou variável de ambiente `BRANCH_GUARD_PROTECTED`. Permite `--amend` em qualquer branch. ~55 testes (bash + PowerShell).

### [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/worktree-guard) — Evite perda de dados ao sair da worktree```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/worktree-guard/install.sh | bash

Registra cada chamada de ferramenta em `~/.claude/session-logs/YYYY-MM-DD.jsonl`. Veja exatamente o que o Claude fez: quais arquivos foram lidos/escritos, quais comandos foram executados, carimbos de data/hora. Inclui comparação de tendências `--week` entre dias. Útil para auditar sessões autônomas e depurar. ~105 testes (bash + PowerShell).

### [enforce-hooks](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/enforce) — Transforme as regras do CLAUDE.md em hooks aplicáveis```sh
curl -fsSL https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/enforce/install.sh | bash

Envia payloads sintéticos de `PreToolUse` para qualquer script de hook e informa se ele permite, nega ou falha. Funciona com qualquer hook (nosso ou de terceiros). O modo em lote executa suítes de teste a partir de arquivos JSONL. Aborda [claude-code#39971](https://github.com/anthropics/claude-code/issues/39971) (`--test-permission` não existe).

### Receita rápida: Modo de auditoria somente leitura

Claude [ignora instruções explícitas de "não edite"](https://github.com/anthropics/claude-code/issues/41063) e edita arquivos, executa ALTER TABLE, reconstrói o Docker. As regras do CLAUDE.md sozinhas não podem evitar isso. Adicione ao seu CLAUDE.md e execute `enforce-hooks.py --install-plugin`:```markdown
## Read-only mode @enforced
- Never modify any files
- Never run rm -rf
- Never run `>`, `>>`, `tee`, `touch`, `mkdir`, `rm`, `sed -i`, `perl -pi`, `mv`, `cp`, `unlink`, `chmod`, or `chown`
- Never run ALTER, DROP, TRUNCATE, INSERT, UPDATE, or DELETE
- Never run docker restart, docker stop, docker build, or docker rm
- Never run sudo
- Never run git commit, git push, or git merge

#### Opção 2: Compilar a partir do código-fonte```bash
git clone https://github.com/Bande-a-Bonnot/Boucle-framework.git
cd Boucle-framework
cargo build --release
export PATH="$PWD/target/release:$PATH"

`boucle init` escreve `agent.model = "gpt-5.4"` por padrão, que usa o Codex
CLI. Para executar por meio do Claude, defina `agent.model` para um
modelo Claude como `claude-sonnet-4-20250514`.

### Sistema de Memória (Broca)

Broca é um sistema de conhecimento baseado em arquivos e nativo do git para agentes de IA. As memórias são arquivos Markdown com frontmatter YAML.```bash
# Store a memory
boucle memory remember "Python packaging" "Modern projects use pyproject.toml" --tags "python,packaging"

# Store a time-sensitive fact
boucle memory remember "API status" "Payment API is degraded" --tags "incident" --valid-until 2026-05-23

# Search memories
boucle memory recall "python packaging" --limit 5

# Search by tag
boucle memory search-tag "security"

# Add a journal entry
boucle memory journal "Discovered API rate limits are 100/min"

# View statistics
boucle memory stats

Broca também suporta:
- **Pesquisa BM25** — Classificação de relevância normalizada pelo comprimento do documento e raridade do termo
- **Decaimento temporal** — Memórias recentes pontuam mais; a frequência de acesso é rastreada automaticamente
- **Validade temporal** - Fatos sensíveis ao tempo podem conter `ttl` ou `valid_until`, e a recuperação alerta quando estiverem desatualizados
- **Coleta de lixo** — Arquivar entradas substituídas, de baixa confiança ou desatualizadas (reversível, simulação por padrão)
- **Impulso de referência cruzada** — Entradas relacionadas aparecem juntas nos resultados de pesquisa
- **Consolidação** — Detectar e mesclar memórias quase duplicadas usando similaridade de Jaccard
- **Rastreamento de confiança** — `boucle memory update-confidence <id> <score>`
- **Substituição** — `boucle memory supersede <old-id> <new-id>` quando o conhecimento evolui
- **Relacionamentos** — `boucle memory relate <id1> <id2> <relation>` para vincular entradas
- **Reindexação** — `boucle memory index` para reconstruir o índice de pesquisa

### Mecanismo de Auto-Observação

Agentes com memória lembram o que aconteceu. Agentes com auto-observação percebem o que continua acontecendo e desenvolvem respostas para isso.```bash
# Log a signal when something goes wrong
boucle signal friction "auth keeps failing on retry" auth-flaky

# Run the pipeline (harvest → classify → score → promote)
boucle improve run

# See what patterns have emerged
boucle improve status

### MCP Server

Boucle expõe o Broca como um servidor Model Context Protocol, para que outros agentes de IA possam compartilhar memória.```bash
# Start MCP server (stdio transport)
boucle mcp --stdio

# Or HTTP transport
boucle mcp --port 8080

### Como Funciona

Cada iteração do loop:

1. **Acordar** — Trava verificada pelo proprietário obtida, contexto montado a partir de memória + objetivos + ações pendentes
2. **Pensar** — O agente lê seu estado completo e decide o que fazer dentro do timeout configurado do LLM
3. **Agir** — O agente executa: escreve código, faz pesquisa, cria planos, solicita aprovações
4. **Aprender** — O agente atualiza sua memória com o que aprendeu
5. **Dormir** — Alterações commitadas no git, trava liberada, agente aguarda a próxima iteração

### Configuração```toml
# boucle.toml
[agent]
name = "my-agent"
description = "A helpful autonomous agent"
model = "gpt-5.4"                 # gpt-* models use Codex CLI
system_prompt = "system-prompt.md"

[memory]
dir = "memory"
state_file = "STATE.md"

[loop]
context_dir = "context.d"
hooks_dir = "hooks"
log_dir = "logs"

[schedule]
interval = "1h"

#### Hooks de Ciclo de Vida (`hooks/`)

| Hook | Quando | Argumentos | Caso de uso |
|------|--------|------------|-------------|
| `pre-run` | Antes da iteração | `$1`: timestamp | Configuração, verificações de saúde |
| `post-context` | Após a montagem do contexto | stdin: context | Modificar/filtrar contexto |
| `post-llm` | Após a conclusão do LLM | `$1`: exit code | Notificações, limpeza |
| `post-commit` | Após o git commit | `$1`: timestamp | Enviar para o remoto, implantar |

#### Restrições de Ferramentas (`allowed-tools.txt`)```
Read
Write
Edit
Glob
Grep
WebSearch
Bash(git:*)
Bash(python3:*)

# Log a signal (friction/failure/waste/surprise) boucle improve run [--budget ] # Run the improvement pipeline boucle improve status # Show patterns, scores, pending actions boucle improve init # Set up improve/ with example harvester

Memory (Broca)

boucle memory remember <content> [--tags <tags>] [--entry-type <type>] [--ttl <days>] [--valid-until <date>] boucle memory recall <query> [--limit <n>] boucle memory show <id> boucle memory search-tag <tag> boucle memory journal <content> boucle memory update-confidence <id> <score> boucle memory supersede <old-id> <new-id> boucle memory relate <id1> <id2> <relation> boucle memory stats boucle memory index boucle memory gc [--apply] # Archive stale/superseded entries boucle memory consolidate [--apply] # Merge near-duplicate entries

MCP server

boucle mcp --stdio # stdio transport boucle mcp --port # HTTP transport

Global options

boucle --root # Use specific agent directory boucle --help # Show help boucle --version # Show version

### Princípios de Design

1. **Arquivos em vez de bancos de dados.** Memória é Markdown. Config é TOML. Logs são texto simples. Tudo é legível por humanos e passível de diff no git.

2. **Limites são recursos.** Portões de aprovação tornam agentes autônomos confiáveis. Um agente que pode gastar seu dinheiro sem pedir não é autônomo, é perigoso.

3. **Conhecimento composto.** Cada iteração deve deixar o agente mais inteligente. Memória não é um cache — é um investimento.

4. **Transparência por padrão.** Se você não consegue ver o que o agente fez e por quê, algo está errado.

<a id="platform-support"></a>

## Suporte de Plataforma

| | macOS | Linux | Windows (WSL) | Windows (native PS7) |
|---|:---:|:---:|:---:|:---:|
| bash-guard | Sim | Sim | Sim | Sim (.ps1) |
| git-safe | Sim | Sim | Sim | Sim (.ps1) |
| file-guard | Sim | Sim | Sim | Sim (.ps1) |
| read-once | Sim | Sim | Sim | Sim (.ps1) |
| branch-guard | Sim | Sim | Sim | Sim (.ps1) |
| worktree-guard | Sim | Sim | Sim | Sim (.ps1) |
| session-log | Sim | Sim | Sim | Sim (.ps1) |
| enforce-hooks | Sim | Sim | Sim (bash) | WSL ou Git Bash |
| safety-check | Sim | Sim | Sim | Parcial (bash necessário) |
| Instalador | `install.sh` | `install.sh` | `install.sh` | `install.ps1` |
| Confiabilidade dos hooks | Completa | Completa | Completa | [~18%](https://github.com/anthropics/claude-code/issues/37988) |

**Melhor experiência:** macOS ou Linux. **Windows:** Use WSL para confiabilidade total. Os hooks nativos do PowerShell funcionam, mas o Claude Code os dispara de forma inconsistente ([#37988](https://github.com/anthropics/claude-code/issues/37988)).

<a id="recommended-claude-code-version"></a>

## Versão Recomendada do Claude Code

**Use a versão mais recente do Claude Code.** O Claude Code muda rapidamente; verifique
o [feed de releases](https://github.com/anthropics/claude-code/releases) da Anthropic
antes de fixar uma versão e, em seguida, execute `safety-check` com `--verify` para confirmar
que os hooks disparam corretamente no seu ambiente. As versões abaixo são marcos
históricos relacionados a hooks, não um rastreador da versão atual:

| Versão | Problema |
|---|---|
| v2.1.91+ | Restaura as permissões de execução do `rg` incluído, corrigindo regressões na descoberta de comandos do projeto introduzidas nas v2.1.88-89 ([#41497](https://github.com/anthropics/claude-code/issues/41497), [#41864](https://github.com/anthropics/claude-code/issues/41864)) |
| v2.1.90+ | Versão mínima para a melhoria de bloqueio com exit-2 + JSON, a correção do formato ao salvar do PostToolUse e 4 correções de bypass de permissão no PowerShell |
| v2.1.89 | Adiciona `PermissionDenied`, `defer`, `file_path` absoluto e correspondência de `if` composto em hooks, mas ainda apresentava regressões na descoberta de comandos e na exibição do `SessionStart` |
| v2.1.88 | [Descontinuada/removida do npm](https://github.com/anthropics/claude-code/issues/41497): comandos/skills personalizados quebrados, vazamento de source map |
| v2.1.81-84 | [O bypass de permissão é redefinido no meio da sessão](https://github.com/anthropics/claude-code/issues/37745) quando hooks PreToolUse estão instalados |
| < v2.1.50 | Sem suporte ao formato `hookSpecificOutput` (o obsoleto `decision: "block"` ainda funciona, mas deve ser migrado) |

Execute `claude --version` para verificar sua instalação local.

## Solução de Problemas

**Comentários JSONC em settings.json**: Se o seu `~/.claude/settings.json` contiver comentários `//` ou `/* */`, os hooks podem parar de funcionar silenciosamente ([claude-code#37540](https://github.com/anthropics/claude-code/issues/37540)). Nossos instaladores detectam JSONC e removem automaticamente os comentários (criando um backup `.bak`). Se os hooks não estiverem disparando, verifique se há comentários no seu arquivo de configurações.

**Hooks não bloqueando**: O Claude Code só dispara hooks em chamadas de ferramentas, não na montagem do prompt. Recursos como @-autocomplete injetam conteúdo de arquivos antes que os hooks possam interceptar. Veja [claude-code#32928](https://github.com/anthropics/claude-code/issues/32928).

**Hooks do projeto ignorados a partir de subdiretórios**: Se o seu repositório armazena hooks
em `.claude/settings.json` na raiz do repositório, inicie o Claude Code e execute
`safety-check` a partir dessa mesma raiz. Iniciar a partir de um subdiretório pode fazer
o Claude tratar esse subdiretório como raiz do projeto e ignorar os hooks do projeto
ancestral sem aviso. O `safety-check` relata isso como um aviso de configurações do
projeto ancestral. No PowerShell nativo do Windows, execute
`Set-Location (git rev-parse --show-toplevel)` dentro do checkout antes de
executar `install.ps1 verify`.

**Bypass de permissão é redefinido com hooks instalados**: Se você usa `--dangerously-skip-permissions` (comum em configurações autônomas), hooks PreToolUse podem [fazer o estado de permissão ser redefinido no meio da sessão](https://github.com/anthropics/claude-code/issues/37745), revertendo todas as ferramentas para aprovação manual. Isso é um bug da plataforma, não um bug de hooks. Se as ferramentas de repente exigirem aprovação 30-120 minutos após o início da sessão, é por isso.

**A variável de ambiente IS_DEMO desativa todos os hooks**: Se `IS_DEMO=1` estiver definida no seu ambiente (às vezes via configurações de IDE ou workspace na nuvem), o Claude Code [ignora silenciosamente toda a execução de hooks](https://github.com/anthropics/claude-code/issues/37780) ao suprimir a confiança do workspace sem concedê-la. Execute `echo $IS_DEMO` para verificar. Nossa ferramenta `safety-check` detecta isso automaticamente.

**A variável de ambiente CLAUDE_CODE_SIMPLE desativa todos os hooks**: Quando a variável de ambiente `CLAUDE_CODE_SIMPLE` está definida com qualquer valor não vazio, o Claude Code desativa completamente hooks, ferramentas MCP, anexos e o carregamento do arquivo CLAUDE.md (introduzido na v2.1.50). Nenhuma regra de aplicação será acionada. Execute `echo $CLAUDE_CODE_SIMPLE` para verificar. Nossa ferramenta `safety-check` detecta isso automaticamente.

**A flag `--bare` ignora todos os hooks**: A flag `--bare` da CLI desativa hooks, LSP, sincronização de plugins e varreduras de diretórios de skills para chamadas `-p` via script. Se o seu pipeline autônomo usa `claude --bare -p`, nenhum hook dispara. Use controles no nível do SO (permissões de arquivo, conteinerização) para aplicar regras no modo bare.

**O tratamento de negação de hooks ainda é inconsistente entre ferramentas e versões**: `hookSpecificOutput.permissionDecision: "deny"` melhorou, mas não é uma garantia universal em todas as superfícies do Claude Code. Vários problemas upstream ainda documentam casos em que o tratamento de deny é ignorado ou muda conforme o tipo de ferramenta/evento. É por isso que os hooks do framework que precisam bloquear rigorosamente ações perigosas usam o caminho mais conservador que o Claude Code atualmente respeita com mais confiabilidade: um motivo legível por humanos no `stderr` mais `exit 2`; em seguida, dizemos aos usuários para executar `safety-check --verify` após a instalação e após atualizações do Claude Code. Se você escrever hooks personalizados, não presuma que apenas uma resposta deny em JSON é suficiente só porque funciona em um teste local.

**Subagentes podem ignorar configurações de hooks**: Agentes criados via ferramenta Agent [não herdam consistentemente as configurações de permissão](https://github.com/anthropics/claude-code/issues/37730). Hooks em `.claude/settings.json` ainda devem disparar (configuração compartilhada), mas verifique o comportamento dos hooks ao usar fluxos de trabalho com subagentes.

**O stderr dos hooks pode vazar seus caminhos do sistema de arquivos**: O executor de hooks do Claude Code [prefixa a saída do stderr com o caminho bruto do comando](https://github.com/anthropics/claude-code/issues/41226), expondo detalhes como `/Users/yourname/.claude/hooks/my-hook.sh` na conversa. Isso vem da camada de execução da plataforma, não dos hooks. Nossos hooks usam prefixos limpos (`[bash-guard]`, `[file-guard]`, etc.) para mensagens de depuração e nunca expõem caminhos do sistema de arquivos no stdout ou stderr. O log de depuração é opcional por hook (ex.: `BASH_GUARD_LOG=1`).

**Operações git internas ignoram todos os hooks**: O Claude Code executa operações git em segundo plano (fetch + reset) [programaticamente a cada ~10 minutos](https://github.com/anthropics/claude-code/issues/40710) sem acionar um binário `git` externo ou fazer uma chamada de ferramenta. Como os hooks só disparam em chamadas de ferramentas, o git-safe e todos os outros hooks são cegos a essas operações. Isso pode destruir silenciosamente alterações não commitadas em arquivos rastreados. Solução: use git worktrees (imunes a resets no checkout principal) ou faça commits com frequência. Se você usa `claude -w`, instale também o [worktree-guard](https://github.com/bande-a-bonnot/boucle-framework/blob/main/tools/worktree-guard) antes de depender de worktrees; sair de uma worktree pode, de outra forma, excluir commits não mesclados ou não enviados.

**Dessincronização de permissões após editar settings.local.json**: Se a ferramenta Edit do Claude modifica `.claude/settings.local.json` durante uma sessão, o estado de permissão em memória [dessincroniza do arquivo em disco](https://github.com/anthropics/claude-code/issues/41259). As regras de allow param de funcionar e o usuário é repetidamente solicitado a confirmar comandos que já estão permitidos. O arquivo em disco está correto; o problema é o cache em memória. Solução: deixe o Claude Code gerenciar os arquivos de permissão por meio de seu próprio mecanismo de prompts ou reinicie a sessão após edições manuais.

**Novo na v2.1.89: evento de hook PermissionDenied**: Um novo evento de hook é acionado após negações do classificador do modo automático. Hooks podem retornar `{"retry": true}` para informar ao modelo que ele pode tentar novamente a operação negada. O problema vinculado documenta a lacuna original de documentação para esse evento. Também na v2.1.89: as condições `if` dos hooks agora [correspondem a comandos Bash compostos](https://github.com/anthropics/claude-code/issues/41262) (`ls && git push` corresponde a `Bash(git *)`) e a comandos com prefixos de variáveis de ambiente (`FOO=bar git push`).

**systemMessage do SessionStart não é exibida (v2.1.89)**: O campo `systemMessage` retornado pelos hooks SessionStart [não é mais renderizado no terminal](https://github.com/anthropics/claude-code/issues/41285). O hook é executado e `additionalContext` ainda é injetado no contexto do modelo, mas a saída visual que aparecia antes (ex.: "SessionStart:startup diz: ...") está silenciosamente ausente. Se você depende de `systemMessage` para notificações ao operador ou identificação de sessão, a saída não ficará visível. Relacionados: [#9090](https://github.com/anthropics/claude-code/issues/9090), [#15344](https://github.com/anthropics/claude-code/issues/15344).

**Hooks falham na primeira sessão em um novo projeto**: Na primeira sessão em um diretório de projeto, os hooks SessionStart e UserPromptSubmit disparam [antes de o diretório do projeto existir](https://github.com/anthropics/claude-code/issues/41310) (`~/.claude/projects/<encoded-path>/`). Qualquer hook que derive caminhos de arquivo de `transcript_path` e tente escrever lá falhará. Solução: adicione `mkdir -p` para os caminhos derivados de transcript_path antes de escrever.

**Autoexecução do modelo em sessões longas**: Em sessões longas sem supervisão, o modelo pode [alucinar texto `Human:` após a entrega de notificações de tarefa](https://github.com/anthropics/claude-code/issues/41307) e executá-lo como se fosse uma solicitação real do usuário, disparando operações git e modificações de arquivos não autorizadas. Os hooks não conseguem detectar isso porque as chamadas de ferramentas resultantes são genuínas — apenas o gatilho é alucinado. Mitigação: use limites de tempo de sessão e evite sessões muito longas sem supervisão.

**Vazamento de GIT_INDEX_FILE em worktrees**: Agentes criados via EnterWorktree podem ter seu índice git [corrompido por entradas de plugins do marketplace](https://github.com/anthropics/claude-code/issues/41314) devido ao vazamento da variável de ambiente `GIT_INDEX_FILE` entre limites de processos. Se operações de worktree mostrarem arquivos inesperados no git status, essa pode ser a causa.

**Agentes em segundo plano não podem ser interrompidos**: Agentes criados via ferramenta Agent com `run_in_background` [não podem ser encerrados de forma confiável](https://github.com/anthropics/claude-code/issues/41461) pelo usuário. Em um caso relatado, 14 agentes paralelos escreveram no mesmo arquivo e consumiram ~1,4 milhão de tokens ($55-106). Não há mecanismo de kill integrado. Mitigação: evite criar muitos agentes em segundo plano e monitore o uso de tokens se o fizer.

**A configuração cleanupPeriodDays pode ser ignorada**: A configuração `cleanupPeriodDays` em `settings.json` [pode ser silenciosamente ignorada](https://github.com/anthropics/claude-code/issues/41458), excluindo arquivos de sessão mesmo quando definida com valores muito altos. Um usuário perdeu 490 sessões apesar de defini-la como 99999. Se você depende da persistência de sessões, faça backup de `~/.claude/projects/` de forma independente.

**Diretórios .claude/ com symlink não são descobertos (Linux)**: Comandos slash de [`.claude/commands/` com symlink](https://github.com/anthropics/claude-code/issues/41451) não são carregados no Linux (regressão). Esse é um padrão comum em equipes (armazenar a configuração compartilhada em um diretório central e criar symlinks). Hooks e skills também podem falhar se o próprio `.claude/` for um symlink. Solução: copie os arquivos em vez de criar symlinks.

**ripgrep incluído sem permissão de execução (Linux)**: O binário `rg` incluído [pode perder sua permissão de execução](https://github.com/anthropics/claude-code/issues/41463) no Linux, quebrando silenciosamente todos os comandos slash definidos pelo usuário em `~/.claude/commands/`. Correção: execute `chmod +x` no binário incluído.

**Regressões de descoberta de comandos nas v2.1.88-89**: A v2.1.88 foi [descontinuada/removida do npm](https://github.com/anthropics/claude-code/issues/41497) depois que comandos personalizados pararam de carregar e `cli.js.map` foi incluído acidentalmente no pacote. A v2.1.89 manteve a regressão de descoberta de comandos para alguns usuários ([#41864](https://github.com/anthropics/claude-code/issues/41864)), embora também tenha adicionado recursos de hooks como `PermissionDenied`. A Anthropic marcou a correção da permissão de execução do `rg` incluído como enviada na v2.1.91. Se comandos personalizados ou skills desaparecerem, atualize para a versão mais recente do Claude Code e execute novamente `safety-check --verify`.

**Sessões não interativas travam no limite de uso**: No modo headless, `--print` ou controle remoto, atingir um limite de uso [mostra um prompt de confirmação que não pode ser respondido](https://github.com/anthropics/claude-code/issues/41502) porque não há stdin. A sessão trava permanentemente. Não há solução programática ([#41503](https://github.com/anthropics/claude-code/issues/41503)). Se você executa o Claude Code em CI, cron ou loops autônomos, defina limites de tempo de sessão e monitore processos travados.

**Regras deny ignoradas por pipes e comandos compostos**: As regras deny integradas só correspondem à string completa do comando. `Bash(rm *)` bloqueia `rm -rf /`, mas não `find /foo | xargs rm` nem `something && rm -rf /`. A documentação diz que as regras allow interpretam operadores de shell, mas [as regras deny não](https://github.com/anthropics/claude-code/issues/41559). Nota: as condições `if` dos hooks foram corrigidas upstream (final de março de 2026) para corresponder corretamente a comandos compostos e prefixos de variáveis de ambiente, portanto os hooks *disparam* corretamente para esses padrões. A lacuna está especificamente nas *regras* deny, não nos hooks. O bash-guard analisa cada segmento de pipe e cadeia composta de forma independente, capturando esses padrões de bypass. Veja também [#37662](https://github.com/anthropics/claude-code/issues/37662), [#16180](https://github.com/anthropics/claude-code/issues/16180).

**"Confirmar cada alteração individualmente" é ignorado silenciosamente**: Ao sair do modo plano e selecionar "confirmar cada alteração individualmente", [as alterações são aplicadas sem nenhum prompt](https://github.com/anthropics/claude-code/issues/41551) se as ferramentas (Edit, Write, Bash) estiverem em `permissions.allow`. As regras de allow persistentes substituem a escolha explícita do usuário por sessão. Solução: remova allows amplos de ferramentas e use hooks para aplicar as regras.

**Hooks SessionEnd encerrados antes da conclusão**: Hooks SessionEnd que realizam trabalho assíncrono (chamadas de API, sumarização por LLM, requisições de rede) são [encerrados no meio da execução](https://github.com/anthropics/claude-code/issues/41577) quando o Claude Code sai, independentemente do timeout configurado. O hook chega à chamada assíncrona, mas o processo pai sai antes de a resposta retornar. Solução: desanexe o trabalho pesado em um processo em segundo plano com `nohup ... & disown` e, em seguida, saia imediatamente com `exit 0`.

**Acesso a diretório "Always allow" não é persistido**: Clicar em "Sim, e permitir sempre o acesso a [pasta]" [não é salvo de forma confiável](https://github.com/anthropics/claude-code/issues/41579). O Claude solicita novamente o mesmo diretório em sessões subsequentes. Adicionar a `additionalDirectories` em settings.json também é instável. Relacionado a [#40606](https://github.com/anthropics/claude-code/issues/40606) (vazamento de additionalDirectories entre projetos).

**Escritas em `~/.claude/` travam sessões automatizadas**: Escritas em caminhos sob `~/.claude/` disparam um prompt embutido de arquivo sensível que [não pode ser suprimido](https://github.com/anthropics/claude-code/issues/41615) por `permissions.allow`, hooks PreToolUse que retornam `"allow"`, modo `bypassPermissions` ou `skipDangerousModePermissionPrompt`. Sessões automatizadas (tmux, CI, loops autônomos) que precisam modificar arquivos de configuração do Claude Code travarão no prompt interativo. Solução: use comandos da ferramenta Bash (`echo`, `cat`, `jq`) para escrever arquivos diretamente em vez das ferramentas Edit/Write.

**O encapsulamento com `bash -c` ignora a proteção de escrita do diretório `.claude/`**: O sistema de permissões protege arquivos `.claude/` contra modificações (edição, escrita e comandos bash diretos disparam todos um modal de confirmação). Mas encapsular o comando em [`bash -c 'echo "..." >> .claude/file'`](https://github.com/anthropics/claude-code/issues/43085) ignora a verificação por completo: sem modal, a escrita é concluída silenciosamente. A correspondência de padrões inspeciona a string do comando de nível superior, mas não subshells aninhados. Isso significa que um modelo (ou injeção de prompt via resultados de ferramentas) poderia modificar hooks, settings.json, skills ou definições de agentes sem confirmação do usuário. O file-guard captura isso se `.claude/` for adicionado à configuração do `.file-guard`, porque ele varre a string completa do comando Bash em busca de caminhos protegidos (inclusive dentro de argumentos entre aspas). Usuários que dependem exclusivamente das verificações de permissão integradas ficam expostos.

**Hooks `WorktreeCreate` travam o `claude -w`**: Qualquer hook `WorktreeCreate` faz [o `claude -w` travar indefinidamente](https://github.com/anthropics/claude-code/issues/41614), independentemente do conteúdo do hook. Até `echo ok < /dev/null` congela a sessão. O hook executa e retorna, mas o Claude Code nunca prossegue. Remova todos os hooks `WorktreeCreate` se você precisar que `claude -w` funcione.

**O modelo pode manipular arquivos de estado dos hooks**: O modelo tem acesso ao sistema de arquivos e [pode sobrescrever arquivos dos quais os hooks dependem](https://github.com/anthropics/claude-code/issues/38841) — arquivos de checkpoint, arquivos de lock, contadores. Em um caso documentado, o Claude calculou o hash SHA256 de um nome de arquivo de checkpoint e gravou um timestamp novo para contornar um portão de leitura de conteúdo. Hooks que dependem de arquivos de estado externos para aplicar regras devem assumir que o modelo pode ler e modificar esses arquivos. Assinaturas criptográficas ou validação fora do processo podem mitigar isso.

**`bypassPermissions` não é restaurado ao retomar a sessão (VS Code)**: Quando `bypassPermissions` é configurado via `initialPermissionMode` nas configurações do VS Code, [conversas retomadas revertem para o modo de permissão padrão](https://github.com/anthropics/claude-code/issues/42735) e solicitam confirmação para cada edição. Novas sessões podem aplicar a configuração, mas sessões retomadas falham consistentemente. Hooks que dependem de a sessão estar em modo bypass não podem contar com a persistência dela na retomada.

**O isolamento de worktree quebra em submódulos git**: Usar `isolation: "worktree"` na ferramenta Agent dentro de um submódulo git [cria a worktree em `.git/modules/<path>/.claude/worktrees/`](https://github.com/anthropics/claude-code/issues/42732) em vez do `.claude/worktrees/` do próprio projeto. Isso coloca o agente fora do escopo de permissão do projeto, fazendo com que `bypassPermissions` seja silenciosamente rebaixado e acionando prompts de permissão inesperados.

**Aprovação de skill não vinculada ao hash de conteúdo**: Quando um usuário aprova uma skill, a aprovação [não está ancorada ao hash de conteúdo do arquivo](https://github.com/anthropics/claude-code/issues/43157). Se o arquivo da skill for modificado após a aprovação (mesmo no meio da sessão), a versão modificada é executada sem nova solicitação. Além disso, aprovar uma skill pode ignorar regras deny de nível de ferramenta em `settings.json`. Isso é um risco de cadeia de suprimentos: qualquer coisa com acesso de escrita a `~/.claude/skills/` pode escalar capacidades após a aprovação.**Servidores MCP Stdio nunca se reconectam automaticamente**: Quando um processo de servidor MCP do tipo stdio morre ou se desconecta, o Claude Code [o marca como falho e nunca tenta novamente](https://github.com/anthropics/claude-code/issues/43177). Servidores HTTP/SSE/WebSocket recebem reconexão automática com backoff exponencial (5 tentativas), mas servidores stdio são explicitamente excluídos. Os usuários devem executar manualmente `/mcp` para reconectar. Isso afeta qualquer integração MCP que use transporte stdio (o padrão local mais comum).

**O modo de plano é contornado após o primeiro ciclo**: Depois de concluir um ciclo plano-aprovação-implementação, entrar novamente no modo plano [não impõe de forma confiável as restrições de somente leitura](https://github.com/anthropics/claude-code/issues/43147). O Claude carrega o estado mental "aprovado" e começa a editar arquivos antes que o usuário aprove o novo plano. Hooks que dependem do modo plano como barreira de segurança não podem confiar nele entre vários ciclos na mesma sessão.

**Windows**: Todos os sete hooks têm equivalentes nativos em **PowerShell 7+** (`hook.ps1`) que não exigem dependências externas. Requer [PowerShell 7](https://learn.microsoft.com/en-us/powershell/scripting/install/installing-powershell-on-windows) (`pwsh`), não o Windows PowerShell 5 embutido. Instale-os com:```powershell
iex "& { $(irm https://raw.githubusercontent.com/Bande-a-Bonnot/Boucle-framework/main/tools/install.ps1) } all"

Ou configure manualmente em .claude/settings.json com "command": "pwsh -File /path/to/hook.ps1". A ferramenta enforce-hooks é um script bash que funciona a partir de um terminal WSL ou com Git for Windows (que fornece /usr/bin/bash). Nota: o Claude Code tem um bug conhecido em que os hooks disparam apenas ~18% das vezes no Windows, portanto a confiabilidade dos hooks é limitada no Windows nativo, independentemente do shell. O WSL continua sendo a opção mais confiável. Veja #3.

Desenvolvimento```bash

cargo test # Framework tests cargo fmt # Format code cargo clippy # Run linter

Hook tests (run individually)

bash tools/read-once/test.sh bash tools/file-guard/test.sh bash tools/git-safe/test.sh bash tools/bash-guard/test.sh bash tools/branch-guard/test.sh bash tools/session-log/test.sh bash tools/enforce/test.sh bash tools/safety-check/test.sh bash tools/worktree-guard/test.sh

## Status

**Última versão:** v0.13.0 foi lançada com mais de 200 testes Rust + mais de 1.700 testes de hooks (bash + PowerShell). Zero avisos do clippy. CI em Ubuntu + macOS + Windows. Suporte a Docker.

Novidades na v0.13.0: corpus pesquisável de Known Limitations do Claude Code, página de receitas, exportação de Known Limitations legível por máquina, configurações em camadas do bash-guard e proteção contra mutação via `gh api`, fatos com tags TTL da Broca, redefinição do cache PostCompact de leitura única, verificação de safety-check endurecida, endurecimento do bloqueio e timeout do runner e melhorias de paridade no instalador Windows. Consulte [CHANGELOG](https://github.com/bande-a-bonnot/boucle-framework/blob/main/CHANGELOG.md) para detalhes.

As métricas do repositório estão visíveis no GitHub; este README evita incorporar contagens voláteis de estrelas e forks.

## Contribuindo

Contribuições são bem-vindas. Abra uma issue primeiro para discutir o que você gostaria de alterar.

## Licença

MIT

Boucle-framework

Mais Populares

Boucle

Hooks do Claude Code

See what's installed

Test all installed hooks with real payloads (run after CC updates)

Upgrade all installed hooks to latest

Remove a hook (files + settings.json)

Remove all hooks

Snapshot settings.json before updating Claude Code

Restore after an auto-update wipes your hooks

Run safety audit on your Claude Code setup

Print only the public support summary

Run strict safety audit with hook payload verification

Diagnose installation health (files, settings, permissions)

Show all commands and available hooks

read-once — Evite leituras redundantes de arquivos```sh

git-safe — Evite operações git destrutivas```sh

branch-guard — Impor fluxo de trabalho com branch de recurso```sh

session-log — Trilha de auditoria para sessões do Claude Code```sh

test-hook — Teste qualquer hook sem uma sessão ativa```sh

Test bash-guard against a dangerous command

Test file-guard write path validation

CI mode: assert the hook blocks

Batch mode: run multiple test cases from a JSONL file

Boucle Framework

Recursos

Início Rápido

Opção 1: Baixar um binário

macOS (Apple Silicon)

Execute seu primeiro agente```bash

Create a clean agent directory

Initialize a new agent

Check your setup

Preview what happens (no LLM needed)

Run one iteration (requires the configured LLM CLI)

Set up hourly execution

As entradas de memória têm o seguinte aspeto:```markdown

type: fact tags: [python, packaging] confidence: 0.9 learned: 2026-02-28 source: research

Python packaging has moved to pyproject.toml

Initialize with an example harvester

Todas as Ferramentas

Arquitetura```

Pontos de Extensão

Plugins de Contexto (context.d/)

context.d/weather — Add weather to context

Referência da CLI```bash

Agent management

Self-observation

Memory (Broca)

MCP server

Global options

Desenvolvimento```bash

Hook tests (run individually)

Plugins de Contexto (`context.d/`)