In non-interactive mode con il flag -p, Claude Code offre AskUserQuestion e ExitPlanMode solo quando l'esecuzione ha un permission host per ricevere il prompt, come un callback canUseTool di Agent SDK. Questi strumenti richiedono l'interazione dell'utente. Restituire permissionDecision: "allow" insieme a updatedInput soddisfa quel requisito: l'hook legge l'input dello strumento da stdin, raccoglie la risposta attraverso la tua UI, e la restituisce in updatedInput in modo che lo strumento si esegua senza chiedere. Restituire "allow" da solo non è sufficiente per questi strumenti. Per AskUserQuestion, ripeti l'array questions originale e aggiungi un oggetto answers che mappa il testo di ogni domanda alla risposta scelta.

A partire dalla v2.1.199, uno strumento MCP il cui server lo contrassegna con _meta["anthropic/requiresUserInteraction"] è più rigoroso: un hook non può saltare il suo prompt di approvazione con "allow", con o senza updatedInput, perché Claude Code non può confermare che l'hook ha raccolto l'interazione di cui lo strumento ha bisogno.

Defer a tool call for later

"defer" è per le integrazioni che eseguono claude -p come un sottoprocesso e leggono il suo output JSON, come un'app Agent SDK o un'UI personalizzata costruita su Claude Code. Ti consente a quel processo di chiamata di mettere in pausa Claude a una chiamata di strumento, raccogliere input attraverso la sua interfaccia, e riprendere da dove si era fermato. Claude Code onora questo valore solo in non-interactive mode con il flag -p. Nelle sessioni interattive registra un avviso e ignora il risultato dell'hook.

Lo strumento AskUserQuestion è il caso tipico: Claude vuole chiedere qualcosa all'utente, ma non c'è un terminale per rispondere. Un'esecuzione -p offre AskUserQuestion solo quando ha un permission host, come uno strumento MCP che passi con --permission-prompt-tool, quindi avvia l'esecuzione con uno. Il round trip funziona così:

1. Claude chiama AskUserQuestion. L'hook PreToolUse si attiva.
2. L'hook restituisce permissionDecision: "defer". Lo strumento non si esegue. Il processo esce con stop_reason: "tool_deferred" e la chiamata dello strumento in sospeso preservata nella trascrizione.
3. Il processo di chiamata legge deferred_tool_use dal risultato dell'SDK, visualizza la domanda nella sua UI, e attende una risposta.
4. Il processo di chiamata esegue claude -p --resume <session-id> con lo stesso permission host. La stessa chiamata dello strumento attiva PreToolUse di nuovo.
5. L'hook restituisce permissionDecision: "allow" con la risposta in updatedInput. Lo strumento si esegue e Claude continua.

Il campo deferred_tool_use porta l'id, il name, e l'input dello strumento. L'input è i parametri che Claude ha generato per la chiamata dello strumento, catturati prima dell'esecuzione:

{
  "type": "result",
  "subtype": "success",
  "stop_reason": "tool_deferred",
  "session_id": "abc123",
  "deferred_tool_use": {
    "id": "toolu_01abc",
    "name": "AskUserQuestion",
    "input": { "questions": [{ "question": "Which framework?", "header": "Framework", "options": [{"label": "React"}, {"label": "Vue"}], "multiSelect": false }] }
  }
}

Non c'è timeout o limite di tentativi. La sessione rimane su disco finché non la riprendi, soggetta alla pulizia cleanupPeriodDays, che elimina i file di sessione dopo 30 giorni per impostazione predefinita, seguendo le regole di pulizia della conservazione. Se la risposta non è pronta quando riprendi, l'hook può restituire "defer" di nuovo e il processo esce nello stesso modo. Il processo di chiamata controlla quando interrompere il ciclo restituendo infine "allow" o "deny" dall'hook.

"defer" funziona solo quando Claude effettua una singola chiamata di strumento nel turno. Se Claude effettua diverse chiamate di strumenti contemporaneamente, "defer" viene ignorato con un avviso e lo strumento procede attraverso il flusso di permesso normale. Il vincolo esiste perché la ripresa può solo ri-eseguire uno strumento: non c'è modo di rinviare una chiamata da un batch senza lasciare le altre irrisolte.

Se lo strumento rinviato non è più disponibile quando riprendi, il processo esce con stop_reason: "tool_deferred_unavailable" e is_error: true prima che l'hook si attivi. Questo accade quando un server MCP che ha fornito lo strumento non è connesso per la sessione ripresa. Il payload deferred_tool_use è comunque incluso in modo che tu possa identificare quale strumento è scomparso.

PermissionRequest

Si esegue quando Claude Code sta per chiederti il permesso di usare uno strumento. Nelle sessioni che non possono mostrare un prompt, come i subagent in background in non-interactive mode, Claude Code esegue comunque questi hook, e se nessun hook restituisce una decisione, nega la chiamata dello strumento. Usa PermissionRequest decision control per consentire o negare per conto dell'utente.

Usa questo evento quando hai bisogno di un segnale nel momento in cui Claude chiede il permesso di usare uno strumento. Claude Code esegue un hook Notification con il tipo permission_prompt solo dopo che il prompt ha atteso circa sei secondi.

Claude Code non esegue gli hook PermissionRequest per la richiesta di rete di un comando sandboxed. Per ottenere un segnale per quel prompt, usa il tipo di notifica permission_prompt.

Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.

PermissionRequest input

Gli hook PermissionRequest ricevono i campi tool_name e tool_input come gli hook PreToolUse, ma senza tool_use_id. Per uno strumento MCP, ricevono anche l'oggetto mcp_server. Un array permission_suggestions facoltativo contiene gli permission updates che Claude Code suggerisce per questa richiesta, come aggiungere una regola di consentimento o cambiare il modo di permesso.

L'array permission_suggestions non è un elenco esatto delle opzioni che vedi, perché ogni dialogo di permesso costruisce le sue stesse opzioni. Alcuni dialoghi, come quello per le modifiche ai file, non leggono affatto l'array e derivano le loro opzioni dalla richiesta stessa. Un dialogo che lo legge può comunque trattenere un'opzione il cui suggerimento rimane nell'array, ad esempio quando allowManagedPermissionRulesOnly nasconde le opzioni di salvataggio delle regole. Può anche offrire opzioni che non hanno una voce di suggerimento, come Yes, and switch to auto mode, che cambia il modo di permesso direttamente piuttosto che attraverso un aggiornamento di permesso.

Gli hook PreToolUse si eseguono prima di ogni chiamata di strumento, indipendentemente dal fatto che abbia bisogno di permesso. Gli hook PermissionRequest si eseguono solo quando Claude Code sta per chiederti il permesso, o quando altrimenti auto-negherebbe una chiamata che non può chiedere. Nessuno dei due eventi si attiva per EndConversation.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PermissionRequest",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf node_modules",
    "description": "Remove node_modules directory"
  },
  "permission_suggestions": [
    {
      "type": "addRules",
      "rules": [{ "toolName": "Bash", "ruleContent": "rm -rf node_modules" }],
      "behavior": "allow",
      "destination": "localSettings"
    }
  ]
}

PermissionRequest decision control

Gli hook PermissionRequest possono consentire o negare le richieste di permesso. Oltre ai JSON output fields disponibili per tutti gli hook, il tuo script hook può restituire un oggetto decision con questi campi specifici dell'evento:

Un hook che esce con 2 senza un oggetto decision lascia il flusso di permesso invariato, e il suo stderr viene scartato. Solo l'oggetto decision può concedere o negare la richiesta.

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedInput": {
        "command": "npm run lint"
      }
    }
  }
}

Permission update entries

Il campo di output updatedPermissions e il campo di input permission_suggestions usano entrambi lo stesso array di oggetti di voce. Ogni voce ha un type che determina i suoi altri campi, e una destination che controlla dove viene scritta la modifica.

Il campo destination su ogni voce determina se la modifica rimane in memoria o persiste in un file di impostazioni.

Un hook può ripetere uno dei permission_suggestions che ha ricevuto come suo proprio output updatedPermissions.

PostToolUse

Si esegue immediatamente dopo che uno strumento si completa con successo.

Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.

Corrisponde più ampiamente quando il nome dello strumento non è il filtro giusto:

• Per eseguire un hook dopo che qualsiasi strumento si completa con successo, ometti il matcher o impostalo su "*". Il tuo hook può quindi scoprire cosa è cambiato da solo, ad esempio eseguendo git status --porcelain, che elenca anche i file non tracciati che git diff perde. Per le chiamate di strumenti che falliscono, aggiungi lo stesso hook sotto PostToolUseFailure.
• Per eseguire un hook quando un file specifico cambia su disco, qualunque cosa l'abbia scritto, usa FileChanged. Claude Code non esegue un hook PostToolUse che corrisponde a Edit|Write quando un comando Bash o un processo al di fuori di Claude Code riscrive lo stesso file.

PostToolUse input

Gli hook PostToolUse si attivano dopo che uno strumento si è già eseguito con successo. L'input include sia tool_input, gli argomenti inviati allo strumento, che tool_response, il risultato che ha restituito. Lo schema esatto per entrambi dipende dallo strumento. I percorsi tool_input dello strumento di file arrivano nello stesso formato di PreToolUse: sempre assoluti, con i separatori nativi della piattaforma, quindi backslash su Windows. Per uno strumento MCP, l'input porta anche l'oggetto mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.txt",
    "content": "file content"
  },
  "tool_response": {
    "filePath": "/path/to/file.txt",
    "type": "create"
  },
  "tool_use_id": "toolu_01ABC123...",
  "duration_ms": 12
}

PostToolUse decision control

Gli hook PostToolUse possono fornire feedback a Claude dopo l'esecuzione dello strumento. Oltre ai JSON output fields disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:

L'esempio seguente sostituisce l'output di una chiamata Bash. Il valore di sostituzione corrisponde alla forma di output dello strumento Bash:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "additionalContext": "Additional information for Claude",
    "updatedToolOutput": {
      "stdout": "[redacted]",
      "stderr": "",
      "interrupted": false,
      "isImage": false
    }
  }
}

Annotate a result for the auto mode classifier

Restituisci classifierContext per inviare una breve nota sul risultato della chiamata dello strumento al classificatore auto mode piuttosto che a Claude. Il classificatore non riceve mai i risultati degli strumenti stessi, quindi questo campo è il modo supportato per dirgli qualcosa su ciò che una chiamata ha restituito prima che riveda le azioni successive. Il campo richiede Claude Code v2.1.236 o successivo.

