Chapitre 2 · Chapitre 2 · Les événements et les filtres
2.3 Les matchers : cibler les bons outils
Suis cette formation dans ton espace : ta progression est gardée, et la communauté répond à tes questions.
Suivre gratuitementSans 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, oufork. - Pour
Notification, il désigne le type de notification, par exemplepermission_prompt(une autorisation attend) ouidle_prompt. - Certains événements, comme
StopouUserPromptSubmit, 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,Bashprennent 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
Stopou utiliseFileChanged. - Ton matcher sur
Stopn'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|WriteouEdit, 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.