O hook é o mecanismo de garantia, não o prompt

Seu agente agora tem mãos. Executa comandos, edita arquivos, chama APIs, envia e-mail, move o dinheiro. Então faça a pergunta que deveria deixá-lo um pouco nervoso: o que o impede de usar essas mãos errado? Para a maioria das equipes a resposta é o bom julgamento do modelo — um sistema probabilístico que, dependendo de como você formulou o prompt, pode decidir que hoje é o dia de rodar o comando de limpeza na pasta errada. O guia de julho de 2026 sobre Claude Code hooks do Professor Glitch no askglitch.com nomeia a correção: um hook é código determinístico que dispara num ponto fixo do loop do agente, e o modelo não o contorna. A propriedade que lhe importa é garantida pelo mecanismo, não por pedir ao modelo que tome cuidado.

Um hook é o Teorema 3 em código

Um hook é código determinístico que roda automaticamente num ponto fixo do loop do agente — antes de uma ferramenta executar, depois que completa, quando o agente declara pronto, quando a sessão termina. Não faz parte do raciocínio do modelo. Senta-se fora do cérebro, e simplesmente roda. O guia de hooks de julho de 2026 do Professor Glitch no askglitch.com coloca a distinção claramente: o modelo é probabilístico, cada instrução é uma sugestão que provavelmente seguirá; um hook é código que roda toda vez, no mesmo ponto, com as mesmas regras, e o modelo não pode esquecê-lo, pulá-lo ou contorná-lo.

[ORIGINAL DATA] Isto é o Teorema 3 dos 21 papers: uma propriedade é garantida exatamente quando seu mecanismo está implementado e medindo. O hook é esse mecanismo. "Os testes passam antes de o agente declarar pronto" é uma propriedade. Um hook Stop que roda a suite e sai com código 2 num falha é o mecanismo implementado e medindo. Remova o hook e você tem um desejo. Mantenha o hook e você tem uma garantia — não porque o modelo ficou mais inteligente, mas porque o caminho de falha é agora fisicamente impossível.

O prompt diz "sempre rode os testes antes de terminar." Isso é uma sugestão que o modelo provavelmente honrará. O hook recusa o stop até que a suite esteja verde. Isso é uma regra. A diferença entre uma sugestão e uma regra é a diferença entre esperar e saber, e essa diferença é toda a disciplina. Imagine o modelo como a multidão e o hook como o segurança da porta, escreve o Professor Glitch: a multidão pode ser charmosa o quanto quiser, o segurança verifica todo mundo, toda vez, sem exceções.

O modelo é probabilístico; a fronteira é determinística

Mecanicamente, segundo a documentação oficial de hooks, um hook do Claude Code é um comando de shell que você registra num arquivo de configuração. Quando o evento dispara, o Claude Code roda seu comando, envia um payload JSON descrevendo o evento pelo stdin — o nome da ferramenta, a entrada exata, o id da sessão, o diretório de trabalho — e lê seu veredito do código de saída e stdout. Sair com 0 significa prosseguir. Sair com 2 significa bloquear, e o que você imprimiu no stderr é devolvido ao modelo como razão. Você os escreve no que quiser: Bash, Python, um binário compilado. Se lê stdin e retorna um código de saída, é um hook.

[UNIQUE INSIGHT] Isto é "the space is the router" na fronteira do agente. No Everythink, a topologia network→community→room roteia uma requisição antes de qualquer coisa responder — o espaço decide quem é endereçado, não o respondente. Um hook PreToolUse é o mesmo padrão um nível abaixo: o hook roteia a chamada da ferramenta antes de a ferramenta executar. O agente não escolhe se sua leitura de .env prossegue; a fronteira decide. Roteamento precede recuperação, e na fronteira da ferramenta o hook precede execução.

