Hooks Claude Code : le guide power-user pour automatiser votre agent

Translation complete.

Claude Code hooks sont des commandes définies par l'utilisateur qui s'exécutent automatiquement à des points précis du cycle de vie de Claude Code — avant un appel d'outil, après une modification, au démarrage d'une session, quand Claude termine un tour — afin que vous puissiez valider, formater, journaliser ou bloquer des actions sans avoir à intervenir à chaque fois. C'est la différence entre un agent de codage IA qui suggère et un agent qui applique vos règles de façon déterministe. Ce guide explique ce que sont les hooks, chaque événement sur lequel ils peuvent se déclencher, comment les configurer, cinq recettes pratiques que vous pouvez reprendre, le piège du code de sortie qui déstabilise tout le monde, et comment exploiter toute la puissance de Claude Code sans aucune installation locale.

Qu'est-ce qu'un Claude Code hook ?

Un hook est un gestionnaire — une commande shell, un endpoint HTTP, un appel d'outil MCP, ou même un prompt de modèle — que Claude Code exécute automatiquement lorsqu'un événement particulier se produit. Le gestionnaire reçoit une entrée structurée (sur stdin pour les hooks de type commande, ou comme corps de requête POST pour les hooks HTTP), peut inspecter ce qui se passe, effectuer une action, et éventuellement renvoyer une décision qui modifie ce que Claude fait ensuite.

Ce dernier point est ce qui rend les hooks puissants plutôt que simplement pratiques. Un hook n'est pas qu'une notification — il peut bloquer un appel d'outil, réécrire l'entrée ou la sortie d'un outil, injecter du contexte supplémentaire, ou arrêter Claude entièrement. Autrement dit, les hooks transforment Claude Code d'un assistant intelligent en un assistant programmable qui applique les garde-fous de votre équipe de manière déterministe, et pas seulement quand le modèle pense à s'en souvenir.

Quand les hooks se déclenchent : le cycle de vie

Les hooks s'attachent à des événements, et Claude Code en expose beaucoup. Ils se regroupent par cadence : certains se déclenchent une fois par session, d'autres une fois par tour, et d'autres à chaque appel d'outil.

Où les hooks se déclenchent au cours d'une session Claude Code — de SessionStart à SessionEnd.

Les événements que vous utiliserez le plus souvent :

• SessionStart / SessionEnd — une fois au début ou à la fin d'une session. Idéal pour charger du contexte (issues ouvertes, informations de branche, variables d'environnement) ou pour le nettoyage.
• UserPromptSubmit — se déclenche quand vous soumettez un prompt, avant que Claude ne le traite. Vous pouvez filtrer ou enrichir le prompt.
• PreToolUse — avant tout appel d'outil. C'est ici que vous bloquez les actions dangereuses.
• PostToolUse (et PostToolUseFailure) — après qu'un appel d'outil réussit (ou échoue). L'endroit idéal pour le linting, le formatage et la vérification.
• Stop / StopFailure — quand Claude termine sa réponse, ou quand le tour se termine sur une erreur.
• Notification — quand Claude Code émet une notification (utile pour les alertes de bureau).

Au-delà de ceux-là, Claude Code déclenche aussi des hooks pour les subagents (SubagentStart/SubagentStop), les tâches (TaskCreated/TaskCompleted), la compaction du contexte (PreCompact/PostCompact), les changements de répertoire de travail (CwdChanged), les changements de fichiers sur disque (FileChanged), le chargement des instructions (InstructionsLoaded), et plus encore. L'étendue est justement l'intérêt : presque n'importe quel moment de la boucle de l'agent est un endroit où vous pouvez attacher une politique.

Les cinq types de gestionnaires de hook

Un événement de hook peut déclencher cinq types de gestionnaires différents, ce qui rend le système flexible :

1. command — exécute une commande shell ; lit l'entrée sur stdin, signale les décisions via le code de sortie et stdout.
2. http — envoie l'événement en JSON via POST à une URL et lit la réponse JSON.
3. mcp_tool — appelle un outil sur un serveur MCP connecté.
4. prompt — une évaluation de modèle en un seul tour qui renvoie une décision JSON oui/non (utile pour les vérifications floues).
5. agent — lance un subagent (expérimental).

Pour la plupart des équipes, les hooks command font 90 % du travail — un script shell suffit pour linter, bloquer, ou journaliser.

Comment configurer un hook

Les hooks résident dans des fichiers de paramètres (la documentation officielle des Claude Code hooks fait référence), et l'endroit où vous les placez contrôle leur portée :

La structure s'imbrique sur trois niveaux : choisissez un événement, ajoutez un groupe de matcher, puis définissez les gestionnaires. Les matchers déterminent à quels appels d'outil un hook s'applique — "*" (ou son omission) correspond à tout, un simple Edit|Write correspond exactement à ces outils, et tout ce qui est plus complexe est traité comme une expression régulière. (Les outils MCP correspondent au motif mcp__<server>__<tool>.)