L'esempio seguente dice al classificatore da dove proviene l'output di una query:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUse",
    "classifierContext": "This query ran against the staging database, not production."
  }
}

Quanto peso il classificatore dà alla nota dipende da dove hai configurato l'hook:

• Hook configurati in Claude Code: per gli hook da file di impostazioni, plugin, skill, e frontmatter dell'agente, il classificatore tratta la nota come contesto non verificato fornito dall'applicazione. La nota non stabilisce mai l'intento dell'utente, e se afferma che hai approvato o richiesto qualcosa, il classificatore controlla quella affermazione rispetto ai tuoi stessi messaggi nella conversazione
• Callback Agent SDK in-process: quando un'applicazione che incorpora Claude Code registra l'hook come un callback TypeScript SDK e restituisce la nota durante la sessione dal vivo, il classificatore può pesare un'affermazione dell'utente inoltrata nella nota come intento dell'utente. Tale affermazione può soddisfare un requisito di consenso che il classificatore accetterebbe da un messaggio che invii, ma non solleva mai un blocco che il tuo stesso messaggio non potrebbe sollevare neanche. Dopo che una sessione riprende, Claude Code tratta le note ripristinate come contesto non verificato. Quando gli hook di entrambi i gruppi annotano la stessa chiamata, il classificatore tratta la nota combinata come non verificata

Claude Code applica questi limiti quando consegna la nota:

• Lunghezza: Claude Code limita le note per una chiamata di strumento a 2.000 caratteri e tronca il resto. Il limite è condiviso su ogni hook che risponde a quella chiamata
• Solo risposte sincrone: Claude Code ignora il campo nella risposta di un hook che si esegue in background, perché quella risposta arriva dopo che Claude Code registra il risultato dello strumento
• Chiamate che il classificatore non registra: la trascrizione del classificatore omette le ricerche di sola lettura come le letture di file e le ricerche. Claude Code scarta una nota allegata a una di quelle chiamate
• Interazione con le riscritture: quando la nota descrive l'output che stai sostituendo con updatedToolOutput, restituisci entrambi i campi nella stessa risposta dell'hook. Claude Code scarta la nota se quella riscrittura viene rifiutata o la riscrittura di un altro hook la sostituisce. Claude Code consegna una nota che restituisci senza una riscrittura anche quando un altro hook riscrive l'output

PostToolUseFailure

Si esegue quando uno strumento che ha iniziato a eseguirsi fallisce: lo strumento ha lanciato un errore, o uno strumento MCP ha restituito un risultato di errore. Usalo per registrare i fallimenti, inviare avvisi, o fornire feedback correttivo a Claude.

Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.

PostToolUseFailure input

Gli hook PostToolUseFailure ricevono gli stessi campi tool_name e tool_input di PostToolUse, insieme alle informazioni di errore come campi di livello superiore. Per uno strumento MCP, ricevono anche l'oggetto mcp_server. Ad esempio, un comando npm test fallito potrebbe consegnare:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolUseFailure",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test",
    "description": "Run test suite"
  },
  "tool_use_id": "toolu_01ABC123...",
  "error": "Exit code 1\nError: Cannot find module 'express'",
  "is_interrupt": false,
  "duration_ms": 4187
}

La stringa error è generalmente lo stesso testo che Claude riceve come risultato dello strumento fallito. Il suo formato varia per strumento e fallimento. Chiavi il tuo hook su tool_name, is_interrupt, e la prima riga Exit code N; tratta il resto della stringa come testo di visualizzazione, non come un formato stabile.

• Per Bash e PowerShell, un comando che si è eseguito e ha uscito produce una prima riga Exit code N, quindi qualsiasi output che il comando ha prodotto come un blocco con stdout e stderr intercalati
• Un payload può anche portare un messaggio di fallimento nudo senza una riga di codice di uscita, quando Claude Code non potrebbe avviare il processo shell stesso
• Claude Code tronca nel mezzo le stringhe lunghe intorno a un marcatore ... [N characters truncated] ..., e può inserire righe proprie, come Command timed out after 2m 0s

PostToolUseFailure decision control

Gli hook PostToolUseFailure possono fornire contesto a Claude dopo un fallimento dello strumento. Oltre ai JSON output fields disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolUseFailure",
    "additionalContext": "Additional information about the failure for Claude"
  }
}

PostToolBatch

Si esegue una volta dopo che ogni chiamata di strumento in un batch si è risolta, prima che Claude Code invii la richiesta successiva al modello. PostToolUse si attiva una volta per strumento, il che significa che si attiva contemporaneamente quando Claude effettua chiamate di strumenti parallele. PostToolBatch si attiva esattamente una volta con il batch completo, quindi è il posto giusto per iniettare contesto che dipende dall'insieme di strumenti che si sono eseguiti piuttosto che da qualsiasi singolo strumento. Non c'è matcher per questo evento.

PostToolBatch input

Oltre ai common input fields, gli hook PostToolBatch ricevono tool_calls, un array che descrive ogni chiamata di strumento nel batch:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "PostToolBatch",
  "tool_calls": [
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/accounts.py"},
      "tool_use_id": "toolu_01...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    },
    {
      "tool_name": "Read",
      "tool_input": {"file_path": "/.../ledger/transactions.py"},
      "tool_use_id": "toolu_02...",
      "tool_response": "     1\tfrom __future__ import annotations\n     2\t..."
    }
  ]
}

tool_response contiene lo stesso contenuto che il modello riceve nel blocco tool_result corrispondente. Il valore è una stringa serializzata o un array di blocchi di contenuto, esattamente come lo strumento l'ha emesso. Per Read, ciò significa testo con prefisso numero di riga piuttosto che contenuti di file grezzi. Le risposte possono essere grandi, quindi analizza solo i campi di cui hai bisogno.

PostToolBatch decision control

Gli hook PostToolBatch possono iniettare contesto per Claude. Oltre ai JSON output fields disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:

{
  "hookSpecificOutput": {
    "hookEventName": "PostToolBatch",
    "additionalContext": "These files are part of the ledger module. Run pytest before marking the task complete."
  }
}

Restituire decision: "block" o continue: false ferma il loop agentico prima della prossima chiamata del modello. Il messaggio di blocco viene dal reason JSON o stopReason, o da stderr all'uscita 2. Lo vedi come un avviso nella trascrizione, e rimane nella conversazione, quindi Claude lo vede quando la conversazione continua.

PermissionDenied

Si esegue quando auto mode nega una chiamata di strumento, incluso quando nega senza un verdetto del classificatore perché un controllo di sicurezza separato da auto mode ha rifiutato la richiesta del classificatore stesso o la sua risposta non ha analizzato. Questo hook si attiva solo in auto mode: non si esegue quando neghi manualmente un dialogo di permesso, quando un hook PreToolUse blocca una chiamata, o quando una regola deny corrisponde. Usalo per registrare le negazioni, regolare la configurazione, o dire al modello che potrebbe riprovare la chiamata dello strumento.

Corrisponde al nome dello strumento, gli stessi valori di PreToolUse.

PermissionDenied input

Oltre ai common input fields, gli hook PermissionDenied ricevono tool_name, tool_input, tool_use_id, e reason. Per uno strumento MCP, ricevono anche l'oggetto mcp_server.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "auto",
  "hook_event_name": "PermissionDenied",
  "tool_name": "Bash",
  "tool_input": {
    "command": "rm -rf /tmp/build",
    "description": "Clean build directory"
  },
  "tool_use_id": "toolu_01ABC123...",
  "reason": "[Irreversible Local Destruction]"
}

PermissionDenied decision control

Gli hook PermissionDenied possono dire al modello che potrebbe riprovare la chiamata dello strumento negato. Restituisci un oggetto JSON con hookSpecificOutput.retry impostato su true:

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionDenied",
    "retry": true
  }
}

Quando retry è true, Claude Code aggiunge un messaggio alla conversazione dicendo al modello che potrebbe riprovare la chiamata dello strumento. Claude Code non inverte la negazione stessa. Se il tuo hook non restituisce JSON, o restituisce retry: false, la negazione rimane e il modello riceve il messaggio di rifiuto originale.

Claude Code ignora retry: true quando il classificatore ha prodotto nessun verdetto sull'azione: la sua risposta non ha analizzato, o un controllo di sicurezza separato da auto mode ha rifiutato la richiesta del classificatore. Per quelle negazioni, Claude Code già dice al modello nel messaggio di rifiuto se riprovare più tardi o procedere.

Notification

Si esegue quando Claude Code invia notifiche. Corrisponde al tipo di notifica. Ometti il matcher per eseguire gli hook per tutti i tipi di notifica.

Ricevi questi eventi hook anche con le notifiche desktop disattivate: l'impostazione preferredNotifChannel, incluso notifications_disabled, cambia solo come sei avvisato, non se il tuo hook si esegue.

I tipi agent_needs_input e agent_completed richiedono Claude Code v2.1.198 o successivo.

I tipi quota_auto_resume_fired, quota_auto_resume_stale, e quota_auto_resume_disabled richiedono Claude Code v2.1.234 o successivo.

Nelle sessioni di terminale, permission_prompt per la richiesta di rete di un comando sandboxed richiede Claude Code v2.1.246 o successivo.

agent_needs_input per una domanda di configurazione del terminale del teammate richiede Claude Code v2.1.248 o successivo.

Claude Code cronometra permission_prompt diversamente nelle sessioni in cui invia richieste di permesso al callback canUseTool di Agent SDK, che è come Claude Desktop e l'estensione VS Code ospitano Claude Code:

• Aspettati permission_prompt circa sei secondi dopo che Claude chiede il permesso. Claude Code non lo rinvia mentre digiti.
• Se tu o un hook PermissionRequest rispondete prima, Claude Code non esegue permission_prompt.
• Imposta CLAUDE_CODE_DISABLE_PERMISSION_PROMPT_NOTIFY_HOOKS su 1 per disattivare permission_prompt in queste sessioni.

Prima della v2.1.233, permission_prompt non si attivava in queste sessioni.

Usa matcher separati per eseguire diversi gestori a seconda del tipo di notifica. Questa configurazione attiva uno script di avviso specifico del permesso quando Claude ha bisogno dell'approvazione del permesso e una notifica diversa quando Claude è stato inattivo:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "permission_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/permission-alert.sh"
          }
        ]
      },
      {
        "matcher": "idle_prompt",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/idle-notification.sh"
          }
        ]
      }
    ]
  }
}

