Hooks

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.

Cosa possono fare gli Hook?

Applicare policy

Bloccare comandi pericolosi, richiedere conferma per azioni specifiche o limitare l’accesso ai file.

Aggiungere contesto

Inserire istruzioni o informazioni aggiuntive quando vengono richiamati strumenti specifici.

Eseguire effetti collaterali

Eseguire script, inviare notifiche o registrare eventi quando si verificano determinate condizioni.

Modificare le autorizzazioni

Concedere o limitare dinamicamente le autorizzazioni in base al contesto.

Esempio rapido

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

{
  "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.

Eventi degli hook

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.

Formato degli hook

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

{
  "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).

Hook di comando

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 di seguito). Input (stdin):

{
  "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 per i nomi degli strumenti integrati e il formato dei nomi degli strumenti MCP che puoi abbinare.

Formato di output

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

{
  "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:

{
  "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):

{
  "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`)

Codici di uscita

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

Dove si trovano gli hook

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.

A livello di progetto

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)

A livello di utente (globale)

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)

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.

Gli hook dei percorsi .claude/ vengono caricati quando read_config_from.claude è abilitato (per impostazione predefinita). Se necessario, puoi disabilitarlo nella tua configurazione utente.

Verifica degli hook

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

/hooks

Per iniziare

Integrazioni dell'Editor

Estensibilità

Enterprise

Riferimento

Changelog

Cosa possono fare gli Hook?

Applicare policy

Aggiungere contesto

Eseguire effetti collaterali

Modificare le autorizzazioni

Esempio rapido

Eventi degli hook

Formato degli hook

Hook di comando

Formato di output

Codici di uscita

Dove si trovano gli hook

A livello di progetto

A livello di utente (globale)

Verifica degli hook

Prossimi passaggi

Hook del ciclo di vita

Configurazione

​Cosa possono fare gli Hook?

Applicare policy

Aggiungere contesto

Eseguire effetti collaterali

Modificare le autorizzazioni

​Esempio rapido

​Eventi degli hook

​Formato degli hook

​Hook di comando

​Formato di output

​Codici di uscita

​Dove si trovano gli hook

​A livello di progetto

​A livello di utente (globale)

​Verifica degli hook

​Prossimi passaggi

Hook del ciclo di vita

Configurazione

Cosa possono fare gli Hook?

Esempio rapido

Eventi degli hook

Formato degli hook

Hook di comando

Formato di output

Codici di uscita

Dove si trovano gli hook

A livello di progetto

A livello di utente (globale)

Verifica degli hook

Prossimi passaggi