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

> Configura gli hook di Devin CLI per eseguire comandi shell o prompt LLM sugli eventi del ciclo di vita, bloccare o riscrivere le chiamate agli strumenti e iniettare contesto.

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 uscendo con il codice `2` (oppure stampando un oggetto JSON `"decision": "block"`); qualsiasi altro codice di uscita non zero viene registrato come errore e non blocca l'azione — vedi [Codici di uscita](#exit-codes).

***

<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 |
| `PostCompaction` | Dopo il completamento della compattazione del contesto |
| `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 /"
  },
  "session_id": "3f8d1c2a-...",
  "prompt_id": "b71e9d40-..."
}
```

Ogni payload dell'evento include anche due ID di correlazione oltre ai campi dell'evento:

| Field | Description |
| - | - |
| `session_id` | ID stabile per la sessione dell'agente. Usalo per correlare le invocazioni degli hook nell'intera sessione. |
| `prompt_id` | ID per turno, rigenerato a ogni prompt dell'utente. Tutti gli hook attivati durante lo stesso turno condividono un `prompt_id`. Assente per gli eventi che si attivano prima del primo prompt dell'utente (ad es. `SessionStart`). |

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."
  }
}
```

Per riscrivere in modo trasparente l'input di uno strumento prima che venga eseguito, restituisci `updatedInput` all'interno di un `hookSpecificOutput` `PreToolUse`. I campi in `updatedInput` vengono integrati negli argomenti dello strumento, quindi puoi aggiornarne un sottoinsieme (ad es. solo `command`):

```json theme={null}
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}
```

| 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`, `PreToolUse`, `PostToolUse`) |
| `hookSpecificOutput.additionalContext` | Testo iniettato nel contesto dell'agente (per `UserPromptSubmit`, `SessionStart`, `PostToolUse`) |
| `hookSpecificOutput.updatedInput` | Oggetto integrato negli argomenti dello strumento prima dell'esecuzione (per `PreToolUse`) |

<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. I file hook a livello di progetto vengono individuati nella directory di lavoro e nelle directory antenate fino alla radice del repository, in modo analogo a come vengono caricati skill e regole.

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.