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

# Hook del ciclo di vita

> Comprendere gli eventi hook e i dati disponibili in ogni fase

Ogni evento hook viene attivato in un punto specifico del ciclo di vita dell'agente. Usa il campo **matcher** (una regex confrontata con il `tool_name` dell'evento hook) per filtrare quali invocazioni di tool attivano il tuo hook.

***

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

Si attiva **prima** dell'esecuzione di un tool. Usalo per bloccare, modificare o aggiungere contesto alle chiamate ai tool.

**Dati stdin:**

| Campo        | Descrizione               | Esempio                                         |
| ------------ | ------------------------- | ----------------------------------------------- |
| `tool_name`  | Nome del tool chiamato    | `exec`, `edit`, `mcp__github__create_issue`     |
| `tool_input` | Argomenti passati al tool | `{ "command": "rm -rf /", "shell_id": "main" }` |

**Esempio — Bloccare i comandi distruttivi:**

```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)\""
        }
      ]
    }
  ]
}
```

**Esempio — Richiedere conferma per le operazioni di scrittura al di fuori di src/:**

Usa uno script che esamina l'input del tool e restituisce una decisione:

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

***

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

Si attiva **dopo** il completamento dell'esecuzione di un tool. Usalo per la registrazione, la convalida o per attivare azioni successive.

**Dati stdin:**

| Campo           | Descrizione                                                                     |
| --------------- | ------------------------------------------------------------------------------- |
| `tool_name`     | Nome del tool eseguito                                                          |
| `tool_input`    | Argomenti passati                                                               |
| `tool_response` | Oggetto con `success` (booleano), `output` (stringa) e `error` (stringa o null) |

**Esempio — Registra tutti i comandi shell:**

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

***

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

Si attiva quando l'agente richiede una decisione sull'autorizzazione. Usalo per implementare una logica di approvazione personalizzata.

**Dati stdin:**

| Campo        | Descrizione                        |
| ------------ | ---------------------------------- |
| `tool_name`  | Tool che richiede l'autorizzazione |
| `tool_input` | Argomenti per la chiamata al tool  |

**Esempio — approvazione automatica dei comandi 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>

Si attiva quando l'utente invia un messaggio. Usalo per aggiungere contesto o attivare flussi di lavoro.

**Dati stdin:**

| Campo    | Descrizione                        |
| -------- | ---------------------------------- |
| `prompt` | Il testo del messaggio dell'utente |

**Esempio — Inserisci contesto in ogni prompt:**

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

Il comando stampa `additionalContext` all'interno di un oggetto `hookSpecificOutput` su stdout, etichettato con il nome dell'evento. Questo testo viene inserito nel contesto dell'agente:

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

***

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

Si attiva quando l'agente decide di fermarsi (concludendo il proprio turno). Usalo per aggiungere istruzioni successive o per evitare che si fermi troppo presto.

**Dati stdin:**

| Campo              | Descrizione                     |
| ------------------ | ------------------------------- |
| `stop_hook_active` | Se un hook di stop è già attivo |

**Esempio — Ricorda all'agente di eseguire i test:**

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

<Warning>
  Fai attenzione agli hook di arresto che bloccano: possono far entrare l’agente in un loop se la condizione non viene soddisfatta prima o poi.
</Warning>

***

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

Si attiva **dopo** il completamento corretto della compattazione del contesto. Usalo per registrare eventi nei log, attivare azioni successive o reinserire il contesto che potrebbe essere andato perso durante la compattazione.

**Dati stdin:**

| Campo     | Descrizione                                                                                            |
| --------- | ------------------------------------------------------------------------------------------------------ |
| `summary` | Testo di riepilogo prodotto dal compattatore (può essere null se non è stato generato alcun riepilogo) |

**Esempio — Registra gli eventi di compattazione nei log:**

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

***

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

Si attiva quando inizia una nuova sessione. Usalo per l'inizializzazione, la registrazione o la configurazione dell'ambiente.

**Dati stdin:**

| Campo    | Descrizione                      |
| -------- | -------------------------------- |
| `source` | Come è stata avviata la sessione |

**Esempio — Esegui lo script di configurazione:**

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

Un comando SessionStart può anche iniettare contesto stampando `additionalContext` all'interno di un oggetto `hookSpecificOutput` su stdout:

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

***

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

Si attiva quando termina una sessione. Usalo per la pulizia o per la registrazione finale.

**Dati stdin:**

| Campo    | Descrizione                      |
| -------- | -------------------------------- |
| `reason` | Motivo della fine della sessione |

***

<div id="matching-multiple-events">
  ## Corrispondenza di più eventi
</div>

Un singolo file di hook può definire hook per più eventi:

```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">
  ## Uso del matcher
</div>

Il campo `matcher` è una **regex** applicata al `tool_name` dell'evento hook. È disponibile per gli eventi relativi ai tool: `PreToolUse`, `PostToolUse` e `PermissionRequest`.

Per gli eventi non relativi ai tool (`UserPromptSubmit`, `Stop`, `PostCompaction`, `SessionStart` e `SessionEnd`), `tool_name` non è presente; usa `""` oppure ometti il matcher per eseguire l'hook per ogni evento di quel tipo.

<Note>
  Il matcher non è un glob di autorizzazione. Pattern come `mcp__github__*` sono utili nelle autorizzazioni, ma i matcher degli hook sono regex. In un matcher di hook, usa `mcp__github__.*`.
</Note>

| Matcher                         | Corrispondenze                                        |
| ------------------------------- | ----------------------------------------------------- |
| `""` (vuoto) o omesso           | Tutti i nomi dei tool per gli eventi relativi ai tool |
| `"exec"`                        | Nomi di tool che contengono `exec`                    |
| `"^exec$"`                      | Solo il tool `exec`                                   |
| `"^(exec\|edit)$"`              | Solo `exec` o `edit`                                  |
| `"^mcp__.*"`                    | Tutti i tool MCP                                      |
| `"^mcp__github__.*"`            | Tutti i tool del server MCP `github`                  |
| `"^mcp__github__create_issue$"` | Il tool `create_issue` del server MCP `github`        |

<div id="tool-names-you-can-match">
  ### Nomi di tool che puoi usare per la corrispondenza
</div>

I matcher degli hook vengono eseguiti sugli stessi nomi di tool esposti esternamente che gli script degli hook ricevono tramite stdin come `tool_name`. I nomi esatti dei tool disponibili possono variare in base alla modalità CLI, al modello e alle integrazioni abilitate.

I nomi più comuni dei tool core pubblici sono:

* `read`
* `edit`
* `grep`
* `glob`
* `exec`

I tool dei server MCP hanno il formato `mcp__<server>__<tool>`. Per esempio, un tool di un server MCP `github` denominato `create_issue` appare come `mcp__github__create_issue`.

Per gli altri tool, fai corrispondere esattamente il `tool_name` mostrato nello stdin dell'hook. Per confermare l'insieme completo disponibile nella sessione corrente, aggiungi temporaneamente un hook `PostToolUse` con `matcher: ""` e registra il payload ricevuto su stdin.