Notification input

Oltre ai common input fields, gli hook Notification ricevono message con il testo della notifica, un title facoltativo, e notification_type che indica quale tipo si è attivato.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Notification",
  "message": "Claude needs your permission",
  "title": "Permission needed",
  "notification_type": "permission_prompt"
}

Gli hook Notification non possono bloccare o modificare le notifiche. Claude Code scarta i loro campi systemMessage e continue ma emette comunque terminalSequence, su cui si basa l'esempio di notifica desktop. Gli hook Notification sono destinati agli effetti collaterali come l'inoltro della notifica a un servizio esterno.

SubagentStart

Si esegue quando Claude genera un subagent con lo strumento Agent, quando Claude riprende un subagent, e ogni volta che un team dell'agente in-process teammate gestisce un nuovo messaggio. Supporta i matcher per filtrare per nome del tipo di agente. Per gli agenti incorporati, questo è il nome dell'agente come general-purpose, Explore, o Plan. Per i subagent personalizzati, questo è il campo name dal frontmatter dell'agente, non il nome del file.

Per i subagent spediti da un plugin, il tipo di agente è l'identificatore con ambito del plugin come my-plugin:reviewer, non il nome del frontmatter nudo. I due punti mettono un nome con ambito del plugin sul percorso dell'espressione regolare, quindi ancora il matcher con ^ e $ per una corrispondenza esatta: ^my-plugin:reviewer$.

SubagentStart input

Oltre ai common input fields, gli hook SubagentStart ricevono agent_id con l'identificatore univoco per il subagent e agent_type con il nome dell'agente che il matcher filtra.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SubagentStart",
  "agent_id": "agent-abc123",
  "agent_type": "Explore"
}

Gli hook SubagentStart non possono bloccare la creazione del subagent, ma possono iniettare contesto nel subagent. Oltre ai JSON output fields disponibili per tutti gli hook, puoi restituire:

{
  "hookSpecificOutput": {
    "hookEventName": "SubagentStart",
    "additionalContext": "Follow security guidelines for this task"
  }
}

Quando l'hook si esegue di nuovo per lo stesso subagent, Claude Code inietta il contesto restituito solo quando il contesto del subagent non contiene già la copia da un'esecuzione precedente. La copia iniettata al lancio rimane in posizione, lasciando intatta la prompt cache del subagent. Dopo che la auto-compaction scarta quella copia, Claude Code inietta il contesto dell'esecuzione successiva di nuovo.

SubagentStop

Si esegue quando un subagent di Claude Code ha finito di rispondere. Corrisponde al tipo di agente, gli stessi valori di SubagentStart.

SubagentStop input

Oltre ai common input fields, gli hook SubagentStop ricevono stop_hook_active, agent_id, agent_type, agent_transcript_path, e last_assistant_message. Il campo agent_type è il valore usato per il filtraggio del matcher. Il transcript_path è la trascrizione della sessione principale, mentre agent_transcript_path è la trascrizione propria del subagent archiviata in una cartella subagents/ annidato. Il campo last_assistant_message contiene il contenuto di testo della risposta finale del subagent, quindi gli hook possono accedervi senza analizzare il file della trascrizione.

Non ogni evento SubagentStop proviene da un subagent che Claude ha generato. Claude Code esegue anche agenti interni per alcune delle sue stesse funzioni, come i suggerimenti di prompt e le domande laterali /btw, e SubagentStop si attiva quando uno di quelli finisce anche. Per questi eventi, agent_type è il nome dell'agente che la sessione stessa esegue, come uno impostato con --agent o l'impostazione agent, e una stringa vuota quando la sessione si esegue senza uno.

Un matcher che nomina i tipi di agente non corrisponde a un agent_type vuoto. Un hook il cui matcher è omesso, "", o "*", o è un'espressione regolare che corrisponde a una stringa vuota, si esegue anche per gli eventi con un agent_type vuoto.

Su Claude Code v2.1.271 o successivo, un subagent che si esegue con lo strumento SubagentHandback consegna il suo rapporto attraverso quello strumento prima che si fermi. Il campo last_assistant_message porta quindi il testo di chiusura del subagent, se presente, che non è il rapporto consegnato. Il rapporto è l'input message di quella chiamata, che un hook PreToolUse o PostToolUse abbinato su SubagentHandback riceve come tool_input.message.

Gli hook SubagentStop ricevono anche gli array background_tasks e session_crons descritti sotto Stop input. Entrambi gli array hanno ambito alla sessione genitore, non al subagent.

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../abc123.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "SubagentStop",
  "stop_hook_active": false,
  "agent_id": "def456",
  "agent_type": "Explore",
  "agent_transcript_path": "~/.claude/projects/.../abc123/subagents/agent-def456.jsonl",
  "last_assistant_message": "Analysis complete. Found 3 potential issues...",
  "background_tasks": [],
  "session_crons": []
}

Gli hook SubagentStop usano lo stesso formato di controllo delle decisioni degli hook Stop, incluso hookSpecificOutput.additionalContext con hookEventName impostato su "SubagentStop", per il feedback non di errore che mantiene il subagent in esecuzione. Restituire decision: "block" con un reason mantiene il subagent in esecuzione e consegna reason al subagent come sua prossima istruzione. Un hook che blocca uscendo con 2 consegna il suo messaggio stderr nello stesso modo. Per iniettare contesto nella sessione genitore dopo che un subagent ritorna, usa un hook PostToolUse sullo strumento Agent invece.

TaskCreated

Si esegue quando un compito viene creato tramite lo strumento TaskCreate. Usalo per applicare convenzioni di denominazione, richiedere descrizioni di compiti, o prevenire la creazione di determinati compiti. In una sessione senza gli strumenti Task, questo evento non si attiva.

Gli hook TaskCreated non supportano i matcher e si attivano su ogni occorrenza.

TaskCreated input

Oltre ai common input fields, gli hook TaskCreated ricevono task_id, task_subject, e opzionalmente task_description, teammate_name, e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "TaskCreated",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCreated decision control

Un hook TaskCreated può bloccare la creazione in due modi. In entrambi i casi, Claude Code elimina il compito e restituisce il tuo messaggio a Claude come errore dello strumento. Claude Code ignora continue: false da questo evento e Claude continua a lavorare.

• Codice di uscita 2: Claude Code restituisce il testo stderr come messaggio.
• JSON {"decision": "block", "reason": "..."}: Claude Code restituisce reason come messaggio.

Questo esempio blocca i compiti i cui soggetti non seguono il formato richiesto:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

if [[ ! "$TASK_SUBJECT" =~ ^\[TICKET-[0-9]+\] ]]; then
  echo "Task subject must start with a ticket number, e.g. '[TICKET-123] Add feature'" >&2
  exit 2
fi

exit 0

TaskCompleted

Si esegue quando un compito viene contrassegnato come completato. Questo si attiva in due situazioni: quando qualsiasi agente contrassegna esplicitamente un compito come completato tramite lo strumento TaskUpdate, o quando un team dell'agente teammate finisce il suo turno con compiti in corso. Usalo per applicare criteri di completamento come il passaggio dei test o dei controlli di lint prima che un compito possa chiudersi.

Gli hook TaskCompleted non supportano i matcher e si attivano su ogni occorrenza.

TaskCompleted input

Oltre ai common input fields, gli hook TaskCompleted ricevono task_id, task_subject, e opzionalmente task_description, teammate_name, e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TaskCompleted",
  "task_id": "task-001",
  "task_subject": "Implement user authentication",
  "task_description": "Add login and signup endpoints",
  "teammate_name": "implementer",
  "team_name": "session-a1b2c3d4"
}

TaskCompleted decision control

Gli hook TaskCompleted supportano due modi per controllare il completamento del compito:

• Codice di uscita 2: il compito non viene contrassegnato come completato e il messaggio stderr viene restituito al modello come feedback.
• JSON {"continue": false, "stopReason": "..."}: quando un teammate che finisce il suo turno ha attivato l'evento, ferma completamente il teammate, corrispondendo al comportamento dell'hook Stop. Il stopReason viene mostrato all'utente. Quando lo strumento TaskUpdate ha attivato l'evento, Claude Code ignora continue: false; il codice di uscita 2 blocca comunque il completamento.

Questo esempio esegue i test e blocca il completamento del compito se falliscono:

#!/bin/bash
INPUT=$(cat)
TASK_SUBJECT=$(echo "$INPUT" | jq -r '.task_subject')

# Run the test suite
if ! npm test 2>&1; then
  echo "Tests not passing. Fix failing tests before completing: $TASK_SUBJECT" >&2
  exit 2
fi

exit 0

Stop

Si esegue quando l'agente Claude Code principale ha finito di rispondere. Non si esegue se l'arresto si è verificato a causa di un'interruzione dell'utente. Gli errori API attivano StopFailure invece.

Stop input

Oltre ai common input fields, gli hook Stop ricevono stop_hook_active, last_assistant_message, background_tasks, e session_crons. Il campo stop_hook_active è true quando Claude Code sta già continuando come risultato di un hook stop. Controlla questo valore o elabora la trascrizione per evitare di bloccarsi su una condizione che non si risolverà mai. Claude Code sovrascrive l'hook e termina il turno dopo 8 blocchi consecutivi.

Il campo last_assistant_message contiene il contenuto di testo della risposta finale di Claude, quindi gli hook possono accedervi senza analizzare il file della trascrizione. Per gli hook che agiscono sul turno appena completato, come gli hook di lettura ad alta voce o notifica, usa questo campo piuttosto che leggere transcript_path: il file della trascrizione non è garantito che includa il messaggio finale al momento di Stop su tutte le versioni.

Gli array background_tasks e session_crons consentono agli hook di distinguere "la sessione è finita" da "la sessione è in pausa in attesa che il lavoro in background la risvegli di nuovo". Entrambi gli array sono presenti quando il registro dei compiti è raggiungibile e sono vuoti quando nulla è in volo o programmato.

Ogni voce in background_tasks descrive un compito in volo e usa questi campi:

Ogni voce in session_crons descrive un risveglio programmato con ambito di sessione, proveniente da CronCreate, ScheduleWakeup, e /loop:

