1

Hooks no Claude Code: exit 1 não bloqueia (e outros 5 detalhes que fazem o hook nunca disparar)

O CLAUDE.md diz "sempre formate depois de editar", e o Claude obedece quase sempre. Um hook formata sempre, porque quem roda é o Claude Code, não o modelo. A própria documentação resume: se você reforça uma linha do CLAUDE.md e o Claude ainda erra, essa linha provavelmente devia ser um hook.

Configurando hooks, eu caí em quase todos os detalhes abaixo. Junto aqui o que a documentação diz sobre eles.

1. Exit 1 não bloqueia

Pelo costume do Unix, 1 é falha. Para o Claude Code, exit 1 sem JSON válido é um erro não bloqueante: a ação acontece mesmo assim e aparece só um aviso.

  • Exit 0: sem objeção. Num PreToolUse, a chamada segue o fluxo normal de permissões (exit 0 não aprova nada).
  • Exit 2: bloqueia. O que você escreve no stderr vira o motivo, e o Claude recebe isso para ajustar o plano.
  • Qualquer outro código: erro não bloqueante.

Hook de política tem de usar exit 2.

2. O matcher é uma string, não uma lista

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash|PowerShell",
        "hooks": [
          { "type": "command", "command": "node", "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/bloquear.js"] }
        ]
      }
    ]
  }
}

Matcher em formato de array é o erro mais comum de hook que nunca dispara. E o nome diferencia maiúsculas: "bash" não casa com nada.

3. No Windows, o shell pode ser o PowerShell

Com a ferramenta PowerShell ativa, o Claude manda os comandos de shell por ela. Um hook de bloqueio que casa só Bash nunca dispara. Por isso o matcher acima é Bash|PowerShell.

4. Não existe arquivo de hooks avulso

Hooks ficam na chave "hooks" de um settings.json (de usuário, de projeto ou local). Só plugins usam um hooks/hooks.json separado.

5. Prefira a forma exec

Com "command": "node" e "args" em lista, não há shell no meio, então não há problema de aspas nem de espaços no caminho. ${CLAUDE_PROJECT_DIR} aponta para a raiz do projeto onde a sessão começou, em qualquer pasta em que o Claude esteja.

Sem args, o comando roda num shell: sh -c no macOS e no Linux, Git Bash no Windows, ou PowerShell quando o Git Bash não está instalado.

6. Hook que falha não protege nada

Por padrão, se o hook não consegue rodar (caminho errado, Node não instalado, tempo esgotado), a ação segue como se ele não existisse. Um erro de digitação desliga a proteção sem ninguém perceber.

Nas versões recentes, "onFailure": "block" faz a falha do hook bloquear a ação. Se a sua versão aceitar, use nos hooks de política.

Como depurar em 1 minuto

  • /hooks mostra se o hook foi carregado, de onde veio e o que ele roda. Se não aparece, o problema é de configuração.
  • Aparece, mas não dispara: confira o matcher.
  • Teste o script fora do Claude, mandando um JSON pelo stdin:
echo '{"tool_input":{"command":"git push -f"}}' | node .claude/hooks/bloquear.js; echo $?

O esperado é 2.

Um último cuidado: hook roda com as permissões do seu usuário, toda vez que o evento acontece. Revise todo PR que mexe em .claude/settings.json ou .claude/hooks/, e desconfie de hooks de repositórios de terceiros.


Transparência: isto é um trecho adaptado do capítulo de hooks de um guia pago que eu escrevi, o Claude Code na Prática, que traz também os três hooks prontos (formatar depois de editar, bloquear comandos perigosos e rodar os testes antes de encerrar): https://guias-praticos.pages.dev/claude-code-na-pratica/

Carregando publicação patrocinada...