claude-code-best-practice/fr/.claude/hooks/HOOKS-README.md

HOOKS-README

Contient tous les détails, scripts et instructions pour les hooks.

Vue d’ensemble des événements de hook - 27 hooks officiels

Claude Code fournit plusieurs événements de hook qui s’exécutent à différents moments du workflow :

#	Hook	Description	Options
1	PreToolUse	S’exécute avant les appels d’outils (peut les bloquer)	async, timeout: 5000, tool_use_id
2	PermissionRequest	S’exécute lorsque Claude Code demande une permission à l’utilisateur	async, timeout: 5000, permission_suggestions
3	PostToolUse	S’exécute après la réussite des appels d’outils	async, timeout: 5000, tool_response, tool_use_id
4	PostToolUseFailure	S’exécute après l’échec d’appels d’outils	async, timeout: 5000, error, is_interrupt, tool_use_id
5	UserPromptSubmit	S’exécute lorsque l’utilisateur soumet un prompt, avant que Claude le traite	async, timeout: 5000, prompt
6	Notification	S’exécute lorsque Claude Code envoie des notifications	async, timeout: 5000, notification_type, message, title
7	Stop	S’exécute lorsque Claude Code termine sa réponse	async, timeout: 5000, stop_reason, last_assistant_message, stop_hook_active
8	SubagentStart	S’exécute lorsque les tâches de sous-agent démarrent	async, timeout: 5000, agent_id, agent_type
9	SubagentStop	S’exécute lorsque les tâches de sous-agent se terminent	async, timeout: 5000, agent_id, agent_type, last_assistant_message, agent_transcript_path, stop_hook_active
10	PreCompact	S’exécute avant que Claude Code lance une opération de compactage	async, timeout: 5000, once, compact_trigger
11	PostCompact	S’exécute après la fin d’une opération de compactage Claude Code	async, timeout: 5000, compact_trigger
12	SessionStart	S’exécute lorsque Claude Code démarre une nouvelle session ou reprend une session existante	async, timeout: 5000, once, agent_type, model, source
13	SessionEnd	S’exécute lorsqu’une session Claude Code se termine	async, timeout: 5000, once, reason
14	Setup	S’exécute lorsque Claude Code lance la commande /setup pour initialiser un projet	async, timeout: 30000
15	TeammateIdle	S’exécute lorsqu’un agent teammate devient inactif (agent teams expérimentaux)	async, timeout: 5000, teammate_name, team_name
16	TaskCreated	S’exécute lorsqu’une tâche est créée via l’outil TaskCreate (agent teams expérimentaux)	async, timeout: 5000, task_id, task_subject, task_description, teammate_name, team_name
17	TaskCompleted	S’exécute lorsqu’une tâche en arrière-plan se termine (agent teams expérimentaux)	async, timeout: 5000, task_id, task_subject, task_description, teammate_name, team_name
18	ConfigChange	S’exécute lorsqu’un fichier de configuration change pendant une session	async, timeout: 5000, file_path, config_source
19	WorktreeCreate	S’exécute lorsque l’isolation par worktree d’agent crée des worktrees pour une configuration VCS personnalisée	async, timeout: 5000, worktree_path, isolation_reason
20	WorktreeRemove	S’exécute lorsque l’isolation par worktree d’agent supprime des worktrees pour le démontage VCS personnalisé	async, timeout: 5000, worktree_path, removal_reason
21	InstructionsLoaded	S’exécute lorsque CLAUDE.md ou des fichiers .claude/rules/*.md sont chargés dans le contexte	async, timeout: 5000, file_path, memory_type, load_reason, globs, trigger_file_path, parent_file_path
22	Elicitation	S’exécute lorsqu’un serveur MCP demande une saisie utilisateur pendant un appel d’outil	async, timeout: 5000, server_name, tool_name, elicitation_schema
23	ElicitationResult	S’exécute après la réponse de l’utilisateur à une elicitation MCP, avant l’envoi de la réponse au serveur	async, timeout: 5000, server_name, tool_name, user_response
24	StopFailure	S’exécute lorsque le tour se termine à cause d’une erreur API (rate limit, échec d’auth, etc.)	async, timeout: 5000, error_type, error_message, last_assistant_message
25	CwdChanged	S’exécute lorsque le répertoire de travail change pendant une session (gestion d’environnement réactive, par exemple direnv)	async, timeout: 5000, old_cwd, new_cwd
26	FileChanged	S’exécute lorsque des fichiers surveillés changent pendant une session (gestion d’environnement réactive, par exemple direnv). Nécessite matcher avec des basenames séparés par des pipes (par exemple .envrc|.env) pour préciser quels fichiers surveiller	async, timeout: 5000, file_path, changed_reason
27	PermissionDenied	S’exécute après qu’un classificateur en mode auto refuse un appel d’outil. Retourne {retry: true} pour indiquer au modèle qu’il peut réessayer	async, timeout: 5000, tool_name, tool_input, tool_use_id, reason

Note : les hooks 15-17 (TeammateIdle, TaskCreated et TaskCompleted) nécessitent la fonctionnalité expérimentale agent teams. Définis CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 au lancement de Claude Code pour les activer.

Non présents dans la documentation officielle

Les éléments suivants existent dans le Claude Code Changelog, mais ne sont pas listés dans la référence officielle des hooks :

Élément	Ajouté dans	Référence changelog	Notes
Hook Setup	v2.1.10	"Added new Setup hook event that can be triggered via --init, --init-only, or --maintenance CLI flags for repository setup and maintenance operations"	Non listé dans la page de référence officielle des hooks (26 hooks listés, Setup exclu)
Hooks dans le frontmatter d’agent	v2.1.0	"Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle"	Le changelog ne mentionne que 3 hooks, mais les tests confirment que 6 hooks se déclenchent réellement dans les sessions d’agent : PreToolUse, PostToolUse, PermissionRequest, PostToolUseFailure, Stop, SubagentStop. Les 27 hooks ne sont pas tous pris en charge.

Prérequis

Avant d’utiliser les hooks, assure-toi d’avoir Python 3 installé sur ton système.

Logiciels requis

Toutes plateformes (Windows, macOS, Linux)

• Python 3 : requis pour exécuter les scripts de hook
• Vérifier l’installation : python3 --version

Instructions d’installation :

• Windows : télécharger depuis python.org ou installer via winget install Python.Python.3
• macOS : installer via brew install python3 (nécessite Homebrew)
• Linux : installer via sudo apt install python3 (Ubuntu/Debian) ou sudo yum install python3 (RHEL/CentOS)

Lecteurs audio (facultatif - détectés automatiquement)

Les scripts de hook détectent et utilisent automatiquement le lecteur audio approprié à ta plateforme :

• macOS : utilise afplay (intégré, aucune installation requise)
• Linux : utilise paplay depuis pulseaudio-utils — installer via sudo apt install pulseaudio-utils
• Windows : utilise le module intégré winsound (inclus avec Python)

Comment les hooks sont exécutés

Les hooks sont configurés dans .claude/settings.json pour s’exécuter directement avec Python 3 :

{
  "type": "command",
  "command": "python3 .claude/hooks/scripts/hooks.py"
}

Configurer les hooks (activer/désactiver)

Les hooks peuvent être facilement activés ou désactivés aux niveaux global et individuel.

Désactiver tous les hooks d’un coup

Modifie .claude/settings.local.json et définis :

{
  "disableAllHooks": true
}

Note : le fichier .claude/settings.local.json est ignoré par git, donc chaque utilisateur peut configurer ses préférences de hooks sans affecter les paramètres partagés de l’équipe dans .claude/settings.json.

Managed Settings : si un administrateur a configuré des hooks via des paramètres de politique gérée, disableAllHooks défini dans les paramètres utilisateur, projet ou locaux ne peut pas désactiver ces hooks gérés (corrigé en v2.1.49).

Désactiver des hooks individuels

Pour un contrôle plus granulaire, tu peux désactiver des hooks spécifiques en modifiant les fichiers de configuration des hooks.

Fichiers de configuration

Il existe deux fichiers de configuration pour gérer les hooks individuels :

1. .claude/hooks/config/hooks-config.json - Configuration partagée/par défaut, committée dans git
2. .claude/hooks/config/hooks-config.local.json - Tes surcharges personnelles (ignorées par git)

Le fichier de configuration local (.local.json) est prioritaire sur la configuration partagée, ce qui permet à chaque développeur de personnaliser le comportement des hooks sans affecter l’équipe.

Configuration partagée

Modifie .claude/hooks/config/hooks-config.json pour les valeurs par défaut de l’équipe :

{
  "disableLogging": false,
  "disablePreToolUseHook": false,
  "disablePermissionRequestHook": false,
  "disablePostToolUseHook": false,
  "disablePostToolUseFailureHook": false,
  "disableUserPromptSubmitHook": false,
  "disableNotificationHook": false,
  "disableStopHook": false,
  "disableSubagentStartHook": false,
  "disableSubagentStopHook": false,
  "disablePreCompactHook": false,
  "disablePostCompactHook": false,
  "disableElicitationHook": false,
  "disableElicitationResultHook": false,
  "disableStopFailureHook": false,
  "disableSessionStartHook": false,
  "disableSessionEndHook": false,
  "disableSetupHook": false,
  "disableTeammateIdleHook": false,
  "disableTaskCompletedHook": false,
  "disableConfigChangeHook": false,
  "disableWorktreeCreateHook": false,
  "disableWorktreeRemoveHook": false,
  "disableInstructionsLoadedHook": false,
  "disableCwdChangedHook": false,
  "disableFileChangedHook": false,
  "disablePermissionDeniedHook": false
}

Options de configuration :

• disableLogging : définir à true pour désactiver la journalisation des événements de hook dans .claude/hooks/logs/hooks-log.jsonl (utile pour éviter la croissance du fichier de log)

Configuration locale (surcharges personnelles)

Crée ou modifie .claude/hooks/config/hooks-config.local.json pour tes préférences personnelles :

{
  "disableLogging": true,
  "disablePostToolUseHook": true,
  "disableSessionStartHook": true
}

Dans cet exemple, la journalisation est désactivée, et les hooks PostToolUse et SessionStart sont surchargés localement. Tous les autres hooks utiliseront les valeurs de configuration partagée.

Note : les toggles de hooks individuels sont vérifiés par le script de hook (.claude/hooks/scripts/hooks.py). Les paramètres locaux surchargent les paramètres partagés ; si un hook est désactivé, le script se termine silencieusement sans jouer de son ni exécuter de logique de hook.

Text to Speech (TTS)

Site web utilisé pour générer les sons : https://elevenlabs.io/ Voix utilisée : Samara X

Hooks dans le frontmatter d’agent

Claude Code 2.1.0 a introduit la prise en charge de hooks spécifiques aux agents, définis dans les fichiers de frontmatter d’agent. Ces hooks ne s’exécutent que dans le cycle de vie de l’agent et prennent en charge un sous-ensemble d’événements.

Hooks d’agent pris en charge

Les hooks de frontmatter d’agent prennent en charge 6 hooks (pas les 27). Le changelog ne mentionnait initialement que 3 hooks, mais les tests confirment que 6 hooks se déclenchent réellement dans les sessions d’agent :

• PreToolUse : s’exécute avant que l’agent utilise un outil
• PostToolUse : s’exécute après qu’un agent termine une utilisation d’outil
• PermissionRequest : s’exécute lorsqu’un outil nécessite une permission utilisateur
• PostToolUseFailure : s’exécute après l’échec d’un appel d’outil
• Stop : s’exécute lorsque l’agent termine
• SubagentStop : s’exécute lorsqu’un sous-agent termine

Note : le changelog v2.1.0 ne mentionne que 3 hooks : "Added hooks support to agent frontmatter, allowing agents to define PreToolUse, PostToolUse, and Stop hooks scoped to the agent's lifecycle". Cependant, les tests avec claude-code-hook-agent confirment que 6 hooks se déclenchent réellement dans les sessions d’agent. Les 21 hooks restants (par exemple Notification, SessionStart, SessionEnd, etc.) ne se déclenchent pas dans les contextes d’agent.

Mise à jour (février 2026) : la référence officielle des hooks indique désormais "All hook events are supported" pour les hooks de frontmatter de skill/agent. Cela peut signifier que la prise en charge s’est étendue au-delà des 6 hooks testés initialement. Il est recommandé de retester pour vérifier si des hooks supplémentaires se déclenchent maintenant dans les sessions d’agent.

Dossiers de sons d’agent

Les sons spécifiques aux agents sont stockés dans des dossiers séparés :

• .claude/hooks/sounds/agent_pretooluse/
• .claude/hooks/sounds/agent_posttooluse/
• .claude/hooks/sounds/agent_permissionrequest/
• .claude/hooks/sounds/agent_posttoolusefailure/
• .claude/hooks/sounds/agent_stop/
• .claude/hooks/sounds/agent_subagentstop/

Créer un agent avec hooks

1. Crée un fichier de définition d’agent dans .claude/agents/ :

---
name: my-agent
description: Description of what this agent does
hooks:
  PreToolUse:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: PreToolUse
  PostToolUse:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: PostToolUse
  PermissionRequest:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: PermissionRequest
  PostToolUseFailure:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: PostToolUseFailure
  Stop:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: Stop
  SubagentStop:
    - type: command
      command: python3 ${CLAUDE_PROJECT_DIR}/.claude/hooks/scripts/hooks.py --agent=my-agent
      timeout: 5000
      async: true
      statusMessage: SubagentStop
---

Your agent instructions here...

2. Ajoute les fichiers son aux dossiers de sons d’agent :
   • agent_pretooluse/agent_pretooluse.wav
   • agent_posttooluse/agent_posttooluse.wav
   • agent_permissionrequest/agent_permissionrequest.wav
   • agent_posttoolusefailure/agent_posttoolusefailure.wav
   • agent_stop/agent_stop.wav
   • agent_subagentstop/agent_subagentstop.wav

Exemple : agent Weather Fetcher

Voir .claude/agents/claude-code-hook-agent.md pour un exemple complet d’agent avec hooks configurés.