A armadilha que pega quase todo mundo, direto da documentação: só o código de saída 2 bloqueia. O código de saída 1 — o código de falha convencional do Unix — é tratado como um erro não bloqueante e a ação prossegue mesmo assim. Se seu script de guarda cai com saída 1, o segurança acaba de deixar toda a multidão passar. Escreva seus hooks de modo que o caminho de falha seja explícito, e prefira a forma de saída JSON (permissionDecision: "deny" no stdout com saída 0) quando quiser que a decisão seja inequívoca. Uma barreira que falha silenciosamente para aberto é pior que nenhuma barreira, porque vende a sensação de segurança sem o mecanismo. O Teorema 3 é implacável aqui: um mecanismo que está implementado mas não está medindo não garante a propriedade. Um hook que cai aberto não está medindo.

Trabalho um: tornar certas falhas impossíveis

O Professor Glitch lista três barreiras que ele realmente roda, em ordem crescente de quanto o salvaram. O padrão através das três é o mesmo: você não está tornando o modelo mais inteligente nem mais cuidadoso. Você está tornando certas falhas impossíveis. Esses são problemas de engenharia diferentes, e o segundo é muito mais fácil de resolver.

Bloquear leituras do arquivo de segredos

Um hook PreToolUse vê toda chamada de ferramenta antes de executar, com a entrada completa. Se o agente está prestes a ler .env ou qualquer coisa sob secrets/, o hook sai com 2 e a leitura nunca acontece. Frio. Não importa quão razoável fosse a justificativa do agente, ou se uma injeção de prompt enterrada numa página web pediu educadamente. O segurança não debate.

Bloquear comandos destrutivos

O mesmo evento, casado com a ferramenta Bash. O hook inspeciona a string do comando em tool_input.command antes de rodar — rm -rf apontando a algo sensível, um force push, um DROP TABLE, o que quer que sua lista pessoal de cicatrizes contenha. Nega em código e simplesmente não é possível, não importa o que o modelo raciocine.

Rejeitar "pronto" até os testes passarem

Esse é o que mais importa, e usa um evento diferente. O Claude Code dispara um evento Stop quando o agente termina de responder. Seu hook roda nesse momento. Se sai com 2, o agente é impedido de parar; sua mensagem de stderr volta ao modelo, e ele volta a trabalhar. O agente diz "tudo certo, shippei a feature." O hook Stop roda silenciosamente a suite de testes. Três falhas. O hook sai com 2 com a saída da falha. O agente não pode dar pronto. É empurrado de volta ao loop com o bug em mãos.

O stop recusado é a garantia que importa

Todo mundo entende que hooks podem bloquear uma má ação. O movimento subestimado é que um hook pode bloquear um mau stop. É aqui que o argumento da fonte e o Teorema 3 se encontram com mais clareza.

"Sempre rode os testes antes de terminar" no seu prompt é uma sugestão. Um hook Stop que recusa o stop é uma regra. O agente literalmente não pode declarar vitória enquanto a suite está vermelha. Duas notas práticas do guia: mantenha a verificação rápida e determinística, porque roda a cada stop; e certifique-se de que uma falha real produza uma mensagem consertável, porque esse texto de stderr é a única orientação que o agente recebe. "Testes falharam" o manda vagar. A saída real da falha o manda direto ao bug.

[PERSONAL EXPERIENCE] O HAI Engine roda em produção desde 2016, e a lição desses anos é a mesma: as propriedades que garantimos — probabilidades normalizadas em exatamente um lugar, cenários ordenados descendentemente, entropia em nats — vivem no código de ensemble do Oracle, não num prompt pedindo às Sisters que tomem cuidado. As Sisters imaginam; o Oracle funde. A normalização é o hook. Roda toda vez, no mesmo ponto, com as mesmas regras, e nenhuma Sister pode convencê-lo a enviar um cone cujas probabilidades somem 1.05. Isso é o Teorema 3: a propriedade vale porque o mecanismo está implementado e medindo.

