Vai al contenuto principale
Un hook è un gestore di eventi: una funzione che Claude Code esegue quando si verifica un evento con un determinato nome. Claude Code genera un evento in ogni punto in cui sta per agire, ad esempio quando esegue uno strumento, invia un prompt, invia una richiesta al modello oppure avvia o termina una sessione. Il tuo hook viene eseguito prima che Claude Code agisca, quindi può osservare l’evento, riscriverlo o rispondere al posto di Claude Code. Registri un hook con on(eventName, handler). Crea il tuo primo mod prima di iniziare da qui. Per ogni evento e i relativi campi esatti, consulta il riferimento oppure leggi i tipi per la tua build.

Come un hook gestisce un evento

Un hook si colloca tra un evento e ciò che Claude Code farebbe in risposta, quindi può osservare l’evento, riscriverlo o rispondere direttamente. Riceve tre argomenti: l’API dei mod come $, l’evento come e e il gestore successivo come next. I gestori di un evento formano una catena middleware. next(e) chiama il gestore successivo, che è l’hook di un altro mod oppure, alla fine della catena, il comportamento nativo di Claude Code, e si risolve nel risultato. Ciò che il tuo hook fa con next determina quale delle tre azioni compie.

Osservare un evento

Per osservare un evento senza modificarlo, esegui il tuo lavoro e restituisci next(e). Questo hook registra nel log ogni strumento che Claude sta per usare:
Prima dell’esecuzione di ogni strumento, nella trascrizione compare una riga attenuata come ● my-mod: Claude is about to use Bash, dove my-mod è il nome del tuo plugin. Lo strumento viene eseguito come farebbe senza il mod. Per agire dopo l’evento, esegui await next(e), svolgi il tuo lavoro e restituisci il risultato. Questo hook registra nel log ogni strumento dopo la sua esecuzione:
Ora la riga compare dopo il termine di ogni strumento. Claude legge lo stesso risultato in entrambi i casi, perché l’hook restituisce ciò in cui si è risolto next(e).

Riscrivere un evento

Per cambiare ciò su cui Claude Code agisce, come il testo di un prompt, chiama next con una copia modificata dell’evento. L’evento stesso è immutabile: è congelato in profondità e l’assegnazione a un campo genera un’eccezione. Questo hook rimuove gli spazi iniziali e finali da ogni prompt prima che venga inviato:
I gestori successivi e Claude Code ricevono il prompt ripulito e non vedono mai l’originale. Puoi anche modificare il risultato: esegui await next(e), poi restituisci una copia del risultato con un campo sostituito.

Rispondere a un evento

Per gestire tu stesso un evento, restituisci un risultato senza chiamare next. In questo modo interrompi la catena, quindi i mod successivi e il comportamento nativo di Claude Code non vengono eseguiti. Questo hook rifiuta ogni comando Bash:
Quando Claude prova un comando Bash, il comando non viene eseguito e Claude legge il testo di deny come risultato dello strumento. Ogni evento ha una propria forma del risultato, elencata nel riferimento degli eventi.

Filtrare gli eventi gestiti da un hook

Per eseguire un hook solo per alcuni eventi, passa un filtro come secondo argomento a on. Claude Code chiama questo filtro matcher. È un oggetto i cui campi vengono confrontati con quelli dell’evento, e l’hook viene eseguito solo quando tutti i campi corrispondono. Un campo può essere un valore, un array di valori consentiti o un’espressione regolare. Ogni riga di questo esempio registra la stessa funzione, hook, per un insieme più ristretto di chiamate agli strumenti:
hook viene eseguita una volta per una chiamata a Bash, Edit o Write, e una volta per una chiamata a uno strumento il cui nome inizia con mcp__github__. Una chiamata a qualsiasi altro strumento, come Read, non corrisponde a nessuno dei tre, quindi hook non viene eseguita. Il nome dell’evento può essere un carattere jolly. 'classic.*' corrisponde a ogni evento degli hook delle impostazioni. '*' corrisponde a ogni evento tranne gli eventi di telemetria, che richiedono il proprio nome e un filtro { to: 'collector' }. Registra ogni evento una sola volta per matcher. Se chiami on due volte per session.start senza matcher, il caricamento del modulo fallisce con on("session.start") is registered twice without a matcher. Inserisci tutto ciò che il tuo mod fa all’avvio della sessione in un unico hook.