Questo esempio mostra un input Stop con un compito shell in volo e un cron ricorrente:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "Stop",
  "stop_hook_active": true,
  "last_assistant_message": "I've completed the refactoring. Here's a summary...",
  "background_tasks": [
    {
      "id": "task-001",
      "type": "shell",
      "status": "running",
      "description": "tail logs",
      "command": "tail -f /var/log/syslog"
    }
  ],
  "session_crons": [
    {
      "id": "cron-001",
      "schedule": "0 9 * * 1-5",
      "recurring": true,
      "prompt": "check the build"
    }
  ]
}

Stop decision control

Gli hook Stop e SubagentStop possono controllare se Claude continua. Oltre ai JSON output fields disponibili per tutti gli hook, il tuo script hook può restituire questi campi specifici dell'evento:

Un hook che blocca uscendo con 2 si instrada nello stesso modo di reason: Claude riceve il messaggio stderr come spiegazione per cui dovrebbe continuare.

{
  "decision": "block",
  "reason": "Must be provided when Claude is blocked from stopping"
}

Usa additionalContext quando l'hook funziona come progettato e dà a Claude una guida, come "esegui la suite di test prima di finire". Mantiene la conversazione attraverso gli stessi loop protections di decision: "block", vale a dire l'input stop_hook_active e il limite di continuazione di 8 consecutivi, ma la trascrizione lo etichetta come Stop hook feedback e nessuna notifica di errore dell'hook viene mostrata:

{
  "hookSpecificOutput": {
    "hookEventName": "Stop",
    "additionalContext": "Please run the test suite before finishing"
  }
}

StopFailure

Si esegue invece di Stop quando il turno termina a causa di un errore API. Claude Code ignora l'output e il codice di uscita dell'hook, a parte terminalSequence. Usalo per registrare i fallimenti, inviare avvisi, o intraprendere azioni di recupero quando Claude non può completare una risposta a causa di limiti di velocità, problemi di autenticazione, o altri errori API.

StopFailure input

Oltre ai common input fields, gli hook StopFailure ricevono error, error_details facoltativo, e last_assistant_message facoltativo. Il campo error identifica il tipo di errore ed è usato per il filtraggio del matcher.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "StopFailure",
  "error": "rate_limit",
  "error_details": "429 Too Many Requests",
  "last_assistant_message": "API Error: Rate limit reached"
}

Gli hook StopFailure non hanno controllo delle decisioni. Si eseguono solo per scopi di notifica e logging.

TeammateIdle

Si esegue quando un team dell'agente teammate sta per andare inattivo dopo aver finito il suo turno. Usalo per applicare gate di qualità prima che un teammate smetta di lavorare, come richiedere il passaggio dei controlli di lint o verificare che i file di output esistano.

Gli hook TeammateIdle non supportano i matcher e si attivano su ogni occorrenza.

TeammateIdle input

Oltre ai common input fields, gli hook TeammateIdle ricevono teammate_name e team_name.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "permission_mode": "default",
  "hook_event_name": "TeammateIdle",
  "teammate_name": "researcher",
  "team_name": "session-a1b2c3d4"
}

TeammateIdle decision control

Gli hook TeammateIdle supportano due modi per controllare il comportamento del teammate:

• Codice di uscita 2: il teammate riceve il messaggio stderr come feedback e continua a lavorare invece di andare inattivo.
• JSON {"continue": false, "stopReason": "..."}: ferma completamente il teammate, corrispondendo al comportamento dell'hook Stop. Il stopReason viene mostrato all'utente.

Questo esempio controlla che un artefatto di build esista prima di consentire a un teammate di andare inattivo:

#!/bin/bash

if [ ! -f "./dist/output.js" ]; then
  echo "Build artifact missing. Run the build before stopping." >&2
  exit 2
fi

exit 0

ConfigChange

Si esegue quando un file di configurazione cambia durante una sessione. Usalo per controllare i cambiamenti delle impostazioni, applicare politiche di sicurezza, o bloccare modifiche non autorizzate ai file di configurazione.

Claude Code esegue gli hook ConfigChange quando un file di impostazioni, un file di politica gestita, o un file di skill cambia. Per la politica gestita, li esegue solo quando managed-settings.json o un file in managed-settings.d/ cambia. Applica le impostazioni gestite dal server e i cambiamenti alle preferenze gestite di macOS o alla politica del registro di Windows senza eseguirli. Su WSL con wslInheritsWindowsSettings, applica anche un file di impostazioni gestite di Windows modificato sul suo sondaggio di politica senza eseguirli.

Il matcher filtra sulla fonte di configurazione:

Questo esempio registra tutti i cambiamenti di configurazione per il controllo di sicurezza:

{
  "hooks": {
    "ConfigChange": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-config-change.sh",
            "args": []
          }
        ]
      }
    ]
  }
}

ConfigChange input

Oltre ai common input fields, gli hook ConfigChange ricevono source e opzionalmente file_path. Il campo source indica quale tipo di configurazione è cambiato, e file_path fornisce il percorso al file specifico che è stato modificato.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ConfigChange",
  "source": "project_settings",
  "file_path": "/Users/.../my-project/.claude/settings.json"
}

ConfigChange decision control

Gli hook ConfigChange possono bloccare i cambiamenti di configurazione dal prendere effetto. Usa il codice di uscita 2 o un JSON decision per prevenire il cambiamento. Quando bloccato, le nuove impostazioni non vengono applicate alla sessione in esecuzione.

{
  "decision": "block",
  "reason": "Configuration changes to project settings require admin approval"
}

I cambiamenti policy_settings non possono essere bloccati. Gli hook si attivano comunque per le fonti policy_settings quando un file di impostazioni gestite sulla macchina cambia, in modo che tu possa registrare quelle modifiche, ma qualsiasi decisione di blocco viene ignorata. Questo assicura che le impostazioni gestite dall'azienda abbiano sempre effetto. Claude Code non esegue gli hook ConfigChange quando le impostazioni gestite dal server arrivano o si aggiornano.

Claude Code agisce sulla decisione di blocco dall'output JSON di un hook ConfigChange e scarta systemMessage e continue. Un cambiamento bloccato non mostra alcun messaggio a te o a Claude, indipendentemente dal fatto che tu blocchi con reason o con stderr all'uscita 2. Claude Code scrive solo una riga nel log di debug.

CwdChanged

Si esegue quando un comando shell nella conversazione principale cambia la directory di lavoro, ad esempio quando Claude esegue un comando cd. Usalo per reagire ai cambiamenti di directory: ricaricare le variabili di ambiente, attivare toolchain specifiche del progetto, o eseguire script di configurazione automaticamente. Si accoppia con FileChanged per strumenti come direnv che gestiscono l'ambiente per directory.

Gli hook CwdChanged hanno accesso a CLAUDE_ENV_FILE. Le variabili scritte in quel file persistono nei comandi Bash successivi fino al prossimo evento CwdChanged, quando Claude Code le cancella.

CwdChanged non supporta i matcher e si attiva su ogni occorrenza.

CwdChanged input

Oltre ai common input fields, gli hook CwdChanged ricevono old_cwd e new_cwd.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project/src",
  "hook_event_name": "CwdChanged",
  "old_cwd": "/Users/my-project",
  "new_cwd": "/Users/my-project/src"
}

CwdChanged output

Oltre ai JSON output fields disponibili per tutti gli hook, gli hook CwdChanged possono restituire watchPaths per impostare dinamicamente quali percorsi di file FileChanged osserva:

Gli hook CwdChanged non hanno controllo delle decisioni. Non possono bloccare il cambiamento di directory.

Claude Code legge watchPaths e systemMessage dal loro output JSON e scarta continue. Nelle sessioni interattive, mostra il systemMessage come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.

DirectoryAdded

Si esegue dopo che aggiungi una directory di lavoro a metà sessione con il comando /add-dir, o dopo che un client SDK ne aggiunge una con la richiesta di controllo register_repo_root. Usalo per preparare un repository appena aggiunto, ad esempio installando le sue dipendenze.

Claude Code non attiva questo evento quando:

• Passi una directory con il flag di avvio --add-dir; SessionStart copre quelle directory
• Aggiungi una directory sulla scheda Workspace /permissions
• Aggiungi una directory che è già una directory di lavoro o dentro una

Claude Code attiva DirectoryAdded dopo aver aggiornato lo stato della sandbox e del permesso, quindi gli strumenti sandboxed vedono già la nuova directory quando il tuo hook si esegue. I comandi dell'hook stessi si eseguono non sandboxed.

Claude Code non attende l'hook: l'aggiunta si completa immediatamente, e l'hook si esegue in background con il timeout predefinito di 600 secondi.

Il matcher filtra su come la directory è stata aggiunta:

DirectoryAdded input

Oltre ai common input fields, gli hook DirectoryAdded ricevono directory e source.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "DirectoryAdded",
  "directory": "/Users/my-other-repo",
  "source": "slash_command"
}

Gli hook DirectoryAdded non hanno controllo delle decisioni. Non possono bloccare l'aggiunta, che si è già completata quando l'hook si esegue. Claude Code scarta il campo continue dal loro output JSON e visualizza il resto diversamente per fonte:

• slash_command: Claude Code consegna il systemMessage dell'hook a Claude come contesto sul prossimo turno della conversazione, piuttosto che mostrarlo a te. Un conteggio degli hook falliti appare nella trascrizione. L'output di fallimento completo va al log di debug
• register_repo_root: Claude Code scrive l'output systemMessage e l'output di fallimento solo nel log di debug

FileChanged

Si esegue quando un file osservato cambia su disco. Claude Code rileva i cambiamenti con un osservatore del file system, non ispezionando le chiamate di strumenti, quindi esegue l'hook indipendentemente da cosa ha cambiato il file: una chiamata di strumento Edit o Write, uno script che Claude esegue con Bash, o un processo al di fuori di Claude Code interamente. Un uso comune è ricaricare le variabili di ambiente quando i file di configurazione del progetto cambiano.

Il matcher per questo evento serve due ruoli:

• Costruire l'elenco di osservazione: il valore viene diviso su | e ogni segmento viene registrato come un nome di file letterale nella directory di lavoro, quindi ".envrc|.env" osserva esattamente quei due file. I modelli regex non sono utili qui: un valore come ^\.env osserverebbe un file letteralmente denominato ^\.env.
• Filtrare quali hook si eseguono: quando un file osservato cambia, lo stesso valore filtra quali gruppi di hook si eseguono usando le regole di matcher standard rispetto al nome di base del file modificato.

