Claude Code / Codex / Cursor Agent Hooks : configuration PreToolUse, script minimal et test fail-open

Les instructions, AGENTS.md et skills sont des suggestions que le modèle peut ignorer ; les hooks sont des scripts déterministes exécutés par le harness à des moments fixes. Cet article compare les chemins de configuration, noms d'événements, exit 2 / deny, fail-open et fail-closed entre Claude Code, Codex et Cursor (PreToolUse ou équivalent), et présente un script d'interception minimal testé sur Claude Code.

9 分钟阅读
Claude Code / Codex / Cursor Agent Hooks : configuration PreToolUse, script minimal et test fail-open

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 utilise preToolUse (ou le plus ciblé beforeShellExecution). L'interception se fait généralement via exit code 2 ou un JSON contenant deny.
  • 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-me est intercepté par PreToolUse (exit 2) ; echo hooks-allow-ok passe 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émentClaude CodeCodexCursor
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'outilPreToolUsePreToolUsepreToolUse ; pour les commandes shell, beforeShellExecution est aussi disponible
Après appel d'outilPostToolUsePostToolUsepostToolUse / afterFileEdit etc.
Nom de l'outil shell (matcher)BashBashShell (beforeShellExecution filtre directement sur le texte de la commande)
Interceptionexit 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 échoueLa 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 / auditLa confiance accordée au workspace influe sur les hooks projetLes hooks non gérés doivent être audités et approuvés via /hooks ; --dangerously-bypass-hook-trust disponible pour un usage ponctuelLes 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 :

  1. Instructions et préférences → AGENTS.md / skills (expliquer l'intention, le style, le workflow).
  2. 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).
  3. 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_stdin pour 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.

bash
#!/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 :

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 :

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 :

json
{
  "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.

  1. Chemin de passage : demande au modèle d'exécuter echo hooks-allow-ok → sortie hooks-allow-ok, environ 8 secondes.
  2. 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 :
text
PreToolUse:Bash hook error: [${CLAUDE_PROJECT_DIR}/.claude/hooks/block-rm.sh]:
Blocked by PreToolUse hook: refusing rm -rf /tmp/hooks-deny-me
  1. 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énarioRecommandationConfiguration
Confort (filtrage des logs de build, auto-format)fail-openComportement 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-closedClaude 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 CodexSelon requirements.toml entreprise / managed hooksVoir 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)

  1. 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.
  2. Timeout court : l'agent attend la fin du hook ; 5 secondes est une valeur courante pour les hooks de confort utilisateur.
  3. Limiter les boucles pour Stop / stop : Cursor applique un loop_limit (5 par défaut) pour stop / subagentStop ; évitez les boucles infinies du type « ajouter un commentaire après la fin ».
  4. 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 utilise Shell.
  5. 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.toml global, utilisez experimental_bearer_token, name = "aicodewith", base_url = "https://api.aicodewith.ai/chatgpt/v1" (notez bien /chatgpt/v1, pas simplement /v1).

Créer une clé API →

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 →

Sources

相关文章

C'est quoi le UI SDK, et comment l'utiliser ? La bibliothèque de comportements Vercel et shadcn pour les agents, installée et testée dans Claude Code / Codex / Cursor (0.1.0-beta.1)

C'est quoi le UI SDK, et comment l'utiliser ? La bibliothèque de comportements Vercel et shadcn pour les agents, installée et testée dans Claude Code / Codex / Cursor (0.1.0-beta.1)

Le UI SDK est la bibliothèque de comportements de Vercel pour les agents, publiée le 12 novembre 2026 en version 0.1.0-beta.1. Les comportements vivent dans le paquet indépendant du framework @ui-sdk/core, puis sont rendus par les adaptateurs React, Vue, Svelte, Solid et Web Components. Ce guide suit la documentation officielle sur ce que c'est, comment l'installer et comment ajouter le skill pour Claude Code, Codex et Cursor, et consigne les commandes, durées et sorties relevées sur notre machine de test.

AWS Emulator, c'est quoi et comment l'installer ? Tester des applications AWS en local avec Claude Code et Codex (testé sur 1.0.322)

AWS Emulator, c'est quoi et comment l'installer ? Tester des applications AWS en local avec Claude Code et Codex (testé sur 1.0.322)

AWS Emulator est l'émulateur local officiel des API AWS, disponible en version GA depuis le 11 novembre 2026 (heure des États-Unis). Il n'entraîne aucuns frais de service supplémentaires, son code source est ouvert, il ne demande aucun compte AWS et couvre plus de 200 services. Nous avons testé la version 1.0.322 sous Debian 13 : commandes d'installation, AWS CLI pointé vers l'endpoint local pour créer un bucket S3 et une table DynamoDB, erreurs rencontrées, et comment laisser Claude Code, Codex et Cursor écrire et tester du code contre l'émulateur.

T3 Code, c'est quoi et comment l'installer ? Connecter Claude Code et Codex, utiliser une clé API tierce, corriger les erreurs courantes (testé sur 0.1.9)

T3 Code, c'est quoi et comment l'installer ? Connecter Claude Code et Codex, utiliser une clé API tierce, corriger les erreurs courantes (testé sur 0.1.9)

T3 Code est la console open source de pingdotgg pour piloter des agents de code. Elle n'embarque aucun modèle et pilote les CLI Claude Code, Codex, Cursor et autres déjà installés sur votre machine. Nous avons testé T3 Code 0.1.9 sous Linux. Ce guide couvre les commandes d'installation, la configuration de Claude Code et de Codex avec une clé API AICodeWith pour que T3 Code les pilote, un essai complet des deux agents avec la commande t3 thread, puis les erreurs rencontrées et leurs solutions.