¿Qué es un hook y cómo se escribe para agentes de código?

¿Por qué no basta con el archivo de reglas?

Hay dos formas de darle una regla a un agente de programación. La primera es el archivo de reglas: escribes «pregúntame antes de hacer merge» en AGENTS.md, CLAUDE.md o GEMINI.md. La segunda es el hook: conviertes esa misma regla en un pequeño script que el agente ejecuta por su cuenta en un momento concreto.

Donde mejor se explica la diferencia es en la documentación de Claude Code: «Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead.» Es decir, el archivo de reglas es solo información para el agente, y el agente no siempre la tiene en cuenta. Si quieres detener una acción decida lo que decida el agente, usas un hook.

A 18 de octubre de 2026, hay hooks en cinco herramientas de programación: Claude Code, Codex de OpenAI, Cursor, Gemini CLI de Google y GitHub Copilot (la CLI y el agente en la nube). En todas funcionan igual: el hook se conecta a un evento, recibe los detalles del evento en JSON y, si hace falta, detiene un comando antes de que se ejecute.

Los ejemplos salen del repositorio en el que desarrollamos diffox y que usamos a diario. Allí trabajamos con Claude Code; lo que contamos no es una función del producto, sino la forma de trabajar del equipo.

¿Dónde se definen los hooks en cada herramienta?

En todas las herramientas, los hooks se escriben en un archivo de configuración; de una a otra cambia sobre todo el nombre del archivo y el del evento. Para poner reglas, el evento más usado es el que se dispara justo antes de que el agente use una herramienta (ejecutar un comando, editar un archivo):

Fuente: la documentación de hooks de cada herramienta, 18 de octubre de 2026. La decisión en JSON se toma con lo que el hook imprime en la salida estándar (stdout). Codex también lee la misma configuración dentro de config.toml. En Copilot, el archivo de usuario solo vale para la CLI; el agente en la nube lee el archivo del repositorio desde la rama por defecto.

Cuando se produce el evento, tu hook recibe los detalles en JSON: qué herramienta se llamó y con qué entrada. En Claude Code, la entrada que llega antes de un comando Bash tiene este aspecto:

Las herramientas también leen los archivos de las demás: Copilot lee además el archivo .claude/settings.json del repositorio, Cursor puede cargar hooks de Claude Code y Gemini CLI define la variable CLAUDE_PROJECT_DIR para que no se rompan los scripts escritos para Claude Code. Así que puedes escribir un hook una vez y usarlo en varias herramientas. Aun así, como los nombres de los eventos y los campos de salida cambian, prueba el hook en cada herramienta por separado.

El 18 de junio de 2026, Google dejó de dar servicio en Gemini CLI a los usuarios gratuitos y a los suscriptores de Google AI Pro y Ultra, y los dirigió a Antigravity CLI; con una clave de API de pago o una licencia de empresa puedes seguir usando Gemini CLI. Según el anuncio de Google, Antigravity CLI también tiene hooks; leímos su documentación el 28 de octubre de 2026. Los hooks se escriben en .agents/hooks.json para un proyecto y en ~/.gemini/config/hooks.json para el usuario. El evento que se dispara antes de usar una herramienta se llama PreToolUse, como en Claude Code. Para detener la acción, el hook devuelve decision: "deny" en el JSON. El tiempo de espera es de 30 segundos por defecto; la documentación no dice qué hacen los códigos de salida.

¿Cómo detiene un hook una acción?

El hook comunica su decisión de dos formas: con el código de salida o con el JSON que imprime. En las cinco herramientas, si el hook sale con el código 2, la acción se detiene y el agente recibe la explicación que el hook escribió en la salida de errores (stderr). Lo que cambia es qué hace cada herramienta cuando el hook sale con otro código de error o agota el tiempo de espera:

Fuente: la documentación de hooks de cada herramienta, 18 de octubre de 2026. «La documentación no lo dice»: en las páginas que leímos ese día no encontramos ninguna frase que describa este caso. El ajuste de Claude Code existe desde la versión 2.1.295. En Windows sin Git Bash, un hook de comando PreToolUse en forma de shell que falla puede detener la acción incluso sin onFailure.

