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
        }
      ]
    }
  ]
}

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 — Ajouter le contexte du projet pour les prompts liés au déploiement :

{
  "UserPromptSubmit": [
    {
      "matcher": "",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/add-deploy-context.sh"
        }
      ]
    }
  ]
}

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
        }
      ]
    }
  ]
}

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.

Documentation Index

​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