Reagire agli eventi con un mod

Gestisci gli eventi di Claude Code da un mod: osserva, riscrivi o rispondi a chiamate agli strumenti, prompt e turni, filtra quali eventi gestisce un hook e pianifica in vista di altri mod.

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:

on('tool.call', async ($, e, next) => {
  // Runs before the tool does
  $.ui.log('Claude is about to use ' + e.tool)
  // Pass the event on unchanged
  return next(e)
})

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:

on('tool.call', async ($, e, next) => {
  // Let the tool run, and wait for its result
  const result = await next(e)
  // Runs after the tool does
  $.ui.log(e.tool + ' finished')
  // Give the result back unchanged
  return result
})

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:

on('prompt.submit', async ($, e, next) => {
  // Pass on a copy of the event with its text changed
  return next({ ...e, text: e.text.trim() })
})

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:

on('tool.call', { tool: 'Bash' }, async () => {
  // No call to next, so the command never runs
  return { deny: 'Bash is turned off in this project. Use the file tools.' }
})

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:

// A string matches one value: Bash calls only
on('tool.call', { tool: 'Bash' }, hook)
// An array matches any value in it: Edit calls and Write calls
on('tool.call', { tool: ['Edit', 'Write'] }, hook)
// A regular expression matches by pattern: every tool of one MCP server
on('tool.call', { tool: /^mcp__github__/ }, hook)

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.

Agganciarsi a ciò che Claude sta facendo

Gestisci questi eventi per vedere o modificare una chiamata a uno strumento, un prompt o un turno 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:

// The matcher limits the hook to Bash calls, so e.command is the shell command
on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
  if (/git push .*--force/.test(e.command)) {
    // Returning without calling next answers the event, so the command never runs
    return { deny: 'Force pushes are not allowed in this repository. Push to a new branch instead.' }
  }
  // Every other command goes on to the permission check and then to Bash
  return next(e)
})

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.

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:

on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
  // Wait for the permission check and the tool, and keep what they produced
  const result = await next(e)
  // A refused call comes back as { deny }, and a failed one has isError set
  const changed = !result.deny && !result.isError
  if (changed && e.file_path.endsWith('.mdx')) $.ui.log('Claude changed ' + e.file_path)
  // Return the result as it came, so Claude reads what the tool returned
  return result
})

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.

Per modificare una chiamata, passa argomenti modificati a next. Per riprovare una 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. Per rispondere tu stesso a una chiamata, restituisci un oggetto con un campo result, come { result: 'Skipped by my-mod' }, senza chiamare next. In questo caso 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.

Gli hook nelle impostazioni gestite della tua organizzazione vengono eseguiti prima dell'hook tool.call di qualsiasi mod, e un blocco da parte di uno di essi è definitivo.

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:

const RISKY = /\brm\s+-rf?\b|\bgit\s+reset\s+--hard\b|\bgit\s+push\b.*--force/

export function register(on) {
  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
    // Let every other command through without a question
    if (!RISKY.test(e.command)) return next(e)
    // Start from the safe answer, so a question nobody answers refuses the command
    let answer = 'Refuse'
    try {
      // The tool call waits here until the user picks one of the two labels
      answer = await $.ui.ask('Run this command? ' + e.command, ['Run it', 'Refuse'])
    } catch {
      // The user dismissed the question, or this is a claude -p run with nobody to ask
    }
    if (answer !== 'Run it') {
      // Answer without calling next, so the command doesn't run
      return { deny: 'The user declined this command. Ask before trying a different approach.' }
    }
    return next(e)
  })
}

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.

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. Si attiva dopo che le regole di permesso e gli hook delle impostazioni hanno deciso, e next(e) si risolve nella loro decisione: allow, ask o deny. Il tuo hook restituisce quella decisione o una diversa. e.input contiene gli argomenti dello strumento, come command per Bash.

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.

Questo hook rifiuta git push mentre il branch corrente è main:

on('tool.check', { tool: 'Bash' }, async ($, e, next) => {
  // What the permission rules and settings hooks decided: 'allow', 'ask', or 'deny'
  const decided = await next(e)
  if (!e.input.command.includes('git push')) return decided
  const branch = await $.process.run(['git', 'branch', '--show-current'])
  if (branch.stdout.trim() !== 'main') return decided
  return { decision: 'deny', reason: 'Push from a branch other than main' }
})

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 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 può restituire allow, ask o deny, quindi può anche approvare una chiamata bloccata da un hook PreToolUse al di fuori delle impostazioni gestite. Estendere i permessi con gli hook elenca quali decisioni prevalgono su un mod.

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:

on('prompt.submit', async ($, e, next) => {
  // Pass on a prompt that doesn't mention a pull request as it is
  if (!/\bPR\b|pull request/i.test(e.text)) return next(e)
  const git = await $.process.run(['git', 'branch', '--show-current'])
  // Outside a git repository the command fails, so there's no branch to add
  if (git.exitCode !== 0) return next(e)
  // Keep any context an earlier hook added, and add one more line for Claude
  return next({ ...e, context: [...(e.context ?? []), 'Current branch: ' + git.stdout.trim()] })
})

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. Se 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.

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. Il testo di questi hook che cambia tra una richiesta e l'altra invalida la cache dei prompt.

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:

// function* makes the hook a generator, which can pass the response on piece by piece
on('turn.step', async function* ($, e, next) {
  // Send the request, forward each piece as it arrives, and keep the finished result
  const result = yield* next(e)
  // Skip a result that reports no token counts
  if (result.usage) {
    $.ui.log('cache read ' + result.usage.cache_read_input_tokens + ' · wrote ' + result.usage.cache_creation_input_tokens)
  }
  // Return the result unchanged, so the turn continues as usual
  return result
})

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.

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.

Questo hook usa Stop, che si attiva quando Claude termina di rispondere, per registrare dove viene salvata la trascrizione della sessione:

on('classic.Stop', async ($, e, next) => {
  // e has the same fields a Stop hook in a settings file reads from stdin
  $.ui.log('Transcript saved at ' + e.transcript_path)
  // Pass the event on, so Stop hooks in your settings files still run
  return next(e)
})

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, e un blocco da parte di uno di essi è definitivo, quindi nessun mod vede la 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 quegli hook e le regole di permesso hanno deciso, quindi un hook su di esso può approvare una chiamata che un hook del secondo gruppo ha bloccato.

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 disegno non supera la validazione viene segnalato in modo diverso, come descritto in Costruire un albero a partire dagli elementi.

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:

// on returns a registration, and .catch attaches a handler to that one hook
on('tool.call', { tool: 'Bash' }, guard).catch(async ($, e, next) => {
  // guard had already called next, so return what came back
  if (next.called) return next(e)
  // next.error.kind says why the handler was asked, such as 'throw' or 'timeout'
  return { deny: 'The command guard failed, so this command was not run: ' + next.error.kind }
})

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:

• tool.check: restituisci { decision: 'deny', reason: 'the reason' }
• plugin.register: restituisci { refuse: 'the reason' }, come mostrato in Rifiutare i mod quando il tuo controllo fallisce

Passaggi successivi

• Usa l'API dei mod: aggiungi comandi e strumenti, chiama un modello ed esegui attività a intervalli regolari
• Disegna nell'interfaccia: mostra ciò che i tuoi hook raccolgono in un riquadro o sopra il prompt
• Testa un mod: attiva uno qualsiasi di questi eventi da un test
• Riferimento dei mod: ogni evento, ogni metodo dell'API dei mod e i limiti