Résumé rapide : Les hooks Claude Code sont des scripts d'automatisation qui s'exécutent à des points spécifiques du cycle de vie pendant les sessions de codage IA, permettant aux développeurs d'exécuter des commandes personnalisées, de valider des actions, de formater du code, d'envoyer des notifications et de faire respecter les règles du projet. Ces hooks s'intègrent au flux de travail de Claude via des événements tels que SessionStart, PreToolUse et PostToolUse, prenant en charge les modèles d'exécution basés sur des commandes, HTTP et des invites, avec des délais d'attente configurables et un comportement de code de sortie.

Le système de hooks de Claude Code transforme l'assistant de codage IA d'un outil utile en un environnement de développement entièrement automatisé. La plupart des développeurs ne réalisent pas l'étendue du contrôle disponible via les hooks.

Voici le truc : les hooks ne servent pas seulement à exécuter des scripts après des modifications de fichiers. Ils fournissent des points d'interception tout au long du processus de prise de décision de Claude. Avant qu'il n'exécute une commande. Après l'échec d'un appel d'outil. Quand il a besoin d'une permission. Même avant de traiter les invites de l'utilisateur.

Ce guide couvre tout ce que la documentation officielle fournit, ainsi que des modèles pratiques qui, selon les discussions de la communauté, fonctionnent réellement dans les environnements de production.

Ce que font réellement les hooks Claude Code

Selon la documentation officielle de Claude Code, les hooks sont des commandes shell, des points d'extrémité HTTP ou des injections d'invites définis par l'utilisateur qui s'exécutent à des points spécifiques du cycle de vie de Claude Code. Ils reçoivent une entrée JSON structurée via stdin et contrôlent le flux de travail par des codes de sortie ou des réponses HTTP.

L'automatisation va plus loin que ce que suggèrent la plupart des guides. Les hooks peuvent bloquer complètement l'exécution des outils, injecter un contexte supplémentaire dans le raisonnement de Claude, déclencher des services externes et faire respecter des règles de validation que Claude doit respecter.

Il existe trois types de hooks principaux :

Hooks de commande : scripts shell qui communiquent via stdout, stderr et les codes de sortie
Hooks HTTP : points d'extrémité distants qui reçoivent des requêtes POST et renvoient des réponses JSON
Hooks d'invite : instructions dynamiques injectées dans le contexte de Claude à des événements spécifiques

Chaque type sert différents modèles d'automatisation. Les hooks de commande gèrent la validation locale et le formatage. Les hooks HTTP s'intègrent aux services externes et aux bases de données. Les hooks d'invite modifient le comportement de Claude sans processus externes.

Cycle de vie des hooks et système d'événements

