01 O que é uma trava

Uma trava é um hook de PreToolUse: ele roda antes da ferramenta e decide se ela pode seguir. O sinal é o código de saída:

• exit 0 — tudo bem, pode rodar.
• exit 2 — barra. O Claude não executa, e o que você imprimiu no stderr vira o motivo.

Repare na diferença: a trava não "avisa depois" — ela impede antes. É a diferença entre um extintor e um relatório de incêndio. Nas próximas aulas você vai ensinar essa trava a ler o comando, cobrir os casos que doem de verdade, e falar allow/ask/deny — mas a base é só isto: exit 0 segue, exit 2 barra.

02 O motivo volta pro Claude

Quando a trava barra, o Claude não fica no escuro: tudo que seu script imprime no stderr antes do exit 2 vira o motivo que ele lê. É a sua única chance de explicar por que — escreva pra ele, não pra você:

# ruim: não diz nada útil
exit 2

# bom: o Claude sabe exatamente o que evitar da próxima vez
echo "trava: rm -rf apaga tudo sem confirmação — use um caminho específico" >&2
exit 2

Pense na mensagem como uma instrução curta pro próprio Claude tentar de novo do jeito certo, não como um log de erro genérico. "bloqueado" diz pouco; "bloqueado: use rm arquivo.txt, não rm -rf pasta/" ensina.

03 Um exemplo mínimo: barrar rm -rf

Junte as duas peças — ler o comando (mais sobre isso na próxima aula) e decidir com exit code — e você já tem uma trava de verdade:

# .claude/settings.json → PreToolUse, matcher "Bash"
jq -r '.tool_input.command' | grep -qE 'rm -rf' && {
  echo "trava: rm -rf bloqueado" >&2
  exit 2
}
exit 0

Leia de dentro pra fora: pega o command do stdin, procura o padrão rm -rf; se achar, imprime o motivo e barra; se não achar, o exit 0 no fim deixa seguir. Curto, e já resolve o acidente mais clássico.

04 exit 0 libera

Todo comando que não casa com o padrão perigoso precisa continuar normalmente — e quem garante isso é um exit 0 explícito no fim do script. Sem ele, o exit code do último comando rodado (o grep, por exemplo) pode vazar e confundir o Claude Code.

• Termine sempre com exit 0 depois do bloco de checagem — mesmo que pareça óbvio.
• Uma trava que só reage a um padrão e deixa tudo o resto passar é o comportamento certo: você quer travar o perigoso, não o resto do trabalho.

Com isso, o ciclo fecha: ler o comando → comparar com o padrão → exit 2 (barra, com motivo) ou exit 0 (segue). É a menor trava que existe, e já é real — o Claude não pode simplesmente "decidir ignorar" ela.

01 O comando chega em tool_input.command

Antes de rodar, o Claude entrega ao seu hook um JSON pela entrada padrão (stdin) com o contexto do momento. Alguns campos estão sempre presentes (session_id, cwd, hook_event_name); no PreToolUse, vêm também tool_name e o tool_input:

{
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": { "command": "rm -rf build/" },
  "cwd": "/home/voce/projeto"
}

Repare: como a ferramenta ainda não rodou, não existe tool_response nesse momento — só a intenção. É exatamente essa intenção que sua trava examina antes de deixar (ou não) ela virar ação.

02 Extrair com jq -r

Pra tirar o texto puro de dentro do JSON, você usa jq. A diferença entre usar -r ou não é o que separa um valor utilizável de um cheio de aspas:

# sem -r: devolve o valor JSON-encoded, com aspas
$ jq '.tool_input.command'
"rm -rf build/"

# com -r (raw): devolve o texto cru, pronto pra comparar
$ jq -r '.tool_input.command'
rm -rf build/

Sem -r, as aspas continuam grudadas no valor e atrapalham qualquer comparação de texto. Guarde o hábito: em hook de shell, jq -r é praticamente sempre o que você quer.

03 Casar padrões perigosos (grep/case)

Com o texto em mãos, comparar com vários padrões de uma vez é rotina. Duas formas equivalentes — escolha a que ler melhor no seu script:

# com grep -E (alternância "|")
cmd=$(jq -r '.tool_input.command')
echo "$cmd" | grep -qE 'rm -rf|git push --force|:\(\)\{ :' && exit 2

# com case (mais legível quando a lista cresce)
case "$cmd" in
  *"rm -rf"*|*"push --force"*) echo "trava: padrão perigoso" >&2; exit 2 ;;
esac
exit 0

grep -E é mais curto pra poucos padrões; case fica mais legível quando a lista de padrões cresce e cada um merece um comentário. As duas fazem a mesma coisa: casar o comando com uma lista do que é perigoso.

04 Falso positivo e aspas: cuidado com escape

Ler o comando bem tem duas armadilhas comuns:

• Falso positivo — um grep largo demais pega coisa inocente (ex.: rm -rf dentro de um comentário ou de uma string). Prefira padrões específicos ao invés de uma palavra solta.
• Nunca reinterpole o comando num shell novo — pegar $cmd e jogar de volta num eval ou noutro bash -c "$cmd" abre a porta pra injeção de comando. Sua trava só deve ler e comparar o texto, nunca executá-lo de novo.