Agganciare i disegni e i controlli di altri mod

Per agganciare i controlli, i pannelli o la riga sopra il prompt di un altro mod, passa un matcher con plugin. Usa il nome del mod senza il suo marketplace, come in { plugin: 'other-mod' }, oppure { plugin: '*' } per tutti i mod. Senza plugin, un hook su ui.press, ui.input, ui.select o ui.focus non viene eseguito per i controlli di altri mod, e un hook ui.render salta i loro pannelli e le loro righe sopra il prompt. Un hook su un carattere jolly senza matcher, come on('*', hook) o on('ui.*', hook), viene comunque eseguito per tutti i mod. Un carattere jolly con un matcher richiede anch’esso plugin.
{ plugin: '*' } richiede Claude Code v2.1.323 o versioni successive. Prima della v2.1.323, un hook senza plugin veniva eseguito per tutti i mod, e un hook con { plugin: '*' } non veniva eseguito. Per far corrispondere tutti i mod in entrambe le versioni, usa { plugin: /./ } su ui.press, ui.input e ui.select. Per ui.focus e ui.render, usa on('ui.*', hook) e controlla il nome dell’evento in next.event, come in if (next.event !== 'ui.focus') return next(e).

Agganciarsi a ciò che Claude sta facendo

Gestisci questi eventi per vedere o modificare una chiamata a uno strumento, un prompt, un turno o una lettura delle impostazioni mentre avviene. Per ogni evento e per ciò che un hook può restituire, consulta il riferimento degli eventi.

Proteggere o modificare una chiamata a uno strumento

Un hook tool.call vede ogni strumento che Claude sta per usare, quindi può rifiutare la chiamata, modificarne gli argomenti o lasciarla passare. tool.call si attiva quando Claude Code sta per eseguire uno strumento, incluse le chiamate effettuate da un subagent e le chiamate agli strumenti MCP. e.tool è il nome dello strumento e gli argomenti dello strumento sono campi di e, come e.command per Bash. Quando chiami next(e), Claude Code esegue il controllo dei permessi e poi lo strumento. Questo hook rifiuta un comando Bash che esegue un force push e spiega a Claude il motivo:
Quando Claude prova git push --force, il comando non viene eseguito e non compare alcuna richiesta di permesso, perché l’hook non chiama mai next. Claude legge il testo di deny come risultato dello strumento, quindi scrivilo come un’istruzione su cui Claude possa agire. Ogni altro comando Bash viene eseguito come farebbe senza il mod. Se questo hook genera un’eccezione o va in timeout, Claude Code lo salta e il comando procede come farebbe senza il mod. Per rifiutare invece il comando, aggiungi un handler .catch all’hook. Per agire dopo che uno strumento è stato eseguito, usa await next(e), svolgi il tuo lavoro e restituisci ciò che next ti ha dato. Questo hook registra ogni file .mdx che Claude modifica, con $.ui.log, che aggiunge alla trascrizione una riga attenuata che Claude non legge:
Dopo che Claude modifica o scrive un file .mdx, una riga attenuata nella trascrizione indica il nome del file. Non viene registrato nulla per un altro tipo di file, né per una chiamata rifiutata o non riuscita. La visione che Claude ha della chiamata non cambia, perché l’hook restituisce il risultato che ha ricevuto. Il tuo hook può anche modificare una chiamata, riprovarla, rispondervi tu stesso o nasconderne il risultato:
  • Modificare la chiamata: passa argomenti modificati a next.
  • Riprovare la chiamata: chiama di nuovo next(e). Un hook che vede isError nel primo risultato può eseguire lo strumento una seconda volta e restituire quel risultato.
  • Rispondere tu stesso alla chiamata: restituisci un oggetto con un campo result, senza chiamare next, e per uno strumento integrato dai a result la forma che ha il risultato di quello strumento nei tipi per la tua build. Non compare alcuna richiesta di permesso e lo strumento non viene eseguito, quindi il risultato che restituisci è tutto ciò che Claude sa di quanto è accaduto.
  • Nascondere il risultato a Claude: restituisci { deny: reason } dopo await next(e). Claude legge il tuo motivo al posto di ciò che next ha restituito. Quando lo strumento è stato eseguito, il deny impedisce a Claude di vederne il risultato e non annulla nulla di ciò che lo strumento ha fatto. Quando lo strumento è stato eseguito con successo, il motivo segue una nota come Bash ran, and a plugin withheld its result:.
