Hooks: pre-tarea, post-edición, ante fallos, al completar

Módulo 5 · Extensibilidad · Lección 6 de 8

Al terminar esta lección podrás configurar un hook para un evento concreto del ciclo de vida, escribir el comando de shell que ejecuta y explicar para qué se usan los hooks en un despliegue empresarial.

¿Podemos registrar cada comando bash que Claude ejecuta?

Los hooks son disparadores a nivel de sistema, no instrucciones de Claude

El equipo de seguridad del cliente pregunta: «¿Podemos registrar automáticamente cada vez que Claude ejecuta un comando bash?». La respuesta es sí: un hook PostToolUse sobre Bash, un bloque JSON en la configuración de hooks.

Los hooks permiten registrar comandos de shell que se ejecutan en puntos concretos del ciclo de vida de Claude Code. No son instrucciones para Claude: se ejecutan independientemente de lo que esté haciendo. Un hook de formateo se dispara después de cada edición de un archivo TypeScript; un hook de registro, después de cada llamada a una herramienta; un hook de bloqueo, antes de una escritura protegida, y puede impedirla por completo.

Si has desplegado puertas de pre-commit de Jira o flujos de aprobación de cambios en ServiceNow, es la misma lógica de cumplimiento: los hooks se ejecutan localmente en la sesión del desarrollador en lugar de en un pipeline de CI compartido.

Casos de uso habituales

La mayoría de los requisitos de hooks en una activación de Claude Code encajan en uno de cuatro casos de uso:

• Notificaciones. Mensaje en Slack cuando Claude termina una tarea. Sonido cuando Claude espera una entrada. Mejoras de calidad de vida para desarrolladores que trabajan en varias terminales.
• Autoformateo. Ejecutar Prettier en cada edición de un archivo .ts. Ejecutar gofmt en cada archivo .go. El formateo se ejecuta tanto si Claude recordó aplicarlo como si no.
• Registro. Escribir un registro con marca de tiempo de cada llamada a una herramienta en un archivo de log o en un sistema de auditoría. Útil para cumplimiento, revisión de incidentes o depuración de comportamientos inesperados de Claude.
• Aplicación de reglas (enforcement). Usa PreToolUse para comprobar condiciones antes de la acción: el código de salida 2 bloquea la llamada a la herramienta por completo. Usa PostToolUse para reaccionar después: ejecutar un linter, registrar el resultado o alertar de infracciones. Bloquear escrituras en directorios protegidos sin una referencia a un ticket.

Cinco eventos comunes: empieza aquí

Cada hook está ligado a un evento del ciclo de vida de Claude Code. Elegir el evento correcto es la primera decisión de configuración. Estos cinco cubren la mayoría de los casos de uso empresariales; Claude Code admite más de 20 eventos del ciclo de vida en total para patrones de gobernanza especializados.

Evento	Cuándo se dispara	Uso principal
PreToolUse	Antes de que Claude ejecute cualquier herramienta	Aplicación bloqueante: comprobar condiciones antes de la acción
PostToolUse	Después de que termina la ejecución de una herramienta	Registro, autoformateo, disparadores de efectos secundarios
Notification	Cuando Claude envía una notificación	Alertas: mensaje en Slack, sonido de escritorio, aviso por webhook
Stop	Cuando termina la tarea del agente principal	Registro de resúmenes, limpieza, acciones de fin de sesión
SubagentStop	Cuando termina un subagente	Gestión del resultado del subagente, coordinación de trabajos paralelos

La distinción de aplicación: usa PreToolUse cuando necesites bloquear una acción antes de que ocurra. Usa PostToolUse cuando necesites reaccionar a posteriori. Esta distinción pesa más que cualquier otra decisión de configuración que tomarás con hooks.

flowchart LR
    A["Claude solicita una herramienta"] --> B["PreToolUse: bloquea si hace falta"]
    B --> C["La herramienta se ejecuta"]
    C --> D["PostToolUse: registra, formatea o alerta"]

Más allá de los cinco: los patrones avanzados de gobernanza usan eventos adicionales como SessionStart (inicialización de sesión), PermissionRequest/PermissionDenied (flujos de aprobación detallados), FileChanged (protección de archivos sensibles) y ConfigChange (detección de desviaciones). Consulta la referencia completa de hooks en la documentación de Claude Code para ver la lista completa.

Formato de configuración de hooks: dos ejemplos reales

Los hooks se configuran con el comando /hooks o en un archivo hooks.json dentro del directorio de hooks de un plugin.

