Inicio / Extender: habilidades, MCP, subagentes, hooks, plugins

Hooks: automatizar el ciclo de vida

Un hook es una acción que el arnés ejecuta él mismo cuando ocurre un evento preciso del ciclo de vida. Una consigna anotada en la memoria sigue siendo una preferencia que el modelo puede olvidar; un hook declarado una sola vez se ejecuta en cada ocurrencia, independientemente de lo que el modelo recuerde en ese instante.

Un hook es una acción que el arnés ejecuta él mismo cuando ocurre un evento preciso del ciclo de vida, nunca una petición que el modelo interpreta en el momento de actuar. Anotar en un archivo de memoria «lanza los tests cada vez que hagas un commit» sigue siendo una preferencia: el modelo puede olvidarla después de una conversación larga o una compactación. Un hook declarado sobre el evento correspondiente se ejecuta en cada ocurrencia, independientemente de lo que el modelo recuerde en ese instante.

El mecanismo: un evento, un comando, una decisión

Un hook se declara en settings.json, o en el archivo hooks.json de un plugin, asociado a un evento del ciclo de vida y a un tipo de acción: un comando de shell, una llamada HTTP, una herramienta MCP, una instrucción o un agente. Cuando el evento ocurre, el arnés ejecuta esa acción y espera a cambio una decisión, antes de que la cuestión llegue al modelo.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command", "command": "./verifier-avant-commande.sh" }
        ]
      }
    ]
  }
}

Esta declaración asocia el evento PreToolUse, restringido a las llamadas de la herramienta Bash, a un script que se ejecuta antes de cada comando propuesto. Cada tipo de hook tiene su propio plazo de expiración por defecto, distinto según el evento que lo dispara: la lección siguiente detalla esos plazos evento por evento, así como los campos JSON precisos que un hook devuelve para bloquear, autorizar o enriquecer lo que ve el modelo.

Hook contra regla de memoria: qué garantiza cada uno

Una regla de memoria depende de un modelo que la relee y decide aplicarla, en una ventana de contexto que crece a lo largo de la sesión. Un hook depende del arnés, que verifica el evento independientemente de lo que contenga la conversación en ese instante. La diferencia se nota sobre todo en una sesión larga: una instrucción repetida veinte veces en un archivo de memoria puede diluirse en un contexto cargado, mientras que un hook declarado una sola vez sigue ejecutándose de forma idéntica en la llamada número mil igual que en la primera.

Un hook que rechaza debe decir qué hacer

Una regla que ya te costó cara una vez se mecaniza como un hook PreToolUse. El rechazo llega antes del efecto, y su mensaje nombra la alternativa: con el código de salida 2, lo que el script escribe en la salida de error es el texto que recibe Claude, que corrige su llamada en lugar de dar vueltas.

#!/bin/sh
# rechaza y dice qué hacer en su lugar
echo "Rechazado: no borre, mueva el archivo a archives/." >&2
exit 2

Por defecto, un hook que falla deja pasar la acción: una ruta errónea o un script que se cae, y todo pasa. Para un hook de seguridad, declara "onFailure": "block" en un hook de comando o HTTP, que también bloquea la acción cuando el hook no arranca, expira o sale con un código inesperado. Para saber qué hooks existen, escribe /hooks: una lista única, agrupada por evento. Para saber si uno se ejecutó, lanza claude --debug, que registra el comando, el plugin, el resultado y la duración de cada hook de comando en las llamadas a herramientas, los prompts, SessionStart y Stop al terminar. Una etiqueta <system-reminder> escrita en la salida de un hook se neutraliza antes de llegar a Claude: la salida de un hook no puede hacerse pasar por una instrucción del sistema.