Gli hook nelle impostazioni gestite della tua organizzazione vengono eseguiti prima dell’hook tool.call di qualsiasi mod. Quando un hook gestito blocca la chiamata, nessun hook tool.call di alcun mod viene eseguito per quella chiamata.

Trattenere una chiamata a uno strumento finché l’utente non decide

Un hook può mettere in pausa una chiamata a uno strumento e chiedere all’utente cosa fare prima che proceda. Un hook tool.call può usare await prima di chiamare next o di restituire un valore, e la chiamata allo strumento resta in sospeso fino ad allora. Per porre la domanda all’utente, chiama $.ui.ask. Mostra la tua domanda sopra un elenco numerato delle tue opzioni, nella finestra di dialogo che Claude usa per chiederti qualcosa, e si risolve nell’etichetta scelta dall’utente. Dopo le tue opzioni, la finestra di dialogo aggiunge una riga per digitare una risposta diversa e una riga Chat about this. Il pattern RISKY in questo esempio corrisponde a rm -r, rm -rf, git reset --hard e git push con --force, e non coglie altre forme come git push -f. Questo modulo chiede conferma prima di eseguire un comando Bash che corrisponde al pattern:
Quando Claude prova un comando come rm -rf build, compare la domanda con il comando al suo interno, e il comando attende la risposta:
  • L’utente sceglie Run it: l’hook chiama next(e), e il consueto controllo dei permessi viene comunque eseguito dopo
  • L’utente sceglie Refuse: il comando non viene eseguito e Claude legge il testo di deny
  • L’utente digita una risposta: $.ui.ask si risolve nel testo digitato. L’hook lo confronta con Run it, quindi qualsiasi altro testo rifiuta il comando.
  • Nessuno risponde: $.ui.ask viene rifiutata quando l’utente chiude la domanda o sceglie Chat about this, e in un’esecuzione claude -p, quindi il blocco catch lascia la risposta a Refuse
Mantieni l’attesa all’interno di una chiamata all’API dei mod come $.ui.ask, perché quel tempo non viene conteggiato nel limite di tempo dell’hook. Il tempo trascorso in attesa di una tua promise invece viene conteggiato. Claude Code salta un hook che va in timeout, quindi il comando trattenuto verrebbe eseguito. Per rifiutarlo invece, concatena un handler .catch alla registrazione restituita da on. Quell’handler è separato dal blocco catch all’interno dell’hook.

Approvare o rifiutare una chiamata a uno strumento prima che venga chiesto all’utente

Per decidere se una chiamata a uno strumento può essere eseguita, gestisci tool.check, l’evento in cui Claude Code prende questa decisione. Per un comando o un percorso fisso, usa una regola di permesso come Bash(npm test), che non richiede codice. Gestisci tool.check quando la decisione dipende da ciò che è vero in quel momento, come il branch Git corrente o un valore registrato da un altro hook.
  • Cosa restituire: per decidere tu stesso la chiamata, restituisci un oggetto tuo, come { decision: 'allow' } o { decision: 'deny', reason }. Per lasciare invariata la decisione, restituisci ciò che ti dà await next(e).
  • Cosa ti dà await next(e): la decisione di Claude Code stesso, come oggetto il cui decision è allow, ask o deny. Non compare alcuna richiesta di permesso mentre next(e) è in esecuzione.
  • Argomenti: e.input contiene gli argomenti dello strumento, come command per Bash
  • Quando si attiva tool.check: dopo l’esecuzione degli hook PreToolUse, e prima della richiesta di permesso, del classificatore della modalità auto o di un hook PermissionRequest
