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

Los eventos de hook, del disparo al mensaje

PreToolUse puede impedir que una llamada se produzca, PostToolUse ya solo puede reaccionar después de los hechos, y la decisión de un hook pasa por campos JSON precisos, nunca por una frase escrita en la salida estándar.

Un hook PreToolUse se ejecuta antes de que la herramienta se active: su decisión puede impedir que la llamada se produzca. Un hook PostToolUse se ejecuta después, una vez que la herramienta ya se ha lanzado: su decisión ya no puede impedir nada, solo reaccionar. Esta diferencia de momento determina lo que un hook puede razonablemente hacer en cada evento, y explica por qué un mismo mecanismo de bloqueo no se comporta de la misma manera según el evento que lo porte.

Una treintena de eventos, del arranque al fin de sesión

La documentación oficial enumera una treintena de eventos del ciclo de vida, desde SessionStart y UserPromptSubmit hasta PreCompact, WorktreeCreate o SessionEnd. Cada uno cubre un momento preciso: un archivo que cambia, un cambio de modelo, un subagente que arranca o termina, una instrucción en curso de expansión. Un automatismo deseado, presentado en la lección anterior como la traducción mecánica de una regla que se esperaba ver seguida, siempre se declara sobre uno de esos eventos precisos, nunca sobre una intención general.

El plazo de expiración depende del tipo de hook, no solo del evento

Un hook de tipo command, http o mcp_tool dispone por defecto de seiscientos segundos para responder. Tres eventos rebajan ese plazo a treinta segundos, UserPromptSubmit, PreModelSwitch y PostModelSwitch, y uno solo lo reduce a diez segundos, MessageDisplay. Un hook de tipo prompt conserva un plazo fijo de treinta segundos, un hook de tipo agent un plazo fijo de sesenta segundos, sea cual sea el evento que lo dispare. SessionEnd funciona de otra manera: el conjunto de sus hooks comparte un presupuesto de un segundo y medio, ampliable hasta sesenta segundos solo si un hook declara explícitamente un plazo más largo.

Lo que realmente llega al modelo: campos JSON, no texto libre

Un hook no comunica su decisión escribiendo una frase en la salida estándar. Devuelve un objeto JSON cuyo campo hookSpecificOutput.permissionDecision lleva el valor allow o deny, acompañado de un permissionDecisionReason que explica la elección, y el campo hookEventName retoma el nombre exacto del evento que lo disparó. Para añadir información sin bloquear nada, hookSpecificOutput.additionalContext inserta texto que el modelo leerá como si viniera de otra parte de la conversación.

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Commande destructive detectee dans le motif teste"
  }
}

El código de salida del script también cuenta, con independencia del JSON: un código de salida 2 bloquea la acción incluso si el cuerpo JSON afirmaba allow. Esta regla sufre excepciones nombradas, PermissionRequest, StopFailure fuera de una secuencia terminal, PermissionDenied, y sobre todo PostToolUse y PostToolUseFailure, donde el código 2 se vuelve no bloqueante y se limita a mostrarse a Claude vía el error estándar: lógico, ya que la herramienta ya ha terminado de ejecutarse cuando se dispara ese hook.

Diferir en lugar de decidir

El campo permissionDecision documenta dos valores, allow y deny. Para devolver la decisión al flujo de permisos habitual en lugar de forzarla, un hook no escribe ningún tercer valor en ese campo: sale con el código 0 sin reportar decisión, y la llamada sigue su camino normal de aprobación, como si ese hook concreto no hubiera tenido nada que decir al respecto.