La documentation officielle définit plusieurs événements de hook (SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, et d'autres) qui se déclenchent pendant le flux d'exécution de Claude Code. Comprendre quand chacun se déclenche détermine quelles automatisations deviennent possibles.

Claude Code hook events and their execution flow during a typical session

Événement	Quand il se déclenche	Peut bloquer
SessionStart	Lorsqu'une session commence ou reprend	Non
UserPromptSubmit	Lorsque vous soumettez une invite, avant que Claude ne la traite	Oui
PreToolUse	Avant qu'un appel d'outil ne s'exécute	Oui
PermissionRequest	Lorsqu'une boîte de dialogue d'autorisation apparaît	Oui
PostToolUse	Après la réussite d'un appel d'outil	Non
PostToolUseFailure	Après l'échec d'un appel d'outil	Non
Notification	Lorsque Claude Code envoie une notification	Non
SubmitMessage	Lorsque Claude soumet un message à l'utilisateur	Non
ContextCompaction	Lorsque la fenêtre de contexte approche de ses limites	Non

La capacité de blocage est la plus importante. Les hooks PreToolUse peuvent empêcher les opérations dangereuses avant qu'elles ne s'exécutent. Le code de sortie 1 bloque l'action. Le code de sortie 0 l'autorise. Le code de sortie 2 demande à Claude de reconsidérer.

Mais attendez. Les hooks PostToolUse ne peuvent pas annuler les actions car l'outil s'est déjà exécuté. Cette limitation façonne la manière dont la logique de validation est structurée. Les vérifications critiques appartiennent à PreToolUse. Le nettoyage et le formatage appartiennent à PostToolUse.

Parcourir les avantages des outils IA lors de la configuration de Claude Code

Si vous travaillez avec les hooks Claude Code, vous choisirez peut-être également d'autres outils IA autour de votre flux de travail. Get AI Perks collecte des crédits de démarrage et des réductions logicielles pour les outils d'IA et cloud en un seul endroit. La plateforme comprend plus de 200 offres, avec des conditions d'avantage et des conseils de réclamation pour chacune.

Vous recherchez des avantages pour Claude ou d'autres outils IA ?

Consultez Get AI Perks pour :

parcourir les offres de Claude et d'autres outils IA
comparer les conditions d'avantage avant de postuler
trouver des réductions de démarrage sur votre pile d'outils

👉 Visitez Get AI Perks pour explorer les avantages actuels des logiciels IA.

Configuration et structure de fichiers

Les hooks sont définis dans le fichier .claude/settings.json au sein d'un projet. Le schéma de configuration prend en charge les hooks globaux et les correspondances spécifiques aux outils qui filtrent l'exécution des hooks.

Structure de base d'un hook de commande :

{
“hooks”: [
{
“event”: “PostToolUse”,
“command”: “prettier –write”,
“args”: [“${file}”]
}
]
}

La variable ${file} est développée pour devenir le chemin d'accès réel du fichier à partir de l'entrée de l'outil. Selon la documentation officielle, les hooks prennent en charge ces expansions de variables dans les champs command et args.

Hiérarchie des emplacements des hooks

Claude Code vérifie plusieurs emplacements pour les définitions de hooks, avec un ordre de priorité clair :

Niveau projet : .claude/settings.json dans l'espace de travail actuel
Niveau utilisateur : ~/.claude/settings.json pour toutes les sessions
Fourni par le plugin : hooks groupés avec les plugins installés

Les hooks de projet remplacent les hooks utilisateur pour le même événement. Cela permet des règles de formatage spécifiques au projet tout en maintenant des gestionnaires de notification globaux.

Modèles de correspondance pour une exécution sélective

Le système de correspondance filtre les hooks pour des outils ou des conditions spécifiques. Sans correspondance, les hooks se déclenchent pour chaque occurrence de leur événement.

{
“hooks”: [
{
“event”: “PreToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “src/**/*.ts”
},
“command”: “./scripts/validate-typescript.sh”
}
]
}

Le champ pathPattern accepte la syntaxe glob. Le champ toolName correspond aux outils intégrés de Claude tels que edit_file, execute_command, read_file et create_directory.

Les discussions de la communauté révèlent que les combinaisons de correspondances fonctionnent avec une logique ET. Tous les correspondants spécifiés doivent correspondre pour que le hook s'exécute.

Hooks de commande : intégration de scripts shell

Les hooks de commande exécutent des commandes shell ou des scripts avec une entrée JSON structurée. Ils représentent le type de hook le plus courant pour l'automatisation locale.

La documentation officielle spécifie que les hooks de commande reçoivent du JSON via stdin avec la structure suivante :

{
“event”: “PreToolUse”,
“toolName”: “edit_file”,
“toolInput”: {
“path”: “src/app.ts”,
“content”: “…”
},
“sessionId”: “abc123”,
“turnId”: “turn-456”
}Les scripts analysent cette entrée pour prendre des décisions. Un hook de validation Python pourrait ressembler à :#!/usr/bin/env python3
import sys
import json

input_data = json.load(sys.stdin)
tool_input = input_data.get(‘toolInput’, {})
file_path = tool_input.get(‘path’, ”)

if file_path.startswith(‘protected/’):
print(“Cannot edit protected files”, file=sys.stderr)
sys.exit(1)

sys.exit(0)

Le code de sortie 0 autorise l'opération. Le code de sortie 1 la bloque et affiche le message stderr à Claude. Le code de sortie 2 déclenche un comportement spécial en fonction de l'événement.

Comportement du code de sortie 2

Selon la documentation officielle de référence des hooks, le code de sortie 2 a une signification spécifique à l'événement (PreToolUse : bloque et demande à reconsidérer ; UserPromptSubmit : fournit un contexte sans bloquer ; PermissionRequest : bloque l'autorisation) :