O mesmo padrão funciona um nível abaixo: SubagentStop dispara quando um subagente termina, então o trabalho delegado pode ser mantido no mesmo padrão que o loop principal. Nos termos do Everythink, isso é por que the space is the router — uma room roteia ao subagente certo, e o stop do subagente é gated pela mesma fronteira que gatela o pai. A garantia compõe-se através da topologia. Uma network roteia a uma community, uma community roteia a uma room, uma room roteia a um subagente, e em cada fronteira a mesma disciplina se aplica: o mecanismo garante a propriedade, não o julgamento do respondente.

Trabalho dois: o diário de fim de turno

Barreiras são para o que todos usam hooks. Há um segundo trabalho de que quase ninguém fala: hooks são como a memória de um agente é escrita.

Seu agente já lê memória; a recuperação puxa os fatos relevantes à janela quando uma tarefa começa. Mas algo tem de arquivar os fatos novos — a preferência que você expressou, a abordagem que funcionou, o erro que vale não repetir. Esse algo é um hook. O Claude Code dispara SessionEnd quando uma sessão termina. Não pode bloquear nada; sua saída é ignorada; existe puramente para efeitos colaterais. Que é exatamente o que é uma escrita de memória: pega o caminho do transcript do stdin, destila a conversa, anexa o durável ao seu armazenamento.

É o diário de fim de turno, exceto que o diário se escreve, todo turno, porque é uma regra e não um humor. Na próxima sessão, o agente entra já sabendo o que esta lhe ensinou.

Duas regras evitam que isso vire um brinquedo. Gate a escrita: a maioria das mensagens é "obrigado" e "entendido", então escreva no fim da sessão e deixe o prompt terminar com "se nada é durável, não escreva nada." Guardar tudo não é memória, é desordem. E use o modelo barato: destilar um transcript num parágrafo não é raciocínio difícil. O modelo sênior pensa durante a sessão; o estagiário redige as atas depois.

Isso mapeia a uma disciplina que mantemos nos 21 papers: uma medição que não é gated é ruído. O Oracle não loga cada rascunho de Sister — ele loga o ensemble normalizado, a entropia, o traço de calibração. O hook SessionEnd é o mesmo portão na fronteira da memória: escreva o fato durável, descarte o ruído. Um sistema de memória que guarda tudo não lembra de nada.

O mapa de eventos

O Claude Code expõe cerca de trinta eventos. Os que você alcança primeiro, segundo a documentação:

• PreToolUse — antes de qualquer chamada de ferramenta executar; pode bloquear; guarda de segredos, filtro de comandos destrutivos.
• PostToolUse — depois que uma chamada de ferramenta completa; só feedback; auto-formatar após edições, logar cada comando.
• UserPromptSubmit — quando você envia um prompt; pode rejeitar o prompt; injetar contexto, filtrar prompts.
• Stop — quando o agente termina de responder; pode recusar o stop; rodar testes antes de aceitar "pronto".
• SubagentStop — quando um subagente termina; pode bloquear; manter trabalho delegado no mesmo padrão.
• SessionStart — quando uma sessão começa; não pode bloquear, adiciona contexto; carregar o estado de hoje na janela.
• PreCompact — antes da compactação de contexto; pode bloquear; salvar estado antes de a janela ser espremida.
• SessionEnd — quando uma sessão termina; só efeitos colaterais; a escrita de memória.

Note a simetria: SessionStart injeta contexto, SessionEnd escreve aprendizado. Esse par sozinho é um sistema de memória funcional — e é um sistema de memória feito de regras, não de humores. O evento PreCompact é a fronteira que impede que a janela descarte estado silenciosamente: salve o conjunto de trabalho antes do espremimento, e o agente retoma do fato, não do resumo.

O que o Everythink garante assim

O HAI Engine ✅ é o sistema de produção que essa disciplina produz. As Sisters ✅ são as imaginadoras; o Oracle ✅ é o fundidor; a normalização do ensemble é o hook que garante que as probabilidades somem um. O World Monitor ✅ roteia geo-sinais ao vivo através de um gateway que limita o volume de chamadas upstream pelo nosso cronograma, não pela contagem de clientes — um hook de rate-limit no nível de arquitetura. Social ✅, Campaigns ✅ e Whitelabel Network ✅ são os módulos onde as regras de roteamento de uma network são impostas em código, não numa diretriz de marca.