Ejemplo 1: registrar cada llamada a Bash (PostToolUse)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            # La entrada de la herramienta llega como JSON por stdin: parsea con jq, nunca uses $TOOL_INPUT (no existe)
            "command": "jq -r '.tool_input.command' | xargs -I {} sh -c 'echo \"[$(date)] Bash: {}\" >> ~/claude-bash-log.txt'"
          }
        ]
      }
    ]
  }
}

Ejemplo 2: autoformatear TypeScript después de cada edición (PostToolUse)

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            # La ruta del archivo llega como JSON por stdin: parsea con jq, nunca uses $EDITED_FILE (no existe)
            "command": "jq -r '.tool_input.file_path' | { read file; [[ \"$file\" == *.ts ]] && npx prettier --write \"$file\"; }"
          }
        ]
      }
    ]
  }
}

Comportamiento del código de salida

La acción que ejecuta tu hook determina lo que Claude hace a continuación. Eso lo controla el código de salida:

• Salida 0: el hook tuvo éxito; Claude Code continúa.
• Salida 1: fallo no bloqueante. El error aparece en el contexto de Claude, pero la ejecución continúa.
• Salida 2: bloquea la ejecución de la herramienta. Es el mecanismo de los hooks de aplicación de reglas: solo un hook PreToolUse que sale con código 2 impide que Claude continúe con la llamada a la herramienta.

flowchart TD
    A["Claude quiere ejecutar una herramienta"] --> B["Hook PreToolUse"]
    B --> C{"Código de salida del hook"}
    C -->|"0: éxito"| D["Claude Code continúa"]
    C -->|"1: fallo no bloqueante"| E["El error aparece en el contexto de Claude y la ejecución continúa"]
    C -->|"2: bloqueo"| F["Se bloquea la ejecución de la herramienta"]

Advertencia de seguridad para el equipo de plataforma del cliente

Los hooks ejecutan comandos de shell con los mismos permisos que la sesión de Claude Code del desarrollador. Los scripts de los hooks deben revisarse antes de desplegarlos. Un hook comprometido es una vía de movimiento lateral. El CoE debe ser dueño de todos los hooks que entren en el plugin del equipo y versionarlos.

Cuándo construir hooks durante una activación, y la advertencia de seguridad

El plan de activación introduce los hooks en la semana 1 (Claude Code 101). No es una función avanzada: es configuración base. Ten una postura definida sobre los hooks para el Día 3.

Semana 1 / Días 3–5: empieza con dos hooks de bajo riesgo y alto valor. Primero, un hook de notificación: un sonido o un aviso en Slack cuando Claude necesita una entrada evita que el desarrollador se quede bloqueado. Segundo, un hook de autoformateo para el lenguaje principal del cliente: una mejora inmediata de productividad y cero esfuerzo adicional para el desarrollador.

Semana 4 / fase de empaquetado: los hooks de registro de seguridad y los hooks de cumplimiento personalizados pertenecen al plugin del equipo. Son los artefactos que demuestran que Claude Code funciona bajo gobernanza, algo que el equipo de seguridad del cliente necesita ver antes de cerrar el proyecto.

Comprueba tu comprensión

Hooks: tres afirmaciones para evaluar

Actividad · ¿Verdadero o falso? Selecciona una respuesta para cada afirmación.

Afirmación 1: un hook PostToolUse sobre Edit puede impedir que Claude guarde un archivo si el contenido no supera una comprobación de validación.

Verdadero / Falso

Ver respuesta

Falso. PostToolUse se dispara después de que la edición ya se ha completado. Bloquear requiere PreToolUse, que intercepta la llamada a la herramienta antes de que se ejecute. PostToolUse sirve para registrar, formatear o disparar efectos secundarios a posteriori.

Afirmación 2: los scripts de hooks se ejecutan con los mismos permisos del sistema que la sesión de Claude Code del desarrollador.

Verdadero / Falso

Ver respuesta

Verdadero. Los scripts de hooks son comandos de shell que se ejecutan en el entorno del desarrollador. Heredan los mismos permisos que la sesión de Claude Code: sin elevación y sin más restricciones que los accesos de la propia sesión. Los scripts deben revisarse antes de desplegarlos, y el equipo de seguridad del cliente debe saber qué hace cada hook.

Afirmación 3: un hook Stop es el evento adecuado para aplicar una comprobación de cumplimiento antes de que Claude edite un archivo de configuración.

Verdadero / Falso

Ver respuesta

