Skip to content
Floskool

Chapter 2 · Chapitre 2 · Les événements et les filtres

2.3 Les matchers : cibler les bons outils

Free lesson 7 minGroup Claude Code & IA

Follow this course in your space: your progress is saved, and the community answers your questions.

Follow for free

Sans matcher, un hook se déclenche à chaque occurrence de son événement. Pour PostToolUse, ce serait après chaque lecture, chaque recherche, chaque commande : beaucoup trop.

Le matcher filtre. Pour les événements liés aux outils, il porte sur le nom de l'outil. Les exemples les plus courants :

  • Edit|Write : les modifications et créations de fichiers ;
  • Bash : les commandes shell ;
  • mcp__.* : tous les outils fournis par des serveurs MCP ;
  • vide, absent ou * : tout.

La barre verticale | sépare les possibilités. La doc précise qu'une virgule fonctionne de la même façon : "Edit, Write" équivaut à "Edit|Write".

Liste simple ou expression régulière

La documentation distingue deux cas. Si ton matcher ne contient que des lettres, des chiffres, _, -, des espaces, des virgules et des |, c'est une liste de noms exacts. Dès qu'il contient un autre caractère (un point, une étoile…), il est lu comme une expression régulière (un motif de recherche de texte) non ancrée. Conséquence donnée par la doc : Edit.* correspond aussi à NotebookEdit. Pour viser exactement un nom avec une expression régulière, écris ^Edit$.

Attention à la casse

Les matchers sont sensibles à la casse. edit|write ne correspondra jamais à l'outil Edit. C'est l'une des causes les plus fréquentes de « mon hook ne se déclenche pas ».

Les autres événements ont leurs propres matchers

  • Pour SessionStart, le matcher indique comment la session a démarré : startup, resume, clear, compact, ou fork.
  • Pour Notification, il désigne le type de notification, par exemple permission_prompt (une autorisation attend) ou idle_prompt.
  • Certains événements, comme Stop ou UserPromptSubmit, n'utilisent pas de matcher : la doc indique qu'il y est ignoré sans avertissement, et le hook se déclenche toujours.

Une limite à connaître

Claude peut aussi créer ou modifier un fichier en lançant une commande shell (par exemple avec sed ou une redirection >). Dans ce cas, l'outil utilisé est Bash, pas Edit ni Write : ton hook Edit|Write ne verra rien. La doc suggère, si tu dois tout voir, d'ajouter un hook Stop qui analyse le dossier une fois par tour, ou d'utiliser l'événement FileChanged, qui réagit quand un fichier surveillé change sur le disque.

Bloc à copier : trois matchers courants

{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [{ "type": "command", "command": "echo 'commande shell' >&2" }] }
    ],
    "PostToolUse": [
      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "echo 'fichier modifié' >&2" }] }
    ],
    "SessionStart": [
      { "matcher": "compact", "hooks": [{ "type": "command", "command": "echo 'Rappel : Prettier, pas de .env'" }] }
    ]
  }
}

Ces commandes echo ne font rien de dangereux : elles servent à observer quand chaque hook se déclenche. Le >&2 envoie le texte sur la sortie d'erreur (stderr), qui part dans le journal de débogage sans gêner Claude. Pense à les retirer une fois tes tests finis.

Exercice

Quel matcher écrire pour un hook qui doit réagir (1) à toutes les commandes shell, (2) aux modifications de fichiers uniquement, (3) au démarrage après une compaction, (4) seulement quand une autorisation attend ?

Corrigé : (1) Bash sur PreToolUse ou PostToolUse ; (2) Edit|Write ; (3) compact sur SessionStart ; (4) permission_prompt sur Notification.

Si ça coince

  • Ton hook ne se déclenche jamais. Vérifie la casse : Edit, Write, Bash prennent une majuscule.
  • Ton hook se déclenche trop souvent. Ton matcher est peut-être vide, ou une expression régulière trop large comme Edit.*. Resserre-le.
  • Un fichier modifié par une commande shell n'est pas formaté. L'outil était Bash. Ajoute un contrôle sur Stop ou utilise FileChanged.
  • Ton matcher sur Stop n'a aucun effet. Il est ignoré sur cet événement : retire-le pour éviter la confusion.

À retenir

  • Le matcher filtre par nom d'outil pour PreToolUse et PostToolUse.
  • Edit|Write ou Edit, Write : liste de noms exacts ; un point ou une étoile en fait une expression régulière.
  • Les matchers sont sensibles à la casse.
  • Les écritures faites via Bash échappent à un matcher Edit|Write.