Os módulos Partial ⚠️ — Matchmaking, Marketplace, Calendar — estão medidos mas ainda não fully hardened; dizemos isso. Os módulos Roadmap 🔵 — Wallet & Token, Super App, Community Credit — são pre-revenue e sujeitos a revisão Howey; não prometemos resultados para eles, e nenhum hook que enviemos pode mudar essa honestidade. Um hook pode garantir uma propriedade; não pode garantir um mercado.

A soberania do cliente é a versão mais profunda desse padrão. Sua network, sua marca, seus dados — as regras de roteamento são suas porque vivem em código que você controla, não no prompt de um fornecedor. A ética de escopo — uso civil e defensivo somente — é ela mesma um hook: uma política escrita na fronteira, não uma esperança de que o modelo recuse o trabalho errado. Inclusão por design — multilíngue, multimodal, baixa conectividade — é uma injeção SessionStart: o locale e a largura de banda moldam o primeiro contexto que o agente vê, antes de ele responder.

Pontos-chave

• Um hook é código determinístico num ponto fixo do loop do agente; o modelo é probabilístico e não o contorna. A propriedade é garantida pelo mecanismo, não pelo prompt.
• O stop recusado é o Teorema 3 em código: "testes passam antes de pronto" é uma propriedade; o hook Stop que sai com 2 na falha é o mecanismo implementado e medindo.
• Sair com 2 bloqueia; sair com 1 falha aberto. Uma barreira que cai aberta é pior que nenhuma — vende a sensação de segurança sem o mecanismo.
• SessionEnd escreve memória para que SessionStart possa lê-la. O par é um sistema de memória feito de regras, não de humores; gate a escrita ou guarda desordem.
• O hook é "the space is the router" na fronteira da ferramenta: roteamento precede execução, e a fronteira decide, não o respondente.

Perguntas frequentes

O que é exatamente um hook do Claude Code? Um comando de shell que você registra num arquivo de configuração. Quando um evento fixo do loop do agente dispara — antes de uma ferramenta rodar, quando o agente declara pronto, quando uma sessão termina — o Claude Code envia um payload JSON ao seu script e lê o veredito do código de saída. Sair com 0 prossegue, sair com 2 bloqueia.

Por que um hook é mais seguro que uma instrução de prompt? Uma instrução de prompt é uma sugestão que um modelo probabilístico provavelmente seguirá. Um hook é código que roda toda vez, no mesmo ponto, com as mesmas regras. O modelo não pode esquecê-lo, pulá-lo nem argumentá-lo. "Esperar que se comporte" torna-se "saber que vai."

O que significa "recusar o stop"? O evento Stop dispara quando o agente termina de responder. Um hook nesse evento pode sair com 2 para impedir o agente de parar, enviando a mensagem de stderr de volta ao modelo. Rode a suite de testes aí, e o agente literalmente não pode declarar vitória enquanto a suite está vermelha.

Como isso se conecta ao Teorema 3? O Teorema 3 diz que uma propriedade é garantida exatamente quando seu mecanismo está implementado e medindo. O hook é esse mecanismo: implementado como código, medindo como código de saída. Remova-o e você tem um desejo; mantenha-o e você tem uma garantia.

O Everythink usa hooks? A mesma disciplina roda o HAI Engine ✅: a normalização do ensemble do Oracle é o hook que garante que as probabilidades somem um, em código, toda execução. Nenhuma Sister pode convencê-lo a enviar um cone não normalizado.

Sources

Professor Glitch, "Claude Code Hooks: The Guardrails Your Agent Can't Talk Past," askglitch.com, 7 de julho de 2026 — https://www.askglitch.com/blog/claude-code-hooks

Claude Code hooks reference, code.claude.com — https://code.claude.com/docs/en/hooks

Crie a sua network.