Fíjate primero en la primera columna. En Unix, el código de error habitual es el 1. Claude Code, Cursor y Gemini CLI lo tratan como un error que no detiene la acción; Copilot, en cambio, la detiene con ese mismo código. Por eso la documentación de Claude Code pide usar exit 2 en los hooks que imponen una regla. Gemini CLI, por su parte, recomienda salir con 0 y escribir JSON incluso cuando se detiene la acción a propósito; si el hook imprime algo que no es JSON, deja pasar la acción.

El problema de la segunda columna cuesta más verlo: si la ruta del hook está mal o el script se cuelga, es como si la regla no existiera. Donde la acción tenga que detenerse sí o sí, usa el ajuste onFailure en Claude Code y failClosed en Cursor.

El ejemplo de abajo es una versión simplificada, para Claude Code, del control de merge de nuestro repositorio. Primero, el archivo de configuración:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/merge-gate.sh"
          }
        ]
      }
    ]
  }
}

Después, el script:

#!/bin/bash
# La entrada llega por stdin en JSON. Si no se puede leer, la acción se detiene.
COMMAND=$(jq -r '.tool_input.command // empty') || {
  echo "El hook no pudo leer la entrada; acción detenida." >&2
  exit 2
}

case "$COMMAND" in
  *"MERGE_APPROVED=1 gh pr merge"*) exit 0 ;;  # la aprobación va en el comando
  *"gh pr merge"*)
    echo "El merge lo decide el dueño del proyecto. Pregunta antes." >&2
    exit 2 ;;                                 # la acción se detiene
esac
exit 0                                        # sin objeciones

Cuando el script sale con 2, Claude Code no ejecuta el comando y le pasa al agente la frase que escribiste en la salida de errores. También puedes tomar la misma decisión saliendo con 0 y escribiendo JSON: en el campo permissionDecision pones deny (rechazar), ask (preguntar) o allow (permitir). Los hooks PreToolUse se ejecutan antes que los ajustes de permisos; una decisión deny vale incluso en el modo bypassPermissions, que se salta todas las preguntas de permiso. Codex todavía no admite el valor ask: da el hook por fallido y la acción sigue adelante.

¿Qué hooks usamos en nuestro repositorio?

El archivo .claude/settings.json de nuestro repositorio tiene 3 hooks. Escribimos cada uno después de un error que nos pasó, para que no se repitiera.

Al abrir la sesión. Cuando empieza una sesión, el hook SessionStart dice la rama actual, cuántos archivos tienen cambios sin commit y qué worktrees hay abiertos, y luego da un veredicto: «puedes trabajar en este directorio» o «abre antes un worktree aparte». Esa regla ya estaba escrita en CLAUDE.md. Pero una sesión la leyó, no la aplicó a su propia situación y planificó cambios en un directorio que cambió de rama tres veces en cuarenta minutos. Una regla que depende de que el agente se acuerde no protege; el hook hace la pregunta en lugar del agente.

Control de merge. En nuestro repositorio no hacemos merge de un pull request sin la aprobación del dueño del proyecto. Pero un agente, cuando pasan los tests, puede lanzar gh pr merge como siguiente paso. El hook PreToolUse que se ejecuta antes de la herramienta Bash detiene ese comando con el código 2 y le dice al agente que pida antes la aprobación. Cuando llega la aprobación, el comando se vuelve a ejecutar con una variable de entorno delante; así, la aprobación queda en el registro de la sesión, justo al lado del merge. Si el hook no puede leer la entrada, también detiene la acción: su primera versión salía con 0 y dejaba pasar los comandos que no podía leer.

