01 settings.json en Git

Hasta aquí, todos los hooks que configuraste vivían en tu máquina. Pero el .claude/settings.json es un archivo normal, dentro de la carpeta del proyecto —y un archivo normal puede ir a Git.

Cuando se versiona (se confirma con commit, con git add), deja de ser "el hook de Nei" y se convierte en el hook del proyecto. Empieza a viajar junto con el código, en el mismo commit que el bloqueo o el formateador que protege.

02 Todo el equipo hereda las mismas reglas

Con el settings.json versionado, el efecto es automático: quien clona el repositorio o ejecuta git pull, recibe el archivo — y Claude Code lee los mismos hooks. Sin pedirle a nadie que instale nada ni pegar instrucciones en ningún README.

Esto cambia el criterio para decidir qué vale la pena automatizar. Un formateador o un bloqueo de seguridad que solo tienes tú te protege solo a ti. El mismo hook, versionado, protege todas las personas que toquen el código — incluso a quienes todavía no se han unido al equipo.

03 settings.local.json: fuera de Git

No todo es del equipo. Secretos, atajos personales, una ruta que solo existe en tu máquina: eso no debería viajar al repositorio. Para eso existe el settings.local.json: el mismo formato, la misma carpeta .claude/, pero aparece en la lista de .gitignore.

# queda fuera del repositorio
echo ".claude/settings.local.json" >> .gitignore

Regla práctica: si un hook debería aplicarse a cualquier persona que, al abrir este proyecto, irá al settings.json. Si es una preferencia tuya — o contiene algo sensible — va en el .local.json.

04 Precedencia: user → project → local

Ahora tienes hasta tres archivos vigentes al mismo tiempo: el global (~/.claude/settings.json, todos tus proyectos), el de proyecto (.claude/settings.json, versionado) y el local (.claude/settings.local.json, solo tuyo, solo aquí).

En caso de conflicto, gana el más específico: la configuración local prevalece sobre la del proyecto, que prevalece sobre la global. Piénsalo así: la global es la regla general de tu casa; la del proyecto es la regla del edificio; la local es la nota adhesiva en tu puerta, y esa es la que prevalece.

01 Idempotencia: ejecutarlo dos veces produce el mismo

Un hook es un comando común, y los comandos comunes no «encuentran» nada: es idempotente: ejecutar la misma entrada dos veces debe dar el mismo resultado, sin que nada falle la segunda vez.

Ejemplo práctico: un hook que formatea un archivo puede ejecutarse diez veces seguidas; el archivo formateado, aunque se vuelva a formatear, sigue igual. En cambio, un hook que suma algo en cada ejecución (como incrementar un contador sin comprobar si ya se ejecutó) no es idempotente — y ahí es donde viven los errores sutiles de automatización.

02 Tiempos de espera: el campo timeout

Un hook se interpone en cada acción; si se bloquea, todo se bloquea juntos. Por eso cada hook tiene un timeout, en segundos:

{ "hooks": { "PreToolUse": [ {
  "matcher": "Bash",
  "hooks": [ { "type": "command", "command": "./guarda.sh",
    "timeout": 10 } ]
} ] } }

Si no defines timeout, el patrón de un hook de comando es 600 segundos (10 minutos) — demasiado generoso para un bloqueo. Un hook rápido ni se acerca; pero un hook que hace una llamada de red sin cuidado puede dejar tu sesión colgada hasta que se agote el tiempo. Por eso conviene definir un límite corto (p. ej.: 10) en los hooks que intervienen en cada acción.

03 Probar de forma aislada: stdin falso

No necesitas Claude Code de verdad para saber si un hook funciona. Todos los hooks leen el mismo stdin — entonces simulas ese JSON a mano y se lo pasas directamente al hook:

# prueba aislada — sin abrir Claude Code
echo '{"tool_name":"Bash","tool_input":{"command":"ls -la"}}' \
  | bash .claude/hooks/guarda.sh
echo "Exit: $?"

Esto vale oro: ves exactamente lo que haría el hook, en tu terminal, en segundos, sin esperar una sesión entera solo para descubrir que olvidaste una comilla.

04 Fail-open + registrar para depurar

Un hook que falla por un error que no previste no debería bloquear todo tu trabajo. La regla es fallar de forma abierta: captura el error y deja que continúe.

# captura cualquier error inesperado y permite continuar
set +e
trap 'exit 0' ERR
# ... lógica del hook ...

Y para depurar cuando algo sale mal, ejecútalo con -x (muestra cada línea ejecutada) y alimenta un archivo con el JSON de prueba:

bash -x .claude/hooks/guarda.sh < entrada.json
echo "Exit: $?"

01 Modo headless: claude -p

