Hooks du cycle de vie

Chaque événement de hook se déclenche à un moment spécifique du cycle de vie de l’agent. Utilisez le champ matcher (une expression régulière appliquée au tool_name de l’événement de hook) pour filtrer les invocations d’outil qui déclenchent votre hook.

PreToolUse

Se déclenche avant l’exécution d’un outil. Utilisez-le pour bloquer, modifier ou ajouter du contexte aux appels d’outils. Données stdin :

Champ	Description	Exemple
`tool_name`	Nom de l’outil appelé	`exec`, `edit`, `mcp__github__create_issue`
`tool_input`	Arguments transmis à l’outil	`{ "command": "rm -rf /", "shell_id": "main" }`

Exemple — Bloquer les commandes destructrices :

{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); sys.exit(2 if 'rm -rf' in cmd else 0)\""
        }
      ]
    }
  ]
}

Exemple — Exiger une confirmation pour les écritures hors de src/ : Utilisez un script qui examine l’entrée de l’outil et renvoie une décision :

{
  "PreToolUse": [
    {
      "matcher": "edit",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/check-edit-path.sh",
          "timeout": 5
        }
      ]
    }
  ]
}

Exemple — Réécrire les commandes avant leur exécution : Un hook peut réécrire de manière transparente l’entrée de l’outil en affichant hookSpecificOutput.updatedInput sur stdout (voir Format de sortie). Par exemple, un script de hook qui fait passer les commandes shell par un wrapper :

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

Les arguments réécrits sont intégrés à l’appel d’outil avant son exécution — l’agent exécute la commande mise à jour au lieu de la commande d’origine.

PostToolUse

Se déclenche après l’exécution d’un outil. Utilisez-le pour la journalisation, la validation ou pour activer des actions de suivi. Données stdin :

Champ	Description
`tool_name`	Nom de l’outil exécuté
`tool_input`	Arguments transmis
`tool_response`	Objet contenant `success` (booléen), `output` (chaîne) et `error` (chaîne ou null)

Exemple — Journaliser toutes les commandes shell :

{
  "PostToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-command-log'"
        }
      ]
    }
  ]
}

PermissionRequest

Se déclenche lorsque l’agent a besoin d’une décision d’autorisation. Utilisez-le pour implémenter une logique d’approbation personnalisée. Données stdin :

Field	Description
`tool_name`	Outil demandant une autorisation
`tool_input`	Arguments de l’appel à l’outil

Exemple — Approbation automatique des commandes git :

{
  "PermissionRequest": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "python3 -c \"import sys, json; data = json.load(sys.stdin); cmd = data.get('tool_input', {}).get('command', ''); print(json.dumps({'decision': 'approve'})) if cmd.startswith('git ') else sys.exit(0)\""
        }
      ]
    }
  ]
}

UserPromptSubmit

Se déclenche lorsque l’utilisateur envoie un message. Servez-vous-en pour ajouter du contexte ou déclencher des workflows. Données stdin :

Field	Description
`prompt`	Le texte du message de l’utilisateur

Exemple — Injecter du contexte pour chaque prompt :

{
  "UserPromptSubmit": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"UserPromptSubmit\", \"additionalContext\": \"Deploys require an approved change ticket.\"}}'"
        }
      ]
    }
  ]
}

La commande affiche additionalContext dans un objet hookSpecificOutput sur stdout, associé au nom de l’événement. Ce texte est injecté dans le contexte de l’agent :

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}

Stop

Se déclenche lorsque l’agent décide de s’arrêter (c’est-à-dire de terminer son tour). Utilisez-le pour ajouter des instructions complémentaires ou éviter un arrêt prématuré. Données stdin :

Field	Description
`stop_hook_active`	Indique si un hook d’arrêt est déjà actif

Exemple — Rappeler à l’agent d’exécuter des tests :

{
  "Stop": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "echo '{\"decision\": \"block\", \"reason\": \"Please run the test suite before stopping.\"}'"
        }
      ]
    }
  ]
}

