01 Qué es un bloqueo

Un bloqueo es un hook de PreToolUse: lo ejecuta antes de la herramienta y decide si puede continuar. La señal es el código de salida:

• exit 0 — está bien, puede ejecutarse.
• exit 2 — bloquea. Claude no lo ejecuta, y lo que imprimiste en el stderr se convierte en el motivo.

Observa la diferencia: el bloqueo no «avisa después», sino que impide antes. Es la diferencia entre un extintor y un informe de incendio. En las próximas clases vas a enseñar a esta barrera a leer el comando, cubrir los casos que realmente duelen y decir allow/ask/deny — pero la base es solo esto: exit 0 continúa, exit 2 bloquea.

02 El motivo vuelve a Claude

Cuando el bloqueo detiene la acción, Claude no se queda a oscuras: todo lo que tu script imprime en el stderr antes del exit 2 se convierte en el motivo que él lee. Es tu única oportunidad de explicar por qué: escríbele a él, no a ti:

# mal: no dice nada útil
exit 2

# bien: Claude sabe exactamente qué evitar la próxima vez
echo "trava: rm -rf apaga tudo sem confirmação — use um caminho específico" >&2
exit 2

Piensa en el mensaje como una instrucción breve para que Claude vuelva a intentarlo de la manera correcta, no como un registro de error genérico. «bloqueado» dice poco; «bloqueado: usa rm arquivo.txt, no rm -rf pasta/" enseña.

03 Un ejemplo mínimo: bloquear rm -rf

Une las dos piezas — leer el comando (más sobre esto en la próxima clase) y decidir con el código de salida — y ya tienes un bloqueo de verdad:

# .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

Lee de adentro hacia afuera: toma el command de stdin, busca el patrón rm -rf; si lo encuentra, imprime el motivo y bloquea; si no lo encuentra, el exit 0 al final deja continuar. Es breve y ya resuelve el accidente más clásico.

04 exit 0 libera

Todo comando que no coincide con el patrón peligroso debe continuar normalmente — y quien lo garantiza es un exit 0 explícito al final del script. Sin él, el código de salida del último comando ejecutado (el grep, por ejemplo) puede filtrarse y confundir a Claude Code.

• Termina siempre con exit 0 después del bloque de verificación — aunque parezca obvio.
• Un bloqueo que solo reacciona ante un patrón y deja pasar todo lo demás es el comportamiento correcto: quieres bloquear el peligroso, no el resto del trabajo.

Con esto, el ciclo se cierra: leer el comando → comparar con el patrón → exit 2 (bloquea, con motivo) o exit 0 (continúa). Es el bloqueo más simple que existe y ya es real: Claude no puede simplemente «decidir ignorarlo».

01 El comando llega a tool_input.command

Antes de ejecutarse, Claude le entrega a tu hook un JSON por la entrada estándar (stdin) con el contexto del momento. Algunos campos están siempre presentes (session_id, cwd, hook_event_name); en el PreToolUse, también vienen tool_name e o tool_input:

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

Ten en cuenta: como la herramienta aún no se ejecutó, no existe tool_response en ese momento — solo el intención. Es exactamente esa intención la que tu barrera examina antes de dejar que se convierta (o no) en una acción.

02 Extraer con jq -r

Para extraer el texto sin formato del JSON, usa jq. La diferencia entre usar -r o no es lo que separa un valor utilizable de uno lleno de comillas:

# sin -r: devuelve el valor codificado en JSON, con comillas
$ jq '.tool_input.command'
"rm -rf build/"

# con -r (raw): devuelve el texto sin procesar, listo para comparar
$ jq -r '.tool_input.command'
rm -rf build/

Sin -r, las comillas siguen pegadas al valor y dificultan cualquier comparación de texto. Adopta este hábito: en un hook de shell, jq -r casi siempre es lo que quieres.

03 Coincidir con patrones peligrosos (grep/case)

Con el texto en mano, comparar con varios varios patrones de una sola vez es algo habitual. Dos formas equivalentes: elige la que se lea mejor en tu script:

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

# con case (más legible cuando la lista crece)
case "$cmd" in
  *"rm -rf"*|*"push --force"*) echo "trava: padrão perigoso" >&2; exit 2 ;;
esac
exit 0

grep -E es más corto para pocos patrones; case se vuelve más legible cuando la lista de patrones crece y cada uno merece un comentario. Ambas hacen lo mismo: coincidir el comando con una lista de lo que es peligroso.

04 Falso positivo y comillas: cuidado con el escape

Leer bien el comando tiene dos trampas comunes:

• Falso positivo — un grep demasiado amplio también captura cosas inocentes (p. ej.: rm -rf dentro de un comentario o de una cadena). Prefiere patrones específicos en lugar de una palabra suelta.
• Nunca vuelvas a interpolar el comando en un shell nuevo — obtener $cmd y devolverlo en un eval o en otro bash -c "$cmd" abre la puerta a inyección de comandos. Tu bloqueo solo debe leer y comparar el texto, nunca volver a ejecutarlo.

