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](https://code.claude.com/docs/en/hooks)
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](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md), mais ne sont **pas listés** dans la [référence officielle des hooks](https://code.claude.com/docs/en/hooks) :

| Élément | Ajouté dans | Référence changelog | Notes |
|---------|-------------|---------------------|-------|
| Hook `Setup` | [v2.1.10](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#2110) | "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](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#210) | "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](https://www.python.org/downloads/) ou installer via `winget install Python.Python.3`
- **macOS** : installer via `brew install python3` (nécessite [Homebrew](https://brew.sh/))
- **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 :

```json
{
  "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 :
```json
{
  "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 :

```json
{
  "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 :

```json
{
  "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](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md#210) 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](https://code.claude.com/docs/en/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/` :

```markdown
---
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.