Accueil / Étendre : compétences, MCP, sous-agents, hooks, plugins

Les événements de hook, du déclenchement au message

PreToolUse peut empêcher un appel de se produire, PostToolUse ne peut plus que réagir après coup, et la décision d'un hook passe par des champs JSON précis, jamais par une phrase écrite sur la sortie standard.

Un hook PreToolUse s'exécute avant que l'outil ne s'active : sa décision peut empêcher l'appel de se produire. Un hook PostToolUse s'exécute après, une fois l'outil déjà lancé : sa décision ne peut plus rien empêcher, seulement réagir. Cette différence de moment détermine ce qu'un hook peut raisonnablement faire à chaque événement, et elle explique pourquoi un même mécanisme de blocage ne se comporte pas de la même façon selon l'événement qui le porte.

Une trentaine d'événements, du démarrage à la fin de session

La documentation officielle liste une trentaine d'événements du cycle de vie, de SessionStart et UserPromptSubmit jusqu'à PreCompact, WorktreeCreate ou SessionEnd. Chacun couvre un moment précis : un fichier qui change, une bascule de modèle, un sous-agent qui démarre ou se termine, une invite en cours d'expansion. Un automatisme voulu, présenté dans la leçon précédente comme la traduction mécanique d'une règle qu'on espérait voir suivie, se déclare toujours sur l'un de ces événements précis, jamais sur une intention générale.

Le délai d'expiration dépend du type de hook, pas seulement de l'événement

Un hook de type command, http ou mcp_tool dispose par défaut de six cents secondes pour répondre. Trois événements abaissent ce délai à trente secondes, UserPromptSubmit, PreModelSwitch et PostModelSwitch, et un seul le réduit à dix secondes, MessageDisplay. Un hook de type prompt garde un délai fixe de trente secondes, un hook de type agent un délai fixe de soixante secondes, quel que soit l'événement qui le déclenche. SessionEnd fonctionne différemment : l'ensemble de ses hooks partage un budget d'une seconde et demie, extensible jusqu'à soixante secondes seulement si un hook déclare explicitement un délai plus long.

Ce qui atteint réellement le modèle : des champs JSON, pas du texte libre

Un hook ne communique pas sa décision en écrivant une phrase sur la sortie standard. Il renvoie un objet JSON dont le champ hookSpecificOutput.permissionDecision porte la valeur allow ou deny, accompagné d'un permissionDecisionReason qui explique le choix, et le champ hookEventName reprend le nom exact de l'événement déclencheur. Pour ajouter de l'information sans rien bloquer, hookSpecificOutput.additionalContext insère du texte que le modèle lira comme s'il venait d'ailleurs dans la conversation.

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

Le code de sortie du script compte aussi, indépendamment du JSON : un code de sortie 2 bloque l'action même si le corps JSON affirmait allow. Cette règle souffre d'exceptions nommées, PermissionRequest, StopFailure hors d'une séquence terminale, PermissionDenied, et surtout PostToolUse et PostToolUseFailure, où le code 2 devient non bloquant et se contente d'être affiché à Claude via l'erreur standard : logique, puisque l'outil a déjà fini de s'exécuter quand ce hook se déclenche.

Déférer plutôt que décider

Le champ permissionDecision documente deux valeurs, allow et deny. Pour renvoyer la décision au flux de permission habituel plutôt que de la forcer, un hook n'écrit aucune troisième valeur dans ce champ : il sort avec le code 0 sans rapporter de décision, et l'appel continue son chemin normal d'approbation, comme si ce hook précis n'avait rien eu à en dire.