Questo esempio normalizza le terminazioni di riga in data.csv dopo qualsiasi cambiamento, incluso un comando Bash o uno script esterno che riscrive il file:

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": "data.csv",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/normalize-line-endings.sh"
          }
        ]
      }
    ]
  }
}

L'hook legge il percorso assoluto del file modificato dal campo file_path dell'input JSON su stdin. La sua guardia grep testa la stessa cosa che perl rimuove, un CR alla fine di una riga, quindi l'esecuzione dopo una normalizzazione esce senza toccare il file. Una guardia più sciolta si cicla per sempre, perché perl -i riscrive il file anche quando non sostituisce nulla e Claude Code esegue l'hook di nuovo dopo ogni riscrittura. Salva questo script in /path/to/normalize-line-endings.sh e rendilo eseguibile:

#!/bin/bash
FILE=$(jq -r .file_path)
if grep -q $'\r$' "$FILE"; then
  perl -pi -e 's/\r$//' "$FILE"
fi

Per confermare che l'hook funziona, chiedi a Claude di aggiungere una riga CRLF a data.csv con un comando Bash. Claude Code esegue l'hook e il file finisce con terminazioni LF.

Per osservare file che non puoi nominare in anticipo, restituisci watchPaths da un hook per aggiornare l'elenco di osservazione dinamicamente. Claude Code avvia l'osservatore solo quando qualcosa nomina un file da osservare, quindi semina l'elenco con un gruppo FileChanged il cui matcher nomina almeno un file, o con un hook SessionStart o CwdChanged che restituisce watchPaths. Il matcher filtra comunque quali gruppi di hook si eseguono quando un file osservato cambia, quindi dai al gruppo che gestisce i percorsi dinamici un matcher omesso, che corrisponde a ogni file osservato e non aggiunge nulla all'elenco di osservazione. Un matcher "*" corrisponde anche a ogni file, ma Claude Code lo registra nell'elenco di osservazione come un file letterale denominato *.

Gli hook FileChanged hanno accesso a CLAUDE_ENV_FILE. Le variabili scritte in quel file persistono nei comandi Bash successivi fino al prossimo evento CwdChanged, quando Claude Code le cancella.

FileChanged input

Oltre ai common input fields, gli hook FileChanged ricevono file_path e event.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../transcript.jsonl",
  "cwd": "/Users/my-project",
  "hook_event_name": "FileChanged",
  "file_path": "/Users/my-project/.envrc",
  "event": "change"
}

FileChanged output

Oltre ai JSON output fields disponibili per tutti gli hook, gli hook FileChanged possono restituire watchPaths per aggiornare dinamicamente quali percorsi di file vengono osservati:

Gli hook FileChanged non hanno controllo delle decisioni. Non possono bloccare il cambiamento del file dal verificarsi.

Claude Code legge watchPaths e systemMessage dal loro output JSON e scarta continue. Nelle sessioni interattive, mostra il systemMessage come una breve notifica di terminale. Il messaggio non raggiunge il flusso di messaggi dell'SDK.

WorktreeCreate

Si esegue quando un worktree viene creato, sia da claude --worktree, da un subagent che usa isolation: "worktree", o per una sessione in background che Claude Code isola nel suo proprio worktree. Per impostazione predefinita Claude Code crea la copia di lavoro isolata con git worktree. Configurare un hook WorktreeCreate sostituisce quel comportamento git predefinito, consentendoti di usare un sistema di controllo della versione diverso come SVN, Perforce, o Mercurial.

Poiché l'hook sostituisce completamente il comportamento predefinito, .worktreeinclude non viene elaborato. Se hai bisogno di copiare file di configurazione locale come .env nel nuovo worktree, fallo dentro il tuo script hook.

L'hook deve restituire il percorso alla directory del worktree creato. Claude Code usa questo percorso come directory di lavoro per la sessione isolata. Vedi WorktreeCreate output per come ogni tipo di hook restituisce il percorso.

Claude Code agisce sul successo dell'hook e sul percorso restituito, e scarta systemMessage e continue.

Questo esempio crea una copia di lavoro SVN e stampa il percorso per Claude Code da usare. Sostituisci l'URL del repository con il tuo:

{
  "hooks": {
    "WorktreeCreate": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'NAME=$(jq -r .name); DIR=\"$HOME/.claude/worktrees/$NAME\"; svn checkout https://svn.example.com/repo/trunk \"$DIR\" >&2 && echo \"$DIR\"'"
          }
        ]
      }
    ]
  }
}

L'hook legge il name del worktree dall'input JSON su stdin, controlla una copia fresca in una nuova directory, e stampa il percorso della directory. L'echo sull'ultima riga è ciò che Claude Code legge come percorso del worktree. Reindirizza qualsiasi altro output a stderr in modo che non interferisca con il percorso.

WorktreeCreate input

Oltre ai common input fields, gli hook WorktreeCreate ricevono il campo name. Questo è un identificatore slug per il nuovo worktree, specificato dall'utente o auto-generato, ad esempio bold-oak-a3f2.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeCreate",
  "name": "feature-auth"
}

WorktreeCreate output

Gli hook WorktreeCreate non usano il modello di decisione di consentimento/blocco standard. Invece, il successo o il fallimento dell'hook determina il risultato. L'hook deve restituire il percorso alla directory del worktree creato:

• Hook di comando (type: "command"): stampa il percorso come l'ultima riga non vuota di stdout. Claude Code rimuove i codici di escape ANSI prima di leggere quella riga, quindi i banner di avvio della shell stampati prima del tuo echo vengono ignorati. Reindirizza qualsiasi altro output dell'hook a stderr.
• Hook HTTP (type: "http"): restituisci { "hookSpecificOutput": { "hookEventName": "WorktreeCreate", "worktreePath": "/absolute/path" } } nel corpo della risposta.

Se l'hook fallisce o non produce alcun percorso, la creazione del worktree fallisce con un errore.

Claude Code risolve un percorso relativo rispetto alla directory in cui l'hook si è eseguito, collassando qualsiasi segmento . o .. in esso. Se il percorso risultante non è una directory in cui Claude Code può entrare, la sessione stampa un errore che nomina il percorso ed esce con il codice 1.

Claude Code rifiuta un percorso assoluto che contiene segmenti . o .., e qualsiasi percorso che passa attraverso un symlink al di sotto della radice del repository, perché un symlink impegnato nel repository potrebbe reindirizzare il worktree al di fuori di esso. L'errore nomina il componente rifiutato. Restituisci un percorso normalizzato che non passa attraverso un symlink all'interno del repository. Prima della v2.1.216, la creazione del worktree seguiva il percorso dell'hook senza questo screening.

WorktreeRemove

Si esegue quando un worktree viene rimosso. Questo è l'equivalente di pulizia di WorktreeCreate. L'evento si attiva quando:

• esci da una sessione --worktree e scegli di rimuoverla
• un subagent con isolation: "worktree" finisce
• elimini una sessione in background il cui worktree l'hook ha creato

Per i worktree basati su git, Claude Code gestisce la pulizia automaticamente con git worktree remove. Se hai configurato un hook WorktreeCreate per un sistema di controllo della versione non git, accoppialo con un hook WorktreeRemove per gestire la pulizia. Senza uno, la directory del worktree viene lasciata su disco.

Claude Code scarta i JSON output fields di un hook WorktreeRemove, come systemMessage e continue.

Per un'eliminazione di sessione in background, Claude Code verifica il percorso del worktree archiviato prima di eseguire l'hook e rifiuta un percorso che è un symlink o passa attraverso uno al di sotto della radice del repository. L'hook si esegue per un worktree che contiene ancora file solo quando confermi l'eliminazione nella agent view; per un tale worktree, claude rm mantiene la sessione e il worktree invece. Prima della v2.1.216, l'hook si eseguiva sul percorso archiviato senza questi controlli.

Claude Code passa il percorso restituito da WorktreeCreate come worktree_path nell'input dell'hook. Questo esempio legge quel percorso e rimuove la directory:

{
  "hooks": {
    "WorktreeRemove": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "bash -c 'jq -r .worktree_path | xargs rm -rf'"
          }
        ]
      }
    ]
  }
}

WorktreeRemove input

Oltre ai common input fields, gli hook WorktreeRemove ricevono il campo worktree_path, che è il percorso assoluto al worktree che viene rimosso.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "WorktreeRemove",
  "worktree_path": "/Users/.../my-project/.claude/worktrees/feature-auth"
}

Il codice di uscita di un hook WorktreeRemove decide il risultato. Quando un hook esce con non-zero e la directory in worktree_path esiste ancora dopo, la rimozione fallisce:

• Il worktree rimane su disco, e il comando dell'hook e stderr vanno al debug log.
• Se stavi eliminando una sessione in background, la sessione rimane anche. Il messaggio di rifiuto nella agent view segnala come l'hook è terminato, come exited 1, cita l'inizio del suo stderr, e dice se eliminare la sessione di nuovo rimuove la directory comunque.

PreCompact

Si esegue prima che Claude Code stia per eseguire un'operazione di compattazione.

Il valore del matcher indica se la compattazione è stata attivata manualmente o automaticamente:

Esci con il codice 2 per bloccare la compattazione. Per un /compact manuale, il messaggio stderr viene mostrato all'utente. Puoi anche bloccare restituendo JSON con "decision": "block".

Bloccare la compattazione automatica ha effetti diversi a seconda di quando si attiva. Se la compattazione è stata attivata in modo proattivo prima del limite di contesto, Claude Code la salta e la conversazione continua non compattata. Se la compattazione è stata attivata per recuperare da un errore di limite di contesto già restituito dall'API, l'errore sottostante emerge e la richiesta corrente fallisce.

Claude Code scarta i campi systemMessage e continue di un hook PreCompact.

PreCompact input

Oltre ai common input fields, gli hook PreCompact ricevono trigger e custom_instructions. Per manual, custom_instructions contiene ciò che l'utente passa in /compact ed è null quando non passa nulla. Per auto, custom_instructions è null.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreCompact",
  "trigger": "manual",
  "custom_instructions": null
}

PostCompact

Si esegue dopo che Claude Code completa un'operazione di compattazione. Usalo per reagire al nuovo stato compattato, ad esempio per registrare il riepilogo generato o aggiornare lo stato esterno. Claude Code scarta i campi systemMessage e continue di un hook PostCompact.