PreToolUse : bloque l'outil et demande à Claude de reconsidérer avec le message stderr comme contexte
UserPromptSubmit : fournit la sortie stderr comme contexte supplémentaire sans bloquer
PermissionRequest : bloque l'octroi de l'autorisation

Cela crée un terrain d'entente entre le blocage strict et l'autorisation. Claude reçoit des commentaires sur la raison pour laquelle l'action pourrait être problématique et peut ajuster son approche.

Hooks de commande asynchrones

Le drapeau async: true exécute les hooks en arrière-plan sans bloquer le flux de travail de Claude. Ceci est important pour les opérations lentes comme les notifications de déploiement ou la collecte de métriques.

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “execute_command”
},
“command”: “./scripts/log-to-analytics.sh”,
“async”: true,
“timeout”: 30
}

Lorsqu'un hook asynchrone se déclenche, Claude Code démarre le processus et continue immédiatement. Le champ timeout définit le temps d'exécution maximum en secondes. S'il n'est pas spécifié, les hooks asynchrones utilisent un délai d'attente par défaut de 10 minutes.

En réalité : les hooks asynchrones ne peuvent pas bloquer les opérations puisqu'ils s'exécutent après que Claude a continué. Ils fonctionnent pour la journalisation, les notifications et le nettoyage, pas pour la validation.

Hooks HTTP : intégration de services externes

Les hooks HTTP envoient des charges utiles JSON à des points d'extrémité distants et analysent les réponses pour le contrôle des décisions. Ils permettent l'intégration avec des services de validation, des bases de données et des outils tiers.

Configuration de base d'un hook HTTP :

{
“event”: “PreToolUse”,
“url”: “api.example.com/validate”,
“headers”: {
“Authorization”: “Bearer ${API_TOKEN}”
},
“timeout”: 5
}

La structure de la charge utile correspond à l'entrée du hook de commande mais arrive en tant que corps de la requête POST HTTP. La réponse détermine la prochaine action de Claude.

Gestion des réponses HTTP

Selon la documentation officielle, les hooks HTTP interprètent les réponses en fonction du code d'état et du contenu du corps :

Code d'état	Effet	Source du message
200	Autoriser l'opération	Corps de la réponse (facultatif)
400	Bloquer l'opération	Corps de la réponse affiché à Claude
500	Erreur de hook, autoriser l'opération	Journalisé mais non affiché à Claude
Autre	Autoriser l'opération	L'échec du hook ne bloque pas le flux de travail

Le corps de la réponse peut inclure un champ de message que Claude voit comme contexte. Cela permet aux services de validation d'expliquer pourquoi une opération a été bloquée.

Interpolation de variables d'environnement

Les hooks HTTP prennent en charge la syntaxe ${VAR} dans les champs url, headers et autres champs de chaîne de caractères. Les variables sont développées à partir de l'environnement où Claude Code s'exécute.

Selon la documentation officielle de MCP, l'expansion des variables d'environnement inclut une syntaxe de secours par défaut : ${VAR:-default} développe en VAR si défini, sinon utilise la valeur par défaut.

Contrainte de sécurité : selon le problème GitHub #28044, les hooks HTTP ne peuvent accéder qu'aux variables d'environnement explicitement listées dans le champ de configuration allowedEnvVars. Cela empêche l'exposition accidentelle d'informations d'identification.

Hooks d'invite : injection de contexte

Les hooks d'invite injectent des instructions dynamiques dans le contexte de Claude à des événements spécifiques. Ils modifient le comportement sans processus externes ni appels d'API.

{
“event”: “SessionStart”,
“prompt”: “You are working on a TypeScript project. Always use strict null checks and prefer async/await over promises.”
}

Le texte injecté fait partie des instructions système de Claude pour cette session. Les hooks d'invite peuvent également utiliser des variables de modèle qui se développent en fonction des données de l'événement.

Génération d'invites dynamiques

Selon la documentation officielle, les hooks d'invite prennent en charge les champs de commande qui génèrent des invites dynamiques :

{
“event”: “ContextCompaction”,
“type”: “prompt”,
“command”: “./scripts/generate-context-summary.sh”
}

La commande reçoit l'entrée JSON standard via stdin et produit le texte de l'invite sur stdout. Cela permet la génération d'instructions contextuelles basées sur l'état du projet.

Hooks basés sur des agents