Faites attention aux hooks d’arrêt bloquants : ils peuvent faire entrer l’agent dans une boucle si la condition n’est pas satisfaite à terme.

PostCompaction

Se déclenche après la réussite du compactage du contexte. À utiliser pour la journalisation, le déclenchement d’actions de suivi ou la réinjection de contexte qui aurait pu être perdu lors du compactage. Données stdin :

Champ	Description
`summary`	Texte de résumé produit par le compacteur (peut être nul si aucun résumé n’a été généré)

Exemple — Journaliser les événements de compactage :

{
  "PostCompaction": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "sh -c 'cat >> ~/.devin-compaction-log'"
        }
      ]
    }
  ]
}

SessionStart

Se déclenche lorsqu’une nouvelle session démarre. À utiliser pour l’initialisation, la journalisation ou la configuration de l’environnement. Données stdin :

Field	Description
`source`	Comment la session a été lancée

Exemple — Exécuter le script de configuration :

{
  "SessionStart": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/dev-setup.sh",
          "timeout": 10
        }
      ]
    }
  ]
}

Une commande SessionStart peut également injecter du contexte en écrivant additionalContext dans un objet hookSpecificOutput sur stdout :

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}

SessionEnd

Se déclenche lorsqu’une session se termine. Utilisez-le pour effectuer un nettoyage ou assurer la journalisation finale. Données stdin :

Champ	Description
`reason`	Raison pour laquelle la session s’est terminée

Associer plusieurs événements

Un même fichier de hooks peut définir des hooks pour plusieurs événements :

{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}

Utiliser le matcher

Le champ matcher est une regex appliquée au tool_name de l’événement de hook. Il est disponible pour les événements liés aux outils : PreToolUse, PostToolUse et PermissionRequest. Pour les événements non liés aux outils (UserPromptSubmit, Stop, PostCompaction, SessionStart et SessionEnd), il n’y a pas de tool_name ; utilisez "" ou omettez le matcher pour exécuter le hook sur chaque événement de ce type.

Le matcher n’est pas un motif glob d’autorisation. Des motifs comme mcp__github__* sont utiles dans les autorisations, mais les matchers de hook sont des regex. Utilisez mcp__github__.* dans un matcher de hook.

Matcher	Correspond
`""` (vide) ou omis	Tous les noms d’outil pour les événements liés aux outils
`"exec"`	Les noms d’outil contenant `exec`
`"^exec$"`	Uniquement l’outil `exec`
`"^(exec\|edit)$"`	Uniquement `exec` ou `edit`
`"^mcp__.*"`	Tous les outils MCP
`"^mcp__github__.*"`	Tous les outils du serveur MCP `github`
`"^mcp__github__create_issue$"`	L’outil `create_issue` du serveur MCP `github`

Noms d’outils que vous pouvez faire correspondre

Les matchers de hook s’appliquent aux mêmes noms d’outils exposés en externe que les scripts de hook reçoivent sur stdin dans tool_name. Les noms d’outils exacts disponibles peuvent varier selon le mode CLI, le modèle et les intégrations activées. Les noms d’outils publics de base les plus courants sont :

read
edit
grep
glob
exec

Les outils d’un serveur MCP se présentent sous la forme mcp__<server>__<tool>. Par exemple, un outil d’un serveur MCP github nommé create_issue apparaît sous la forme mcp__github__create_issue. Pour les autres outils, faites correspondre exactement le tool_name affiché sur stdin par le hook. Pour confirmer l’ensemble complet disponible dans votre session actuelle, ajoutez un hook PostToolUse temporaire avec matcher: "" et consignez la charge utile reçue sur stdin.

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Stop

​PostCompaction

​SessionStart

​SessionEnd

​Associer plusieurs événements

​Utiliser le matcher

​Noms d’outils que vous pouvez faire correspondre

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

Associer plusieurs événements

Utiliser le matcher

Noms d’outils que vous pouvez faire correspondre