Les hooksHooksLos hooks
Parcours : Construire un agent de code, le harnais · OpérationnelCourse: Building a Coding Agent: the Harness · PractitionerCurso: Construir un agente de código: el harness · Operativo

≈ 9 min
Le problème
Le problème : chaque nouveau besoin (journal, contrôle, notification) s’écrit dans la boucle, qui grossit et se fragilise.
Au programme de ce moduleIn this moduleEn el programa de este módulo
- 01Le problème≈ 9 min
- 02L’intuition≈ 8 min
- 03Le mécanisme≈ 9 min
- 04Le code, pas à pas≈ 10 min
- 05Pièges & pratiques≈ 10 min
- 06Exercice≈ 6 min
- 07Quiz≈ 5 min
Objectifs d’apprentissage
À la fin de ce module, vous saurez étendre le comportement d’un agent sans modifier sa boucle, grâce à un registre de hooks. Voici les acquis visés.
- Expliquer pourquoi les extensions écrites dans la boucle la fragilisent ;
- Nommer les quatre événements d’un cycle d’agent (UserPromptSubmit, PreToolUse, PostToolUse, Stop) et ce que chacun permet ;
- Coder un registre de hooks (register_hook, trigger_hooks) et y déplacer le contrôle de permissions du module 3 ;
- Distinguer un hook qui observe d’un hook qui décide, et maîtriser les risques d’un hook qui empêche l’agent de s’arrêter.
Sources
Curriculum open-source shareAI-lab/learn-claude-code, chapitre s04 (Hooks), publié sous licence MIT, © shareAI-lab, adaptation Getul. La notice de licence est reproduite sur la page Sources et références. Documentation publique de Claude Code (Anthropic) sur les hooks, citée pour comparer avec un outil en production. Le motif présenté est indépendant du fournisseur : il vaut pour toute API offrant l’appel d’outils.
La boucle qui grossit
Votre agent sait désormais demander la permission. Puis les besoins arrivent, raisonnables un par un : garder un journal de chaque commande lancée, prévenir l’équipe quand un fichier de configuration change, vérifier la sortie d’un outil avant de la renvoyer au modèle, ajouter la date du jour à chaque demande. Chacun tient en trois lignes. Et chacun, faute d’autre endroit, s’écrit dans agent_loop.
for block in response.content:
if block.type == "tool_use":
journaliser(block) # ajouté en janvier
refus = check_permission(block.name, block.input)
notifier_equipe(block) # ajouté en février
...
output = DISPATCH[block.name](block.input)
verifier_sortie(block, output) # ajouté en mars
...Le problème n’est pas la longueur. C’est que la boucle porte des invariants délicats (une réponse par demande, l’ordre des messages, l’unique critère d’arrêt) et que chaque ajout est une occasion de les casser. Ce que vous voulez étendre, c’est le COMPORTEMENT de l’agent ; ce que vous modifiez, c’est son MOTEUR.
Pour comprendre : les extensions vivent à l’extérieur
Un navigateur ne se recompile pas à chaque extension installée : il expose des points d’accroche, et les extensions s’y branchent. Un harnais d’agent bien conçu fait de même. La boucle reste un noyau stable, qui se contente d’annoncer « je vais exécuter un outil », « je viens de l’exécuter », « je vais m’arrêter » ; ce qui doit se passer à ces moments-là vit ailleurs.
Vérifiez votre compréhensionCheck your understandingVerifique su comprensión
Pourquoi éviter d’ajouter chaque nouvelle vérification directement dans agent_loop ?
À retenir
Chaque besoin écrit dans la boucle la fragilise. La boucle doit rester un noyau stable ; les extensions doivent s’y brancher de l’extérieur.