Falso. Stop se dispara cuando termina toda la sesión. Para entonces, todas las ediciones ya se han hecho. Para aplicar una comprobación antes de una edición concreta de un archivo, usa PreToolUse sobre Edit con un matcher por la ruta del archivo.

Las distinciones clave: PreToolUse bloquea, PostToolUse reacciona. Stop se dispara al final de la sesión, no antes de cada llamada a una herramienta. Los permisos se heredan, y cada hook es una decisión de confianza.

Bloquear ediciones en un directorio protegido

Un requisito de cumplimiento muy habitual. El evento de hook equivocado es peor que no tener hook.

Decisión · Diseño de hooks

Quieres impedir que Claude Code edite archivos del directorio /config sin un número de ticket en el contexto de la sesión. ¿Qué patrón de hook funciona?

• A · PreToolUse sobre Edit: antes de que se ejecute la edición, comprobar si el archivo de destino está en /config. Si no hay número de ticket en la sesión, salir con código distinto de cero y bloquear la edición.
• B · PostToolUse sobre Edit: comprobar si el archivo editado está en /config. Si no hay ticket en el contexto, salir con código distinto de cero y registrar una advertencia.
• C · Hook Stop que revisa todas las ediciones al final de la sesión: al final de cada sesión, buscar ediciones en /config hechas sin ticket. Avisar al equipo si se encuentra alguna.

Ver respuesta

A es correcta. PreToolUse se dispara antes de que se ejecute la herramienta: salir con código 2 impide la edición por completo. Es el único patrón que realmente bloquea el cambio en lugar de reaccionar después.

B: PostToolUse se dispara después de que la edición ya ha ocurrido. El cambio ya está en el archivo. Puedes registrar que se incumplió una regla, pero no puedes deshacerlo.

C: el hook Stop se dispara al final de la sesión, demasiado tarde para cada edición hecha durante ella. Avisar después es auditoría, no aplicación de reglas.

Temporización de la notificación: ¿qué evento encaja?

Un cliente quiere recibir un mensaje en Slack cuando termina un subagente de auditoría de seguridad. Hay tres opciones, y una de ellas corresponde al evento del ciclo de vida adecuado.

Decisión · Selección de evento

Quieres enviar un mensaje en Slack en el momento en que un subagente de auditoría de seguridad termina su escaneo. ¿Qué evento de hook configuras?

• A · Stop: se dispara cuando termina la tarea del agente principal.
• B · SubagentStop: se dispara específicamente cuando termina un subagente generado.
• C · PostToolUse sobre Bash: se dispara después de cada comando Bash que ejecuta el subagente.

Ver respuesta

B es correcta. SubagentStop se dispara en el momento en que un subagente concreto termina su tarea y devuelve resultados al agente principal: justo cuando termina la auditoría.

A: Stop se dispara cuando termina toda la tarea del agente principal, que puede ser minutos después de que termine el subagente. Notificarías demasiado tarde.

C: PostToolUse sobre Bash se dispara después de cada comando de shell que ejecuta el subagente. Enviarías decenas de mensajes en Slack por cada auditoría, no uno al final.

El hook que configuraste aquí es el componente hooks/hooks.json del plugin de activación. Pruébalo durante el proyecto y empaquétalo el Día 30.

Artefacto del curso · Contribución de la lección 6

Plugin de activación

Script de hook funcional

1. Escribe un hooks.json con al menos una regla PreToolUse o PostToolUse relevante para el entorno del cliente: un guardia contra escrituras en producción o un hook de registro son buenos puntos de partida.
2. Pruébalo localmente: dispara la condición que vigila y confirma que se produce la respuesta esperada.
3. Este archivo se convierte en el componente hooks/ del plugin de activación que empaquetarás en la lección 5.8.

Ideas clave

• Los hooks son la capa de aplicación de reglas en entornos empresariales: PreToolUse bloquea la ejecución de la herramienta antes de que ocurra, y PostToolUse reacciona después de que se complete.
• Un hook PreToolUse que sale con código 2 es el único mecanismo que impide que Claude continúe con la llamada a la herramienta.
• Un hook Stop se dispara al final de la sesión: no sirve para comprobaciones antes de una edición concreta.
• Los hooks heredan los permisos de la sesión: cada hook es una decisión de confianza que debe revisar el equipo de seguridad.
• Empieza en la semana 1 con un hook de notificación y uno de autoformateo; en la semana 4, incluye un hook de registro de seguridad en el plugin del equipo.

Siguiente: Subagentes y orquestación en paralelo