Questo hook rifiuta git push mentre il branch corrente è main:
L’hook rifiuta git push su main e lascia passare ogni altra chiamata:
  • Su main: l’hook restituisce deny, anche quando una regola consente git push
  • Su un altro branch, e per altri comandi: la chiamata riceve la decisione che riceverebbe senza il mod
  • L’hook genera un’eccezione o va in timeout: anche in questo caso la chiamata riceve la decisione che riceverebbe senza il mod. Per rifiutare invece la chiamata, aggiungi un handler .catch che restituisca { decision: 'deny', reason: 'the reason' }.
L’hook confronta il testo del comando, quindi consideralo un promemoria per Claude. Per bloccare i push su main per tutti, proteggi il branch sul tuo host Git.
Un hook tool.check può anche restituire allow o ask. In plan mode, per una chiamata che non è di sola lettura, come la modifica di un file, il tuo hook può rendere più restrittiva la decisione restituita da next(e) ma non può allentarla. Per le regole di permesso e le decisioni degli hook PreToolUse che l’allow del tuo hook non può sostituire, consulta Estendere i permessi con gli hook.

Verificare se una chiamata a uno strumento è di sola lettura

In un hook tool.check, e.isReadOnly è true quando lo strumento segnala la chiamata come di sola lettura. Altrimenti il campo è assente, non false. e.isReadOnly richiede Claude Code v2.1.304 o successivo. Alcuni strumenti, come Read, Grep, Glob e WebSearch, segnalano ogni chiamata come di sola lettura. Bash e gli strumenti MCP segnalano una chiamata come di sola lettura in questi casi: Il valore è ciò che segnala lo strumento stesso, quindi non approvare una chiamata basandoti solo su questo campo. Ad esempio, le chiamate WebFetch e Agent vengono segnalate come di sola lettura, anche se WebFetch richiede un URL e Agent avvia un subagent che esegue strumenti propri. Questo hook restituisce un ask per ogni chiamata mcp__github__ che non è di sola lettura e non è già stata rifiutata:

Filtrare un hook tool.check in base al fatto che la chiamata sia di sola lettura

Per limitare le chiamate gestite dal tuo hook in base a e.isReadOnly, usa il matcher per le chiamate di sola lettura e il corpo dell’hook per le altre:
  • Solo chiamate di sola lettura: aggiungi isReadOnly: true al matcher, come in on('tool.check', { tool: 'Bash', isReadOnly: true }, hook)
  • Chiamate che non sono di sola lettura: verifica e.isReadOnly nel corpo dell’hook, come fa l’esempio mcp__github__. Se metti isReadOnly: false in un matcher, il tuo hook non viene mai eseguito.

Riscrivere o integrare un prompt

Un hook prompt.submit vede ogni prompt prima che inizi il turno, quindi può riscriverne il testo o aggiungervi qualcosa. e.text è ciò che è stato digitato. Questo hook aggiunge per Claude il nome del branch corrente ogni volta che un prompt menziona una pull request:
Quando invii un prompt come open a PR for this change, il tuo messaggio appare invariato nella trascrizione, e Claude legge anche una riga come Current branch: feature/auth dopo di esso. Un prompt che non menziona una pull request passa invariato, e git non viene eseguito. Per bloccare un prompt, restituisci { drop: 'the reason' } senza chiamare next. Il testo torna nel campo di input del prompt dell’utente, che vede Prompt dropped by a hook: seguito dal tuo motivo, quindi rivolgi il motivo all’utente. Il prompt passa comunque in questi casi:
  • Il tuo hook restituisce un drop dopo che la sua chiamata a next(e) ha lasciato passare il prompt: il turno viene comunque eseguito e l’hook non riesce con un messaggio che include a drop after its next() was answered
  • Il tuo hook genera un’eccezione o va in timeout: Claude Code lo salta e invia il prompt. Aggiungi un handler .catch in modo che un errore non invii un prompt che l’hook avrebbe bloccato.
