Hooks Claude Code : événements, exemples et fonctionnement

Les événements des hooks Claude Code

La référence recense plus de trente événements. Voici ceux qu’utilisent la plupart des hooks ; un matcher limite un hook à certains outils, fichiers ou sources.

Où placer les hooks

Exemples de hooks Claude Code, étape par étape

Ajoutez chaque bloc sous la clé hooks d’un fichier de paramètres ; si le fichier contient déjà un objet hooks, ajoutez l’événement comme clé voisine au lieu de le remplacer. Lancez /hooks pour vérifier que Claude Code l’a chargé. Vous pouvez aussi demander à Claude d’écrire le hook pour vous.

1. Recevoir une notification sur le bureau quand Claude a besoin de vous

   Un hook Notification dans ~/.claude/settings.json. Celui-ci utilise osascript sur macOS ; utilisez notify-send sous Linux ou PowerShell sous Windows.

   {
     "hooks": {
       "Notification": [
         {
           "matcher": "",
           "hooks": [
             {
               "type": "command",
               "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
             }
           ]
         }
       ]
     }
   }

2. Formater automatiquement chaque fichier que Claude modifie

   Un hook PostToolUse avec le matcher Edit|Write lit avec jq le chemin modifié dans le JSON reçu sur stdin et lance Prettier dessus. Placez-le dans .claude/settings.json pour que toute l’équipe en profite.

   {
     "hooks": {
       "PostToolUse": [
         {
           "matcher": "Edit|Write",
           "hooks": [
             { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }
           ]
         }
       ]
     }
   }

3. Bloquer une commande dangereuse

   Un hook PreToolUse sur Bash exécute ce script. Le code de sortie 2 bloque l’appel, et ce que vous écrivez sur stderr devient le retour adressé à Claude, qui peut alors changer de cap. Sortir avec 0 signifie aucune décision : les autorisations normales s’appliquent toujours.

   #!/bin/bash
   # .claude/hooks/block-drop-table.sh, exécuté comme hook PreToolUse sur Bash
   INPUT=$(cat)
   COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command')
   
   if echo "$COMMAND" | grep -q "drop table"; then
     echo "Blocked: dropping tables is not allowed" >&2  # devient le retour adressé à Claude
     exit 2                                               # 2 = bloquer l’action
   fi
   
   exit 0  # aucune décision : le flux d’autorisations normal s’applique

4. Faire travailler Claude jusqu’à ce que la tâche soit finie

   Un hook Stop de type prompt demande à un modèle si tout est terminé. S’il répond ok: false, Claude continue de travailler avec le reason comme instruction suivante. C’est l’exemple classique de hook Stop.

   {
     "hooks": {
       "Stop": [
         {
           "hooks": [
             {
               "type": "prompt",
               "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
             }
           ]
         }
       ]
     }
   }

Source : documentation de Claude Code, Automate actions with hooks

Comment les hooks décident de ce qui se passe

• Entrée : chaque hook reçoit l’événement en JSON sur stdin, par exemple le nom de l’outil et tool_input, l’ID de session et cwd.
• Sortie 0 : aucune objection. Pour quelques événements, comme SessionStart et UserPromptSubmit, le texte écrit sur stdout est ajouté au contexte de Claude.
• Sortie 2 : blocage, lorsque l’événement le permet. Stderr est renvoyé à Claude ou à vous, selon l’événement.
• JSON sur stdout : un contrôle plus fin, comme hookSpecificOutput avec une décision d’autorisation, updatedInput pour réécrire l’entrée d’un outil, ou additionalContext.
• Autres codes de sortie : en général une erreur non bloquante, sauf si le hook définit onFailure: "block".
• Les hooks correspondant à un même événement s’exécutent en parallèle.

Hooks command, prompt, agent et HTTP

Hooks, skills ou CLAUDE.md, et autres pièges

• Le CLAUDE.md et les skills sont des instructions que Claude suit en général ; les hooks s’exécutent toujours. Mettez dans un hook tout ce qui ne doit jamais être sauté.
• PostToolUse ne peut pas annuler une action déjà exécutée ; utilisez PreToolUse pour l’empêcher.
• Stop se déclenche chaque fois que Claude termine une réponse, pas seulement à la fin d’une tâche, et pas lors d’une interruption par l’utilisateur.
• Les hooks ne peuvent ni lancer de commandes slash ni appeler eux-mêmes des outils ; ils ne répondent que par codes de sortie, stdout, stderr ou JSON.
• "disableAllHooks": true désactive les hooks ; les hooks gérés continuent de s’exécuter, sauf si les paramètres gérés les désactivent aussi.
• Les hooks sont propres à votre installation de Claude Code. Les contrôles à l’échelle de l’organisation sur tous les produits Claude relèvent d’une autre fonctionnalité : les inference hooks de Claude.
• Un hook PreToolUse qui filtre la sortie des tests est aussi l’un des meilleurs moyens de réduire la consommation de tokens.

Les hooks tiennent Claude Code dans le droit chemin. Crewmark le fait travailler.

Les hooks sont ce qui rend sûr un agent laissé sans surveillance : formatage, tests et garde-fous s’exécutent à chaque fois. Crewmark transforme une session Claude Code, Codex, DeepSeek Harness ou OpenCode en employé IA avec un rôle, un objectif et des horaires de travail, et la réveille à chaque pulsation pour qu’elle prenne la prochaine issue d’un tableau, avec les hooks de votre projet en place.

1. Committez vos hooks

   Les hooks de .claude/settings.json se chargent dans la session de l’employé comme dans la vôtre : ses modifications sont formatées et ses commandes risquées bloquées.

2. Laissez la pulsation lancer le travail

   Pendant ses horaires de travail, l’employé se réveille toutes les 15, 30 ou 60 minutes dans la même conversation ; voir comment rendre Claude Code proactif.

3. Ne répondez qu’à ce qui a besoin de vous

   Il commente ses issues et vous écrit quand il a besoin d’une décision. Découvrez ce qu’est un employé IA.

FAQ hooks Claude Code