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

Hooks : automatiser le cycle de vie

Un hook est une action que le harnais exécute lui-même quand un événement précis du cycle de vie survient. Une consigne écrite en mémoire reste une préférence que le modèle peut oublier ; un hook déclaré une seule fois s'exécute à chaque occurrence, indépendamment de ce que le modèle retient à cet instant.

Un hook est une action que le harnais exécute lui-même quand un événement précis du cycle de vie survient, jamais une demande que le modèle interprète au moment d'agir. Écrire dans un fichier de mémoire la consigne de lancer les tests à chaque commit reste une préférence : le modèle peut l'oublier après une longue conversation ou une compaction. Un hook déclaré sur l'événement correspondant s'exécute à chaque occurrence, indépendamment de ce que le modèle retient à cet instant.

Le mécanisme : un événement, une commande, une décision

Un hook se déclare dans settings.json, ou dans le fichier hooks.json d'un plugin, associé à un événement du cycle de vie et à un type d'action : une commande shell, un appel HTTP, un outil MCP, une invite ou un agent. Quand l'événement survient, le harnais exécute cette action et attend en retour une décision, avant que la question n'atteigne le modèle.

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

Cette déclaration associe l'événement PreToolUse, restreint aux appels de l'outil Bash, à un script qui s'exécute avant chaque commande proposée. Chaque type de hook porte son propre délai d'expiration par défaut, différent selon l'événement qui le déclenche : la leçon suivante détaille ces délais événement par événement, ainsi que les champs JSON précis qu'un hook renvoie pour bloquer, autoriser ou enrichir ce que le modèle voit.

Hook contre règle de mémoire : ce que chacun garantit réellement

Une règle de mémoire dépend d'un modèle qui la relit et décide de l'appliquer, dans une fenêtre de contexte qui grossit au fil de la session. Un hook dépend du harnais, qui vérifie l'événement indépendamment de ce que la conversation contient à cet instant. La différence se voit surtout sur une session longue : une instruction répétée vingt fois dans un fichier de mémoire peut se diluer dans un contexte chargé, alors qu'un hook déclaré une seule fois continue de s'exécuter identiquement au millième appel comme au premier.

Traduire un automatisme voulu en hook plutôt qu'en note de mémoire relève de la fiabilité mécanique : l'un dépend d'une lecture attentive du modèle, l'autre d'un événement que le harnais constate lui-même.

Un hook qui refuse doit dire quoi faire

Une règle qui a coûté cher une fois se mécanise en hook PreToolUse. Le refus arrive avant l'effet, et son message nomme l'alternative : avec le code de sortie 2, ce que le script écrit sur la sortie d'erreur est le texte que Claude reçoit, et il corrige son appel au lieu de tourner en rond.

#!/bin/sh
# refuse et dit quoi faire à la place
echo "Refusé : ne supprimez pas, déplacez le fichier vers archives/." >&2
exit 2

Par défaut, un hook qui échoue laisse passer l'action : un chemin faux ou un script qui plante, et tout passe. Pour un hook de sécurité, déclarez "onFailure": "block" sur un hook de commande ou HTTP, ce qui bloque aussi l'action quand le hook ne démarre pas, expire ou sort avec un code inattendu. Pour savoir quels hooks existent, tapez /hooks : une liste unique, groupée par événement. Pour savoir si l'un a tourné, lancez claude --debug, qui journalise la commande, le plugin, l'issue et la durée de chaque hook de commande sur les appels d'outils, les invites, SessionStart et Stop, à sa fin. Une balise <system-reminder> écrite dans la sortie d'un hook est neutralisée avant d'atteindre Claude : une sortie de hook ne peut pas se faire passer pour une consigne système.