Codex : imposer vos règles avec un hook Stop

Un contrôle déclenché sur l’événement Stop peut empêcher Codex de conclure une session si un rapport n’atteint pas des seuils de sources et de domaines. Dans un test sur l’infrastructure des data centers, le rapport n’a été validé qu’après 12 sources uniques issues de 10 domaines. La mécanique repose sur un script externe, un schéma JSON de sortie et une configuration de hook en mode commande. L’approche s’étend aux autres événements de cycle de vie pour insérer une logique déterministe autour de l’exécution.

Un test validé après 12 sources uniques et 10 domaines

Lors d’une exécution sur le thème des tendances récentes dans l’infrastructure des centres de données, Codex a d’abord livré trois tendances appuyées par sept sources uniques. Chaque tendance dépassait deux références, mais l’ensemble ne satisfaisait pas l’objectif de dix sources. Le hook déclenché sur Stop a renvoyé un retour demandant davantage de corroborations, avec l’ajout d’au moins trois sources indépendantes sur la même fenêtre temporelle. Après un tour supplémentaire, la sortie a atteint 12 sources uniques provenant de 10 domaines. Trois axes majeurs ont été retenus : l’essor de campus IA à l’échelle des gigawatts, les contraintes d’accès à l’énergie et de permis, et la montée du refroidissement liquide. Le hook s’est exécuté une nouvelle fois et a autorisé la fin de la session, la synthèse étant sauvegardée dans outputs/research_brief.json.

La validation intervient au moment Stop sans terminer l’exécution

Les vérifications ayant lieu une fois le rapport préparé, le point d’accroche retenu est l’événement Stop. À ce stade, Codex transmet last_assistant_message conforme au schéma défini, ce qui permet au script de contrôler le contenu. Une décision de blocage sur Stop n’interrompt pas le run : elle empêche simplement la clôture et renvoie des indications pour qu’un nouveau tour améliore la sortie dans le même cycle. Le hook est déclaré dans .codex/hooks.json avec un type "command" lançant le script Python, et un champ commandWindows pour l’environnement Windows. Aucun matcher n’est prévu ici, Codex n’en appliquant pas sur l’événement Stop.

Trois seuils contrôlés par un script Python dédié

Le fichier .codex/hooks/validate_research.py définit trois seuils : au moins deux sources par tendance, dix sources uniques au total et cinq domaines uniques. Le script lit l’événement sur l’entrée standard, charge la dernière réponse de l’assistant en dictionnaire, puis parcourt les tendances numérotées dès 1. Les URLs sont agrégées dans un ensemble pour obtenir l’unicité, et urlparse extrait les domaines. Des messages d’erreur sont ajoutés si un seuil n’est pas atteint, puis regroupés dans un texte d’échec préfixé par "Échec de la vérification du rapport de recherche :". L’objet retourné place decision à "block" et reason au message détaillant les manques.

Un schéma JSON et un prompt bornent la forme de sortie

Le cadrage amont s’appuie sur un modèle d’instruction précisant le sujet, une fenêtre de publication inclusive et la production de trois tendances clés assorties d’un bref rapport sourcé. Un schéma JSON de type object, sans propriétés additionnelles, rend obligatoires summary et trends, et impose pour chaque tendance les champs title, summary et un tableau de sources en chaînes de caractères. Enregistré sous schemas/research_brief.schema.json, ce format est celui que le hook attend lors de l’événement Stop. L’agent doit ainsi retourner une synthèse structurée conforme à ces contraintes.

Exécution non interactive et trace d’événements en JSONL

Le test utilise le sujet "tendances récentes dans l'infrastructure des centres de données", avec as_of fixé à 2026-08-01 et lookback_days à 90. Le prompt rendu est enregistré dans outputs/research_prompt.md et peut être précédé d’une revue des hooks via la commande /hooks dans le projet. L’exécution se fait en mode non interactif avec exec et l’option --search active la recherche web. Le modèle sélectionné est gpt-5.6-sol, la sortie étant contrainte par --output-schema vers schemas/research_brief.schema.json et enregistrée avec -o dans outputs/research_brief.json. Le fichier d’instruction est fourni en entrée standard par "< outputs/research_prompt.md" et la sortie d’événements est redirigée vers outputs/run.jsonl. L’option --json fait émettre ces événements au format JSONL, offrant une trace d’exécution. Le signe "-" indique à Codex d’accepter l’entrée via stdin lorsque la redirection est utilisée.

Où brancher ses hooks dans la boucle et avec quelles règles

Plusieurs points d’attache rythment une session : SessionStart au lancement, PreToolUse avant l’appel d’un outil, PostToolUse après son exécution, Stop juste avant la fin de réponse, puis SessionEnd à la clôture. Un hook peut charger du contexte dès SessionStart, inspecter une opération à PreToolUse, traiter un résultat à PostToolUse, ou valider la sortie à Stop. À chaque événement, Codex peut transmettre au script les informations utiles, mais un même moment peut correspondre à de multiples actions : un matcher sélectionne alors les cas visés, par exemple seulement les commandes shell. La configuration articule trois composantes — event, matcher et handler — qui définissent quand exécuter, dans quelles conditions et quelle action réaliser. Ce cadre permet d’ajouter une logique déterministe autour de l’exécution de Codex sur l’ensemble du cycle.