Aviso de cambio de rama. El veredicto del inicio de sesión describe la situación de ese momento y puede quedar desfasado: si hay dos sesiones abiertas en la misma rama y una pasa a otra rama, cambia el sitio donde trabaja la otra. El segundo hook PreToolUse se ejecuta antes de las herramientas que editan archivos y, antes de cada edición, compara la rama y el commit con lo último que se le dijo a la sesión. Si no coinciden, le manda al agente una nota que empieza con esta línea: «drift: this checkout MOVED since the session was last told what it is». No detiene la acción; pasa la nota en el campo additionalContext y sale con 0.

Un hook de git es otra cosa. En el mismo repositorio hay también un hook pre-push: impide hacer push directamente a las ramas protegidas. No lo ejecuta el agente de programación, sino git; por eso alcanza a cualquiera que haga push desde ese clon, también a los agentes, usen la herramienta que usen. Los dos tipos se ejecutan solo en tu máquina: el pre-push se puede saltar con --no-verify, así que no sustituye a los controles del lado del servidor.

En qué se diferencian un hook, una skill y el archivo de reglas

Los tres deciden cómo se comporta el agente, pero entran en juego en momentos distintos. Esta es la comparación de la documentación de Claude Code:

Fuente: documentación de Claude Code, página «Extend Claude Code», 18 de octubre de 2026.

En resumen: si el agente tiene que decidir cómo aplicar los pasos, usa una skill; si la acción tiene que hacerse siempre igual, un hook. La lista de comprobación para publicar una versión es una skill; formatear cada archivo que se guarda es un hook. Como dice la misma página, una instrucción en el archivo de reglas o en una skill es una petición, no una garantía. Las reglas que no tienen vuelta atrás si se incumplen (un push a la rama equivocada, un merge antes de tiempo) no las dejes solo en manos de una instrucción.

Los hooks no se definen solo en el archivo de configuración: las skills y los subagentes también pueden llevar hooks en su propia definición. En Claude Code, el hook de un subagente solo vale mientras ese subagente está en marcha; el de una skill, en cambio, sigue ejecutándose hasta el final de la sesión una vez que se ha llamado a la skill. En Copilot, el hook de un agente personalizado solo se ejecuta mientras ese agente está seleccionado.

No conviertas todas las reglas en hooks

Un hook se ejecuta cada vez, y un hook mal escrito también falla cada vez. Antes de escribir uno, ten en cuenta esto:

• Deja en el archivo de reglas la información que no cambia. La documentación de Claude Code recomienda CLAUDE.md para los datos fijos. Un hook encaja mejor para pasar el estado del momento (en qué rama estás, cuál fue el último resultado de la CI).
• No dejes en manos de un hook las decisiones que piden criterio. Una simple comprobación de texto no puede responder «¿este cambio necesita tests?»; un paso así se escribe en una skill.
• No detengas el trabajo sin motivo. De nuestros tres hooks, dos solo informan y no detienen la acción. Un hook que detiene el trabajo sin razón acaba desactivado en poco tiempo, en vez de corregido.
• Un hook que busca texto no es una medida de seguridad. Nuestro control de merge no detecta un comando de merge escrito dentro de una variable o de un eval. Detiene al agente que se olvida de preguntar, no al que intenta saltarse la regla a propósito. La documentación de Codex también describe los hooks como «a useful guardrail, not a complete enforcement boundary». Para permisos y prohibiciones estrictos, la documentación de Claude Code recomienda las reglas de permisos.
• Revisa como si fuera código un hook que escribió otra persona. Los hooks de comando se ejecutan con tus permisos de usuario. Codex no ejecuta un hook que llega del repositorio hasta que lo revisas y lo apruebas; Cursor solo ejecuta los hooks del proyecto en espacios de trabajo de confianza, y Gemini CLI trata un hook modificado como un hook nuevo y no confiable.

Los hooks se ejecutan en tu máquina, antes de la acción; no miran si el código escrito es correcto. Eso le toca a la revisión de código: cuando diffox revisa un pull request, lee también el archivo de reglas del repositorio (AGENTS.md o, si no existe, CLAUDE.md) y usa como reglas de revisión las frases que dicen qué hay que hacer.