Una línea en CLAUDE.md dice: no edites nunca .env. El modelo la lee, está de acuerdo y, tres llamadas a herramientas después, escribe un fixture de prueba en .env porque parecía el camino más corto. Las instrucciones influyen en un modelo. No lo restringen.
Claude Code tiene dos mecanismos que sí lo restringen. Las reglas de permisos deciden si una herramienta puede ejecutarse siquiera. Los hooks ejecutan tus propios comandos de shell en puntos del ciclo de vida y pueden bloquear una llamada antes de que ocurra. Este tutorial crea un pequeño hook PreToolUse que rechaza escrituras en secretos y unos cuantos comandos de shell destructivos, y después lo prueba sin involucrar al modelo.
Los ejemplos usan el contrato de hooks documentado de Claude Code: el hook recibe JSON por la entrada estándar, y el código de salida 2 bloquea la llamada a la herramienta y envía de vuelta a Claude el mensaje escrito en la salida de error estándar.
Paso 1 — escribe un guarda que lea JSON
Crea .claude/hooks/guard.sh. Lee tool_name y el campo correspondiente de tool_input: file_path para Edit y Write, command para Bash.
#!/usr/bin/env bash
set -euo pipefail
input=$(cat)
tool=$(printf '%s' "$input" | jq -r '.tool_name // empty')
path=$(printf '%s' "$input" | jq -r '.tool_input.file_path // empty')
command=$(printf '%s' "$input" | jq -r '.tool_input.command // empty')
block() {
printf 'blocked (%s): %s\n' "$tool" "$1" >&2
exit 2
}
case "$path" in
*.env|*/.env|*/.env.*|*/.git/*|*/node_modules/*)
block "protected path: $path" ;;
esac
case "$command" in
*"git push --force"*|*"git push -f"*|*"rm -rf /"*|*"| sh"*|*"| bash"*)
block "dangerous command: $command" ;;
esac
exit 0Hazlo ejecutable con chmod +x .claude/hooks/guard.sh. El script necesita jq; instálalo con tu gestor de paquetes si falta el comando.
Dos detalles importan. Primero, un código de salida 2 es la señal de bloqueo. Cualquier otro código de salida distinto de cero se notifica como error, pero no bloquea la llamada. Segundo, el mensaje va a la salida de error estándar, que es como Claude se entera de por qué falló la acción.
Paso 2 — regístralo para Bash, Edit y Write
Añade el hook a .claude/settings.json para que viaje con el repositorio. Usa ~/.claude/settings.json solo para guardas personales que no quieras compartir.
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash|Edit|Write",
"hooks": [
{
"type": "command",
"command": "$CLAUDE_PROJECT_DIR/.claude/hooks/guard.sh"
}
]
}
]
}
}El matcher selecciona nombres de herramientas. Bash|Edit|Write cubre las tres rutas que entiende este guarda. Si usas otra herramienta de edición o un servidor MCP con acceso de escritura, añádelo deliberadamente en lugar de ampliar el matcher a todo.
Dentro de una sesión, /hooks abre una vista de solo lectura de lo que está cargado. Edita el archivo JSON para cambiarlo; no esperes que el menú sea un editor.
Paso 3 — prueba el script sin el agente
Los hooks fallan en abierto de la peor manera: una errata puede hacer que el guarda termine con código 0 para todo. Prueba el contrato directamente antes de confiar en él.
printf '%s' '{"tool_name":"Write","tool_input":{"file_path":".env"}}' \
| .claude/hooks/guard.sh
echo "exit=$?" # se espera 2
printf '%s' '{"tool_name":"Bash","tool_input":{"command":"git status"}}' \
| .claude/hooks/guard.sh
echo "exit=$?" # se espera 0Ejecuta la misma comprobación para un force push y para un npm test seguro. Si el caso del archivo de entorno termina con 0, probablemente el nombre del campo JSON sea incorrecto. Imprime los valores parseados mientras depuras, pero elimina la salida de depuración antes de hacer commit: el hook recibe rutas de archivos y comandos que pueden contener datos sensibles.
Paso 4 — verifícalo dentro de una sesión
Pide a Claude que añada una línea a .env. La escritura debería rechazarse, y Claude debería ver el motivo en la salida de error estándar. Después, pídele que ejecute git status; eso debería continuar con normalidad. Prueba un force push solo en un repositorio desechable.
Si el hook no se dispara, comprueba tres cosas: que el archivo de configuración esté en la raíz del proyecto, que el matcher coincida exactamente con el nombre de la herramienta y que la ruta del comando se resuelva. $CLAUDE_PROJECT_DIR evita depender del directorio de trabajo actual.
Paso 5 — combínalo con reglas de permisos
Los hooks son una capa. Las reglas de permisos son otra. Claude Code evalúa las reglas de denegación antes que las de preguntar y permitir, así que una regla de denegación es el lugar adecuado para un límite estricto como Bash(rm *) o una herramienta que nunca quieras tener disponible. Los hooks son mejores para comprobaciones que dependen del contexto: esta ruta, este patrón de comando, este repositorio.
Usa ambos. Una regla de denegación elimina una capacidad. Un hook explica una política y puede inspeccionar argumentos que una regla estática no puede expresar.
Lo que los hooks no resuelven
Un hook se ejecuta como tu usuario, con tus credenciales. Es ejecución de código, no un sandbox. Cualquiera que pueda editar .claude/settings.json puede desactivarlo. Para aplicar normas en toda la organización, distribuye hooks y reglas de permisos mediante ajustes gestionados en lugar de confiar en cada repositorio.
El guarda también necesita mantenimiento. Las nuevas estructuras de archivos, los nuevos gestores de paquetes y las nuevas herramientas crean nuevas rutas. Revisa los patrones cuando añadas un conector o un flujo de trabajo, y mantén una prueba para cada regla que proteja algo irreversible. El objetivo no es una lista perfecta de cadenas malas. Es un punto de control determinista que falla cerrado para las pocas acciones que no puedes deshacer.