Hook del ciclo di vita

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.

PreToolUse

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:

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

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

Esempio — Riscrivere i comandi prima dell’esecuzione: Un hook può riscrivere in modo trasparente l’input del tool stampando hookSpecificOutput.updatedInput nello stdout (vedi Formato di output). Per esempio, uno script hook che inoltra i comandi della shell tramite un wrapper:

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "updatedInput": {
      "command": "rtk git status"
    }
  }
}

Gli argomenti riscritti vengono integrati nella chiamata al tool prima dell’esecuzione: l’agent esegue il comando aggiornato invece di quello originale.

PostToolUse

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:

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

PermissionRequest

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:

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

UserPromptSubmit

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:

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

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Deploys require an approved change ticket."
  }
}

Stop

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:

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

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.

PostCompaction

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:

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

SessionStart

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:

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

{
  "hookSpecificOutput": {
    "hookEventName": "SessionStart",
    "additionalContext": "Session started. Project uses ESM imports only."
  }
}

SessionEnd

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

Corrispondenza di più eventi

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

{
  "PreToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ],
  "PostToolUse": [
    {
      "matcher": "",
      "hooks": [
        { "type": "command", "command": "./scripts/audit.sh" }
      ]
    }
  ]
}

Uso del matcher

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.

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__.*.

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`

Nomi di tool che puoi usare per la corrispondenza

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.

​PreToolUse

​PostToolUse

​PermissionRequest

​UserPromptSubmit

​Stop

​PostCompaction

​SessionStart

​SessionEnd

​Corrispondenza di più eventi

​Uso del matcher

​Nomi di tool che puoi usare per la corrispondenza

PreToolUse

PostToolUse

PermissionRequest

UserPromptSubmit

Stop

PostCompaction

SessionStart

SessionEnd

Corrispondenza di più eventi

Uso del matcher

Nomi di tool che puoi usare per la corrispondenza