Stop Hook: o porteiro ao final de cada turno do Claude
🎯 O que é o Stop Hook
O Stop Hook é um script que o Claude Code executa todo turno antes do Claude poder encerrar. É um ponto de extensão padrão da plataforma — qualquer plugin pode registrar um hook ali. O Claudex usa esse ponto pra colocar a lógica do ciclo: ler o estado, decidir a próxima ação, escrever o prompt da próxima rodada se preciso.
📍 Onde fica registrado
O hook é registrado no arquivo de configuração do plugin (settings.json do Claude Code). Quando você instala o plugin Claudex, essa entrada é adicionada automaticamente:
// .claude/settings.json (trecho) { "hooks": { "stop": ".claude/claudex/hooks/stop.sh" } }
Toda vez que o Claude termina um turno, o Claude Code executa esse script. Esse é o gancho.
🚪 ALLOW vs BLOCK
O hook tem duas decisões possíveis. Ele comunica isso pelo exit code e por uma mensagem que aparece pro Claude.
✅ ALLOW — exit 0
"Claude, pode sair. Trabalho feito."
Acontece quando: ciclo terminou (todas rodadas concluídas), ou o usuário cancelou, ou não há ciclo ativo.
🛑 BLOCK — exit 2
"Claude, não pode sair. Faça isso primeiro."
Acontece quando: ciclo ainda tem rodadas. O hook devolve um prompt instruindo o Claude a executar o runner e revisar.
📤 Mensagem típica de BLOCK
Execute .claude/claudex/runner.sh, depois leia findings-round-2.md e atualize o PLAN.md integrando os achados de severidade alta e média.
É essa mensagem que mantém o ciclo se movendo. Sem o hook bloqueando, o Claude encerraria depois do rascunho e o Codex nunca seria chamado.
⚙️ Por que o hook é necessário
Sem hook, o Claude termina o turno e o controle volta pra você. Não há quem invoque a próxima rodada. O ciclo morreria após o primeiro PLAN.md.
❌ O que aconteceria sem hook
- ✗Claude escreve o PLAN.md inicial e encerra
- ✗Você precisaria digitar manualmente "agora chama o Codex"
- ✗Você precisaria orquestrar 3 rodadas de revisão na mão
- ✗Provavelmente desistiria depois da 2ª, e o ciclo perderia força
O hook é o que torna o ciclo automático. Você invoca /claudex plan uma vez, e o hook garante que as 3 rodadas aconteçam sem você intervir.
🛡️ O que o hook evita
O hook não só faz o ciclo acontecer — ele previne falhas de comportamento que aconteceriam com prompts manuais.
Evita encerramento cedo
Claude poderia "achar que terminou" depois da rodada 1. Hook garante que continua até a meta.
Evita rodadas a mais
Sem controle, o ciclo poderia rodar indefinidamente. Hook respeita o max_rounds do estado.
Evita pular fase
Hook força ordem: drafting → reviewing → summarizing → done. Não dá pra pular.
Evita ignorar achados
Mensagem de BLOCK força o Claude a ler findings.md antes de poder revisar.
⏱️ Como dispara ao final do turno
O Claude Code define "fim de turno" como o momento em que o Claude declara que terminou. Naquele instante exato, antes do controle voltar pro usuário, o hook é invocado.
🔄 Sequência exata
1. Claude termina de escrever (ex: salvou PLAN.md) 2. Claude declara fim do turno 3. Stop Hook é invocado ← aqui 4. Hook lê o estado em .claude/claudex/state.yaml 5. Hook decide: ALLOW ou BLOCK 6. Se BLOCK: hook devolve mensagem; turno continua 7. Se ALLOW: Claude encerra; controle volta pro usuário
👻 O hook como motor invisível
Você nunca vê o Stop Hook executando. Ele é silencioso, rápido (milissegundos) e essencial. É o "motor" no sentido que ninguém liga o motor do carro pensando — só liga e dirige.
💡 Insight de arquitetura
A força do Claudex está em colocar inteligência num ponto de extensão que todo plugin tem. O Stop Hook não é uma invenção do Claudex — é mecânica padrão do Claude Code. O Claudex só descobriu como usar esse gancho pra criar um ciclo automático sem pedir nada novo da plataforma.
📌 Resumo
Próximo Módulo:
2.2 — 📋 O Arquivo de Estado YAML