Les hooks d'agents spécifient un sous-agent qui gère l'événement au lieu d'une injection directe d'invite. Le sous-agent reçoit le contexte de l'événement et peut effectuer un raisonnement en plusieurs étapes.

{
“event”: “PostToolUseFailure”,
“agent”: “debugger”,
“agentPrompt”: “A tool call failed. Analyze the error and suggest fixes.”
}

Le sous-agent nommé doit être défini dans la configuration du projet. Les hooks d'agents permettent une logique de décision complexe que l'injection d'invites simple ne peut pas fournir.

Modèles de hooks pratiques

Les discussions de la communauté et les exemples officiels révèlent des modèles d'automatisation qui fonctionnent de manière fiable en production.

Mise en forme automatique du code après les modifications

Le modèle le plus courant formate automatiquement le code après que Claude ait modifié des fichiers :

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “**/*.{js,ts,jsx,tsx}”
},
“command”: “prettier”,
“args”: [“–write”, “${toolInput.path}”]
}

La variable ${toolInput.path} est développée pour devenir le chemin du fichier modifié. PostToolUse garantit que le formatage se produit après les modifications réussies, mais ne bloque pas le flux de travail de Claude.

Bloquer les modifications de fichiers protégés

Les hooks PreToolUse appliquent les règles de protection des fichiers :

{
“event”: “PreToolUse”,
“matcher”: {
“toolName”: “edit_file”
},
“command”: “./scripts/check-protected.sh”
}

Le script valide le chemin cible par rapport aux modèles protégés et se termine avec le code 1 pour bloquer les modifications interdites.

Être informé lorsque Claude a besoin d'une entrée

Selon le guide de flux de travail officiel, les hooks de notification peuvent déclencher des alertes de bureau ou envoyer des messages à des services externes :

{
“event”: “Notification”,
“command”: “osascript”,
“args”: [“-e”, “display notification \”${message}\” with title \”Claude Code\””]
}

Cela se déclenche chaque fois que Claude Code envoie une notification, y compris lorsqu'il attend une entrée utilisateur ou après l'achèvement d'une tâche.

Réinjecter le contexte après la compaction

Les hooks ContextCompaction restaurent le contexte important lorsque la fenêtre de conversation se remplit :

{
“event”: “ContextCompaction”,
“type”: “prompt”,
“command”: “cat .claude/critical-context.md”
}

La sortie de la commande est réinjectée dans le contexte de Claude après que la compaction a supprimé les messages plus anciens. Cela évite la perte d'instructions critiques spécifiques au projet.

Auditer les modifications de configuration

Suivre quand Claude modifie les fichiers de configuration :

{
“event”: “PostToolUse”,
“matcher”: {
“toolName”: “edit_file”,
“pathPattern”: “**/{package.json,.env,*.config.*}”
},
“command”: “git”,
“args”: [“add”, “${toolInput.path}”],
“async”: true
}

L'exécution asynchrone empêche de bloquer Claude pendant la complétion des opérations git. Cela crée une piste d'audit des modifications de configuration sans staging manuel.

Sortie JSON et contrôle des décisions

Les hooks de commande peuvent générer du JSON structuré pour fournir des commentaires détaillés au-delà des simples codes de sortie. Selon la référence officielle, la sortie JSON permet des réponses à plusieurs champs que Claude interprète pour la prise de décision.

{
“allowed”: false,
“message”: “This file is protected by team policy”,
“suggestion”: “Create a new file in src/features/ instead”
}

Le champ allowed contrôle si l'opération progresse. Le message apparaît à Claude comme contexte. Le champ suggestion fournit des approches alternatives.

Pour que les hooks génèrent du JSON, ils doivent :

Écrire du JSON valide sur stdout
Se terminer avec le code 0 (pour autorisé) ou 1 (pour bloqué)
Inclure au minimum le champ booléen allowed

Claude Code analyse le JSON et l'utilise pour améliorer la boucle de rétroaction. Les codes de sortie déterminent toujours la décision principale, mais le JSON fournit un contexte plus riche.

Référence des champs d'entrée des hooks

Tous les hooks reçoivent un objet JSON via stdin avec des champs communs plus des données spécifiques à l'événement. Comprendre le schéma complet permet une logique de hook plus sophistiquée.

