Conclusion en tête :
- AGENTS.md / skills / instructions système sont des suggestions : le modèle les lit, mais peut les oublier ou les contourner.
- Les hooks sont des scripts exécutés par le harness : ils s'exécutent à des moments fixes (avant ou après un appel d'outil), indépendamment du fait que le modèle « se souvienne » des règles.
- Les trois plateformes peuvent intercepter les appels d'outils : Claude Code / Codex utilisent
PreToolUse; Cursor utilisepreToolUse(ou le plus ciblébeforeShellExecution). L'interception se fait généralement via exit code 2 ou un JSON contenantdeny. - Le comportement par défaut est souvent fail-open : si le script plante, dépasse le délai ou retourne un code non 0/2, l'appel d'outil continue en général ; les politiques de sécurité doivent être explicitement configurées en fail-closed (Claude Code :
onFailure: "block"; Cursor :failClosed: true). Selon la documentation officielle de Codex, un échec de hook remonte une erreur de hook, mais cet échec n'est pas traité comme un blocage forcé par défaut. - Testé sur Claude Code : un appel Bash correspondant à
rm -rf /tmp/hooks-deny-meest intercepté par PreToolUse (exit 2) ;echo hooks-allow-okpasse normalement. Cursor n'a pas pu être testé de la même façon dans un environnement sans interface graphique ; la configuration Cursor est présentée d'après la documentation officielle, sans prétendre à un test réel sur Cursor.
Selon l'article de SwiftLee / Antoine van der Lee du 2026-11-02 et le retweet de @peterfriese sur X : les hooks sont bien plus fiables que d'écrire des règles dans AGENTS.md. La suite se base sur la documentation officielle de chaque plateforme ; en cas de divergence avec des articles tiers, la documentation officielle prévaut et la source est indiquée.
Contexte connexe : les plugins peuvent silencieusement attacher des hooks SessionStart (voir Vérification et suppression du plugin Postman) ; AGENTS.md peut également être influencé par le contexte du répertoire (voir Détournement via le répertoire Downloads). Les hooks ne remplacent pas « ne pas ouvrir un agent dans Downloads », mais ils permettent d'appliquer des règles strictes que le markdown ne peut pas imposer. Pour MCP et les limites de permissions, voir le guide de sécurité Codex Playwright MCP ; pour la répartition des rôles entre skills et hooks, voir Comment utiliser les Skills dans un AI Agent.
Tableau comparatif en un coup d'œil
| Élément | Claude Code | Codex | Cursor |
|---|---|---|---|
| Config utilisateur | ~/.claude/settings.json | ~/.codex/hooks.json ou config.toml | ~/.cursor/hooks.json |
| Config projet | .claude/settings.json | .codex/hooks.json ou config.toml | .cursor/hooks.json (workspace de confiance requis) |
| Avant appel d'outil | PreToolUse | PreToolUse | preToolUse ; pour les commandes shell, beforeShellExecution est aussi disponible |
| Après appel d'outil | PostToolUse | PostToolUse | postToolUse / afterFileEdit etc. |
| Nom de l'outil shell (matcher) | Bash | Bash | Shell (beforeShellExecution filtre directement sur le texte de la commande) |
| Interception | exit 2, ou JSON permissionDecision: "deny" | exit 2, ou JSON permissionDecision: "deny" / ancienne forme decision: "block" | exit 2, ou JSON permission: "deny" |
| Comportement par défaut si hook échoue | La plupart des événements continuent (fail-open) ; configurable via onFailure: "block" | Remonte une erreur de hook, échec non traité comme blocage forcé (selon la page Hooks officielle) | fail-open par défaut ; configurable via failClosed: true |
| Confiance / audit | La confiance accordée au workspace influe sur les hooks projet | Les hooks non gérés doivent être audités et approuvés via /hooks ; --dangerously-bypass-hook-trust disponible pour un usage ponctuel | Les hooks projet ne se chargent que dans les workspaces de confiance |
Références officielles : Claude Code Hooks · Codex Hooks · Cursor Hooks.
Pourquoi ne pas se contenter d'AGENTS.md
Selon l'expérience rapportée dans l'article de SwiftLee : après avoir écrit « filtrer la sortie xcodebuild » dans les instructions globales, l'agent continuait souvent à injecter les logs bruts dans le contexte. Le texte des instructions entre dans le prompt et c'est le modèle qui décide de les respecter ou non ; les hooks s'exécutent au niveau du harness, le modèle n'a aucun droit de veto sur leur exécution.
Répartition recommandée :
- Instructions et préférences → AGENTS.md / skills (expliquer l'intention, le style, le workflow).
- Règles qui doivent toujours s'appliquer → hooks (bloquer des commandes dangereuses, réécrire des commandes de build, auditer, écrire une note en fin de session).
- Ne pas traiter les hooks comme seule ligne de défense → certains chemins contournent les hooks (la documentation Codex précise par exemple que
write_stdinpour interroger une commande déjà approuvée par PreToolUse ne relance pas PreToolUse).
Script minimal : intercepter une commande Bash dangereuse (fail-open)
Le script ci-dessous fonctionne sur les trois plateformes : il lit le JSON depuis stdin, extrait la commande ; si elle correspond au pattern, il la bloque ; sinon il la laisse passer ; en cas d'erreur de parsing, il fait exit 0 (fail-open). Sauvegardez-le en fichier exécutable, par exemple ~/.agents/hooks/block-rm-demo.sh.
#!/bin/bash
# fail-open : si jq est absent ou si le JSON est invalide → exit 0, ne bloque pas le travail
input=$(cat || true)
command=$(printf '%s' "$input" | jq -r '.tool_input.command // .command // empty' 2>/dev/null || true)
if [[ -z "$command" ]]; then
exit 0
fi
if [[ "$command" == *"rm -rf /tmp/hooks-deny-me"* ]]; then
# Cursor : si le champ cursor_version est présent, utiliser le deny JSON (selon la doc officielle Cursor Hooks + syntaxe de l'article SwiftLee)
if printf '%s' "$input" | jq -e 'has("cursor_version")' >/dev/null 2>&1; then
jq -n '{permission:"deny", agent_message:"Blocked by PreToolUse-style hook: refusing rm -rf /tmp/hooks-deny-me"}'
exit 0
fi
# Claude Code / Codex : stderr + exit 2
echo "Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me" >&2
exit 2
fi
exit 0
Faites chmod +x avant d'enregistrer la configuration.
Enregistrement dans Claude Code
À écrire dans ~/.claude/settings.json ou dans le fichier projet .claude/settings.json :
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm-demo.sh",
"timeout": 5
}
]
}
]
}
}
Pour la configuration utilisateur, utilisez un chemin absolu. Pour les hooks de politique de sécurité, il est recommandé d'ajouter "onFailure": "block" (disponible à partir d'une version récente, voir la référence Hooks officielle) afin d'éviter qu'une erreur de chemin de script ne rende toute la politique inefficace.
Enregistrement dans Codex
La structure est proche de celle de Claude Code ; à placer dans ~/.codex/hooks.json ou dans le fichier projet .codex/hooks.json :
{
"hooks": {
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "/usr/bin/bash /absolute/path/to/block-rm-demo.sh",
"timeout": 5,
"statusMessage": "Checking Bash command"
}
]
}
]
}
}
À noter : Codex exige que les hooks non gérés soient d'abord audités et approuvés via /hooks dans le CLI ; les hooks au niveau projet nécessitent en plus que .codex/ du projet soit de confiance. Pour une automatisation ponctuelle, la documentation officielle prévoit --dangerously-bypass-hook-trust. Il est possible de désactiver les hooks globalement avec [features] hooks = false.
Enregistrement dans Cursor
Le fichier hooks.json de Cursor est plus plat et requiert un champ version :
{
"version": 1,
"hooks": {
"preToolUse": [
{
"command": "~/.agents/hooks/block-rm-demo.sh",
"matcher": "Shell",
"timeout": 5
}
]
}
}
Pour les hooks au niveau projet, le chemin est relatif à la racine du dépôt, par exemple .cursor/hooks/block-rm-demo.sh. Pour les hooks critiques en matière de sécurité, ajoutez "failClosed": true. Il est aussi possible d'utiliser beforeShellExecution à la place, où le matcher filtre directement sur le texte de la commande (ex. rm\\s+-rf).
Test : Claude Code PreToolUse (clé du site)
Environnement : Claude Code CLI 2.1.319, fichier .claude/settings.json dans le projet avec le script fail-open ci-dessus, exécuté en mode non-interactif -p via l'interface compatible aicodewith.
- Chemin de passage : demande au modèle d'exécuter
echo hooks-allow-ok→ sortiehooks-allow-ok, environ 8 secondes. - Chemin d'interception : demande au modèle d'exécuter
rm -rf /tmp/hooks-deny-me→ retour d'une erreur PreToolUse hook, commande non exécutée, environ 9 secondes. Extrait du message d'erreur :
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
- Fail-open au niveau unitaire : injection d'un JSON invalide sur stdin → le script fait exit 0 (ne bloque pas la suite).
Cursor n'a pas été testé de façon équivalente dans un environnement sans interface graphique ; la colonne Cursor du tableau ci-dessus est basée sur la documentation officielle Cursor Hooks. La configuration Codex a été vérifiée d'après la documentation officielle ; le test d'intégration a été réalisé sur la chaîne Claude Code uniquement, afin d'éviter une consommation redondante.
Si vous utilisez Codex, attachez le même script à PreToolUse avec le matcher Bash, faites /hooks trust, puis lancez une commande correspondante et une commande non correspondante pour valider vous-même.
Fail-open ou fail-closed ?
| Scénario | Recommandation | Configuration |
|---|---|---|
| Confort (filtrage des logs de build, auto-format) | fail-open | Comportement par défaut ; le script fait exit 0 en cas d'erreur de parsing |
| Sécurité / conformité (interdire la suppression, l'exfiltration, la modification de fichiers de clés) | fail-closed | Claude Code : onFailure: "block" ; Cursor : failClosed: true ; et tester soi-même « si le script est supprimé, l'outil est-il bloqué ? » |
| Hooks gérés Codex | Selon requirements.toml entreprise / managed hooks | Voir la documentation Managed hooks officielle ; les hooks utilisateur locaux en cas d'échec ne bloquent pas par défaut |
Selon l'article de SwiftLee : les hooks de confort doivent être fail-open pour éviter qu'un hook cassé ne bloque le travail ; seuls les hooks qui empêchent des opérations dangereuses doivent être fail-closed.
Points d'attention de configuration (communs aux trois plateformes)
- Lire avant d'activer : les hooks provenant d'un dépôt ou d'un plugin sont des scripts locaux avec les mêmes permissions que vous. Certains plugins comme Postman ont déjà installé automatiquement des hooks SessionStart — vérifiez ce qui est attaché avant l'installation.
- Timeout court : l'agent attend la fin du hook ; 5 secondes est une valeur courante pour les hooks de confort utilisateur.
- Limiter les boucles pour Stop / stop : Cursor applique un
loop_limit(5 par défaut) pourstop/subagentStop; évitez les boucles infinies du type « ajouter un commentaire après la fin ». - Ne pas mélanger les noms de matcher : l'outil shell de Claude Code / Codex s'appelle
Bash; pour le matching générique dans Cursor, on utiliseShell. - Hooks ≠ skills : les skills sont des capacités invoquées par nom ou description ; les hooks se déclenchent sur des événements, sans qu'on les appelle explicitement.
Utiliser une clé aicodewith pour Claude Code / Codex (optionnel)
Tester les hooks ne dépend pas d'un fournisseur de modèle particulier. Si vous passez par aicodewith pour accéder aux modèles :
- Claude Code : configurez la Base URL compatible et la clé selon la documentation du site.
- Codex : dans
~/.codex/config.tomlglobal, utilisezexperimental_bearer_token,name = "aicodewith",base_url = "https://api.aicodewith.ai/chatgpt/v1"(notez bien/chatgpt/v1, pas simplement/v1).
Questions fréquentes
Quelle est la différence entre les hooks et AGENTS.md ?
AGENTS.md entre dans le contexte et le modèle peut l'ignorer ; les hooks sont exécutés directement par Claude Code / Codex / Cursor sur les événements du cycle de vie. Les intentions vont dans le markdown, les contraintes strictes deviennent des hooks.
Faut-il choisir exit code 2 ou JSON deny ?
Les deux fonctionnent. Claude Code / Codex utilisent généralement stderr + exit 2 ; le JSON (ex. permissionDecision / updatedInput) est préférable quand on a besoin d'une raison structurée ou de réécrire l'entrée. Cursor pour les hooks de permission privilégie le champ permission en JSON sur stdout ; exit 2 est aussi équivalent à un deny.
Pourquoi mes hooks projet ne s'exécutent-ils pas ?
Vérifiez : le workspace / projet est-il de confiance ? Codex a-t-il approuvé les hooks via /hooks ? Le chemin est-il correct (les hooks projet Cursor sont relatifs à la racine du dépôt) ? Le nom du matcher correspond-il au bon nom d'outil ? Dans Claude Code, le menu /hooks permet de vérifier l'origine des hooks actifs.
Les hooks peuvent-ils remplacer entièrement une politique de sécurité ?
Non. La documentation officielle reconnaît que certains chemins ne passent pas par les hooks ; les scripts de plugins et de SessionStart sont eux-mêmes une surface de risque. Les hooks constituent une couche de garde déterministe, à combiner avec le modèle de permissions, la gestion des clés et le choix du répertoire de travail.
Le retour ask de Cursor dans preToolUse est-il fiable ?
Selon la documentation officielle de Cursor : "ask" dans la sortie de preToolUse n'est pas appliqué de force pour l'instant ; pour bloquer une opération, utilisez "deny" ou exit 2. Les événements comme beforeShellExecution supportent allow / deny / ask.
Résumé
Faites passer les règles que « le modèle devrait retenir » au niveau de hooks que « le harness exécutera à chaque fois ». Commencez par un script PreToolUse / preToolUse minimal : matcher sur Bash ou Shell, exit 2 / deny en cas de correspondance, fail-open par défaut, fail-closed pour les scénarios de sécurité. Les fichiers de configuration et les noms d'événements diffèrent entre Claude Code, Codex et Cursor, mais la logique événement → matcher → script → décision est identique sur les trois plateformes.
Créer une clé API → · Voir les modèles et la documentation d'intégration →



