Hook en Claude Code

Un hook en Claude Code es un comando de shell configurado para dispararse automáticamente en puntos específicos del ciclo de vida del agente: antes de usar una herramienta, después de editar un archivo, cuando Claude termina de responder, etc. A diferencia de las instrucciones en lenguaje natural, que Claude puede interpretar o ignorar, un hook es código determinista que siempre se ejecuta cuando ocurre el evento asociado.

Cómo funciona

Los hooks se definen en los archivos de configuración de Claude Code (por ejemplo en .claude/settings.json del proyecto o en la configuración global del usuario). Cada hook asocia un evento a uno o varios comandos shell. Los eventos disponibles cubren los momentos clave del flujo del agente:

• PreToolUse: antes de que Claude ejecute una herramienta (como editar un archivo o lanzar un comando). Puede bloquear la acción.
• PostToolUse: después de que la herramienta se ejecute correctamente.
• UserPromptSubmit: cuando el usuario envía un prompt, antes de que Claude lo procese.
• Stop y SubagentStop: cuando el agente principal o un subagente terminan.
• SessionStart y Notification: inicio de sesión y notificaciones.

El hook recibe por stdin un JSON con el contexto del evento (nombre de la herramienta, parámetros, rutas de archivo afectadas). El código de salida importa: un código distinto de cero en PreToolUse puede bloquear la acción y devolver el error a Claude para que reaccione. Un ejemplo típico es ejecutar un formateador tras cada edición:

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{ "type": "command", "command": "prettier --write $CLAUDE_FILE_PATHS" }]
    }]
  }
}

Por qué importa

Los hooks convierten expectativas difusas en garantías. Si quieres que todo código que Claude escribe pase por un linter, confiarlo a una instrucción del prompt es frágil: el modelo puede olvidarlo bajo presión de contexto. Un hook lo impone sin excepción. Esto es clave en equipos donde Claude Code opera de forma semiautónoma: validaciones de seguridad, bloqueo de comandos peligrosos (rm -rf), ejecución automática de tests, envío de notificaciones o registro de auditoría de cada acción del agente.

En la práctica, los hooks te dan control determinista sobre un agente no determinista. Son la capa de policy que rodea al modelo. Dominar este tipo de automatización forma parte de aprender a construir flujos de desarrollo con Claude Code que sean reproducibles y seguros en un entorno profesional.

Hooks frente a otras extensiones

Es fácil confundir hooks con otros mecanismos de extensión de Claude Code:

• El archivo CLAUDE.md aporta contexto e instrucciones que Claude puede seguir. Un hook es código que se ejecuta pase lo que pase.
• MCP conecta a Claude con herramientas y fuentes de datos externas. Un hook no añade capacidades al modelo: intercepta y controla las que ya usa.
• Los subagentes delegan tareas a instancias de Claude. Un hook no razona: ejecuta un comando.

Errores comunes

Un fallo habitual es escribir hooks que bloquean en exceso y rompen el flujo del agente sin darle información útil para corregirse; conviene devolver mensajes de error claros por stderr. Otro error es asumir que un hook sanea toda la seguridad: un hook ejecuta con tus permisos, así que un comando mal escrito puede ser peligroso por sí mismo. Tampoco conviene meter lógica lenta en PreToolUse, porque se ejecuta en el camino crítico y ralentiza cada acción de Claude. Prueba siempre los hooks en un proyecto aislado antes de desplegarlos globalmente.