Siempre usa "$cmd" entre comillas dobles al manipular la variable (evita que los espacios rompan la comparación), y trata el valor como dato, no como código para ejecutar.

01 rm -rf y rutas fuera del proyecto

El peligro real no es la frase "rm -rf" por sí sola: es el objetivo. Una rm -rf dentro de la carpeta build/ del proyecto es difícil de recuperar; un rm -rf /, rm -rf ~ o rm -rf .. es catastrófico. Bloquea objetivos amplios, no la sintaxis:

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

Vale la pena hacer una verificación adicional: comparar la ruta con $CLAUDE_PROJECT_DIR (la raíz del proyecto) garantiza que el objetivo del comando no salga de la carpeta que realmente estás dispuesto a arriesgar.

02 push/force en la rama principal

git push --force reescribe el historial remoto, si es en la main o master, el daño afecta a todo el equipo. Bloquea la combinación específica (forzado + rama protegida), no solo el forzado por separado:

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

Fíjate en las dos condiciones combinadas: necesita tener fuerza e apuntar a la rama principal. Eso deja pasar un --force inofensivo en una rama de feature tuya, y bloquea solo lo que amenaza al equipo.

03 Tocar .env y secretos

Editar archivos es otro evento: aquí el hook revisa tool_input.file_path, no para command. Bloquea la edición de secretos antes de que ocurra:

# 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

Esto bloquea la creación y la edición, incluso la «primera vez» que alguien intentaría pegar una clave dentro de un .env versionado sin querer.

04 Editar archivos protegidos en general

La misma técnica del paso anterior se generaliza: cualquier archivo que no quieras que cambie sin revisión se convierte en una entrada de la lista — package-lock.json, .github/workflows/*, el propio .claude/settings.json. La plantilla siempre es:

• Evento: PreToolUse.
• Matcher: Edit|Write (captura la edición o creación de archivos).
• Verificación: comparar tool_input.file_path con tu lista de elementos protegidos.

No existe una lista perfecta desde el principio. Empieza por los secretos (paso 03) y luego agrega lo que te dé problemas: cada susto se convierte en una línea nueva del bloqueo.

01 Además del exit code: decisión en JSON

Exit code es rápido, pero rudimentario: solo bloquea o no, y el motivo es un texto suelto en stderr. Existe una segunda opción: tu hook imprime un JSON de decisión en el stdout, y termina con exit 0 incluso cuando está bloqueando:

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

Fíjate en el cambio: en la ruta del código de salida, exit 2 Es la decisión. En la ruta JSON, exit 0 casi siempre es la respuesta: lo que decide es el contenido impreso en stdout.

02 permissionDecision: allow, ask, deny

Dentro de hookSpecificOutput, el campo permissionDecision tiene tres posturas y un permissionDecisionReason para explicar cuál de ellas y por qué:

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

• allow — permite continuar sin preguntar (útil para reducir la fricción en un caso en el que ya confías).
• deny — bloquea, equivalente a exit 2, pero con un motivo estructurado.
• ask — pausa y pide confirmación a la persona. Úsalo cuando lo correcto dependa de un contexto que solo tú tienes.

03 fail-open: nunca te bloquees por un error tuyo

Un hook es solo un script, y los scripts fallan (el jq falla, una variable queda vacía, hay un error de sintaxis). La pregunta que importa: cuando tu propio hook tiene un bug, ¿qué debería pasar? La respuesta correcta es fail-open: permitir y avisar, nunca bloquear todo el proyecto por un error que no es del usuario.

# justo al inicio del script
set +e
trap 'exit 0' ERR
# … resto del hook …

O trap garantiza que, si algo dentro del script falla, el hook igual termina con exit 0 — Claude sigue trabajando y el error queda para que lo investigues después, sin detener a nadie a mitad del proceso. Fail-open no es una excusa para escribir la barrera con poco cuidado: es una red de seguridad para cuando falle de una manera que no habías previsto.

04 Un hook es poder: quoting, validar, no filtrar secretos

Un hook se ejecuta con todos tus permisos de usuario — no es un entorno aislado. Trátalo como código de producción, con cuatro reglas de higiene:

• Quoting — siempre "$var" entre comillas; nunca vuelvas a interpolar tool_input directamente en un shell nuevo.
• Valida las rutas — verifica que un file_path no sale del proyecto (sin ../ escapando hacia afuera).
• Protege los secretos — .env, credenciales, .ssh, .git, las claves privadas nunca deben aparecer en ningún registro, ni en el motivo impreso.
• Fail-open — como en el paso anterior: un error tuyo no puede convertirse en un bloqueo permanente.

Estas cuatro reglas caben en una frase: un hook rápido, idempotente y que no filtre secretos, que cierra esta ruta y se convierte en hábito de aquí en adelante.