Altri eventi coprono il resto di ciò che Claude legge: prompt.section per ogni sezione del prompt di sistema, prompt.context per il contesto inviato con il primo messaggio e skill.prompt per il testo di una skill. Per modificare una sezione dopo l’inizio di una conversazione, consulta Inviare una sezione del prompt di sistema o una descrizione di uno strumento modificata. In un hook skill.prompt puoi anche leggere da quale plugin o file proviene la skill.

Seguire un turno

Un turno è tutto ciò che Claude fa in risposta a un prompt. Gestisci turn.start, turn.step e turn.complete per seguirne uno: Scrivi un hook turn.step come generatore asincrono, perché l’evento è in streaming. yield* next(e) inoltra la risposta mentre arriva in streaming e restituisce il risultato finale. Questo hook registra quanto di ogni richiesta la Claude API ha servito dalla cache dei prompt:
La risposta di Claude viene mostrata sullo schermo in streaming come accade senza il mod. Al termine di ogni richiesta, una riga attenuata nella trascrizione indica il numero di token letti dalla cache e il numero di quelli scritti in essa. Un turno con chiamate agli strumenti ha diverse richieste, quindi aggiunge diverse righe. result.usage contiene i conteggi di token che la Claude API riporta per una richiesta, più il model che ha risposto: input_tokens, output_tokens, cache_read_input_tokens e cache_creation_input_tokens. L’hook viene eseguito anche per le richieste dei subagent, quindi controlla e.agentId quando vuoi solo la conversazione principale. Per vedere le chiamate agli strumenti che l’API ha eseguito autonomamente durante la richiesta, come le chiamate allo strumento advisor, leggi result.serverToolUses. Claude Code non esegue queste chiamate, quindi nessun hook tool.call o tool.check si attiva per esse. Il campo è assente quando la risposta non contiene chiamate di questo tipo e richiede Claude Code v2.1.290 o successivo.

Inviare una richiesta a un modello diverso

Se una richiesta turn.step non riesce con un errore del modello quando model è un alias come haiku, aggiorna a Claude Code v2.1.309 o successivo, oppure usa un id di modello completo. Prima della v2.1.309, un alias veniva inviato così come scritto. Per inviare una richiesta a un modello diverso, passa a next l’evento con model modificato, come in yield* next({ ...e, model: 'haiku' }).

Modificare o rifiutare una lettura delle impostazioni

Usa un hook settings.read per modificare o rifiutare una lettura delle impostazioni, sia quella di un mod sia quella di Claude Code stesso:
  • La lettura di un mod: un mod chiama $.settings.read.
  • La lettura di Claude Code stesso: il tuo hook viene eseguito per la prima volta quando Claude Code unisce le impostazioni della sessione, dopo che i mod della sessione sono stati caricati. Il tuo hook viene eseguito di nuovo quando cambiano le impostazioni o i plugin caricati.
Verifica quali mod ricevono questo evento e la tua versione di Claude Code:
  • La protezione integrata: dove viene caricata la protezione integrata, questa può saltare questo hook in un mod che installi o carichi con --plugin-dir. Per verificarlo, cerca nel log di debug settings.read bypassed by cc-plugin-sec-default. Se una riga con quel testo nomina il tuo mod, chiedi all’amministratore della tua organizzazione di installare il mod come uno dei mod dell’organizzazione.
  • La versione: l’attivazione dell’evento sulla lettura di Claude Code stesso, e il campo e.layers, richiedono Claude Code v2.1.304 o successivo.