Hook input JSON schema showing common fields and event-specific extensions

Champs d'entrée courants

Chaque hook reçoit ces champs de base :

event : le nom de l'événement du hook (par ex. “PreToolUse”)
sessionId : identifiant unique de la session Claude actuelle
turnId : identifiant du tour de conversation actuel
timestamp : horodatage ISO 8601 lorsque l'événement s'est déclenché

Champs d'événement d'outil

Les événements PreToolUse, PostToolUse et PostToolUseFailure incluent :

toolName : nom de l'outil appelé (edit_file, execute_command, etc.)
toolInput : objet contenant les paramètres d'entrée de l'outil
toolResponse : données de sortie de l'outil (PostToolUse uniquement)
error : détails de l'erreur, y compris le message et le code (PostToolUseFailure uniquement)

La structure toolInput varie selon l'outil. Pour edit_file, elle contient path et content. Pour execute_command, elle contient command et args.

Champs d'événement de permission

Les événements PermissionRequest incluent :

permissionType : type de permission demandé (file_write, command_execute, etc.)
requestedAction : action spécifique nécessitant une permission
resourcePath : chemin de fichier ou identifiant de ressource affecté

Hooks d'outils MCP

Selon la documentation de référence des hooks, les hooks peuvent correspondre aux outils du protocole de contexte modèle (MCP) en utilisant le champ de correspondance mcpTool. Cela permet l'exécution de hooks lorsque Claude utilise des outils externes fournis par les serveurs MCP.

{
“event”: “PreToolUse”,
“matcher”: {
“mcpTool”: “database/query”
},
“command”: “./scripts/validate-sql.sh”
}

La valeur mcpTool correspond au nom de l'outil au format nom-serveur/nom-outil. Cela permet une logique de validation pour les requêtes de base de données, les appels d'API ou d'autres opérations externes.

Les demandes de fonctionnalités sur GitHub indiquent un intérêt croissant pour une intégration MCP plus approfondie, y compris des hooks qui peuvent inspecter les notifications du serveur MCP et répondre aux événements externes.

Considérations de sécurité

Les hooks s'exécutent avec les mêmes permissions que Claude Code lui-même. Cela crée des implications de sécurité pour les environnements multi-utilisateurs et les configurations partagées.

Sandbox d'exécution de commandes

Selon le problème GitHub #28044, les hooks HTTP passent par un proxy sandbox qui restreint l'accès réseau et filtre les variables d'environnement. Les hooks de commande n'ont pas de telles restrictions ; ils s'exécutent avec un accès shell complet.

La documentation recommande ces pratiques :

Ne jamais stocker d'informations d'identification dans les commandes de hook
Utiliser les variables d'environnement pour les données sensibles
Valider toutes les entrées des expansions ${...}
Mettre en place des limites de temps pour les services externes
Utiliser des hooks asynchrones pour les opérations non critiques afin d'éviter le blocage en cas d'échec

Isolation de l'exécution des hooks

Les hooks au niveau utilisateur dans ~/.claude/settings.json s'appliquent à tous les projets. Cela crée des risques lorsque l'on travaille sur différentes limites de confiance. Les hooks au niveau du projet remplacent les hooks utilisateur mais ne peuvent pas les désactiver complètement.

Le menu /hooks dans Claude Code affiche tous les hooks actifs pour la session en cours. L'examen de cette liste avant de travailler sur des projets sensibles aide à identifier les problèmes de sécurité potentiels.

Débogage et dépannage

Les échecs de hooks ne sont pas toujours clairement visibles dans la conversation de Claude. La documentation officielle fournit plusieurs approches de débogage.

Journaux d'exécution des hooks

Claude Code enregistre l'exécution des hooks dans la sortie de débogage de la session. Selon le guide de dépannage, l'activation de la journalisation de débogage révèle :

Quels hooks ont correspondu pour chaque événement
L'entrée JSON envoyée à chaque hook
La sortie stdout et stderr des processus de hook
Les codes de sortie et le temps d'exécution
Les codes et corps de réponse HTTP pour les hooks HTTP

Activez la journalisation de débogage en définissant CLAUDE_DEBUG=1 dans l'environnement avant de démarrer Claude Code.

Tester les hooks indépendamment

Les hooks de commande peuvent être testés en dehors de Claude Code en construisant manuellement une entrée JSON :

