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.
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" } |
{
"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)\""
}
]
}
]
}
{
"PreToolUse": [
{
"matcher": "edit",
"hooks": [
{
"type": "command",
"command": "./scripts/check-edit-path.sh",
"timeout": 5
}
]
}
]
}
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) |
{
"PostToolUse": [
{
"matcher": "exec",
"hooks": [
{
"type": "command",
"command": "sh -c 'cat >> ~/.devin-command-log'"
}
]
}
]
}
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 |
{
"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)\""
}
]
}
]
}
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 |
{
"UserPromptSubmit": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "./scripts/add-deploy-context.sh"
}
]
}
]
}
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 |
{
"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.
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) |
{
"PostCompaction": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "sh -c 'cat >> ~/.devin-compaction-log'"
}
]
}
]
}
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 |
{
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "./scripts/dev-setup.sh",
"timeout": 10
}
]
}
]
}
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
{
"PreToolUse": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "./scripts/audit.sh" }
]
}
],
"PostToolUse": [
{
"matcher": "",
"hooks": [
{ "type": "command", "command": "./scripts/audit.sh" }
]
}
]
}
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 |
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:
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. 