Cosa riceve un hook settings.read

In e.layers, plugin contiene le impostazioni fornite dai plugin abilitati ed è solo il nome di un livello, non una source che puoi passare a $.settings.read. flag contiene le impostazioni passate con --settings, e policy contiene le impostazioni gestite.

Distinguere la lettura di Claude Code stesso dalla lettura di un mod

Controlla next.origin:
  • La lettura di Claude Code stesso: { plugin: 'engine', tier: 'core' }
  • La lettura di un mod: plugin è il nome del mod chiamante

Cosa può restituire un hook settings.read

Restituisci invariato il risultato di next(e) per lasciare la lettura così com’è, oppure restituisci uno di questi: Nella lettura di Claude Code stesso, costruisci il tuo { value } a partire dal value di next(e), poiché una chiave che ometti risulta non impostata. Quando Claude Code legge una chiave come env da ciascuna origine separatamente, modificarla nel tuo value non ha effetto. next(e) si risolve in { value } o in { deny }:
  • { value }: value sono le impostazioni unite, oppure le impostazioni di una sola origine quando e.source è impostato. Se un hook che viene eseguito dopo il tuo ha restituito un { value } proprio, ricevi invece il value di quell’hook.
  • { deny }: un hook eseguito dopo il tuo ha rifiutato la lettura. Restituisci quel { deny } invariato.

Modificare un’impostazione da un hook settings.read

Verifica prima quali mod ricevono questo evento e da quale versione. Per modificare una chiave, espandi il value di next(e) e imposta quella chiave, come fa questo hook con spinnerTipsEnabled. L’hook non controlla next.origin, quindi modifica la chiave sia nella lettura di Claude Code stesso sia nella lettura unita di un mod:
Nella lettura di Claude Code stesso, se il tuo hook restituisce un valore al di fuori dello schema della chiave, come una stringa, solo quella chiave mantiene il valore unito prima che qualsiasi hook rispondesse. Il log di debug riporta quindi the answer for <key> is no value the key can hold. Se il tuo valore è valido e la chiave comunque non cambia, consulta perché una chiave non ha effetto.

Gestire gli eventi degli hook delle impostazioni

Gli hook delle impostazioni sono gli hook di comando, HTTP, prompt e agente che configuri nei file di impostazioni. Ogni evento degli hook delle impostazioni, come Stop, SessionEnd o PostToolUse, è anche un evento denominato classic. seguito dal nome dell’evento dell’hook delle impostazioni, come classic.Stop. e è il JSON che un hook delle impostazioni riceve su stdin, incluso transcript_path. Dove viene caricata la protezione integrata, un hook su questi eventi in un mod che installi non viene eseguito. Questo hook usa Stop, che si attiva quando Claude termina di rispondere, per registrare dove viene salvata la trascrizione della sessione:
Ogni volta che Claude termina di rispondere, una riga attenuata nella trascrizione indica il percorso del file della trascrizione. L’hook restituisce next(e), quindi osserva l’evento e non modifica nulla del modo in cui termina il turno.

Eseguire insieme ad altri mod

Più mod possono gestire lo stesso evento e ognuno di essi può fallire. Se il tuo mod blocca le chiamate agli strumenti, controlla la sua posizione nella catena e cosa succede quando il suo hook fallisce.

L’ordine in cui vengono eseguiti i mod

Gli hook sullo stesso evento formano un’unica catena middleware. Il next di ciascun mod chiama l’hook del mod successivo, e l’ultimo next raggiunge il comportamento proprio di Claude Code. Il primo mod è il più esterno: vede l’evento prima degli altri e il risultato dopo di loro, e decide se gli altri vengono eseguiti o meno. Un mod successivo non può impedire a uno precedente di vedere un evento. Claude Code ordina la catena in base alla provenienza di ciascun mod:
  1. La protezione integrata sec-default@builtin, un mod integrato in Claude Code che /plugin elenca come cc-plugin-sec-default, dove viene caricata, i mod che la tua organizzazione elenca in prependPlugins, e poi qualsiasi altro mod che conta come della tua organizzazione e non è in appendPlugins
  2. I mod che installi tu
  3. I mod che la tua organizzazione elenca in appendPlugins
  4. Gli altri mod integrati in Claude Code