echo ‘{“event”:”PreToolUse”,”toolName”:”edit_file”,”toolInput”:{“path”:”test.txt”}}’ | ./scripts/my-hook.sh

Cela valide la logique du hook sans déclencher les opérations réelles de Claude. Le code de sortie et la sortie stdout/stderr doivent correspondre au comportement attendu.

Échecs courants des hooks

Les discussions de la communauté identifient ces problèmes fréquents :

Erreurs de délai d'attente : le délai d'attente par défaut de 10 minutes est trop court pour les opérations lentes - augmentez avec le champ timeout
Échecs d'expansion de chemin : les variables comme ${file} sont indéfinies pour les événements qui n'incluent pas de contexte de fichier
Erreurs d'autorisation : les scripts de hook n'ont pas les permissions d'exécution - exécutez chmod +x script.sh
Erreurs d'analyse JSON : sortie JSON mal formée des hooks - validez avec jq avant de renvoyer
Indisponibilité des variables d'environnement : les variables ne sont pas propagées au processus de hook - vérifiez l'environnement de Claude Code

Implications de performance des hooks

Les hooks synchrones bloquent le flux de travail de Claude jusqu'à leur achèvement. Le délai d'attente par défaut de 10 minutes empêche les blocages indéfinis, mais même de courts retards s'accumulent sur plusieurs opérations.

Les praticiens rapportent que les hooks de validation simples ont un impact négligeable sur les performances. Les hooks de formatage de fichiers ont un impact notable mais acceptable sur les performances. Les appels d'API externes peuvent créer des frictions dans le flux de travail. Les opérations de calcul intensif bénéficient de l'exécution asynchrone.

Regroupement de hooks

Plusieurs hooks peuvent correspondre au même événement. Selon la documentation de référence, les hooks s'exécutent séquentiellement dans l'ordre de définition. Si un hook bloque l'opération, les hooks restants ne s'exécutent pas.

Ceci est important pour les performances. Cinq hooks synchrones à 200 ms chacun ajoutent une seconde par événement. Combiner les validations connexes en un seul hook réduit les frais généraux.

Modèles avancés

Au-delà de l'automatisation de base, les hooks permettent une personnalisation sophistiquée du flux de travail.

Chaînes de hooks avec état

Les hooks peuvent maintenir un état entre les exécutions à l'aide de fichiers ou de bases de données. Un hook PostToolUse pourrait enregistrer les opérations réussies qu'un hook PreToolUse valide ensuite :

#!/bin/bash
# Enregistrer les modifications réussies
echo “${toolInput.path}” >> .claude/edit-history.txt

Un hook PreToolUse compagnon pourrait vérifier cet historique pour empêcher les opérations redondantes ou faire respecter les contraintes d'ordre.

Activation conditionnelle des hooks

Les variables d'environnement contrôlent le comportement des hooks au moment de l'exécution. La définition de CLAUDE_SKIP_HOOKS=1 désactive les hooks pour les situations d'urgence.

Les hooks eux-mêmes peuvent vérifier les indicateurs d'environnement :

#!/bin/bash
if [ “$STRICT_MODE” = “1” ]; then
# Appliquer une validation stricte
exit 1
fi
exit 0

Cela permet un comportement en mode développement par rapport au mode production sans modifications de configuration.

Validation en plusieurs étapes

Les hooks PreToolUse peuvent implémenter une validation à plusieurs niveaux où le code de sortie 2 permet à Claude de continuer avec des avertissements :

Échecs critiques (sortie 1) : bloquent les opérations dangereuses
Avertissements légers (sortie 2) : alertent Claude pour qu'il reconsidère
Réussite avec contexte (sortie 0 + JSON) : fournissent des informations supplémentaires

Cela crée un spectre de validation plus nuancé qu'une simple interdiction/autorisation binaire.

Intégration avec CI/CD

Selon la documentation officielle d'intégration de plateforme, Claude Code s'exécute dans les environnements CI/CD pour la revue automatique de code et le triage des problèmes. Les hooks étendent cette automatisation.

Les flux de travail GitHub Actions peuvent définir des hooks qui appliquent les politiques de l'équipe pendant les sessions automatisées :

-- name: Run Claude Code with strict hooks
env:
STRICT_MODE: 1
run: |
claude “Review this PR and suggest improvements”

