¿Qué son los hooks de Claude Code, y cuándo usarlos?

La idea central: automático, no recordado

Claude Code ya te deja guiar el comportamiento con instrucciones, en lugares como el CLAUDE.md o un system prompt — pero eso depende de que el modelo las lea y elija seguirlas en el momento correcto. Un hook elimina esa dependencia: es un comando que la propia aplicación ejecuta en un punto fijo, siempre, sin importar lo que el modelo recuerde o deje de recordar.

Esa es la propuesta en una frase: un hook convierte una sugerencia en garantía, porque quien decide si algo ocurre es el shell ejecutando un comando, no el modelo eligiendo obedecer.

Los eventos a los que un hook puede engancharse

Claude Code define más eventos que estos siete, incluyendo PreCompact, PostCompact, SubagentStart y SubagentStop, entre otros — pero estos son los que la mayoría de las configuraciones usa primero, porque corresponden a los momentos en que la gente realmente quiere intervenir.

• SessionStart — cuando una sesión empieza o se reanuda.
• UserPromptSubmit — cuando envías un prompt, antes de que Claude lo procese.
• PreToolUse — antes de que una llamada a herramienta se ejecute; es el único que puede bloquearla.
• PermissionRequest — cuando una llamada a herramienta necesita una decisión de permiso.
• PostToolUse — después de que una llamada a herramienta tiene éxito.
• Stop — cuando Claude termina de responder.
• SessionEnd — cuando una sesión termina.

Cómo se configura un hook

Un hook es JSON escrito en un archivo de settings, con tres niveles de anidamiento: una clave hooks, luego el nombre del evento, luego un array de entradas — cada una con un matcher y su propia lista de { type: "command", command, timeout }.

El archivo de settings puede vivir en más de un lugar. ~/.claude/settings.json aplica a todos los proyectos de la máquina y no está pensado para compartirse. .claude/settings.json aplica a un proyecto y está pensado para subirse a git. .claude/settings.local.json también aplica a un proyecto, pero queda fuera de git (gitignored). Además de estos, una organización puede publicar managed policy settings, y un plugin puede traer su propio hooks/hooks.json.

El matcher decide a qué llamadas de herramienta se aplica una entrada. “*”, o dejar el matcher fuera, coincide con todo. Un matcher formado solo por letras, dígitos, _, -, espacios, comas o | — como “Bash” o “Edit|Write” — se compara como string exacto. Cualquier otro carácter convierte todo el matcher en una expresión regular de JavaScript sin anclar, y por eso algo como “^Edit$” se comporta distinto de un simple “Edit”.

Bloqueo, salida estructurada, y quién puede apagar un hook

Un hook controla lo que pasa después principalmente por su código de salida. Exit code 0 sin ninguna salida significa que el hook no tiene decisión que reportar, y la llamada a herramienta sigue el flujo normal de permisos. Exit code 2 es el error bloqueante: en eventos que pueden bloquear, el exit 2 bloquea la acción aunque el hook también haya impreso JSON — ni un permissionDecision de “allow” en JSON puede anularlo. Cualquier otro código es un error no bloqueante en la mayoría de los eventos, y la acción sigue adelante de todos modos.

Un hook también puede devolver JSON estructurado en lugar de depender solo del código de salida: un objeto hookSpecificOutput lleva el nombre del evento, un permissionDecision de allow, deny o escalate, y el motivo, además de campos universales como continue (que, si es false, hace que Claude deje de procesar), stopReason y systemMessage.

Los hooks pueden apagarse por completo con disableAllHooks: true en los settings — excepto los hooks configurados por las managed policy settings de una organización, que los settings de usuario, proyecto o local no pueden apagar. Un administrador puede ir más allá con allowManagedHooksOnly, restringiendo qué hooks tienen permiso de ejecutarse.