Referencia de hooks
Esta página proporciona documentación de referencia para implementar hooks en Claude Code.
Para una guía de inicio rápido con ejemplos, consulta Comenzar con los hooks de Claude Code.
Configuración
Los hooks de Claude Code se configuran en tus archivos de configuración:
~/.claude/settings.json
- Configuración de usuario.claude/settings.json
- Configuración de proyecto.claude/settings.local.json
- Configuración local de proyecto (no confirmada)- Configuración de política gestionada empresarial
Estructura
Los hooks se organizan por coincidencias, donde cada coincidencia puede tener múltiples hooks:
- matcher: Patrón para coincidir con nombres de herramientas, sensible a mayúsculas y minúsculas (solo aplicable para
PreToolUse
yPostToolUse
)- Las cadenas simples coinciden exactamente:
Write
coincide solo con la herramienta Write - Soporta regex:
Edit|Write
oNotebook.*
- Usa
*
para coincidir con todas las herramientas. También puedes usar cadena vacía (""
) o dejarmatcher
en blanco.
- Las cadenas simples coinciden exactamente:
- hooks: Array de comandos a ejecutar cuando el patrón coincide
type
: Actualmente solo se soporta"command"
command
: El comando bash a ejecutar (puede usar la variable de entorno$CLAUDE_PROJECT_DIR
)timeout
: (Opcional) Cuánto tiempo debe ejecutarse un comando, en segundos, antes de cancelar ese comando específico.
Para eventos como UserPromptSubmit
, Notification
, Stop
, y SubagentStop
que no usan coincidencias, puedes omitir el campo matcher:
Scripts de Hook Específicos del Proyecto
Puedes usar la variable de entorno CLAUDE_PROJECT_DIR
(solo disponible cuando Claude Code genera el comando hook) para referenciar scripts almacenados en tu proyecto, asegurando que funcionen independientemente del directorio actual de Claude:
Eventos de Hook
PreToolUse
Se ejecuta después de que Claude crea los parámetros de la herramienta y antes de procesar la llamada a la herramienta.
Coincidencias comunes:
Task
- Tareas del agenteBash
- Comandos de shellGlob
- Coincidencia de patrones de archivoGrep
- Búsqueda de contenidoRead
- Lectura de archivosEdit
,MultiEdit
- Edición de archivosWrite
- Escritura de archivosWebFetch
,WebSearch
- Operaciones web
PostToolUse
Se ejecuta inmediatamente después de que una herramienta se completa exitosamente.
Reconoce los mismos valores de coincidencia que PreToolUse.
Notification
Se ejecuta cuando Claude Code envía notificaciones. Las notificaciones se envían cuando:
- Claude necesita tu permiso para usar una herramienta. Ejemplo: “Claude necesita tu permiso para usar Bash”
- La entrada del prompt ha estado inactiva durante al menos 60 segundos. “Claude está esperando tu entrada”
UserPromptSubmit
Se ejecuta cuando el usuario envía un prompt, antes de que Claude lo procese. Esto te permite agregar contexto adicional basado en el prompt/conversación, validar prompts, o bloquear ciertos tipos de prompts.
Stop
Se ejecuta cuando el agente principal de Claude Code ha terminado de responder. No se ejecuta si la detención ocurrió debido a una interrupción del usuario.
SubagentStop
Se ejecuta cuando un subagente de Claude Code (llamada a herramienta Task) ha terminado de responder.
PreCompact
Se ejecuta antes de que Claude Code esté a punto de ejecutar una operación de compactación.
Coincidencias:
manual
- Invocado desde/compact
auto
- Invocado desde auto-compact (debido a ventana de contexto llena)
Entrada de Hook
Los hooks reciben datos JSON a través de stdin que contienen información de sesión y datos específicos del evento:
Entrada PreToolUse
El esquema exacto para tool_input
depende de la herramienta.
Entrada PostToolUse
El esquema exacto para tool_input
y tool_response
depende de la herramienta.
Entrada Notification
Entrada UserPromptSubmit
Entrada Stop y SubagentStop
stop_hook_active
es verdadero cuando Claude Code ya está continuando como resultado de un hook de parada. Verifica este valor o procesa la transcripción para evitar que Claude Code se ejecute indefinidamente.
Entrada PreCompact
Para manual
, custom_instructions
proviene de lo que el usuario pasa a /compact
. Para auto
, custom_instructions
está vacío.
Salida de Hook
Hay dos formas para que los hooks devuelvan salida de vuelta a Claude Code. La salida comunica si bloquear y cualquier retroalimentación que deba mostrarse a Claude y al usuario.
Simple: Código de Salida
Los hooks comunican el estado a través de códigos de salida, stdout, y stderr:
- Código de salida 0: Éxito.
stdout
se muestra al usuario en modo transcripción (CTRL-R), excepto paraUserPromptSubmit
, donde stdout se agrega al contexto. - Código de salida 2: Error de bloqueo.
stderr
se devuelve a Claude para procesar automáticamente. Ver comportamiento por evento de hook abajo. - Otros códigos de salida: Error no bloqueante.
stderr
se muestra al usuario y la ejecución continúa.
Recordatorio: Claude Code no ve stdout si el código de salida es 0, excepto para el hook UserPromptSubmit
donde stdout se inyecta como contexto.
Comportamiento del Código de Salida 2
Evento de Hook | Comportamiento |
---|---|
PreToolUse | Bloquea la llamada a la herramienta, muestra stderr a Claude |
PostToolUse | Muestra stderr a Claude (la herramienta ya se ejecutó) |
Notification | N/A, muestra stderr solo al usuario |
UserPromptSubmit | Bloquea el procesamiento del prompt, borra el prompt, muestra stderr solo al usuario |
Stop | Bloquea la detención, muestra stderr a Claude |
SubagentStop | Bloquea la detención, muestra stderr al subagente de Claude |
PreCompact | N/A, muestra stderr solo al usuario |
Avanzado: Salida JSON
Los hooks pueden devolver JSON estructurado en stdout
para un control más sofisticado:
Campos JSON Comunes
Todos los tipos de hook pueden incluir estos campos opcionales:
Si continue
es false, Claude deja de procesar después de que se ejecuten los hooks.
- Para
PreToolUse
, esto es diferente de"permissionDecision": "deny"
, que solo bloquea una llamada específica a la herramienta y proporciona retroalimentación automática a Claude. - Para
PostToolUse
, esto es diferente de"decision": "block"
, que proporciona retroalimentación automatizada a Claude. - Para
UserPromptSubmit
, esto evita que el prompt sea procesado. - Para
Stop
ySubagentStop
, esto tiene precedencia sobre cualquier salida"decision": "block"
. - En todos los casos,
"continue" = false
tiene precedencia sobre cualquier salida"decision": "block"
.
stopReason
acompaña a continue
con una razón mostrada al usuario, no mostrada a Claude.
Control de Decisión PreToolUse
Los hooks PreToolUse
pueden controlar si procede una llamada a herramienta.
"allow"
omite el sistema de permisos.permissionDecisionReason
se muestra al usuario pero no a Claude. (El valor obsoleto"approve"
+reason
tiene el mismo comportamiento.)"deny"
evita que la llamada a la herramienta se ejecute.permissionDecisionReason
se muestra a Claude. (El valor"block"
+reason
tiene el mismo comportamiento.)"ask"
pide al usuario que confirme la llamada a la herramienta en la UI.permissionDecisionReason
se muestra al usuario pero no a Claude.
Control de Decisión PostToolUse
Los hooks PostToolUse
pueden controlar si procede una llamada a herramienta.
"block"
solicita automáticamente a Claude conreason
.undefined
no hace nada.reason
se ignora.
Control de Decisión UserPromptSubmit
Los hooks UserPromptSubmit
pueden controlar si se procesa un prompt de usuario.
"block"
evita que el prompt sea procesado. El prompt enviado se borra del contexto."reason"
se muestra al usuario pero no se agrega al contexto.undefined
permite que el prompt proceda normalmente."reason"
se ignora."hookSpecificOutput.additionalContext"
agrega la cadena al contexto si no está bloqueado.
Control de Decisión Stop
/SubagentStop
Los hooks Stop
y SubagentStop
pueden controlar si Claude debe continuar.
"block"
evita que Claude se detenga. Debes poblarreason
para que Claude sepa cómo proceder.undefined
permite que Claude se detenga.reason
se ignora.
Ejemplo de Código de Salida: Validación de Comando Bash
Ejemplo de Salida JSON: UserPromptSubmit para Agregar Contexto y Validación
Para hooks UserPromptSubmit
, puedes inyectar contexto usando cualquier método:
- Código de salida 0 con stdout: Claude ve el contexto (caso especial para
UserPromptSubmit
) - Salida JSON: Proporciona más control sobre el comportamiento
Ejemplo de Salida JSON: PreToolUse con Aprobación
Trabajando con Herramientas MCP
Los hooks de Claude Code funcionan perfectamente con herramientas del Protocolo de Contexto de Modelo (MCP). Cuando los servidores MCP proporcionan herramientas, aparecen con un patrón de nomenclatura especial que puedes coincidir en tus hooks.
Nomenclatura de Herramientas MCP
Las herramientas MCP siguen el patrón mcp__<server>__<tool>
, por ejemplo:
mcp__memory__create_entities
- Herramienta de crear entidades del servidor de memoriamcp__filesystem__read_file
- Herramienta de leer archivo del servidor de sistema de archivosmcp__github__search_repositories
- Herramienta de búsqueda del servidor de GitHub
Configurando Hooks para Herramientas MCP
Puedes dirigirte a herramientas MCP específicas o servidores MCP completos:
Ejemplos
Para ejemplos prácticos incluyendo formato de código, notificaciones, y protección de archivos, consulta Más Ejemplos en la guía de inicio.
Consideraciones de Seguridad
Descargo de Responsabilidad
USA BAJO TU PROPIO RIESGO: Los hooks de Claude Code ejecutan comandos de shell arbitrarios en tu sistema automáticamente. Al usar hooks, reconoces que:
- Eres el único responsable de los comandos que configures
- Los hooks pueden modificar, eliminar, o acceder a cualquier archivo al que tu cuenta de usuario pueda acceder
- Los hooks maliciosos o mal escritos pueden causar pérdida de datos o daño al sistema
- Anthropic no proporciona garantía y no asume responsabilidad por ningún daño resultante del uso de hooks
- Debes probar exhaustivamente los hooks en un entorno seguro antes del uso en producción
Siempre revisa y entiende cualquier comando de hook antes de agregarlo a tu configuración.
Mejores Prácticas de Seguridad
Aquí hay algunas prácticas clave para escribir hooks más seguros:
- Validar y sanear entradas - Nunca confíes ciegamente en los datos de entrada
- Siempre citar variables de shell - Usa
"$VAR"
no$VAR
- Bloquear traversal de rutas - Verifica
..
en rutas de archivo - Usar rutas absolutas - Especifica rutas completas para scripts (usa
$CLAUDE_PROJECT_DIR
para la ruta del proyecto) - Omitir archivos sensibles - Evita
.env
,.git/
, claves, etc.
Seguridad de Configuración
Las ediciones directas a hooks en archivos de configuración no toman efecto inmediatamente. Claude Code:
- Captura una instantánea de hooks al inicio
- Usa esta instantánea durante toda la sesión
- Advierte si los hooks se modifican externamente
- Requiere revisión en el menú
/hooks
para que los cambios se apliquen
Esto evita que las modificaciones maliciosas de hooks afecten tu sesión actual.
Detalles de Ejecución de Hook
- Timeout: Límite de ejecución de 60 segundos por defecto, configurable por comando.
- Un timeout para un comando individual no afecta los otros comandos.
- Paralelización: Todos los hooks coincidentes se ejecutan en paralelo
- Entorno: Se ejecuta en el directorio actual con el entorno de Claude Code
- La variable de entorno
CLAUDE_PROJECT_DIR
está disponible y contiene la ruta absoluta al directorio raíz del proyecto
- La variable de entorno
- Entrada: JSON a través de stdin
- Salida:
- PreToolUse/PostToolUse/Stop: Progreso mostrado en transcripción (Ctrl-R)
- Notification: Registrado solo en debug (
--debug
)
Depuración
Solución de Problemas Básica
Si tus hooks no están funcionando:
- Verificar configuración - Ejecuta
/hooks
para ver si tu hook está registrado - Verificar sintaxis - Asegúrate de que tu configuración JSON sea válida
- Probar comandos - Ejecuta comandos de hook manualmente primero
- Verificar permisos - Asegúrate de que los scripts sean ejecutables
- Revisar logs - Usa
claude --debug
para ver detalles de ejecución de hook
Problemas comunes:
- Comillas no escapadas - Usa
\"
dentro de cadenas JSON - Matcher incorrecto - Verifica que los nombres de herramientas coincidan exactamente (sensible a mayúsculas y minúsculas)
- Comando no encontrado - Usa rutas completas para scripts
Depuración Avanzada
Para problemas complejos de hook:
- Inspeccionar ejecución de hook - Usa
claude --debug
para ver ejecución detallada de hook - Validar esquemas JSON - Prueba entrada/salida de hook con herramientas externas
- Verificar variables de entorno - Verifica que el entorno de Claude Code sea correcto
- Probar casos extremos - Prueba hooks con rutas de archivo o entradas inusuales
- Monitorear recursos del sistema - Verifica agotamiento de recursos durante la ejecución de hook
- Usar logging estructurado - Implementa logging en tus scripts de hook
Ejemplo de Salida de Debug
Usa claude --debug
para ver detalles de ejecución de hook:
Los mensajes de progreso aparecen en modo transcripción (Ctrl-R) mostrando:
- Qué hook se está ejecutando
- Comando siendo ejecutado
- Estado de éxito/falla
- Mensajes de salida o error