Il riferimento completo sono le dichiarazioni TypeScript per i mod di Claude Code, che descrivono ogni evento, metodo ed elemento, con esempi. La copia su GitHub può essere più vecchia della versione di Claude Code che hai installato. Quando le due non coincidono, fai affidamento sulla copia che Claude Code scrive per la tua versione.
File
Un mod è una directory di plugin con questi file:register riceve on e options. options contiene i valori dei campi userConfig dichiarati dal manifest, con i valori predefiniti compilati.
La funzione hook
Un mod registra ciascuno dei suoi hook, che sono gestori di eventi, chiamandoon all’interno di register. on accetta il nome dell’evento, un matcher facoltativo, che è un filtro sui campi dell’evento, e l’hook, come in on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e)). on restituisce una registrazione con un solo metodo, .catch(handler), che imposta il gestore degli errori dell’hook.
Eventi
Gli eventi sono raggruppati in base a ciò che riguardano, ciascuno con il momento in cui si attiva e ciò che un hook su di esso può restituire. Gli hook suturn.step e process.spawn sono generatori asincroni, mentre gli altri hook sono funzioni asincrone.
L’ultima colonna di ogni tabella usa una notazione abbreviata. next(e) passa l’evento senza modificarlo. next({ ...e, text }) passa una copia con il campo indicato modificato, come in next({ ...e, text: e.text.trim() }). Un oggetto risponde all’evento senza chiamare next, e una parola come reason indica una stringa che scrivi tu, come in { deny: 'Use the file tools.' }.
Strumenti
Gli eventi degli strumenti si attivano attorno a ogni chiamata a uno strumento effettuata da Claude, dalla descrizione che Claude legge fino alla decisione se la chiamata viene eseguita:Campi dell’agente e dell’organizzazione su tool.check
In un hook tool.check, leggi questi campi per distinguere la chiamata di un subagent da quella della conversazione principale e per verificare se la tua organizzazione richiede l’approvazione per uno strumento di un connettore:
e.agentId: impostato quando la chiamata viene effettuata da un subagent o da un membro del team in-process, e assente quando la effettua la conversazione principalee.ceiling:askper uno strumento di un connettore che la tua organizzazione ha impostato suask, nelle sessioni in cui tale impostazione raggiunge Claude Code
tool.check, e.agentId e e.ceiling richiedono Claude Code v2.1.290 o versioni successive.
Il campo e.isReadOnly su tool.check
In un hook tool.check, e.isReadOnly è true quando lo strumento segnala questa chiamata come di sola lettura. Altrimenti il campo è assente, non false. Il valore è ciò che segnala lo strumento stesso, quindi leggi Verificare se una chiamata a uno strumento è di sola lettura prima di approvare una chiamata basandoti solo su questo campo.
Su tool.check, e.isReadOnly richiede Claude Code v2.1.304 o versioni successive.
Prompt e ciò che Claude legge
Gli eventi dei prompt riguardano il testo che l’utente digita e il testo che Claude Code invia a Claude di propria iniziativa, come il prompt di sistema e i promemoria:Campi di origine e frontmatter su skill.prompt
In un hook skill.prompt, puoi leggere questi campi insieme al nome della skill in e.skill e al testo che Claude legge in e.text:
Un hook può passare un
text o un frontmatter modificato a next: gli hook successivi leggono entrambi e Claude legge il text finale. Un hook che modifica qualsiasi altro campo non riesce.
Su skill.prompt, e.source, e.pluginName, e.path, e.frontmatter e e.frontmatterProblem richiedono Claude Code v2.1.299 o versioni successive.
Inviare una sezione del prompt di sistema o una descrizione di uno strumento modificata con breakPromptCache
Per modificare una sezione o la descrizione di uno strumento in una conversazione in corso, chiama $.ui.invalidate('prompt.section') o $.ui.invalidate('tool.describe') in modo che il tuo hook venga eseguito di nuovo. Restituisci da esso { text, breakPromptCache: true } oppure { description, breakPromptCache: true }. Senza il campo, Claude continua a leggere il testo salvato con la conversazione per una sezione o per uno strumento caricato subito, fino a una nuova conversazione o a una compattazione.
Il testo modificato raggiunge Claude al turno successivo e la cache del prompt riparte da zero, quindi quel turno è più lento e più costoso. Il campo richiede Claude Code v2.1.321 o versioni successive. Dalla v2.1.299 fino alla v2.1.321, una conversazione in corso riceveva il testo modificato al turno successivo.
Comandi e configurazione
e.layers e e.source su settings.read
e.layers: un oggetto{ source, settings }per ogni origine in uso che contiene impostazioni, a partire da quella con la precedenza più bassa. Consulta Cosa riceve un hooksettings.read.e.source: l’unica origine richiesta da un mod, come in$.settings.read({ source: 'policy' }). Assente nella lettura effettuata da Claude Code stesso e in una lettura delle impostazioni unite
Turni
Gli eventi dei turni seguono una risposta dall’inizio alla fine, inclusa ogni richiesta al modello al suo interno:Sessione
Gli eventi della sessione segnano l’avvio, la fine e la compattazione della sessione e lo scambio di messaggi con altre sessioni:Subagent
Gli eventi dei subagent si attivano quando un tipo di subagent viene offerto a Claude e quando un subagent o un membro di un team di agenti sta per avviarsi:
Il tuo hook
agent.spawn viene eseguito anche quando un subagent che ha terminato o è stato interrotto sta per essere eseguito di nuovo, ad esempio quando Claude gli invia un messaggio con lo strumento SendMessage. In quell’evento, e.resume è { agentId }. Se il tuo hook conta i subagent, salta gli eventi in cui e.resume è impostato, in modo che un subagent ripreso non venga conteggiato di nuovo.
Restituisci { deny: reason } per rifiutare un’esecuzione ripresa. L’esecuzione non si avvia e il subagent rimane com’era. Quando l’esecuzione è stata richiesta da una chiamata a SendMessage, Claude legge a plugin declined the resume: seguito dal tuo motivo come risultato di quella chiamata. Se passi un evento modificato a next per un’esecuzione ripresa, ad esempio un model diverso, Claude Code ignora la modifica.
L’evento per un’esecuzione ripresa richiede Claude Code v2.1.299 o versioni successive. Prima della v2.1.299, il tuo hook
agent.spawn non veniva eseguito quando un subagent veniva ripreso. In quelle versioni, per rifiutare le chiamate a SendMessage che riprendono un subagent, individua quello strumento in un hook tool.call.Interfaccia
Gli eventi dell’interfaccia si attivano quando Claude Code disegna un punto di rendering e quando l’utente usa un controllo disegnato da un mod. Disegnare nell’interfaccia mostra cosa restituisce un hookui.render:
Altri mod
Questi eventi consentono a un mod di agire sugli altri mod mentre vengono caricati, per rifiutarne uno o modificare l’API dei mod che riceve:
Quando l’hook di un altro mod chiama un metodo su un namespace che hai aggiunto in
engine.create, le chiamate $ del tuo metodo vengono eseguite nel contesto di quell’hook finché ogni hook su quell’evento non ha restituito un risultato. Ad esempio, un percorso relativo viene risolto rispetto alla directory di lavoro di quell’hook, e $.prompt.submit viene rifiutata mentre il turno è in attesa di quell’hook. Le chiamate che il tuo metodo effettua dopo quel momento vengono eseguite nel contesto proprio del tuo mod.
Telemetria
Gli eventi di telemetria si attivano per i record di utilizzo che Claude Code registra nei log:Eventi degli hook delle impostazioni
Ogni evento degli hook delle impostazioni è un evento denominatoclassic.<Event>, come classic.Stop o classic.PostToolUse. e è il JSON dello stdin dell’hook.
Chiamate all’API dei mod
Ogni metodo dell’API dei mod è anche un evento, denominato in base al suo namespace e al metodo, comefs.read, model.complete o ui.open. Un hook su uno di essi può restituire next(e), { deny: reason } oppure { value }.
Alcuni di questi eventi si attivano anche per le azioni di Claude Code stesso, quindi verifica se next.origin.plugin è engine prima di rifiutarne uno.
Campi sulle richieste http.fetch di Claude Code stesso
In un hook http.fetch, un next.origin pari a { plugin: 'engine', tier: 'core' } contrassegna una delle richieste di Claude Code stesso, come una richiesta al modello, e non una chiamata $.http.fetch di un mod. Dove è caricata la protezione integrata, il tuo hook non riceve questi eventi a meno che il tuo mod non sia considerato un mod della tua organizzazione.
In questi eventi, e.init e il value in cui si risolve next(e) possono contenere, tra gli altri, questi campi:
Questi eventi e campi richiedono Claude Code v2.1.321 o versioni successive.
Metodi dell’API dei mod
L’API dei mod è l’argomento$ che ogni hook riceve. I suoi metodi sono raggruppati in namespace, come $.ui. Questa tabella elenca i metodi di ogni namespace per nome, quindi open nella riga $.ui corrisponde alla chiamata $.ui.open(...). Le guide mostrano l’uso di quelli più comuni, e i tipi per la tua build documentano ogni metodo con un esempio.
Punti di rendering
Un punto di rendering è un punto di estensione nell’interfaccia di Claude Code. Ogni riga è un valore die.component in un hook ui.render, con i campi di e.props e le app che lo visualizzano. e.surface indica l’app che sta disegnando, come terminal, desktop o vscode. Modificare ciò che Claude Code disegna già mostra cosa può fare un hook in un punto, con un esempio per ciascuna scelta.
Il rendering nell’estensione VS Code richiede la versione 2.1.299 o successiva dell’estensione. Una sessione che non recupera i feature flag richiede la versione 2.1.304 o successiva. Disegnare nell’estensione VS Code elenca ciò che l’estensione disegna in modo diverso.
e.viewport contiene columns, rows e isFullscreen. Nel terminale e nell’app Desktop, è assente finché l’app non ha misurato la propria finestra. Lì, il suo rows è l’altezza dell’intera finestra, non del tuo pannello. Nell’estensione VS Code, è sempre presente.
Per adattare un albero al suo punto, leggi queste prop nell’hook:
- Larghezza di un
Paneo della fascia: disegna fino ae.props.bodyColumns - Altezza di un
Paneaccanto alla trascrizione: quandoe.props.placementè'dock',e.props.scroll.bodyRowsè il numero di righe di cui dispone il pannello per il tuo albero - Altezza di un
Panesopra il prompt: quandoe.props.placementè'inline', il pannello cresce insieme al tuo albero fino a un limite, ebodyRowsè quel limite. Per richiedere un limite diverso, consulta il camporowsdi$.ui.open.
Elementi
Gli elementi sono i componenti di base di un albero restituito da un hookui.render, e li ottieni da $.ui.resolve(e). Crea un albero a partire dagli elementi mostra quelli più comuni insieme a come il terminale li disegna, e la galleria dell’interfaccia contiene screenshot della maggior parte di essi. Un segno di spunta indica che l’app può disegnare l’elemento.
Altre regole per
Button:
action: indica una delle scorciatoie da tastiera di Claude Code, e la combinazione assegnata dall’utente a quell’azione preme il pulsante quando si tratta di un accordo o di un tasto con modificatore- Hotkey numerici nella banda: un
hotkeynumerico su un pulsante nella banda si attiva anche quando l’utente digita solo quella cifra in un prompt vuoto e si ferma - Una banda compressa: mentre la banda è compressa, né una combinazione
actionné un hotkey premono un pulsante al suo interno - Due pulsanti sullo stesso hotkey: quando due dei tuoi pulsanti nello stesso disegno indicano lo stesso
hotkey, lo ottiene quello successivo. Per il pulsante di un altro mod sullo stesso tasto, consulta Gli hotkey non fanno nulla. variant:primaryosecondary, e qualsiasi altro valore genera un’eccezione. Nel terminale, un pulsanteprimaryviene disegnato nel colore di accento, a meno che non siaplain.role:dismisscontrassegna un pulsante di chiusura, e qualsiasi altro valore genera un’eccezione. Esegui la chiusura nel tuoonPress. In una banda che contiene testo e una riga di pulsanti, l’app Desktop può disegnare il primo pulsantedismissdella riga come un proprio controllo di chiusura. Il terminale disegna il pulsante come farebbe senzarole.
Button può contenere children al posto di una label:
- Cosa possono essere i children: stringhe ed elementi
Text, come un nome seguito da un dettaglio attenuato o da un chip colorato. Claude Code rifiuta qualsiasi altro elemento all’interno di unButton. - Assegnare un nome al pulsante: la
labelassegna il nome al pulsante e, per impostazione predefinita, corrisponde al testo dei suoi children. Assegna unakeyo unalabela un pulsante con children diversi da una singola stringa. - Nel terminale: i children vengono disegnati dove si troverebbe la label, e una pressione in qualsiasi punto su di essi conta come una sola pressione, quindi puoi trasformare ogni riga di un elenco in un singolo pulsante
- Nell’app Desktop e nell’estensione VS Code: il pulsante disegna la sua
label
Un
Button con children diversi da una singola stringa richiede Claude Code v2.1.295 o successivo.autoFocus accetta solo true su qualsiasi controllo, quindi ometti la prop per lasciarlo disattivato.
L’estensione VS Code ignora alcune prop degli elementi e disegna l’elemento come se le avessi omesse:
Box:positioncon i relativitop,left,rightebottom,alignSelf,borderDimColorehoverText:size,mono,tabularehoverButton:hotkey,plain,autoFocus,actionehover, quindi lì l’utente preme un pulsante con un clic, oppure con Invio quando ha il focus. L’estensione ignora anchevarianterole.Code:language,path,startLine,formatewrap, quindi il codice viene disegnato senza colori né numeri di riga, e un bloccoformat: 'diff'mostra il testo grezzo del diffInputeSelect:autoFocus, erowssu unInputSvg:isInteractive
Stili del bordo di Box
Per disegnare un bordo attorno a un Box, imposta la sua borderStyle su uno di questi nomi, come in borderStyle: 'round'. Ogni riga indica cosa disegna il terminale per quel nome e mostra il bordo superiore.
Un
Box la cui borderStyle indica qualsiasi altro nome, come 'rounded', viene disegnato senza bordo.
Passi di spaziatura di Box
Le prop di spaziatura di Box sono gap, columnGap, rowGap, padding, margin e le forme di padding e margin per un solo lato o un solo asse, come paddingX e marginTop. Ognuna accetta un numero di celle del terminale, come gap: 1, oppure il nome di un passo, come gap: 'md'. Nel terminale e nell’estensione VS Code, ogni passo corrisponde a questo numero di celle:
Se imposti
gap, padding o margin su un passo, il passo si applica contemporaneamente in orizzontale e in verticale. Ad esempio, nel terminale e nell’estensione VS Code, padding: 'md' corrisponde a due celle su ciascun lato e a una riga sopra e sotto.
I nomi dei passi richiedono Claude Code v2.1.299 o successivo. Su una release precedente, un albero che usa il nome di un passo non viene disegnato.
Prop tipografiche di Text
Imposta size, weight, mono o tabular su un Text per chiedere all’app che disegna il tuo albero una dimensione del testo, uno spessore, un carattere a spaziatura fissa o cifre di larghezza uguale. Prima di fare affidamento su una prop, verifica cosa ne fanno il terminale e l’estensione VS Code. Se un’app ignora una prop che hai impostato, il tuo albero viene comunque disegnato, con il testo come se avessi omesso quella prop.
Queste quattro prop richiedono Claude Code v2.1.299 o successivo. Su una release precedente, un albero che imposta
size, weight, mono o tabular non viene disegnato.
Sostituisci bold con weight
bold su un Text è deprecato in favore di weight e funziona ancora. Per sostituirlo su un Text senza weight, cambia bold: true in weight: 'semibold' per ottenere lo stesso risultato su Claude Code v2.1.299 o successivo.
Su una release precedente alla v2.1.299, un albero che imposta weight non viene disegnato. Se imposti sia bold sia weight su un Text, bold non ha alcun effetto.
Limiti
Gli hook e le chiamate all’API dei mod sono soggetti a limiti di tempo e di dimensione. Claude Code salta un hook che supera un limite di tempo. Un albero che supera il limite di annidamento, di elementi, di celleRaster o di byte di Image non viene disegnato.
Impostazioni e variabili d’ambiente
Queste sono le impostazioni e le variabili d’ambiente che influiscono sui mod. La colonna Dove indica da quale file di impostazioni o ambiente viene letta ciascuna:sec-default@builtin è una protezione integrata in Claude Code, elencata come cc-plugin-sec-default in /plugin e nel log di debug. Dove viene caricata, viene eseguita prima di ogni mod installato da una persona. Se è impostato prependPlugins nelle impostazioni gestite, la protezione viene caricata solo quando quell’elenco la nomina, nella posizione indicata.
Il suo codice sorgente si trova nella directory mods/sec-default del repository di Claude Code.
Comandi
Questi comandi e flag caricano, ispezionano e testano un mod. I comandiclaude vengono eseguiti nella tua shell e i comandi / nel prompt di Claude Code. Nella tabella, <directory> indica un percorso che digiti, come in claude plugin validate ./first-mod. Le parentesi quadre indicano un argomento facoltativo.