Gli stessi valori di matcher si applicano come per PreCompact:

PostCompact input

Oltre ai common input fields, gli hook PostCompact ricevono trigger e compact_summary. Il campo compact_summary contiene il riepilogo della conversazione generato dall'operazione di compattazione.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PostCompact",
  "trigger": "manual",
  "compact_summary": "Summary of the compacted conversation..."
}

Gli hook PostCompact non hanno controllo delle decisioni. Non possono influenzare il risultato della compattazione ma possono eseguire compiti di follow-up.

PreModelSwitch

Si esegue prima che Claude Code applichi un cambio di modello che hai richiesto tu o un client. Usalo per bloccare un cambio, richiedere conferma, o mostrare quale sarà il costo del cambio prima che accada.

PreModelSwitch richiede Claude Code v2.1.251 o successivo. Claude Code lo esegue per queste richieste:

• /model <name> e il picker /model
• Il picker del modello Option+P o Alt+P
• L'impostazione Model in /config
• Attivare la fast mode quando ciò cambia il modello della sessione
• Una richiesta set_model, o un cambiamento di modello in una richiesta apply_flag_settings, da un host Agent SDK o Remote Control

Claude Code non esegue gli hook PreModelSwitch per i cambi che fa da solo, come un fallback automatico del modello o il ripristino del modello quando riprendi una sessione. Quei cambi raggiungono PostModelSwitch solo.

Claude Code confronta il matcher rispetto al nome canonico del modello a cui la sessione sta passando, ignorando qualsiasi suffisso [1m]. Un alias come opus, un ID di modello datato, e un ID specifico del provider come un ID di modello Amazon Bedrock corrispondono tutti al nome canonico unico a cui si risolvono, quindi claude-opus-5 copre ogni ortografia di Opus 5.

Quando Claude Code non può determinare un nome canonico per il target, ad esempio un ID di modello personalizzato che solo il tuo LLM gateway conosce, esegue ogni hook PreModelSwitch indipendentemente dal matcher. Un hook che blocca dovrebbe quindi controllare to_model dal suo input piuttosto che fare affidamento solo sul matcher.

Scrivi il matcher come un nome esatto, un elenco separato da | come claude-opus-4-6|claude-opus-5, o un'espressione regolare come .*opus.*. Questo esempio usa un matcher di nome esatto e controlla anche to_model dall'input dell'hook, quindi rifiuta un cambio a Opus 4.6 uscendo con il codice 2 e consente qualsiasi altro target:

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "jq -e '.to_model | test(\"opus-4-6\")' > /dev/null && { echo 'Opus 4.6 is retired for this project. Use a newer model.' >&2; exit 2; }; exit 0"
}
]
}
]
}
}

{
"hooks": {
"PreModelSwitch": [
{
"matcher": "claude-opus-4-6",
"hooks": [
{
"type": "command",
"command": "powershell.exe",
"args": [
"-NoProfile",
"-ExecutionPolicy",
"Bypass",
"-File",
"${CLAUDE_PROJECT_DIR}/.claude/hooks/block-opus-46.ps1"
]
}
]
}
]
}
}

$hookInput = [Console]::In.ReadToEnd() | ConvertFrom-Json
if ($hookInput.to_model -match 'opus-4-6') {
[Console]::Error.WriteLine('Opus 4.6 is retired for this project. Use a newer model.')
exit 2
}
exit 0

Per confermare che l'hook funziona, esegui /model claude-opus-4-6 da una sessione che esegue un modello diverso. Claude Code mantiene il modello corrente e segnala che un hook PreModelSwitch ha bloccato il cambio, con il tuo messaggio come motivo.

PreModelSwitch input

Oltre ai common input fields, gli hook PreModelSwitch ricevono i campi in questa tabella. Gli ultimi cinque descrivono quale costo ha l'invio della conversazione al nuovo modello, quindi un hook può mostrare quella cifra prima che il cambio accada.

Questo esempio mostra l'input per /model opus in una sessione che esegue Sonnet 5:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "PreModelSwitch",
  "from_model": "claude-sonnet-5",
  "to_model": "claude-opus-5",
  "requested_model": "opus",
  "source": "command",
  "context_tokens": 182340,
  "prompt_cache_warm": true,
  "cache_ttl": "5m",
  "estimated_cache_write_usd": 1.1396,
  "pricing": "catalog"
}

PreModelSwitch decision control

Gli hook PreModelSwitch possono annullare il cambio, chiedere all'utente di confermarlo, o consentirgli di procedere. Il codice di uscita 2 o un decision: "block" di livello superiore annulla il cambio.

Per un controllo più fine, restituisci permissionDecision e permissionDecisionReason in un oggetto hookSpecificOutput, come su PreToolUse. PreModelSwitch accetta "allow", "deny", e "ask". Non accetta "defer", updatedInput, o additionalContext. La tabella seguente descrive entrambi i campi:

Solo /model in una sessione interattiva può mostrare il prompt "ask". Su ogni altra superficie, inclusa la modalità non interattiva con il flag -p, /config, e le richieste set_model, Claude Code tratta "ask" come un rifiuto.

Questo esempio chiede all'utente di confermare e cita il conteggio dei token da context_tokens:

{
  "hookSpecificOutput": {
    "hookEventName": "PreModelSwitch",
    "permissionDecision": "ask",
    "permissionDecisionReason": "Switching now re-sends about 180k tokens to the new model. Continue?"
  }
}

Quando più hook PreModelSwitch restituiscono decisioni diverse, la precedenza è deny > ask > allow.

Claude Code mostra all'utente qualsiasi systemMessage che il tuo hook restituisce indipendentemente dalla decisione, quindi un hook di rapporto dei costi può restituire {"systemMessage": "..."} e uscire 0.

Un hook PreModelSwitch che non risponde prima del suo timeout blocca il cambio. Su PreToolUse, al contrario, un hook di comando che scade consente alla chiamata dello strumento di continuare. Il timeout predefinito per questo evento è 30 secondi. PreModelSwitch esegue solo gli hook command, http, e mcp_tool, quindi i default prompt e agent non si applicano.

Un hook che esce con un codice diverso da 0 o 2 e non stampa alcuna decisione JSON non blocca: Claude Code mostra il suo stderr e applica il cambio, come descritto sotto Other exit codes.

PostModelSwitch

Si esegue dopo che il modello della sessione cambia. Usalo per dare a Claude una guida specifica del modello senza modificare ogni CLAUDE.md, ad esempio un'istruzione a livello di organizzazione che si applica su determinati modelli.

PostModelSwitch richiede Claude Code v2.1.251 o successivo. Non può bloccare, perché il modello è già cambiato. Claude Code esegue gli hook PostModelSwitch dopo qualsiasi di questi cambi:

• Un cambio che hai richiesto tu o un client
• Un fallback automatico del modello, che cambia il modello della sessione
• Un'impostazione come opusplan che entra o esce dalla plan mode
• Claude Code che ripristina il modello quando riprendi una sessione

Claude Code non esegue gli hook PostModelSwitch quando un modello da una catena di fallback del modello serve un turno, perché quella sostituzione dura un turno e lascia il modello della sessione invariato.

Il matcher segue le stesse regole di PreModelSwitch: Claude Code confronta il matcher rispetto al nome canonico del modello a cui la sessione è passata.

Questo esempio aggiunge una guida ogni volta che il modello della sessione cambia a qualsiasi modello Opus:

{
  "hooks": {
    "PostModelSwitch": [
      {
        "matcher": ".*opus.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'On Opus, delegate implementation work to subagents and keep this conversation for planning and review.'"
          }
        ]
      }
    ]
  }
}

Per confermare che l'hook funziona, passa a un modello Opus da una sessione che esegue un modello diverso, ad esempio esegui /model opus da una sessione Sonnet, quindi chiedi a Claude quale guida ha sul modello corrente.

PostModelSwitch input

Gli hook PostModelSwitch ricevono gli stessi campi di PreModelSwitch, con hook_event_name impostato su "PostModelSwitch" e due valori source in più: "auto" per un fallback automatico o un altro cambiamento che Claude Code ha fatto da solo, e "resume" per il modello ripristinato quando riprendi una sessione.

requested_model è null quando source è "auto". Quando source è "resume", è l'impostazione del modello salvato che Claude Code ha ripristinato.

PostModelSwitch decision control

Claude Code prende il tuo stdout in testo semplice dell'hook plain-text stdout all'uscita 0, o additionalContext dall'output JSON, e lo consegna a Claude con la richiesta successiva dopo il cambio. Oltre ai JSON output fields disponibili per tutti gli hook, puoi restituire:

Se l'hook non finisce entro cinque secondi dopo che invii la richiesta successiva, Claude Code invia quella richiesta senza l'output e lo allega alla richiesta seguente invece. Se il modello cambia diverse volte prima della richiesta successiva, Claude Code consegna solo l'output per il modello target dell'ultimo cambio.

SessionEnd

Si esegue quando una sessione di Claude Code termina. Utile per i compiti di pulizia, la registrazione delle statistiche della sessione, o il salvataggio dello stato della sessione. Supporta i matcher per filtrare per motivo di uscita.

Il campo reason nell'input dell'hook indica perché la sessione è terminata:

SessionEnd input

Oltre ai common input fields, gli hook SessionEnd ricevono un campo reason che indica perché la sessione è terminata. Vedi la tabella dei motivi sopra per tutti i valori.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "SessionEnd",
  "reason": "other"
}

Gli hook SessionEnd non hanno controllo delle decisioni. Non possono bloccare la terminazione della sessione ma possono eseguire compiti di pulizia. Claude Code scarta i loro JSON output fields, come systemMessage.

Gli hook SessionEnd hanno un timeout predefinito di 1,5 secondi. Questo si applica all'uscita della sessione, a /clear, e al passaggio di sessioni tramite /resume interattivo. Se un hook ha bisogno di più tempo, imposta un timeout per hook nella configurazione dei file di impostazioni. Il budget complessivo viene automaticamente aumentato al timeout per hook più alto configurato nei file di impostazioni, fino a 60 secondi. I timeout impostati su hook forniti da plugin non aumentano il budget.

Questo esempio imposta il budget a 5 secondi:

CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS=5000 claude