Tra i mod che installi, un mod viene eseguito prima dei mod che elenca sotto dependencies nel suo manifest. All’interno di un modulo, gli hook vengono eseguiti nell’ordine in cui register ha chiamato on.

Dove vengono eseguiti gli hook delle impostazioni nell’ordine

Anche gli hook PreToolUse configurati nei file di impostazioni vengono eseguiti durante una chiamata a uno strumento, in punti fissi della catena di mod:
  • Hook PreToolUse dalle impostazioni gestite: vengono eseguiti prima dell’hook tool.call del primo mod. Quando un hook gestito blocca la chiamata, nessun hook tool.call di alcun mod viene eseguito per quella chiamata.
  • Hook PreToolUse da ogni altro file di impostazioni e da hooks/hooks.json dei plugin: vengono eseguiti dopo che l’ultimo mod ha chiamato next, come parte del comportamento proprio di Claude Code. Un mod che risponde a tool.call senza chiamare next ne impedisce l’esecuzione, e un mod che chiama next vede la loro decisione nel risultato che restituisce.
tool.check si attiva dopo che gli hook PreToolUse sono stati eseguiti. Per le regole di permesso e le decisioni degli hook PreToolUse che l’allow di un hook tool.check non può sostituire, consulta Estendere i permessi con gli hook.

Gestire un hook che fallisce

Un hook che fallisce non interrompe la sessione, e puoi decidere cosa succede al suo posto. Quando un hook senza un gestore .catch genera un’eccezione, va in timeout o restituisce un risultato con la forma sbagliata, ciò che succede dopo dipende dal fatto che abbia chiamato next:
  • È fallito prima di chiamare next: Claude Code lo salta, e il gestore successivo viene eseguito al suo posto
  • È fallito dopo che next è stato risolto: quel risultato rimane valido, e nulla viene eseguito una seconda volta
Una riga indica il mod, l’evento e il motivo, ad esempio my-mod: tool.call hook skipped: threw Error: boom. Dove la leggi dipende dalla sessione, come elencato in Scoprire perché un mod non fa nulla. Un hook ui.render il cui albero non supera la validazione conta come un hook che ha restituito un risultato con la forma sbagliata. Per fare in modo che un hook che blocca le chiamate fallisca in modo chiuso, aggiungi un gestore di errori .catch che risponda al suo posto. Qui, guard è la tua funzione hook, e il gestore verifica next.called per capire se guard aveva già chiamato next quando è fallito:
Quando guard genera un’eccezione o va in timeout su una chiamata Bash, Claude Code chiama il gestore con lo stesso evento:
  • guard è fallito prima di chiamare next: il comando non viene eseguito, e Claude legge il testo di deny con il tipo alla fine
  • guard è fallito dopo aver chiamato next: il next(e) del gestore si risolve nel risultato prodotto dalla chiamata di guard senza eseguire di nuovo il comando, e Claude legge quel risultato
Il gestore ha un proprio limite di tempo più breve. Se il gestore stesso genera un’eccezione o va in timeout, Claude Code salta l’hook come se non avesse alcun gestore. Se guard non aveva chiamato next, il comando prosegue quindi come farebbe senza il mod. La stessa forma del gestore si adatta a una protezione su prompt.submit o config.set. Quando next.called è false, restituisci il rifiuto che il riferimento degli eventi elenca per quell’evento: { drop: 'the reason' } per prompt.submit, { deny: 'the reason' } per config.set. Su tool.check e plugin.register, un rifiuto restituito dopo che next è stato risolto rimane comunque valido, quindi restituiscilo senza verificare next.called: Su tool.call, un deny restituito dopo che next è stato risolto nasconde il risultato a Claude.

Passaggi successivi