Le drapeau STRICT_MODE active la logique de validation conditionnelle dans les scripts de hook. Cela garantit que les sessions automatisées suivent des règles plus rigides que le développement interactif.

Génération de piste d'audit

Les hooks PostToolUse dans les environnements CI créent des journaux d'audit détaillés de toutes les opérations de Claude :

{
“event”: “PostToolUse”,
“command”: “./scripts/log-to-database.sh”,
“async”: true
}

La journalisation en arrière-plan n'a pas d'impact sur les performances mais fournit un historique complet des opérations pour la conformité et le débogage.

Le menu /hooks

Claude Code fournit une commande /hooks qui affiche tous les hooks actifs pour la session en cours. Selon la documentation officielle, ce menu affiche :

Type d'événement du hook
Modèles de correspondance
Commande ou point de terminaison d'URL
Si le hook s'exécute en mode asynchrone
Source de configuration (projet, utilisateur ou plugin)

La sélection d'un hook affiche sa configuration complète et permet sa désactivation temporaire pour la session en cours.

Désactiver ou supprimer les hooks

Les hooks peuvent être désactivés sans supprimer la configuration en ajoutant “enabled”: false à la définition du hook. Cela préserve la configuration tout en empêchant l'exécution.

Pour supprimer définitivement un hook, supprimez son entrée du fichier settings.json approprié. Les modifications prennent effet au redémarrage de la session suivante ou lors de l'exécution de /reload.

Hooks dans les compétences et les agents

Selon la documentation officielle, les hooks définis dans la configuration des compétences ou des sous-agents s'appliquent uniquement lorsque cette compétence ou cet agent s'exécute. Cela permet une automatisation spécialisée pour des flux de travail spécifiques.

Un sous-agent de débogage peut inclure des hooks qui enregistrent tous les appels d'outils :

{
“name”: “debugger”,
“hooks”: [
{
“event”: “PostToolUse”,
“command”: “./scripts/log-debug.sh”,
“async”: true
}
]
}

Ces hooks ne se déclenchent que pendant les sessions de l'agent débogueur, et non pendant le fonctionnement normal de Claude Code.

Référencer des scripts par chemin

Les commandes de hook prennent en charge les chemins relatifs et absolus. Les chemins relatifs sont résolus à partir de la racine du projet où Claude Code s'exécute.

Meilleures pratiques des discussions de la communauté :