Prima della v2.1.268, CLAUDE_CODE_SESSIONEND_HOOKS_TIMEOUT_MS aumentava solo il budget complessivo, e un hook senza il suo timeout era comunque annullato dopo 1,5 secondi.

Elicitation

Si esegue quando un server MCP richiede input dell'utente a metà compito. Per impostazione predefinita, Claude Code mostra un dialogo interattivo per l'utente per rispondere. Gli hook possono intercettare questa richiesta e rispondere programmaticamente, saltando completamente il dialogo.

Il campo matcher corrisponde al nome del server MCP.

Elicitation input

Oltre ai common input fields, gli hook Elicitation ricevono mcp_server_name, message, e campi facoltativi mode, url, elicitation_id, e requested_schema.

Per l'elicitazione in modalità modulo, il caso più comune:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please provide your credentials",
  "mode": "form",
  "requested_schema": {
    "type": "object",
    "properties": {
      "username": { "type": "string", "title": "Username" }
    }
  }
}

Per l'elicitazione in modalità URL, usata per l'autenticazione basata su browser:

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "Elicitation",
  "mcp_server_name": "my-mcp-server",
  "message": "Please authenticate",
  "mode": "url",
  "url": "https://auth.example.com/login"
}

Elicitation output

Per rispondere programmaticamente senza mostrare il dialogo, restituisci un oggetto JSON con hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "Elicitation",
    "action": "accept",
    "content": {
      "username": "alice"
    }
  }
}

L'uscita con il codice 2 nega l'elicitazione. Claude Code non mostra il tuo messaggio stderr da nessuna parte.

Claude Code agisce su hookSpecificOutput dall'output JSON di un hook Elicitation e scarta systemMessage e continue.

ElicitationResult

Si esegue dopo che un utente risponde a un'elicitazione MCP. Gli hook possono osservare, modificare, o bloccare la risposta prima che venga inviata di nuovo al server MCP.

Il campo matcher corrisponde al nome del server MCP.

ElicitationResult input

Oltre ai common input fields, gli hook ElicitationResult ricevono mcp_server_name, action, e campi facoltativi mode, elicitation_id, e content.

{
  "session_id": "abc123",
  "transcript_path": "/Users/.../.claude/projects/.../00893aaf-19fa-41d2-8238-13269b9b3ca0.jsonl",
  "cwd": "/Users/...",
  "hook_event_name": "ElicitationResult",
  "mcp_server_name": "my-mcp-server",
  "action": "accept",
  "content": { "username": "alice" },
  "mode": "form",
  "elicitation_id": "elicit-123"
}

ElicitationResult output

Per sovrascrivere la risposta dell'utente, restituisci un oggetto JSON con hookSpecificOutput:

{
  "hookSpecificOutput": {
    "hookEventName": "ElicitationResult",
    "action": "decline",
    "content": {}
  }
}

L'uscita con il codice 2 blocca la risposta, cambiando l'azione effettiva a decline. Claude Code non mostra il tuo messaggio stderr da nessuna parte.

Claude Code agisce su hookSpecificOutput dall'output JSON di un hook ElicitationResult e scarta systemMessage e continue.

Hook basati su prompt

Oltre agli hook di comando, HTTP e MCP tool, Claude Code supporta gli hook basati su prompt (type: "prompt") che utilizzano un LLM per valutare se consentire o bloccare un'azione, e gli hook basati su agenti (type: "agent") che generano un verificatore agentico con accesso agli strumenti. Non tutti gli eventi supportano ogni tipo di hook.

Gli eventi che supportano tutti e cinque i tipi di hook (command, http, mcp_tool, prompt e agent):

• PermissionDenied
• PostToolBatch
• PostToolUse
• PostToolUseFailure
• PreToolUse
• Stop
• SubagentStop
• TaskCompleted
• TaskCreated
• TeammateIdle
• UserPromptExpansion
• UserPromptSubmit

PermissionRequest supporta gli hook command, http, mcp_tool e prompt ma non gli hook agent. Se configuri un hook agent su questo evento, Claude Code lo salta e il flusso di autorizzazione procede invariato. Per consentire o negare da un hook, restituisci l'oggetto decisione da un hook di comando o HTTP.

Gli eventi che supportano gli hook command, http e mcp_tool ma non prompt o agent:

• ConfigChange
• CwdChanged
• DirectoryAdded
• Elicitation
• ElicitationResult
• FileChanged
• InstructionsLoaded
• MessageDisplay
• Notification
• PostCompact
• PostModelSwitch
• PreCompact
• PreModelSwitch
• SessionEnd
• StopFailure
• SubagentStart
• WorktreeCreate
• WorktreeRemove

SessionStart e Setup supportano gli hook command e mcp_tool, e i campi degli hook MCP tool descrivono quando i loro hook mcp_tool vengono eseguiti. Non supportano gli hook http, prompt o agent.

Come funzionano gli hook basati su prompt

Invece di eseguire un comando Bash, gli hook basati su prompt:

1. Inviano l'input del hook e il prompt a un modello Claude, Haiku per impostazione predefinita
2. L'LLM risponde con JSON strutturato contenente una decisione
3. Claude Code elabora automaticamente la decisione

Configurazione del prompt hook

Impostare type su "prompt" e fornire una stringa prompt invece di un command. Utilizzare il segnaposto $ARGUMENTS per iniettare i dati di input JSON del hook nel testo del prompt.

Questo hook Stop chiede all'LLM di valutare se tutti i compiti sono completi prima di consentire a Claude di terminare:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Evaluate if Claude should stop: $ARGUMENTS. Check if all tasks are complete."
          }
        ]
      }
    ]
  }
}

Schema di risposta

L'LLM deve rispondere con JSON contenente:

{
  "ok": true | false,
  "reason": "Explanation for the decision",
  "impossible": true | false
}

Ciò che accade con ok: false dipende dall'evento:

• Stop e SubagentStop: il motivo viene reinviato a Claude come sua prossima istruzione e il turno continua, a meno che la risposta non imposti anche impossible: true, nel qual caso Claude Code consente lo stop e il turno termina
• PreToolUse: la chiamata dello strumento viene negata; per impostazione predefinita il turno termina e il motivo della negazione appare nella chat come una riga di avviso. Impostare continueOnBlock: true per reinviare il motivo a Claude come errore dello strumento in modo che possa adattarsi e continuare, equivalente a un hook di comando con permissionDecision: "deny". Prima della v2.1.210, il motivo della negazione veniva restituito a Claude come errore dello strumento e il turno continuava
• PostToolUse: per impostazione predefinita il turno termina e il motivo appare nella chat come una riga di avviso. Impostare continueOnBlock: true per reinviare il motivo a Claude e continuare il turno invece
• PostToolBatch, UserPromptSubmit e UserPromptExpansion: il turno termina e il motivo appare come una riga di avviso. Questi eventi terminano il turno su decision: "block" indipendentemente da continue
• PostToolUseFailure e TaskCreated: il motivo viene restituito a Claude come errore dello strumento e il turno continua, indipendentemente da continueOnBlock
• TaskCompleted: quando si attiva perché un'attività è contrassegnata come completata durante un turno, il motivo viene restituito a Claude come errore dello strumento e il turno continua, indipendentemente da continueOnBlock. Quando si attiva perché un compagno di squadra si ferma, si comporta come TeammateIdle e arresta il compagno di squadra per impostazione predefinita
• TeammateIdle: per impostazione predefinita il compagno di squadra si ferma e il motivo appare come una riga di avviso. Impostare continueOnBlock: true per reinviare il motivo al compagno di squadra e mantenerlo al lavoro invece
• PermissionRequest: ok: false non ha effetto. Per negare un'approvazione da un hook, utilizzare un hook di comando che restituisce hookSpecificOutput.decision.behavior: "deny"
• PermissionDenied: ok: false non ha effetto perché il rifiuto è già avvenuto. L'unico output che questo evento legge è hookSpecificOutput.retry, che gli hook di prompt e agenti non possono impostare. Vengono eseguiti su questo evento, ma il loro output viene scartato. Utilizzare un hook di comando per restituire retry

Se hai bisogno di un controllo più fine su qualsiasi evento, utilizza un hook di comando con i campi per evento descritti in Controllo delle decisioni.

Controllare più condizioni prima di fermarsi

Questo hook Stop utilizza un prompt dettagliato per controllare tre condizioni prima di consentire a Claude di fermarsi. Gli hook SubagentStop utilizzano lo stesso formato per valutare se un subagent dovrebbe fermarsi. Se il modello restituisce "ok": false perché la condizione non è ancora soddisfatta, Claude continua a lavorare con il motivo fornito come sua prossima istruzione:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "You are evaluating whether Claude should stop working. Context: $ARGUMENTS\n\nAnalyze the conversation and determine if:\n1. All user-requested tasks are complete\n2. Any errors need to be addressed\n3. Follow-up work is needed\n\nRespond with JSON: {\"ok\": true} to allow stopping, or {\"ok\": false, \"reason\": \"your explanation\"} to continue working.",
            "timeout": 30
          }
        ]
      }
    ]
  }
}

Hook basati su agenti

Gli hook basati su agenti (type: "agent") sono come gli hook basati su prompt ma con accesso agli strumenti multi-turno. Invece di una singola chiamata LLM, un hook agente genera un subagent che può leggere file, cercare codice e ispezionare il codebase per verificare le condizioni. Gli hook agente supportano gli stessi eventi degli hook basati su prompt, ad eccezione di PermissionRequest.

Come funzionano gli hook basati su agenti

Quando un hook agente si attiva:

1. Claude Code genera un subagent con il prompt e l'input JSON del hook
2. Il subagent può utilizzare strumenti come Read, Grep e Glob per investigare
3. Dopo fino a 50 turni, il subagent restituisce una decisione strutturata { "ok": true/false }
4. Claude Code consente l'azione se ok è true. Se ok è false, Claude Code gestisce il blocco nello stesso modo di un hook di prompt con continueOnBlock: true su quell'evento, come elencato sotto Schema di risposta

Gli hook agente sono utili quando la verifica richiede l'ispezione dei file effettivi o dell'output dei test, non solo la valutazione dei dati di input del hook da soli.

Configurazione dell'hook agente

Impostare type su "agent" e fornire una stringa prompt, utilizzando $ARGUMENTS come segnaposto per l'input JSON del hook. I campi di configurazione sono gli stessi degli hook di prompt, ad eccezione del fatto che gli hook agente hanno un timeout predefinito più lungo di 60 secondi e nessun campo continueOnBlock.

