> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hooks du cycle de vie

> Comprendre les événements de hook et les données disponibles à chaque étape

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.

***

<div id="pretooluse">
  ## PreToolUse
</div>

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 :**

```json theme={null}
{
  "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 :

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

***

<div id="posttooluse">
  ## PostToolUse
</div>

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 :**

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

***

<div id="permissionrequest">
  ## PermissionRequest
</div>

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 :**

```json theme={null}
{
  "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)\""
        }
      ]
    }
  ]
}
```

***

<div id="userpromptsubmit">
  ## UserPromptSubmit
</div>

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 :**

```json theme={null}
{
  "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 :

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}
```

***

<div id="stop">
  ## Stop
</div>

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 :**

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

<Warning>
  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.
</Warning>

***

<div id="postcompaction">
  ## PostCompaction
</div>

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 :**

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

***

<div id="sessionstart">
  ## SessionStart
</div>

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 :**

```json theme={null}
{
  "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 :

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}
```

***

<div id="sessionend">
  ## SessionEnd
</div>

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 |

***

<div id="matching-multiple-events">
  ## Associer plusieurs événements
</div>

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

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}
```

<div id="using-the-matcher">
  ## Utiliser le matcher
</div>

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.

<Note>
  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.
</Note>

| 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`            |

<div id="tool-names-you-can-match">
  ### Noms d’outils que vous pouvez faire correspondre
</div>

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.