Stocker les scripts de hook dans le répertoire .claude/hooks/
Utiliser des noms descriptifs : validate-typescript.sh et non hook1.sh
Rendre les scripts exécutables : chmod +x .claude/hooks/*.sh
Inclure une ligne shebang : #!/usr/bin/env bash ou #!/usr/bin/env python3
Ajouter une gestion des erreurs avec set -e dans les scripts bash

Capacités futures des hooks

Les demandes de fonctionnalités sur GitHub révèlent des améliorations prévues et demandées pour les hooks :

Hooks de script en ligne : définir la logique du hook directement dans settings.json sans fichiers externes
Intégration d'outils MCP : invoquer les outils du serveur MCP à partir des hooks au lieu des commandes shell
Collaboration multi-agents : hooks qui coordonnent entre les instances Claude sur différentes machines
Typage amélioré : définitions de types TypeScript pour les schémas d'entrée/sortie des hooks

Selon le problème GitHub #4274, la demande de types de hooks intégrés (outil MCP, script en ligne, appel API) vise à simplifier la configuration et à améliorer l'expérience développeur.

Foire aux questions

Les hooks peuvent-ils empêcher Claude d'exécuter des commandes dangereuses ?

Oui. Les hooks PreToolUse peuvent bloquer l'exécution de n'importe quel outil en se terminant avec le code 1. Cela inclut les modifications de fichiers, l'exécution de commandes et les appels d'outils MCP. Le hook reçoit l'entrée complète de l'outil et peut valider selon n'importe quel critère avant d'autoriser l'opération.

Comment déboguer un hook qui ne fonctionne pas ?

Activez la journalisation de débogage avec CLAUDE_DEBUG=1 avant de démarrer Claude Code. Vérifiez les journaux de session pour les détails d'exécution des hooks, y compris quels hooks ont correspondu, l'entrée JSON envoyée, la sortie stdout/stderr et les codes de sortie. Testez les hooks indépendamment en transmettant un JSON d'exemple au script de hook.

Les hooks fonctionnent-ils avec toutes les plateformes Claude Code ?

Les hooks fonctionnent dans l'application CLI, de bureau et l'extension VS Code. Selon la documentation officielle, les hooks s'exécutent partout où Claude Code s'exécute avec accès au système de fichiers. Claude basé sur navigateur et les applications mobiles ne prennent pas en charge les hooks en raison de contraintes de sandboxing.

Les hooks peuvent-ils modifier les réponses ou le comportement de Claude ?

Les hooks d'invite injectent des instructions qui influencent le comportement de Claude. Les hooks d'agents délèguent la gestion des événements à des sous-agents spécialisés. Cependant, les hooks ne peuvent pas modifier directement le texte généré ou le processus de raisonnement de Claude ; ils fonctionnent en fournissant un contexte et en bloquant les opérations.

Quelle est la différence entre les hooks asynchrones et synchrones ?

Les hooks synchrones bloquent le flux de travail de Claude jusqu'à l'achèvement ou le délai d'attente. Les hooks asynchrones s'exécutent en arrière-plan sans bloquer. Les hooks synchrones peuvent empêcher les opérations via des codes de sortie. Les hooks asynchrones ne peuvent pas bloquer car Claude continue avant que le hook ne soit terminé. Utilisez les hooks asynchrones pour la journalisation et les notifications, les hooks synchrones pour la validation.

Comment partager des hooks avec une équipe ?

Commitez le fichier .claude/settings.json dans le contrôle de version. Les hooks au niveau du projet s'appliquent à tous les membres de l'équipe qui clonent le dépôt. Pour les politiques à l'échelle de l'organisation, les équipes peuvent maintenir un fichier de paramètres partagé au niveau de l'utilisateur que les membres copient dans ~/.claude/settings.json.

Les hooks HTTP peuvent-ils appeler des API internes derrière des pare-feu ?

Oui, si Claude Code s'exécute dans un environnement ayant un accès réseau à ces API. Les hooks HTTP effectuent des requêtes POST standard à partir de la machine exécutant Claude Code. Les pare-feu d'entreprise et les VPN s'appliquent normalement. Le proxy sandbox mentionné dans la documentation contrôle l'exposition des variables d'environnement, pas le routage réseau.

Les hooks augmentent-ils l'utilisation des tokens de Claude Code ?

Les hooks d'invite injectent du texte dans le contexte de Claude, ce qui consomme des tokens. Les hooks de commande et HTTP n'affectent pas directement l'utilisation des tokens, mais leur sortie (messages d'erreur, suggestions) fait partie du contexte de conversation. Le code de sortie 2 avec des messages explicatifs ajoute plus de contexte que le code de sortie 1 avec un blocage simple.

Conclusion

Les hooks Claude Code transforment l'assistant IA d'un outil puissant en une plateforme de développement entièrement automatisée. Le système d'événements fournit des points d'interception tout au long du flux de travail de Claude, de l'initialisation de la session à la compaction du contexte.

Les hooks de commande gèrent la validation locale et le formatage. Les hooks HTTP intègrent des services externes et des bases de données. Les hooks d'invite modifient le comportement par injection de contexte. Ensemble, ils permettent des modèles d'automatisation qui appliquent les politiques d'équipe, maintiennent la qualité du code et s'intègrent à l'infrastructure de développement existante.

Le système de correspondance filtre les hooks pour des outils et des modèles de fichiers spécifiques. Les codes de sortie et la sortie JSON contrôlent le flux de décision. L'exécution asynchrone empêche le blocage sur les opérations lentes. Le schéma de configuration complet prend en charge tout, du simple formatage automatique à la validation complexe en plusieurs étapes.

Commencez par des hooks PostToolUse de base pour le formatage du code. Ajoutez la validation PreToolUse au fur et à mesure que les politiques émergent. Expérimentez avec les hooks d'invite pour la modification du comportement. Créez des intégrations HTTP pour une application à l'échelle de l'équipe.

Consultez la documentation officielle de Claude Code pour la référence complète des hooks et le schéma de configuration mis à jour à mesure que de nouvelles fonctionnalités sont publiées.