Un hook de Claude Code es una regla que se ejecuta siempre en un momento concreto del ciclo de trabajo del asistente: antes de usar una herramienta, después de editar un archivo o al terminar de responder. A diferencia de una instrucción en CLAUDE.md, que el modelo puede pasar por alto, un hook es código tuyo que corre sí o sí. Esta guía explica cómo configurarlos y trae dos ejemplos de la documentación oficial.
Nota de versión: el registro de cambios de GitHub indica que en la versión 2.1.326 la decisión "block" de un hook se respeta en más casos. Esa página no muestra fecha para esa versión, así que no la fechamos aquí.
Qué es un hook y por qué importa
La documentación oficial los describe como comandos de shell, endpoints HTTP, llamadas a herramientas MCP, prompts de LLM o subagentes que se ejecutan automáticamente en puntos del ciclo de vida. Lo que ofrecen es lo que la guía llama «deterministic control»: ciertas acciones ocurren siempre, sin depender de que el modelo decida hacerlas.
Casos típicos: impedir que se toquen archivos sensibles, bloquear comandos destructivos, formatear el código tras cada edición, avisarte cuando Claude necesita atención o inyectar contexto al iniciar una sesión.
Dónde se configuran
Los hooks viven en un objeto hooks dentro de un archivo de ajustes JSON. La estructura tiene tres niveles: evento, grupo de matcher y manejador. Según la documentación, las entradas se combinan entre niveles en vez de reemplazarse.
| Ubicación | Alcance | ¿Se comparte? |
|---|---|---|
~/.claude/settings.json | Todos tus proyectos | No |
.claude/settings.json | Un proyecto | Sí, se puede subir al repositorio |
.claude/settings.local.json | Un proyecto | No, queda fuera de git |
| Ajustes administrados | Toda la organización | Sí, los controla el administrador |
hooks/hooks.json de un plugin | Mientras el plugin esté activo | Sí |
Para ver qué hooks tienes activos y de dónde vienen, escribe /hooks en el prompt de Claude Code: abre un explorador de hooks. Para quitar uno, borra su entrada del archivo de ajustes.
Eventos y matchers
La referencia lista decenas de eventos. Los que más se usan son PreToolUse (antes de ejecutar una herramienta, y puede bloquearla), PostToolUse (después de que la herramienta tuvo éxito), UserPromptSubmit, SessionStart, Notification y Stop (cuando Claude termina de responder).
El matcher filtra por nombre de herramienta. Reglas principales según la documentación:
- Un asterisco, una cadena vacía o ningún matcher coinciden con todo.
- Si solo usas letras, números, guiones bajos, espacios, comas o barras verticales, se compara el nombre exacto o una lista, por ejemplo
Edit|Write. - Con cualquier otro carácter se interpreta como expresión regular de JavaScript sin anclar:
Edit.*también coincide conNotebookEdit; para evitarlo usa^Edit$. - Distingue mayúsculas y minúsculas. Las herramientas MCP se llaman
mcp__servidor__herramienta, así que para todas las de un servidor usamcp__memory__.*.
Además, un manejador puede llevar un campo if con sintaxis de reglas de permisos, como Bash(rm *), para filtrar todavía más. Solo funciona en eventos de herramientas como PreToolUse y PostToolUse.
Qué recibe el hook y cómo responde
El hook recibe por la entrada estándar un JSON con el evento. Para un PreToolUse sobre Bash se ve así:
{
"session_id": "abc123",
"cwd": "/Users/sarah/myproject",
"hook_event_name": "PreToolUse",
"tool_name": "Bash",
"tool_input": {
"command": "npm test"
}
}
Para responder tienes dos vías, y la guía recomienda elegir una por hook:
| Vía | Cómo funciona |
|---|---|
| Código de salida | exit 0: sin decisión, sigue el flujo normal de permisos (no aprueba la acción). exit 2: bloquea y lo que escribas en stderr llega a Claude como retroalimentación. Otros códigos normalmente no bloquean. |
| JSON con salida 0 | Un objeto hookSpecificOutput con permissionDecision (allow, deny, ask o defer) y un motivo. |
Si varios hooks coinciden, todos corren en paralelo y gana la decisión más restrictiva. La documentación también recuerda que exit 2 bloquea aunque el JSON permitiera la acción.
Paso a paso: bloquear comandos peligrosos
Este ejemplo sale de la referencia oficial. Primero el script, guardado como .claude/hooks/block-rm.sh (requiere jq instalado):
#!/bin/bash
# .claude/hooks/block-rm.sh
COMMAND=$(jq -r '.tool_input.command')
if echo "$COMMAND" | grep -q 'rm -rf'; then
jq -n '{
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Destructive command blocked by hook"
}
}'
else
exit 0 # no decision; normal permission flow applies
fi
Después lo registras en .claude/settings.json. Recuerda darle permisos de ejecución al script con chmod +x:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"if": "Bash(rm *)",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh",
"args": []
}
]
}
]
}
}
La guía oficial muestra además una variante con exit 2: el script lee el comando, y si contiene «drop table» escribe un aviso en stderr y termina con código 2.
Paso a paso: formatear el código tras cada edición
Otro ejemplo de la guía oficial usa PostToolUse para ejecutar Prettier sobre el archivo que Claude acaba de editar o escribir:
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
}
]
}
]
}
}
Cuando funciona, Claude Code no muestra nada en la conversación. Ojo: este hook no cubre archivos reescritos desde comandos Bash; para eso la guía apunta al evento FileChanged.
Tipos de hook
Además de command, la referencia menciona http (envía el evento a una URL), mcp_tool (llama a una herramienta MCP), prompt (una evaluación de un LLM que devuelve sí o no) y agent (un subagente con herramientas, marcado como experimental). Para empezar, command es suficiente.
Seguridad y buenas prácticas
- Un hook es un comando que se ejecuta con tu entorno: revisa siempre el código de hooks que vengan de un repositorio o plugin ajeno.
- Mantén el matcher lo más estrecho posible. La guía advierte que un matcher vacío o
.*en un hook de permisos aprobaría todos los avisos de permiso. - No dependas de que el
denyde un hook evite los efectos secundarios de otro: corren en paralelo. - Un hook con
ifes un filtro de mejor esfuerzo; para reglas duras usa el sistema de permisos y, si quieres un límite más fuerte para Bash, mira el sandbox de Claude Code. - Los administradores pueden restringir hooks con
allowManagedHooksOnlyen los ajustes administrados.
Qué significa para quien programa
Los hooks convierten reglas de equipo en comportamiento automático: nada de .env, nada de rm -rf, formato siempre aplicado. Empieza con uno solo, el de formateo, pruébalo con /hooks y añade los bloqueos cuando lo tengas claro. Si ya usas Code Mode u otras funciones experimentales, revisa que tus hooks sigan comportándose igual tras cada actualización.
Preguntas frecuentes
¿Un hook puede aprobar una acción por sí solo?
Con exit 0 no: significa que no hay decisión y sigue el flujo normal. Con permissionDecision: "allow" sí aprueba, pero igualmente se respetan las reglas de denegación y consulta.
¿Dónde pongo el hook si quiero compartirlo con el equipo?
En .claude/settings.json del proyecto, que se puede subir al repositorio. Para uso personal, usa ~/.claude/settings.json o .claude/settings.local.json.
¿Cómo sé si mi hook se está ejecutando?
Escribe /hooks para ver los hooks configurados y su origen. Si un PostToolUse funciona, no verás mensajes en la conversación, así que prueba con un archivo de ejemplo.
Fuentes
- Guía de hooks de Claude Code (documentación oficial)
- Referencia de hooks de Claude Code (documentación oficial)
- Registro de cambios de Claude Code en GitHub
Última revisión: 17 de noviembre de 2026. Este artículo fue preparado con ayuda de IA; consulta cómo usamos la IA. Los comandos y la configuración vienen de la documentación oficial y no los ejecutamos en un entorno propio.
