Hooks

O que é

Pense em uma luz com sensor de movimento: ela acende sozinha no instante em que alguém passa por perto, sem que ninguém precise se lembrar de apertar o interruptor. Um hook funciona da mesma forma. Um hook é um comando seu que roda automaticamente em um ponto específico do ciclo de vida de um agente — antes de ele executar um comando de shell, depois de editar um arquivo, quando uma sessão começa, e assim por diante. Hooks permitem observar e controlar o que o agente faz usando scripts comuns, em vez de confiar que ele vai se lembrar de uma regra sozinho. Eles são a camada de aplicação (enforcement) de um harness de codificação.

Pontos fortes

• Determinístico: um hook roda todas as vezes, então uma regra não pode ser esquecida ou contornada.
• Escrito como shell ou scripts simples, então você pode fazer qualquer coisa que sua máquina consiga fazer.
• Pode bloquear uma ação, não só registrá-la — um hook de pré-comando pode recusar um comando perigoso.
• Ótimo para guardrails (proteções): formatar ao salvar, rodar testes após edições, buscar segredos antes de um commit.

Contrapartidas

• Um hook é código de verdade que roda automaticamente, então um hook com bugs pode quebrar o fluxo de trabalho.
• Hooks lentos adicionam latência a cada evento que os dispara.
• Eles disparam com base em padrões, então um hook amplo demais pode interferir em ações legítimas.
• Mais configuração e mais um lugar para olhar quando algo se comporta de forma inesperada.

Quando usar

Use hooks quando você quiser uma garantia sólida sobre o comportamento do agente — formatação automática, execução obrigatória de testes, bloqueio de comandos destrutivos ou registro de cada ação — em vez de depender da conformidade voluntária do agente.

Encaixe no vibe coding

Hooks são a forma de manter um agente seguro enquanto ele se move rápido. O agente propõe; o hook aplica (enforce). Um hook de "antes de executar" que bloqueia rm -rf ou um hook de "depois de editar" que roda o verificador de tipos transforma um assistente solto em um que fisicamente não consegue pular seus guardrails.

// run the formatter after every file edit
{
  "hooks": {
    "PostToolUse": [
      { "matcher": "Edit", "command": "npx prettier --write $FILE" }
    ]
  }
}