HOOK COOKBOOK

Quando — você confia no Claude pra rodar Bash, mas nunca quer ver rm -rf, git push --force, ou instalação de dependência sem lockfile. Bloqueia esses por forma, não por negação global.

▸ Script — .claude/hooks/pre-bash.sh

#!/usr/bin/env bash
set -euo pipefail
cmd=$(jq -r '.tool_input.command')
block() { echo "blocked: $1" >&2; exit 2; }
[[ "$cmd" =~ rm[[:space:]]+-[rRf]+ ]] && block "rm -rf is denied"
[[ "$cmd" =~ git[[:space:]]+push.*--force ]] && block "force push is denied"
[[ "$cmd" =~ (npm|pnpm|bun)[[:space:]]+(i|install) ]] && {
  [[ -f package-lock.json || -f pnpm-lock.yaml || -f bun.lock ]] ||     block "install without lockfile in tree"
}
exit 0

▸ Configuração

{ "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": "bash .claude/hooks/pre-bash.sh"
      }]
    }]
} }

Pegadinha — matcher: "Bash" no nível do array limita o hook a chamadas Bash. Sem isso, o hook dispara em toda chamada de tool e seu jq query falha em payload com forma errada.

Quando — você sempre acaba com sub-agents under-specificados que inventam o próprio framing. Impõe um handoff estruturado: TASK / CONTEXT / CONSTRAINTS / DELIVERABLE / DONE_WHEN.

▸ Script — .claude/hooks/pre-agent.sh

#!/usr/bin/env bash
set -euo pipefail
prompt=$(jq -r '.tool_input.prompt')
required=(TASK CONTEXT CONSTRAINTS)
outcome=0
for f in "${required[@]}"; do
  echo "$prompt" | grep -qiE "^[[:space:]]*$f:" || { missing+=" $f"; outcome=1; }
done
echo "$prompt" | grep -qiE "^[[:space:]]*(DELIVERABLE|DONE_WHEN):" || outcome=1

[[ $outcome -eq 0 ]] && exit 0
cat >&2 <<MSG
delegation-gate: missing fields$missing (and/or DELIVERABLE/DONE_WHEN).
Use 5-field handoff:
  TASK:        <one sentence>
  CONTEXT:     <files/paths>
  CONSTRAINTS: <what NOT to do>
  DELIVERABLE: <artifact> | DONE_WHEN: <verifier>
MSG
exit 2

Pegadinha — match case-insensitive (-i) é proposital; agents escrevem Task:, TASK:, task: indiferentemente. Ancorar no início da linha (^) evita match em "task list" dentro da prosa.

Quando — você quer consistência de format sem prettier --write manual depois de cada edit. O hook roda --check e mostra violações pro agent no próximo turno.

▸ Script — .claude/hooks/post-edit-prettier.sh

#!/usr/bin/env bash
set -euo pipefail
file=$(jq -r '.tool_input.file_path // .tool_input.path // empty')
[[ -z "$file" ]] && exit 0
[[ "$file" =~ \.(ts|tsx|js|jsx|json|md|css)$ ]] || exit 0
out=$(npx -y prettier --check "$file" 2>&1) && exit 0
echo "prettier-advisory: $file is not formatted" >&2
echo "$out" >&2
exit 0  # advisory: log, do not block

Pegadinha — o matcher "Edit|Write|MultiEdit" usa alternação regex. Nomes de campos de payload diferem: Edit/MultiEdit usam file_path; Write usa file_path; algumas tools legadas usaram path. O fallback // empty no jq cobre todas as formas.