Hooks de Claude Code : un contrôle déterministe des actions de l’agent

Anatomie d’un hook

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

Trois parties : l’événement, un filtre de correspondance (une expression régulière sur le nom de l’outil pour les événements d’outil ; omettez-le pour tout sélectionner), et une ou plusieurs commandes. La commande reçoit sur stdin un objet JSON décrivant l’événement — pour les événements d’outil, il comprend tool_name et tool_input, ce qui permet à l’exemple ci-dessus de trouver le fichier qui vient d’être modifié. Placez-le dans .claude/settings.json pour le partager avec le dépôt, ~/.claude/settings.json pour votre usage personnel, ou exécutez /hooks et laissez Claude Code l’écrire.

Les événements

• PreToolUse — avant l’exécution d’un outil. Le seul événement qui peut bloquer : le code de sortie 2 annule l’appel et Claude lit votre sortie stderr pour en connaître la raison.
• PostToolUse — après la réussite d’un outil. Formatage, linting et vérification des types sur le fichier modifié.
• UserPromptSubmit — lorsque vous envoyez un prompt ; peut injecter du contexte ou rejeter le prompt.
• Stop / SubagentStop — lorsque l’agent (ou un sous-agent) est sur le point de terminer. Le code de sortie 2 signifie ici « pas encore terminé » — l’usage classique consiste à refuser l’arrêt tant que les tests échouent.
• PreCompact — avant /compact ; enregistrez tout ce dont vous avez besoin dans la transcription complète.
• SessionStart — lorsqu’une session commence ou reprend ; charger l’environnement, afficher des rappels.
• Notification — lorsque Claude Code sollicite votre attention (demande d’autorisation, inactivité) ; reliez-le à une notification de bureau ou Slack.

Bloquer les commandes dangereuses

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

Le code de sortie 2 constitue le contrat : l’appel d’outil n’a pas lieu, et tout ce que le hook a écrit sur stderr devient l’explication que Claude voit, afin qu’il puisse choisir une autre approche au lieu de réessayer la même chose. Tout autre code de sortie non nul est consigné, mais ne bloque pas l’exécution.

« Ne pas s’arrêter tant que les tests ne réussissent pas »

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Associez-le à une limite de --max-turns dans les exécutions sans interface afin qu’un échec réellement impossible à corriger ne provoque pas une boucle infinie.

Hooks, CLAUDE.md et autorisations

CLAUDE.md contient des conseils que le modèle lit ; /permissions est une liste de ce qu’il peut faire sans demander ; les hooks sont du code qui s’exécute dans tous les cas. Utilisez CLAUDE.md pour le style et le contexte, les autorisations pour définir ce qui est permis ou nécessite une demande, et les hooks pour tout ce qui doit être garanti à chaque fois — formatage, détection de secrets, contrôles de tests, journaux d’audit. Ils se combinent : une autorisation permet l’exécution de Bash(git *) , tandis qu’un hook PreToolUse bloque toujours git push --force.

Les hooks et la passerelle

Les hooks s’exécutent localement et ne font jamais appel à l’API ; rien ne change donc lorsque Claude Code pointe vers ANTHROPIC_BASE_URL=https://aiprimetech.io. Une combinaison utile : un hook Stop qui affiche /costdes données d’utilisation dans ce style à partir de vos propres journaux, afin qu’une équipe utilisant des crédits facturés à l’usage voie le coût de chaque session à sa clôture.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Questions fréquentes

AI Prime Tech est une passerelle API indépendante et n’est ni affiliée à Anthropic, ni approuvée ou parrainée par Anthropic. « Claude » et « Claude Code » sont des marques commerciales d’Anthropic. Les fonctionnalités de Claude Code décrites ici correspondent à la documentation publique d’Anthropic au moment de la rédaction et évoluent fréquemment ; les prix et les listes de modèles de cette page proviennent des paramètres en temps réel de cette passerelle.