Sempre use "$cmd" entre aspas duplas ao manipular a variável (evita que espaços quebrem a comparação), e trate o valor como dado, não como código pra rodar.

01 rm -rf e caminhos fora do projeto

O perigo real não é a palavra "rm -rf" isolada — é o alvo. Um rm -rf dentro da pasta build/ do projeto é chato de recuperar; um rm -rf /, rm -rf ~ ou rm -rf .. é catastrófico. Trave alvos amplos, não a sintaxe:

jq -r '.tool_input.command' | grep -qE 'rm -rf (/|~|\.\.)($| )' && exit 2

Uma checagem extra vale o esforço: comparar o caminho contra $CLAUDE_PROJECT_DIR (a raiz do projeto) garante que o alvo do comando não sai da pasta que você está de fato disposto a arriscar.

02 push/force na branch principal

git push --force reescreve o histórico remoto — se for na main ou master, o estrago é do time inteiro. Trave o combo específico (força + branch protegida), não só a força isolada:

cmd=$(jq -r '.tool_input.command')
echo "$cmd" | grep -qE -- '--force' && echo "$cmd" | grep -qE '\b(main|master)\b' &&
  { echo "trava: push --force direto na main/master" >&2; exit 2; }
exit 0

Note as duas condições combinadas: precisa ter força e apontar pra branch principal. Isso deixa passar um --force inofensivo numa branch de feature sua, e barra só o que ameaça o time.

03 Tocar .env e segredos

Editar arquivos é outro evento: aqui o hook olha pra tool_input.file_path, não pra command. Barre a edição de segredos antes de acontecer:

# PreToolUse, matcher "Edit|Write"
file=$(jq -r '.tool_input.file_path')
case "$file" in
  *.env|*.pem|*id_rsa*|*credentials*)
    echo "trava: arquivo protegido ($file)" >&2; exit 2 ;;
esac
exit 0

Isso barra a criação e a edição — inclusive a "primeira vez" que alguém tentaria colar uma chave dentro de um .env versionado sem querer.

04 Editar arquivos protegidos, de forma geral

A mesma técnica do passo anterior generaliza: qualquer arquivo que você não quer que mude sem revisão vira uma entrada na lista — package-lock.json, .github/workflows/*, o próprio .claude/settings.json. O molde é sempre:

• Evento: PreToolUse.
• Matcher: Edit|Write (pega edição ou criação de arquivo).
• Checagem: comparar tool_input.file_path com a sua lista de protegidos.

Não existe lista perfeita de primeira. Comece pelos segredos (passo 03), depois adicione o que te morder — cada susto vira uma linha nova na trava.

01 Além do exit 2: JSON de decisão

Exit code é rápido, mas rústico: só barra ou não, e o motivo é um texto solto no stderr. Existe um segundo caminho — seu hook imprime um JSON de decisão no stdout, e sai com exit 0 mesmo quando está barrando:

{
  "decision": "approve" | "block",
  "reason": "string",
  "hookSpecificOutput": {
    "permissionDecision": "allow" | "deny" | "ask"
  }
}

Note a virada: no caminho do exit code, exit 2 É a decisão. No caminho JSON, exit 0 é quase sempre a resposta — quem decide é o conteúdo impresso no stdout.

02 permissionDecision: allow, ask, deny

Dentro de hookSpecificOutput, o campo permissionDecision tem três posturas — e um permissionDecisionReason pra explicar qual delas e por quê:

{ "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "push --force na main não é permitido por aqui" } }

• allow — libera, sem perguntar (útil pra baixar o atrito num caso que você já confia).
• deny — barra, equivalente ao exit 2, só que com motivo estruturado.
• ask — pausa e pede confirmação ao humano. Use quando o certo depende do contexto que só você tem.

03 fail-open: nunca trave por um bug seu

Um hook é só um script — e scripts quebram (o jq falha, uma variável vem vazia, uma sintaxe erra). A pergunta que importa: quando seu próprio hook tem um bug, o que deve acontecer? A resposta certa é fail-open: liberar e avisar, nunca travar o projeto inteiro por um erro que não é do usuário.

# logo no topo do script
set +e
trap 'exit 0' ERR
# … resto do hook …

O trap garante que, se algo dentro do script explodir, o hook ainda sai com exit 0 — o Claude segue trabalhando, e o bug fica pra você investigar depois, sem travar ninguém no meio do caminho. Fail-open não é desculpa pra escrever a trava com pouco cuidado — é uma rede de segurança para quando ela falhar de um jeito que você não previu.

04 Hook é poder: quoting, validar, não vazar segredo

Um hook roda com todas as suas permissões de usuário — não é uma sandbox. Trate-o como código de produção, com quatro regras de higiene:

• Quoting — sempre "$var" entre aspas; nunca reinterpole tool_input direto num shell novo.
• Valide caminhos — cheque que um file_path não sai do projeto (sem ../ escapando pra fora).
• Proteja segredos — .env, credenciais, .ssh, .git, chaves privadas nunca devem aparecer em log nenhum, nem no motivo impresso.
• Fail-open — como no passo anterior: bug seu não pode virar trava permanente.

Essas quatro regras cabem numa frase: um hook rápido, idempotente e sem vazar segredo — que fecha esta trilha e vira hábito daqui pra frente.