Que sont les hooks et les permissions dans les agents de programmation?

Un agent de programmation est un modèle d’IA qui travaille dans votre projet : il lit des fichiers, modifie du code et lance des commandes dans le terminal pour atteindre un objectif que vous décrivez. Les instructions d’un fichier comme CLAUDE.md lui disent comment vous aimez que les choses soient faites, mais des instructions restent des demandes. Le modèle les suit habituellement, et parfois il les oublie ou les interprète mal. Quand une règle compte vraiment, comme « ne jamais faire de commit d’un mot de passe », vous voulez quelque chose de plus ferme.

Deux fonctions le permettent. Les permissions contrôlent l’accès : ce que l’agent peut faire sans demander, ce qui exige votre approbation et ce qui est interdit. Les hooks (crochets) ajoutent de la logique : ce sont des scripts qui s’exécutent automatiquement à des moments fixes du travail de l’agent et qui peuvent arrêter une action contraire à vos règles. Cet article prend comme exemple Claude Code, l’agent de programmation d’Anthropic; d’autres agents offrent des contrôles comparables sous d’autres noms.

Les permissions : autoriser, demander, refuser

Par défaut, Claude Code est prudent. Anthropic l’a conçu pour demander avant toute action qui pourrait modifier votre système, comme écrire des fichiers ou lancer bien des commandes du terminal. C’est sûr, mais lent; vous pouvez donc ajuster les règles dans un fichier de paramètres. Le fichier .claude/settings.json d’un projet peut être versé (commit) dans votre dépôt pour que toute l’équipe le partage.

Les règles se répartissent en trois listes :

{
  "permissions": {
    "allow": ["Edit", "Bash(npm test:*)", "Bash(git commit:*)"],
    "ask":   ["Bash(git push:*)"],
    "deny":  ["WebFetch", "WebSearch"]
  }
}

Lisez-le ainsi : les modifications de fichiers, le lancement de la suite de tests et les commits se font sans interruption; pousser vers un dépôt partagé exige toujours un oui de votre part; consulter des pages Web et faire des recherches sur le Web n’est pas permis du tout. Tout ce qui n’est pas dans les listes garde le comportement par défaut, qui consiste à demander pour la plupart des commandes du terminal. La forme Bash(git commit:*) signifie « les commandes du terminal qui commencent par git commit ».

L’exemple strict qu’Anthropic propose pour les organisations va plus loin : il exige une approbation pour chaque commande du terminal, refuse les outils Web et désactive le mode qui saute toutes les vérifications de permissions. Anthropic prévient que sauter entièrement les vérifications peut entraîner des pertes de données ou des attaques cachées dans le contenu que lit l’agent, et suggère de le faire seulement dans un conteneur isolé sans accès à Internet.

Les hooks : vos vérifications, exécutées chaque fois

Les permissions répondent à la question « l’agent peut-il utiliser cet outil? » Les hooks répondent à « cette action précise est-elle acceptable? » Un hook est rattaché à un événement. Le plus utile pour la sécurité est PreToolUse, qui se déclenche juste avant que l’agent utilise un outil. Un filtre (matcher) choisit l’outil que le hook surveille, comme Bash pour les commandes du terminal.

Quand le hook s’exécute, Claude Code lui envoie sur l’entrée standard un court message JSON qui décrit l’action, y compris le nom de l’outil et ses données d’entrée; pour une commande du terminal, le texte de la commande se trouve dans tool_input.command. Le hook répond par son code de sortie, le nombre qu’un programme renvoie quand il se termine :

Un exemple concret : bloquer les commits qui contiennent des secrets

L’objectif : chaque fois que l’agent essaie de lancer git commit, examiner les modifications indexées et arrêter le commit si elles contiennent quelque chose qui ressemble à une clé ou à un mot de passe. Enregistrez ceci sous .claude/hooks/block_secrets.py :

#!/usr/bin/env python3
import json, re, subprocess, sys

PATTERNS = [
    (r"AKIA[0-9A-Z]{16}", "un identifiant de clé d’accès AWS"),
    (r"-----BEGIN [A-Z ]*PRIVATE KEY-----", "une clé privée"),
    (r"(?i)(api[_-]?key|secret|token|password)\s*[:=]\s*['\"][^'\"]{12,}['\"]",
     "un identifiant codé en dur"),
]

data = json.load(sys.stdin)
command = data.get("tool_input", {}).get("command", "")
if not re.search(r"\bgit\s+commit\b", command):
    sys.exit(0)  # pas un commit : rien à vérifier

diff = subprocess.run(["git", "diff", "--cached", "-U0"],
                      capture_output=True, text=True,
                      cwd=data.get("cwd") or ".").stdout
added = "\n".join(l for l in diff.splitlines() if l.startswith("+"))

found = [label for pattern, label in PATTERNS if re.search(pattern, added)]
if found:
    print("Commit bloqué : les modifications indexées semblent contenir "
          + ", ".join(found) + ". Retirez le secret, chargez-le depuis une "
          "variable d’environnement ou un gestionnaire de secrets, puis refaites le commit.",
          file=sys.stderr)
    sys.exit(2)  # bloquer l’appel d’outil et dire pourquoi à l’agent

Inscrivez-le ensuite dans .claude/settings.json, à côté de vos permissions :

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          { "type": "command",
            "command": "python3 .claude/hooks/block_secrets.py" }
        ]
      }
    ]
  }
}

Si l’agent indexe un fichier qui contient une ligne d’exemple comme API_KEY = "example-not-a-real-key-123" et essaie d’en faire le commit, le hook se termine avec le code 2. Le commit n’a jamais lieu, et l’agent reçoit le message qui explique pourquoi; il peut donc déplacer la valeur dans une variable d’environnement et réessayer.

Comment les utiliser pour faire respecter vos règles?

Commencez par trier vos règles selon les dégâts que causerait un écart. Les préférences de style ont leur place dans CLAUDE.md. Les règles pour lesquelles une erreur coûte cher ou se répare difficilement, comme la fuite d’identifiants, une poussée vers la branche principale ou la suppression de données, vont dans les permissions ou les hooks, parce que ceux-ci ne dépendent pas de la mémoire du modèle.

Utilisez les permissions pour des catégories entières d’actions : refusez les outils dont le projet n’a jamais besoin, gardez les commandes risquées sur « demander » et n’autorisez que les commandes courantes que vous approuveriez de toute façon. Utilisez les hooks quand la décision dépend des détails, comme dans l’exemple, où git commit est correct sauf quand le contenu ne l’est pas.

Gardez chaque hook petit, rapide et centré sur une seule règle, et rédigez son message d’erreur pour l’agent : dites ce qui n’allait pas et quoi faire à la place, pour qu’il puisse corriger le problème de lui-même. Testez vos hooks avec une infraction volontaire avant de vous y fier.

Enfin, connaissez les limites. Un hook ne voit que ce que l’agent fait au moyen de ses outils; un commit que vous tapez vous-même dans un autre terminal y échappe, alors gardez aussi une vérification git pre-commit ordinaire ou un détecteur de secrets dans votre dépôt. Les listes de motifs ratent aussi les secrets pour lesquels elles n’ont pas été écrites. Pour les équipes, les paramètres d’exemple d’Anthropic montrent comment les administrateurs peuvent verrouiller de façon centrale les règles de permissions et les hooks, pour que chaque projet ne puisse pas les assouplir discrètement.