Voici un hook PostToolUse qui exécute une vérification de lint après chaque modification :

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/path/to/lint-check.sh" }]
      }
    ]
  }
}

Cinq recettes pratiques de hooks

Ce sont les schémas vers lesquels les équipes se tournent en premier :

1. Linter ou formater après chaque modification. Un hook PostToolUse associé à Edit|Write qui exécute votre formateur ou linter, afin que le code de l'agent respecte toujours vos règles de style.
2. Bloquer les commandes destructrices. Un hook PreToolUse associé à Bash qui inspecte la commande et bloque rm -rf et ses semblables avant qu'ils ne s'exécutent.
3. Notifications de bureau. Un hook Notification qui vous alerte quand Claude a besoin d'attention ou termine une tâche longue.
4. Journalisation d'audit. Un hook PostToolUse (ou ciblé MCP) qui journalise chaque appel d'outil à des fins de conformité — ce qui a été exécuté, quand, et avec quels arguments.
5. Charger le contexte du projet au démarrage. Un hook SessionStart qui récupère les issues ouvertes, la branche courante, ou les variables d'environnement afin que l'agent commence chaque session déjà orienté.

Cinq recettes de hooks courantes et les événements auxquels elles s'attachent.

Le piège du code de sortie

C'est le détail qui déstabilise tout le monde, alors retenez-le bien : pour les hooks command, seul le code de sortie 2 bloque. La sortie 0 signifie succès (et stdout est analysé pour toute décision JSON). La sortie 2 est une erreur bloquante — son stderr est renvoyé à Claude. Tout autre code, y compris la sortie 1, est une erreur non bloquante — Claude continue.

Donc si vous écrivez un hook « bloque ceci » et que vous faites exit 1, il ne bloquera pas — l'action se poursuit. Pour réellement appliquer une politique depuis un hook de commande, faites exit 2. (Les hooks de commande peuvent aussi renvoyer un contrôle plus riche sous forme de JSON sur stdout — permissionDecision: "deny" pour PreToolUse, updatedInput pour réécrire les arguments, additionalContext pour injecter des informations, et continue: false pour arrêter Claude entièrement.)

Un exemple concret : bloquer rm -rf

Construisons de bout en bout la protection contre les commandes destructrices, car cela illustre chaque rouage. D'abord, la configuration — un hook PreToolUse associé à Bash :

{ "hooks": { "PreToolUse": [{ "matcher": "Bash",
  "hooks": [{ "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/guard.sh" }] }] } }

Puis le script, guard.sh. Claude Code envoie l'événement en JSON sur stdin, y compris l'entrée de l'outil ; le script la lit, vérifie la commande, et décide :

#!/usr/bin/env bash
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // ""')
if echo "$cmd" | grep -Eq 'rm +-rf|mkfs'; then
  echo "Blocked: destructive command refused by policy." >&2
  exit 2     # exit 2 blocks — exit 1 would NOT
fi
exit 0

La ligne décisive est exit 2. Renvoyez 0 et la commande s'exécute ; renvoyez 1 et — contre toute intuition — elle s'exécute quand même en tant qu'erreur non bloquante ; seul exit 2 bloque et renvoie votre message stderr à Claude pour qu'il comprenne pourquoi. Rendez le script exécutable, committez-le sous .claude/hooks/, et chaque appel Bash passe désormais par votre garde-fou — pour toute votre équipe, puisque le settings.json du projet est partageable. Pour une garantie stricte plutôt qu'un filet de sécurité au mieux-effort, associez-le aux règles de permission de Claude Code ; en tant que filet de sécurité déterministe et versionné, ce hook fait déjà le travail.

Quand les hooks ne sont pas la réponse

Les hooks servent à des politiques déterministes et répétables — « toujours linter après une modification », « ne jamais exécuter rm -rf ». Ce n'est pas le bon outil pour ce qui nécessite du jugement (utilisez le modèle ou un hook prompt pour les décisions floues) ni pour des garanties de sécurité strictes (utilisez le système de permissions, puisque les filtres if des hooks de commande échouent de manière permissive). N'abusez pas non plus des hooks : chaque hook de commande exécute un processus avec un délai d'expiration, et une accumulation de hooks lents ajoute de la latence à chaque appel d'outil. Gardez-les rapides, peu nombreux, et concentrés sur les règles qui comptent vraiment.

Notes de sécurité à connaître

Quelques réalités que la documentation énonce explicitement :

• Le filtre if échoue de manière permissive. Si vous utilisez le champ if pour restreindre un hook à une règle de permission et que la commande ne peut pas être analysée, le hook s'exécute quand même. Pour une application stricte d'autorisation/refus, utilisez le système de permissions de Claude Code, pas les hooks.
• Les hooks s'exécutent sans terminal de contrôle — ils ne peuvent pas demander une saisie sur /dev/tty. Utilisez systemMessage ou la sortie restreinte terminalSequence pour les messages destinés à l'utilisateur.
• Stdout doit être propre. Seul l'objet de décision JSON doit figurer sur stdout ; une sortie parasite de profil shell peut casser l'analyse.
• Traitez le contexte injecté avec précaution. additionalContext doit être rédigé sous forme d'énoncés factuels, pas de commandes impératives, pour bien s'articuler avec les défenses contre l'injection de prompt.