Lo schema di risposta è { "ok": true } per consentire o { "ok": false, "reason": "..." } per bloccare. Su ok: false, Claude Code gestisce un hook agente nello stesso modo in cui gestisce un hook di prompt con continueOnBlock: true sullo stesso evento; gli hook agente non hanno un campo continueOnBlock e non supportano il campo impossible dell'hook di prompt.

Questo hook Stop verifica che tutti i test unitari passino prima di consentire a Claude di finire:

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

Eseguire i hook in background

Per impostazione predefinita, gli hook bloccano l'esecuzione di Claude fino al completamento. Per le attività a lunga esecuzione come distribuzioni, suite di test o chiamate API esterne, impostare "async": true per eseguire l'hook in background mentre Claude continua a lavorare. Gli hook asincroni non possono bloccare o controllare il comportamento di Claude: i campi di risposta come decision, permissionDecision e continue non hanno effetto, perché l'azione che avrebbero controllato è già stata completata.

Configurare un hook asincrono

Aggiungere "async": true alla configurazione di un command hook per eseguirlo in background senza bloccare Claude. Questo campo è disponibile solo sui hook type: "command".

Questo hook esegue uno script di test dopo ogni chiamata dello strumento Write. Claude continua a lavorare immediatamente mentre run-tests.sh viene eseguito. Quando lo script termina, l'output viene consegnato al turno di conversazione successivo:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "command": "/path/to/run-tests.sh",
            "async": true
          }
        ]
      }
    ]
  }
}

Una volta che un hook asincrono è in esecuzione in background, Claude Code non applica timeout su di esso. Claude Code continua ad applicare timeout su un hook che si esegue con asyncRewake.

Claude Code consegna i risultati di un hook asincrono solo mentre la sessione è in esecuzione:

• In modalità non interattiva con il flag -p, Claude Code termina qualsiasi hook asincrono ancora in esecuzione al teardown e lo finalizza con esito cancelled
• Se il lavoro del vostro hook deve sopravvivere a una sessione claude -p, avviate un processo completamente staccato da esso

Come vengono eseguiti gli hook asincroni

Quando un hook asincrono si attiva, Claude Code avvia il processo del hook e continua immediatamente senza aspettare il completamento. L'hook riceve lo stesso input JSON tramite stdin di un hook sincrono.

Dopo che il processo in background esce, Claude Code consegna i campi additionalContext e systemMessage dalla risposta JSON dell'hook a Claude al turno di conversazione successivo. A differenza di systemMessage di un hook sincrono, nessuno dei due campi viene mostrato a voi.

Claude Code convalida quella risposta JSON rispetto allo stesso schema di output degli hook sincroni e scarta qualsiasi campo il cui valore ha il tipo errato, come un systemMessage che non è una stringa, invece di consegnarlo. Eseguire con --debug per vedere un avviso che nomina ogni campo scartato. Prima della v2.1.202, l'output JSON malformato da un hook asincrono poteva causare l'arresto della sessione e l'arresto si ripeteva ogni volta che la sessione veniva ripresa.

Le notifiche di completamento degli hook asincroni sono soppresse per impostazione predefinita. Per vederle, abilitare la modalità verbose con Ctrl+O o avviare Claude Code con --verbose.

Eseguire i test dopo le modifiche ai file

Questo hook avvia una suite di test in background ogni volta che Claude scrive un file, quindi segnala i risultati a Claude quando i test terminano. Salvare questo script in .claude/hooks/run-tests-async.sh nel progetto e renderlo eseguibile con chmod +x:

#!/bin/bash
# run-tests-async.sh

# Leggere l'input del hook da stdin
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Eseguire i test solo per i file di origine
if [[ "$FILE_PATH" != *.ts && "$FILE_PATH" != *.js ]]; then
  exit 0
fi

# Eseguire i test e segnalare i risultati a Claude tramite additionalContext
RESULT=$(npm test 2>&1)
EXIT_CODE=$?

if [ $EXIT_CODE -eq 0 ]; then
  MSG="Tests passed after editing $FILE_PATH"
else
  MSG="Tests failed after editing $FILE_PATH: $RESULT"
fi
jq -nc --arg msg "$MSG" '{hookSpecificOutput: {hookEventName: "PostToolUse", additionalContext: $msg}}'

Quindi aggiungere questa configurazione a .claude/settings.json nella radice del progetto. Il flag async: true consente a Claude di continuare a lavorare mentre i test vengono eseguiti:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/run-tests-async.sh",
            "args": [],
            "async": true
          }
        ]
      }
    ]
  }
}

Limitazioni

Gli hook asincroni hanno vincoli aggiuntivi rispetto agli hook sincroni:

• L'output del hook viene consegnato al turno di conversazione successivo. Se la sessione è inattiva, la risposta attende fino alla prossima interazione dell'utente. Eccezione: un hook asyncRewake che esce con il codice 2 riattiva Claude immediatamente anche quando la sessione è inattiva.
• Ogni esecuzione crea un processo in background separato. Non c'è deduplicazione tra più attivazioni dello stesso hook asincrono.

Considerazioni sulla sicurezza

Disclaimer

Fiducia nell'area di lavoro

Claude Code verifica la fiducia nell'area di lavoro prima di eseguire qualsiasi hook da un file di impostazioni. Ciò che conta come attendibile dipende dal tipo di sessione:

• Sessione interattiva: Claude Code trattiene i hook da ogni file di impostazioni, incluso il vostro ~/.claude/settings.json, fino a quando non accettate la finestra di dialogo di fiducia nell'area di lavoro per la cartella, o per una directory padre la cui fiducia si estende ad essa
• Sessione -p o SDK: Claude Code non mostra mai la finestra di dialogo e tratta la cartella come attendibile, quindi i hook sottoposti a commit nel .claude/settings.json di un repository vengono eseguiti in una cartella che non avete mai considerato attendibile

Prima di eseguire lo script claude -p su un repository che non avete scritto, rivedete i file di impostazioni .claude/, iniziate con --bare, o disattivate i hook per quella esecuzione con --settings '{"disableAllHooks": true}'. I hook nel frontmatter in un subagent di progetto seguono una regola più ristretta rispetto ai hook dei file di impostazioni. Ciò che viene eseguito prima di considerare attendibile una cartella elenca ogni tipo di contenuto del repository per tipo di sessione.

Migliori pratiche di sicurezza

Tenere presenti queste pratiche quando si scrivono i hook:

• Convalidare e disinfettare gli input: non fidarsi mai ciecamente dei dati di input
• Citare sempre le variabili shell: utilizzare "$VAR" non $VAR
• Bloccare l'attraversamento del percorso: controllare .. nei percorsi dei file
• Utilizzare percorsi assoluti: specificare percorsi completi per gli script. Nel modulo exec, utilizzare ${CLAUDE_PROJECT_DIR} e il percorso non necessita di virgolette. Nel modulo shell, racchiuderlo tra virgolette doppie
• Saltare i file sensibili: evitare .env, .git/, chiavi, ecc.

Strumento Windows PowerShell

Su Windows, è possibile eseguire singoli hook in PowerShell impostando "shell": "powershell" su un command hook. Claude Code rileva automaticamente pwsh.exe, l'eseguibile di PowerShell 7 e versioni successive, e ricade su powershell.exe per Windows PowerShell 5.1.

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write",
        "hooks": [
          {
            "type": "command",
            "shell": "powershell",
            "command": "Write-Host 'File written'"
          }
        ]
      }
    ]
  }
}

Per fare riferimento alla directory radice del progetto da un comando in forma shell di PowerShell, scrivere ${CLAUDE_PROJECT_DIR} o $env:CLAUDE_PROJECT_DIR. A partire dalla v2.1.198, Claude Code riscrive i segnaposti ${CLAUDE_PROJECT_DIR}, ${CLAUDE_PLUGIN_ROOT} e ${CLAUDE_PLUGIN_DATA} in un comando in forma shell di PowerShell nella forma ${env:NAME} di PowerShell, indipendentemente dal fatto che l'hook sia definito in settings.json, un plugin o una skill. PowerShell quindi risolve il valore dall'ambiente esportato dopo l'analisi, quindi il segnaposto funziona all'interno di stringhe tra virgolette doppie ma non all'interno di stringhe tra virgolette singole, dove PowerShell non espande mai le variabili.

Prima della v2.1.198, questa riscrittura si applicava solo agli hook dei plugin. Nelle versioni precedenti, un hook settings.json necessita della forma $env: o della forma exec, dove ${CLAUDE_PROJECT_DIR} viene sostituito in ogni elemento args indipendentemente da dove l'hook è definito.

Non scrivere la forma nuda $CLAUDE_PROJECT_DIR in un hook di PowerShell. PowerShell la analizza come una variabile locale non definita e la risolve in $null, il che lascia il percorso dello script senza il prefisso della directory radice del progetto. Claude Code non riscrive quella forma; invece registra un avviso nel log di debug.

L'esempio seguente mostra un hook settings.json che esegue uno script di progetto con la forma $env:, che funziona su ogni versione:

{
  "type": "command",
  "shell": "powershell",
  "command": "& \"$env:CLAUDE_PROJECT_DIR\\.claude\\hooks\\check.ps1\""
}

Debug dei hook

I dettagli dell'esecuzione dei hook vengono scritti nel file di log di debug. Avviare Claude Code con claude --debug-file <path> per scrivere il log in una posizione nota, oppure eseguire claude --debug e leggere il log in ~/.claude/debug/<session-id>.txt. Il flag --debug non stampa nel terminale.

Ad esempio, un hook PostToolUse su Write il cui comando stampa hook-ran produce voci come:

2026-07-19T02:03:24.382Z [DEBUG] Hook output does not start with {, treating as plain text
2026-07-19T02:03:24.382Z [DEBUG] "Hook PostToolUse:Write (PostToolUse) success:\nhook-ran"

Per dettagli di corrispondenza dei hook più granulari, impostare CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose per visualizzare righe di log aggiuntive come i conteggi dei matcher del hook e la corrispondenza delle query.

Per la risoluzione dei problemi comuni come i hook che non si attivano, i Stop hook che continuano a bloccare, o gli errori di configurazione, consultare Limitations and troubleshooting nella guida. Per una procedura diagnostica più ampia che copre /context, /doctor e la precedenza delle impostazioni, consultare Debug your config.