Claude Code también se ejecuta sin ninguna interfaz: el modo headless, activado por un script: claude -p "seu comando aqui". Lee el prompt, trabaja, responde y termina. Nada de pantalla ni de que tú tengas que mirar.

Este es el modo que se usa en un script de deploy, en un cron o dentro de un pipeline. Y justamente ahí los hooks demuestran su valor.

02 Hooks en CI/pipeline

Si el settings.json está versionado (Lección 1), se aplica en cualquier lugar que ejecute Claude Code, incluso dentro de un runner de CI, sin nadie conectado y sin ninguna pantalla.

El bloqueo que impide rm -rf, el formateador que corrige el código, el registro que anota los comandos: todo eso sigue activo. El mismo patrón que te protege en el día a día protege al robot también.

03 Exit codes y falta de interactividad

Sin nadie en pantalla, el hook no puede detenerse para preguntar. Los hooks no son interactivos: no esperes que una persona escriba «sí» a mitad de la ejecución. Todo se resuelve mediante PreToolUse y por el código de salida:

• exit 0 — continúa con normalidad.
• exit 2 — bloquea (solo aplica en PreToolUse e Stop); o stderr se convierte en el motivo.
• exit 1, 3+ — un error no bloqueante; Claude continúa (fail-open).

En CI esto es aún más importante: si un hook intentara «preguntar», el pipeline se quedaría bloqueado para siempre esperando una respuesta que nunca llega.

04 SubagentStop: cuando termina un subagente

Existe un evento parecido a Stop, pero para un nivel inferior: SubagentStop se activa cuando un subagente termina su propio turno; no el del agente principal, sino el de una tarea delegada.

Diferencias importantes: SubagentStop no bloquea (a diferencia de Stop, que acepta exit 2), y no usa matcher. Trátalo como un aviso («esta parte terminó»), no como un bloqueo — y no construyas lógica crítica basándote solo en él, ya que su comportamiento puede llegar incompleto.

01 Los hooks se ejecutan con TODOS tus poderes

Un hook no es un sandbox ni un script «de juguete»; se ejecuta con los los mismos permisos que tu usuario: el mismo shell, las mismas credenciales, el mismo acceso a la red que tienes al abrir la terminal.

Esto no es un defecto, es la razón por la que funcionan los hooks: para formatear un archivo o bloquear un rm -rf, el hook debe poder interactuar con el sistema de verdad. Pero ese mismo poder que protege también puede, si está mal escrito, estropear — entonces trata el hook con el respeto que merece un script de acceso total.

02 Nunca confíes en el input

O tool_input que llega a tu hook proviene de un contexto que no controlas por completo. Poner ese valor directamente dentro de un comando shell es la puerta de entrada clásica para inyección de shell:

# peligroso: interpola directamente en el shell
cmd=$(jq -r '.tool_input.command')
eval "$cmd"  ← NO hagas esto

# mejor: trátalo como dato, valídalo antes de actuar
cmd=$(jq -r '.tool_input.command')
echo "$cmd" | grep -qE 'rm -rf|:\(\)\{' && { echo "bloqueado" >&2; exit 2; }
exit 0

El mismo cuidado se aplica a las rutas de archivos: siempre valida (sin ../ saliendo de la carpeta del proyecto) antes de leer o escribir: path traversal es el mismo problema, pero con archivos en vez de comandos. Y protege a propósito lo que es sensible: .env, .ssh, .git, claves privadas.

03 PreCompact y limpieza del estado

Existe un evento llamado PreCompact, vinculado al momento en que se compacta el contexto de la conversación. La idea es darte una oportunidad para guardar o limpiar el estado antes de que ocurra.

Pero es uno de los eventos menos documentados oficialmente — no des por sentadas garantías sólidas sobre exactamente cuándo o cómo se activa. En la práctica: úsalo para cosas no críticas (un registro, una copia de seguridad), siempre teniendo el mismo cuidado de fallar de forma abierta, y nunca apuestes la seguridad del proyecto solo a eso.

04 Lista final de seguridad

Antes de considerar que un hook está «listo para el equipo», revisa esta lista:

• Rápido — no bloquea el flujo; tiene timeout definido.
• Idempotente — ejecutarlo dos veces no rompe nada.
• Nunca confía en el input — sin eval de cadena sin procesar, rutas validadas.
• Protege lo sensible — .env, .ssh, .git, claves fuera del alcance de un hook mal escrito.
• Sin secretos en el comando — nada de escribir el token o la contraseña directamente en settings.json (está en una variable de entorno o en un archivo).
• Fallar en modo abierto — un error inesperado se convierte en exit 0 con registro, no bloquea a Claude.

Empieza poco a poco y refuerza las medidas con el tiempo. El hook que sobrevive en tu equipo es el que nadie nota, porque nunca estorba y siempre protege.