HOOK COOKBOOK

Cuándo — confías en Claude para ejecutar Bash, pero nunca quieres ver rm -rf, git push --force, o instalación de dependencia sin lockfile. Bloquea esos por forma, no por negación 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

▸ Configuración

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

Trampa — matcher: "Bash" a nivel de array limita el hook a llamadas Bash. Sin esto, el hook dispara en cada llamada a tool y tu query jq falla en un payload con forma equivocada.

Cuándo — sigues recibiendo sub-agents subespecificados que se inventan su propio framing. Impón un handoff estructurado: 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

Trampa — match case-insensitive (-i) es a propósito; los agents escriben Task:, TASK:, task: indistintamente. Anclar al inicio de línea (^) evita match en "task list" dentro de la prosa.

Cuándo — quieres consistencia de formato sin prettier --write manual después de cada edit. El hook ejecuta --check y muestra violaciones al agent en su 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

Trampa — el matcher "Edit|Write|MultiEdit" usa alternación regex. Los nombres de campos del payload difieren: Edit/MultiEdit usan file_path; Write usa file_path; algunas tools legacy usaron path. El fallback // empty en jq cubre todas las formas.