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

> Esegui logica personalizzata quando si verificano eventi specifici durante una sessione

Gli hook ti consentono di eseguire logica personalizzata in risposta agli eventi del ciclo di vita dell'agente. Puoi usare gli hook per applicare policy, aggiungere contesto, registrare azioni, modificare le autorizzazioni o integrarti con sistemi esterni.

Gli hook sono configurati in formato JSON. Inseriscili nella directory `.devin/` del tuo progetto (o in una configurazione a livello utente) e Devin CLI li esegue in corrispondenza degli eventi del ciclo di vita corrispondenti. Anche gli hook esistenti nelle directory `.claude/` vengono rilevati automaticamente — vedi [Dove si trovano gli hook](#where-hooks-live).

***

<div id="what-can-hooks-do">
  ## Cosa possono fare gli Hook?
</div>

<CardGroup cols={2}>
  <Card title="Applicare policy" icon="shield">
    Bloccare comandi pericolosi, richiedere conferma per azioni specifiche o limitare l'accesso ai file.
  </Card>

  <Card title="Aggiungere contesto" icon="message">
    Inserire istruzioni o informazioni aggiuntive quando vengono richiamati strumenti specifici.
  </Card>

  <Card title="Eseguire effetti collaterali" icon="bolt">
    Eseguire script, inviare notifiche o registrare eventi quando si verificano determinate condizioni.
  </Card>

  <Card title="Modificare le autorizzazioni" icon="lock">
    Concedere o limitare dinamicamente le autorizzazioni in base al contesto.
  </Card>
</CardGroup>

***

<div id="quick-example">
  ## Esempio rapido
</div>

Crea `.devin/hooks.v1.json` nel tuo progetto:

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

Viene eseguito `./scripts/check-command.sh` prima di ogni esecuzione di un comando shell. Lo script riceve i dati dell'evento su stdin e può bloccare l'azione restituendo un codice di uscita non zero.

***

<div id="hook-events">
  ## Eventi degli hook
</div>

Gli hook possono rispondere a questi eventi del ciclo di vita:

| Evento              | Quando si attiva                                       |
| ------------------- | ------------------------------------------------------ |
| `PreToolUse`        | Prima dell'esecuzione di uno strumento                 |
| `PostToolUse`       | Dopo il completamento di uno strumento                 |
| `PermissionRequest` | Quando è necessaria una decisione su un'autorizzazione |
| `UserPromptSubmit`  | Quando l'utente invia un messaggio                     |
| `Stop`              | Quando l'agente vuole interrompersi                    |
| `SessionStart`      | Quando inizia una sessione                             |
| `SessionEnd`        | Quando termina una sessione                            |

Per i dettagli su ciascun evento e sui dati disponibili, consulta [Hook del ciclo di vita](/it/cli/extensibility/hooks/lifecycle-hooks).

***

<div id="hook-format">
  ## Formato degli hook
</div>

Ogni hook ha un **tipo** (`command` o `prompt`), un **matcher** facoltativo (regex sul `tool_name` dell'evento hook) e una configurazione:

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

| Field     | Descrizione                                                                                                                                                 |
| --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `matcher` | Espressione regolare confrontata con `tool_name` dell'evento hook. Una stringa vuota o l'omissione di `matcher` corrisponde a tutti i nomi degli strumenti. |
| `type`    | `"command"` per eseguire un comando shell oppure `"prompt"` per valutare un prompt LLM.                                                                     |
| `command` | Comando shell da eseguire (per il tipo `command`).                                                                                                          |
| `prompt`  | Prompt LLM da valutare (per il tipo `prompt`).                                                                                                              |
| `timeout` | Timeout in secondi (facoltativo).                                                                                                                           |

<div id="command-hooks">
  ### Hook di comando
</div>

Gli hook di comando eseguono un comando shell. I dati dell'evento vengono passati come JSON su **stdin** e il comando può restituire JSON su **stdout** per determinare l'esito (vedi [Formato di output](#output-format) di seguito).

**Input** (stdin):

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

La variabile di ambiente `DEVIN_PROJECT_DIR` viene impostata automaticamente sulla directory radice del progetto.

Consulta [Using the Matcher](/it/cli/extensibility/hooks/lifecycle-hooks#using-the-matcher) per i nomi degli strumenti integrati e il formato dei nomi degli strumenti MCP che puoi abbinare.

<div id="output-format">
  ### Formato di output
</div>

Un hook di comando può stampare un oggetto JSON su **stdout** per controllare l'esito.

Per approvare o bloccare un'azione, restituisci una `decision` di primo livello (con un `reason` facoltativo):

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

Per aggiungere testo al contesto dell'agente, restituisci `additionalContext` all'interno di un oggetto `hookSpecificOutput` contrassegnato con il nome dell'evento:

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

| Campo di output                        | Descrizione                                                                                      |
| -------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `decision`                             | `"approve"` per consentire l'azione, oppure `"block"` per impedirla                              |
| `reason`                               | Spiegazione mostrata all'agente                                                                  |
| `hookSpecificOutput.hookEventName`     | Evento a cui si applica l'output (ad es. `UserPromptSubmit`, `SessionStart`, `PostToolUse`)      |
| `hookSpecificOutput.additionalContext` | Testo iniettato nel contesto dell'agente (per `UserPromptSubmit`, `SessionStart`, `PostToolUse`) |

<div id="exit-codes">
  ### Codici di uscita
</div>

| Codice | Significato                             |
| ------ | --------------------------------------- |
| 0      | Successo — l'hook continua normalmente  |
| 2      | Blocco — l'azione viene negata          |
| Altri  | Errore — viene registrato ma non blocca |

***

<div id="where-hooks-live">
  ## Dove si trovano gli hook
</div>

Devin CLI legge gli hook nelle seguenti posizioni. In tutti i casi, il formato JSON è lo stesso.

<div id="project-level">
  ### A livello di progetto
</div>

| Percorso                      | Descrizione                                         |
| ----------------------------- | --------------------------------------------------- |
| `.devin/hooks.v1.json`        | File hooks indipendente (consigliato)               |
| `.devin/config.json`          | chiave `"hooks"` nel file di configurazione         |
| `.devin/config.local.json`    | chiave `"hooks"` (override locale, ignorato da git) |
| `.claude/settings.json`       | chiave `"hooks"` (formato Claude Code)              |
| `.claude/settings.local.json` | chiave `"hooks"` (formato Claude Code)              |

<div id="user-level-global">
  ### A livello di utente (globale)
</div>

| Posizione                                                                | Descrizione                                  |
| ------------------------------------------------------------------------ | -------------------------------------------- |
| `~/.config/devin/config.json` (`%APPDATA%\devin\config.json` in Windows) | chiave `"hooks"` nella configurazione utente |
| `~/.claude.json`                                                         | chiave `"hooks"` (formato Claude Code)       |
| `~/.claude/settings.json`                                                | chiave `"hooks"` (formato Claude Code)       |
| `~/.claude/settings.local.json`                                          | chiave `"hooks"` (formato Claude Code)       |

<Note>
  In `.devin/hooks.v1.json`, l'oggetto hooks coincide con **l'intero file** (non è necessaria alcuna chiave contenitore). In tutte le altre posizioni, hooks è annidato sotto la chiave `"hooks"` in un file Settings.
</Note>

<Note>
  Gli hook dei percorsi `.claude/` vengono caricati quando `read_config_from.claude` è abilitato (per impostazione predefinita). Se necessario, puoi disabilitarlo nella tua [configurazione utente](/it/cli/reference/configuration/read-config-from).
</Note>

***

<div id="verifying-hooks">
  ## Verifica degli hook
</div>

Usa il comando slash `/hooks` per visualizzare tutti gli hook attualmente caricati e i relativi file sorgente:

```
/hooks
```

***

<div id="next-steps">
  ## Prossimi passaggi
</div>

<CardGroup cols={2}>
  <Card title="Hook del ciclo di vita" icon="rotate" href="/it/cli/extensibility/hooks/lifecycle-hooks">
    Approfondisci ogni tipo di evento e i dati disponibili.
  </Card>

  <Card title="Configurazione" icon="gear" href="/it/cli/reference/configuration/read-config-from">
    Controlla da quali percorsi di configurazione Devin CLI legge gli hook.
  </Card>
</CardGroup>