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

> Exécuter une logique personnalisée lorsque des événements spécifiques se produisent pendant une session

Les hooks vous permettent d’exécuter une logique personnalisée en réaction à des événements du cycle de vie de l’agent. Vous pouvez utiliser des hooks pour appliquer des politiques, ajouter du contexte, consigner des actions, modifier des autorisations ou vous intégrer à des systèmes externes.

Les hooks sont configurés au format JSON. Placez-les dans le répertoire `.devin/` de votre projet (ou dans une configuration niveau utilisateur), et Devin CLI les exécute lors des événements correspondants du cycle de vie. Les hooks existants dans les répertoires `.claude/` sont également détectés automatiquement — voir [Où se trouvent les hooks](#where-hooks-live).

***

<div id="what-can-hooks-do">
  ## Que peuvent faire les hooks ?
</div>

<CardGroup cols={2}>
  <Card title="Appliquer des politiques" icon="shield">
    Bloquer les commandes dangereuses, exiger une confirmation pour des actions spécifiques ou restreindre l'accès aux fichiers.
  </Card>

  <Card title="Ajouter du contexte" icon="message">
    Injecter des instructions ou des informations supplémentaires lorsque des outils spécifiques sont appelés.
  </Card>

  <Card title="Déclencher des effets secondaires" icon="bolt">
    Exécuter des scripts, envoyer des notifications ou consigner des événements lors de certains événements.
  </Card>

  <Card title="Modifier les autorisations" icon="lock">
    Accorder ou restreindre dynamiquement les autorisations selon la situation.
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## Exemple rapide
</div>

Créez `.devin/hooks.v1.json` dans votre projet :

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

`./scripts/check-command.sh` est exécuté avant chaque exécution de commande shell. Le script reçoit les données d'événement via stdin et peut bloquer l'opération en renvoyant un code de sortie non nul.

***

<div id="hook-events">
  ## Événements des hooks
</div>

Les hooks peuvent réagir aux événements de cycle de vie suivants :

| Événement           | Quand il se déclenche                          |
| ------------------- | ---------------------------------------------- |
| `PreToolUse`        | Avant l’exécution d’un outil                   |
| `PostToolUse`       | Après l’exécution d’un outil                   |
| `PermissionRequest` | Lorsqu’une décision d’autorisation est requise |
| `UserPromptSubmit`  | Lorsque l’utilisateur envoie un message        |
| `Stop`              | Lorsque l’agent souhaite s’arrêter             |
| `SessionStart`      | Lorsqu’une session démarre                     |
| `SessionEnd`        | Lorsqu’une session se termine                  |

Consultez [les hooks de cycle de vie](/fr/cli/extensibility/hooks/lifecycle-hooks) pour en savoir plus sur chaque événement et les données disponibles associées.

***

<div id="hook-format">
  ## Format des hooks
</div>

Chaque hook comporte un **type** (`command` ou `prompt`), un **matcher** facultatif (une regex appliquée au `tool_name` de l’événement du hook) et une configuration :

```json theme={null}
{
  "PreToolUse": [
    {
      "matcher": "exec",
      "hooks": [
        {
          "type": "command",
          "command": "./scripts/validate.sh",
          "timeout": 10
        }
      ]
    }
  ]
}
```

| Champ     | Description                                                                                                                                        |
| --------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matcher` | Expression régulière appliquée à `tool_name` de l’événement de hook. Une chaîne vide ou l’absence de `matcher` correspond à tous les noms d’outil. |
| `type`    | `"command"` pour exécuter une commande shell, ou `"prompt"` pour évaluer un prompt de LLM.                                                         |
| `command` | Commande shell à exécuter (pour le type `command`).                                                                                                |
| `prompt`  | Prompt de LLM à évaluer (pour le type `prompt`).                                                                                                   |
| `timeout` | Délai d’expiration en secondes (facultatif).                                                                                                       |

<div id="command-hooks">
  ### Hooks de commande
</div>

Les hooks de commande lancent une commande shell. Les données d’événement sont transmises au format JSON sur **stdin**, et la commande peut renvoyer du JSON sur **stdout** pour en contrôler le résultat (consultez [Format de sortie](#output-format) ci-dessous).

**Entrée** (stdin):

```json theme={null}
{
  "hook_event_name": "PreToolUse",
  "tool_name": "exec",
  "tool_input": {
    "command": "rm -rf /"
  }
}
```

La variable d’environnement `DEVIN_PROJECT_DIR` est automatiquement définie sur le répertoire racine du projet.

Consultez [Utiliser le Matcher](/fr/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) pour connaître les noms des outils intégrés et le format des noms d’outils MCP sur lesquels vous pouvez effectuer une correspondance.

<div id="output-format">
  ### Format de sortie
</div>

Un hook de commande peut afficher un objet JSON sur **stdout** pour contrôler l’issue.

Pour approuver ou bloquer une action, renvoyez un champ `decision` à la racine (avec un champ `reason` facultatif) :

```json theme={null}
{
  "decision": "block",
  "reason": "Destructive command blocked by policy"
}
```

Pour injecter du texte dans le contexte de l’agent, renvoyez `additionalContext` dans un objet `hookSpecificOutput` identifié par le nom de l’événement :

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

| Champ de sortie                        | Description                                                                                         |
| -------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `decision`                             | `"approve"` pour autoriser l’action, ou `"block"` pour la refuser                                   |
| `reason`                               | Explication affichée à l’agent                                                                      |
| `hookSpecificOutput.hookEventName`     | Événement auquel cette sortie s’applique (p. ex. `UserPromptSubmit`, `SessionStart`, `PostToolUse`) |
| `hookSpecificOutput.additionalContext` | Texte injecté dans le contexte de l’agent (pour `UserPromptSubmit`, `SessionStart`, `PostToolUse`)  |

<div id="exit-codes">
  ### Codes de sortie
</div>

| Code  | Signification                                        |
| ----- | ---------------------------------------------------- |
| 0     | Succès — le hook continue normalement                |
| 2     | Blocage — l’action est refusée                       |
| Autre | Erreur — consignée dans les logs, mais ne bloque pas |

***

<div id="where-hooks-live">
  ## Où se trouvent les hooks
</div>

Devin CLI lit les hooks aux emplacements suivants. Ils utilisent tous le même format JSON.

<div id="project-level">
  ### Au niveau du projet
</div>

| Emplacement                   | Description                                       |
| ----------------------------- | ------------------------------------------------- |
| `.devin/hooks.v1.json`        | Fichier de hooks autonome (recommandé)            |
| `.devin/config.json`          | Clé `"hooks"` dans le fichier de configuration    |
| `.devin/config.local.json`    | Clé `"hooks"` (surcharge locale, ignorée par Git) |
| `.claude/settings.json`       | Clé `"hooks"` (format Claude Code)                |
| `.claude/settings.local.json` | Clé `"hooks"` (format Claude Code)                |

<div id="user-level-global">
  ### Niveau utilisateur (global)
</div>

| Emplacement                                                                | Description                                     |
| -------------------------------------------------------------------------- | ----------------------------------------------- |
| `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` sous Windows) | Clé `"hooks"` dans la configuration utilisateur |
| `~/.claude.json`                                                           | Clé `"hooks"` (format Claude Code)              |
| `~/.claude/settings.json`                                                  | Clé `"hooks"` (format Claude Code)              |
| `~/.claude/settings.local.json`                                            | Clé `"hooks"` (format Claude Code)              |

<Note>
  Dans `.devin/hooks.v1.json`, l’objet hooks correspond à **l’intégralité du fichier** (sans clé enveloppante). Dans tous les autres emplacements, les hooks sont imbriqués sous la clé `"hooks"` dans un fichier de configuration.
</Note>

<Note>
  Les hooks issus des chemins `.claude/` sont chargés lorsque `read_config_from.claude` est activé (par défaut). Vous pouvez désactiver ce comportement dans votre [configuration utilisateur](/fr/cli/reference/configuration/read-config-from) si nécessaire.
</Note>

***

<div id="verifying-hooks">
  ## Vérifier les hooks
</div>

Utilisez la commande `/hooks` pour afficher tous les hooks actuellement chargés ainsi que leurs fichiers sources :

```
/hooks
```

***

<div id="next-steps">
  ## Étapes suivantes
</div>

<CardGroup cols={2}>
  <Card title="hook de cycle de vie" icon="rotate" href="/fr/cli/extensibility/hooks/lifecycle-hooks">
    Découvrez en détail chaque type d’événement et les données disponibles.
  </Card>

  <Card title="Configuration" icon="gear" href="/fr/cli/reference/configuration/read-config-from">
    Contrôlez les emplacements de configuration depuis lesquels Devin CLI lit les hooks.
  </Card>
</CardGroup>