Les hooks, c'est de l'ingénierie de harnais en miniature

Prenez du recul, et les hooks sont un exemple concret d'une idée plus large : le modèle n'est pas l'agent tout entier — le système qui l'entoure compte aussi. Les hooks font partie du harnais qui rend un agent de codage fiable, aux côtés de la boucle, des outils, de la mémoire et du sandbox. (Nous approfondissons ce modèle mental dans harness engineering.) Quand vous écrivez un blocage PreToolUse ou un linter PostToolUse, vous faites de l'ingénierie de harnais — vous façonnez le comportement de l'agent de manière déterministe plutôt que d'espérer que le modèle se comporte bien.

Ce cadrage vous indique aussi quand les hooks valent l'effort : toute règle que vous devriez sinon rappeler à l'agent à chaque fois est une candidate pour un hook.

Exploiter toute la puissance de Claude Code sans installation locale

Les hooks résident dans le CLI Claude Code, ce qui signifie que vous devez l'avoir installé et configuré pour les utiliser — un obstacle pour quiconque n'est pas à l'aise dans un terminal, et impossible pour les coéquipiers non développeurs. Si vous voulez les capacités d'agent de Claude Code sans gérer une installation locale, vous pouvez exécuter Claude Code dans votre navigateur sur Happycapy : il exécute Claude Code dans un sandbox cloud managé où le harnais — la boucle, les outils, la mémoire et l'isolation auxquels les hooks se connectent — est déjà mis en place pour vous. Vous décrivez une tâche et regardez l'agent travailler sur un bureau visuel, sans terminal requis.

Voyez-le ainsi : les hooks permettent aux utilisateurs avancés d'ajuster manuellement le harnais de Claude Code ; Happycapy offre à tout le monde un harnais managé prêt à l'emploi. Si vous avez voulu mettre Claude Code au travail mais que la configuration du CLI vous a arrêté, commencez gratuitement sur happycapy.ai et exécutez une vraie tâche dans votre navigateur dès aujourd'hui.

Questions fréquentes

Q : Que sont les Claude Code hooks ?

Ce sont des gestionnaires définis par l'utilisateur — commandes shell, endpoints HTTP, appels d'outils MCP, ou prompts de modèle — que Claude Code exécute automatiquement lors d'événements du cycle de vie comme avant un appel d'outil (PreToolUse), après une modification (PostToolUse), ou au démarrage de la session. Ils peuvent valider, formater, journaliser, bloquer, ou réécrire des actions.

Q : Quels événements de hook Claude Code prend-il en charge ?

Beaucoup — notamment SessionStart/SessionEnd, UserPromptSubmit, PreToolUse, PostToolUse (et PostToolUseFailure), Stop/StopFailure, Notification, les événements de subagent et de tâche, et les événements de compaction. Ils se déclenchent une fois par session, une fois par tour, ou à chaque appel d'outil.

Q : Comment faire en sorte qu'un hook bloque un appel d'outil ?

Pour les hooks de commande, terminez avec le code 2 — seul le code 2 bloque (le code 1 ne bloque pas). Pour PreToolUse, vous pouvez aussi renvoyer du JSON avec permissionDecision: "deny". Pour une application stricte, privilégiez le système de permissions de Claude Code, puisque le filtre if des hooks échoue de manière permissive.

Q : Où configurer les Claude Code hooks ?

Dans des fichiers de paramètres : ~/.claude/settings.json (tous les projets), .claude/settings.json (un seul projet, partageable), ou .claude/settings.local.json (local uniquement). Vous choisissez un événement, ajoutez un matcher, et définissez les gestionnaires.

Q : Puis-je utiliser les Claude Code hooks sans installer le CLI ?

Les hooks eux-mêmes nécessitent le CLI Claude Code. Si votre objectif est d'utiliser Claude Code sans installation locale, exécutez-le dans un sandbox de navigateur managé comme Happycapy, qui fournit l'agent et son harnais prêts à l'emploi — idéal quand vous ne voulez pas installer et configurer le CLI vous-même.

Q : Quel est un bon premier hook à ajouter ?

Un linter PostToolUse associé à Edit|Write — il exécute votre formateur après chaque modification de code, afin que la sortie de l'agent respecte toujours vos règles de style. C'est peu risqué et immédiatement utile.

Guides connexes

• How Claude Code Review Actually Works: Diffs, Hooks, and What the Agent Catches
• Build Autonomous Agents with the Claude Code SDK: A Practical Developer's Guide
• Claude Code Web: How to Run Claude Code in Your Browser (No Install)
• Claude Code vs GitHub Copilot: Autonomous Agent or In-Editor Assistant?