Larssen Consulting
Agents et outils

Hook

Le hook est un programme que l’outil faisant tourner un agent exécute automatiquement à un moment défini de son travail, pour surveiller, compléter ou interdire une action, indépendamment de ce que le modèle a décidé.

  • Lecture : 4 minutes
  • Mis à jour le 29 octobre 2026
  • 5 sources

En clair

Dans un immeuble de bureaux, le badge déclenche des règles à chaque passage : la porte du local serveur refuse les visiteurs, l’entrée enregistre l’heure d’arrivée, l’alarme se met en route quand le dernier sort. Personne ne demande l’avis de la personne qui passe : la règle s’applique à l’instant précis où l’événement survient. Un hook fonctionne de la même manière pour un agent IA.

Le mot anglais signifie « crochet » : on accroche son propre programme à un moment précis du travail de l’agent. Juste avant qu’il lance une commande, un hook peut vérifier qu’elle n’est pas dangereuse et l’arrêter. Juste après qu’il a modifié un fichier, un autre peut remettre le code en forme ou lancer les tests. Quand l’agent ou l’un de ses sous-agents termine, un troisième peut prévenir l’équipe.

L’intérêt tient en un mot : la certitude. Une consigne écrite dans le prompt, le modèle peut l’oublier ou la contourner. Un hook, lui, s’exécute à chaque fois, parce que c’est le logiciel qui entoure le modèle qui le déclenche, pas le modèle qui le choisit.

Un exemple

Une société de services informatiques équipe ses développeurs d’un agent de code. La direction technique craint deux choses : qu’un agent efface des fichiers par erreur et qu’il lise les fichiers contenant des mots de passe. Plutôt que de multiplier les consignes, elle installe sur tous les postes un hook déclenché avant chaque commande : toute suppression de fichiers et toute lecture des fichiers de secrets sont refusées, et l’agent reçoit en retour le motif du refus pour chercher une autre voie.

Elle ajoute un deuxième hook, déclenché après chaque modification de fichier, qui lance l’outil de mise en forme et les tests rapides, et un troisième, déclenché à la fin de chaque sous-agent, qui inscrit dans un journal ce qui a été fait. Les règles sont désormais les mêmes pour tous, et l’équipe sécurité peut les relire à un seul endroit.

Niveau technique

Comment ça marche

L’idée est bien plus ancienne que les agents. Le logiciel de gestion de versions Git, par exemple, exécute depuis longtemps des scripts placés dans un dossier dédié du dépôt à des moments clés : avant d’accepter un message de validation, un script qui se termine en erreur fait échouer l’opération, tandis qu’un script lancé après la validation sert seulement à notifier et ne peut plus en changer l’issue 1. Cette distinction entre hooks qui peuvent bloquer et hooks qui se contentent d’observer se retrouve à l’identique chez les agents.

  1. DéclarerOn associe un script à un événement du cycle de vie de l’agent, éventuellement limité à certains outils.
  2. DéclencherQuand l’événement survient, le harness lance le script et lui transmet le contexte : outil visé, arguments, session.
  3. DéciderLe script laisse passer, bloque l’action avec un motif, ou ajoute une information pour le modèle.
  4. ReprendreL’agent poursuit son travail en tenant compte de la décision, par exemple en cherchant une autre voie.

Seuls certains événements, comme l’avant d’un appel d’outil, permettent de bloquer ; les autres servent à observer ou à compléter.

Dans Claude Code, l’agent de code d’Anthropic, la documentation énumère une vingtaine d’événements, dont le début de session, l’envoi d’un prompt, l’avant et l’après d’un appel d’outil, le lancement et la fin d’un sous-agent (SubagentStart, SubagentStop) et la fin de la réponse (Stop) 2. Le hook reçoit le contexte de l’événement au format JSON ; s’il se termine avec le code de sortie 2, l’action est bloquée là où l’événement le permet, et son message d’erreur est transmis au modèle comme motif 2. Cursor a introduit un système comparable dans sa version 1.7, avec des événements comme beforeShellExecution, beforeReadFile ou afterFileEdit 3. Un point de vigilance : chez Cursor, un hook qui plante ou dépasse son délai laisse par défaut passer l’action, sauf si on l’a configuré pour bloquer en cas d’échec, ce qui est recommandé pour les contrôles de sécurité 4.

Les kits de développement d’agents proposent la même idée sous forme de fonctions plutôt que de scripts : le SDK Agents d’OpenAI fournit une classe qui reçoit des rappels à chaque étape d’une exécution, juste avant l’appel au modèle ou lors du passage de relais d’un agent à un autre 5. Il ne faut pas confondre le hook avec l’appel d’outils : un outil est choisi par le modèle, un hook est déclenché par le harness, que le modèle le veuille ou non. Ni avec le webhook, qui désigne une notification envoyée par un service web à un autre.

Ce que ça change pour une entreprise

Les hooks sont l’endroit où une entreprise traduit ses règles en contrôles automatiques autour des agents : interdire certaines commandes, protéger les fichiers sensibles, imposer les tests, journaliser chaque action pour l’audit, alerter quand un travail se termine. Ils ne coûtent presque rien à l’exécution et s’écrivent avec des outils que les équipes connaissent déjà. Surtout, ils déplacent la confiance du modèle vers du code relu et versionné, ce qui facilite le dialogue avec la sécurité et la conformité.

Ce sont pourtant des programmes qui tournent avec les droits de l’utilisateur : un hook mal écrit peut ralentir chaque action, se déclencher en boucle, ou laisser passer ce qu’il devait bloquer s’il plante, comme le comportement par défaut de Cursor en cas d’échec le montre 4. Ils ne remplacent ni des permissions bien bornées ni un bac à sable : un filtre sur le texte d’une commande se contourne. Il faut aussi les maintenir, car les événements et leurs formats évoluent d’une version de l’outil à l’autre.

Idées reçues

  • « Un hook, c’est une consigne de plus donnée à l’IA. »

    Non : c’est du code exécuté par le logiciel qui entoure le modèle. Le modèle ne peut ni l’ignorer ni décider de le sauter.

  • « Avec des hooks, l’agent est sécurisé. »

    Ils ajoutent une barrière utile, mais un filtre peut être contourné ou tomber en panne. Ils complètent les permissions, le bac à sable et la relecture humaine, sans les remplacer.

  • « Les hooks sont une spécificité de Claude Code. »

    Le principe existe depuis longtemps, dans Git par exemple, et se retrouve chez Cursor ou dans le SDK Agents d’OpenAI, avec des noms d’événements différents.

Sources

  1. Git, « githooks – Hooks used by Git », documentation officielle
  2. Anthropic, « Hooks reference », documentation de Claude Code
  3. InfoQ, « Cursor 1.7 Adds Hooks for Agent Lifecycle Control », 2025
  4. Cursor, « Hooks », documentation officielle
  5. OpenAI, « Lifecycle », documentation du SDK Agents

Voir aussi