Por Canuto  

Claude Code documentó cómo sus “hooks” permiten automatizar, auditar y hasta bloquear acciones durante una sesión: desde la llegada de un prompt hasta la ejecución de herramientas como Bash, todo puede pasar por eventos con entrada y salida en JSON.
***

  • Los hooks se disparan en eventos concretos del ciclo de vida de una sesión, como PreToolUse, PostToolUse o SessionStart.
  • La entrada llega en JSON (por stdin en comandos de shell o por POST en hooks HTTP), y el controlador puede devolver una decisión que afecte el flujo.
  • Un ejemplo de seguridad: un hook PreToolUse puede negar permisos si detecta un comando destructivo como rm -rf.

 

Los “hooks” en Claude Code funcionan como puntos de extensión que se ejecutan automáticamente en momentos específicos del ciclo de vida de una sesión. Según la documentación técnica publicada por el equipo del producto, estos hooks pueden tomar la forma de comandos de shell definidos por el usuario, endpoints HTTP o incluso instrucciones para un modelo de lenguaje (LLM). El objetivo es que el desarrollador pueda inspeccionar el contexto de lo que está ocurriendo, ejecutar acciones adicionales y, en algunos casos, intervenir el flujo.

La idea central es sencilla: cuando ocurre un evento y se cumple un comparador, Claude Code entrega un paquete de contexto en formato JSON al “controlador” del hook. En los hooks de comando, ese JSON llega por la entrada estándar (stdin). En los hooks HTTP, llega como el cuerpo de una solicitud POST. Con esa información, el controlador puede decidir si solo registra, si transforma datos, o si devuelve una decisión que impacte directamente la ejecución.

Este diseño se conecta con una preocupación cada vez más relevante para equipos que trabajan con asistentes de programación y flujos agentic: la gobernanza. Cuando un agente puede invocar herramientas, tocar repositorios o ejecutar comandos del sistema, se vuelve crucial tener controles finos y automatizables. Los hooks buscan cubrir esa necesidad con un esquema claro de eventos, más opciones avanzadas como hooks asincrónicos, hooks HTTP y hooks para herramientas MCP.

Eventos: el ciclo de vida donde se activan los hooks

Claude Code define una lista de eventos que pueden disparar hooks durante una sesión. Algunos se ejecutan una sola vez por sesión, y otros se repiten dentro del bucle agentic. En términos prácticos, esto permite instrumentar desde el inicio hasta el cierre, pasando por momentos sensibles como permisos y uso de herramientas.

Entre los eventos listados aparece SessionStart, que se activa cuando una sesión comienza o se reanuda, y SessionEnd, que marca el término de la sesión. También existe UserPromptSubmit, que ocurre cuando el usuario envía un prompt, pero antes de que Claude lo procese. Para equipos que necesitan auditoría o preprocesamiento, ese punto puede resultar útil.

La lista incluye eventos directamente asociados al uso de herramientas: PreToolUse ocurre antes de ejecutar una llamada de herramienta y puede bloquearla; PostToolUse se dispara tras una llamada exitosa; y PostToolUseFailure se activa después de un fallo. Esta separación facilita construir políticas que diferencien entre prevención, registro de éxito y manejo de errores.

Otros eventos cubren interacciones y estados del sistema: PermissionRequest cuando aparece un cuadro de diálogo de permiso; Notification cuando Claude Code emite una notificación; Stop cuando Claude termina de responder; y TaskCompleted cuando una tarea se marca como completada. El catálogo también contempla subagentes con SubagentStart y SubagentStop, además de un evento de inactividad llamado TeammateIdle.

Hay eventos asociados a configuración y contexto: InstructionsLoaded se activa cuando se carga un archivo CLAUDE.md o reglas en .claude/rules/*.md al contexto. La documentación indica que esto ocurre al inicio de la sesión y también cuando los archivos se cargan de forma diferida durante una sesión. Complementariamente, ConfigChange se dispara cuando un archivo de configuración cambia mientras la sesión está activa.

Finalmente, se incluyen puntos vinculados a operaciones de repositorio y manejo de contexto: WorktreeCreate y WorktreeRemove para creación y eliminación de worktrees, y PreCompact antes de la compactación del contexto. En el caso de WorktreeCreate, la documentación especifica que reemplaza el comportamiento predeterminado de git cuando se crea un worktree mediante –worktree o usando isolation: “worktree”.

Entrada y comparadores: cuándo corre el hook y qué recibe

El mecanismo operativo depende de dos piezas: el evento y el comparador. Cuando un evento se activa, Claude Code verifica si existe un comparador que deba coincidir para ejecutar el hook. Si no hay comparador, o si se usa el comodín “*”, el hook se ejecuta en cada ocurrencia de ese evento. En cambio, los hooks solo se omiten cuando hay un comparador definido y no coincide.

La entrada llega como JSON, y su canal depende del tipo de hook. Para hooks implementados como comandos, la información se entrega por stdin. Para hooks HTTP, viaja como el cuerpo de una solicitud POST. En ambos casos, el controlador obtiene suficiente contexto para inspeccionar qué está por ocurrir o qué ocurrió, y responder en consecuencia.

El punto más sensible es que algunos eventos habilitan decisiones de control. La documentación lo describe como “decisiones de resolución de un hook”, donde el controlador puede devolver un resultado en JSON que afecte el flujo, por ejemplo permitir o bloquear una acción. Esto habilita políticas automatizadas de seguridad y cumplimiento, sin necesidad de intervención manual en cada paso.

En términos de ingeniería, este modelo se parece a un middleware de eventos: intercepta acciones, las describe en un esquema, y ofrece una salida formal que el sistema entiende. Para equipos que construyen flujos de trabajo con agentes, la ventaja es que el control vive en scripts o servicios propios, y puede versionarse, auditarse y endurecerse igual que el resto del pipeline.

Ejemplo: un hook PreToolUse que bloquea comandos destructivos

Para ilustrar el flujo, la documentación presenta un hook del evento PreToolUse pensado para bloquear comandos de shell destructivos. El ejemplo ejecuta un script llamado block-rm.sh antes de cada llamada de herramienta Bash. La intención es detectar patrones peligrosos y negar la ejecución si aparecen.

El script lee la entrada JSON desde stdin, extrae el comando con jq desde el campo .tool_input.command, y evalúa si el texto contiene rm -rf. Si lo detecta, imprime un JSON en stdout con permissionDecision en “deny” y una razón: “Comando destructivo bloqueado por el hook”. Si no hay coincidencia, el script termina sin salida explícita, lo que en el ejemplo equivale a permitir el comando.

El recorrido que describe la documentación se compone de cuatro pasos. Primero, Claude Code dispara el evento PreToolUse y envía la entrada de la herramienta como JSON a stdin del hook. Allí se muestra, por ejemplo, tool_name como “Bash” y en tool_input el comando “rm -rf /tmp/build”.

Segundo, se realiza la verificación del comparador. En el ejemplo, el comparador “Bash” coincide con el nombre de la herramienta, por lo que el script block-rm.sh se ejecuta. La documentación aclara que si se omite el comparador o se usa “*”, el hook corre en cada ocurrencia del evento.

Tercero, el controlador del hook procesa la entrada. El script extrae el comando, encuentra el patrón rm -rf y emite la decisión en JSON. La estructura de salida incluye un objeto hookSpecificOutput con hookEventName como “PreToolUse”, más la decisión de permiso y su motivo.

Cuarto, Claude Code actúa sobre el resultado. Lee la decisión JSON, bloquea la llamada de herramienta y muestra la razón a Claude. En otras palabras, el hook no solo observa, sino que puede convertirse en un control preventivo para evitar ejecuciones de alto riesgo dentro de un entorno asistido por IA.

Por qué importa para equipos que usan agentes y herramientas

La capacidad de engancharse al ciclo de vida de una sesión y controlar llamadas a herramientas responde a un problema práctico: el poder operativo de los asistentes. En entornos donde un agente puede ejecutar Bash o modificar archivos, un error de interpretación o una instrucción mal planteada puede generar pérdidas de datos. Un hook como el del ejemplo actúa como última línea de defensa.

Más allá del caso extremo de rm -rf, el enfoque permite construir controles más sutiles. Por ejemplo, un equipo podría usar PreToolUse para forzar que ciertos comandos solo se ejecuten en rutas específicas, o para requerir confirmación adicional cuando el comando afecta directorios críticos. La documentación no agrega esos casos, pero el mecanismo descrito sugiere esa flexibilidad.

También aparece un valor operativo para auditoría y trazabilidad. Eventos como PostToolUse y PostToolUseFailure pueden alimentar bitácoras o sistemas de monitoreo con el contexto exacto del intento, su resultado y el momento en que ocurrió. En procesos de cumplimiento, esos registros ayudan a reconstruir decisiones y entender incidentes.

Finalmente, al incluir eventos como InstructionsLoaded y ConfigChange, Claude Code abre la puerta a flujos donde las reglas del proyecto y la configuración sean observables y controlables durante la sesión. En equipos grandes, ese detalle puede ser tan importante como el control de herramientas, porque define qué instrucciones y políticas están efectivamente activas cuando el agente toma decisiones.


ADVERTENCIA: DiarioBitcoin ofrece contenido informativo y educativo sobre diversos temas, incluyendo criptomonedas, IA, tecnología y regulaciones. No brindamos asesoramiento financiero. Las inversiones en criptoactivos son de alto riesgo y pueden no ser adecuadas para todos. Investigue, consulte a un experto y verifique la legislación aplicable antes de invertir. Podría perder todo su capital.

Suscríbete a nuestro boletín

Artículos Relacionados