Riferimento dei mod

Riferimento completo per i mod di Claude Code: struttura del modulo degli hook, eventi, metodi dell'API dei mod, punti di rendering, elementi per superficie, limiti e impostazioni.

Consulta qualsiasi evento che un mod può gestire, qualsiasi metodo dell'API dei mod che può chiamare o qualsiasi punto di rendering in cui può disegnare. Le voci coprono la CLI di Claude Code e l'app Desktop a partire dalla v2.1.290, e l'estensione VS Code a partire dalla v2.1.299. Ogni voce riporta il nome e una descrizione di una riga e, dove presente, rimanda alla sezione della guida che lo spiega.

[!NOTE]

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, chiamando on 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 su turn.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 principale
• e.ceiling: ask per uno strumento di un connettore che la tua organizzazione ha impostato su ask, nelle sessioni in cui tale impostazione raggiunge Claude Code

Su 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 hook settings.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.

[!NOTE]

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 hook ui.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 denominato classic.<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, come fs.read, model.complete o ui.open. Un hook su uno di essi intercetta le chiamate provenienti dai mod eseguiti dopo di esso e può restituire next(e), { deny: reason } oppure { value }.

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 di e.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 Pane o della fascia: disegna fino a e.props.bodyColumns
• Altezza di un Pane accanto alla trascrizione: quando e.props.placement è 'dock', e.props.scroll.bodyRows è il numero di righe di cui dispone il pannello per il tuo albero
• Altezza di un Pane sopra il prompt: quando e.props.placement è 'inline', il pannello cresce insieme al tuo albero fino a un limite, e bodyRows è quel limite. Per richiedere un limite diverso, consulta il campo rows di $.ui.open.

Un albero più alto del pannello scorre nel suo insieme.

Elementi

Gli elementi sono i componenti di base di un albero restituito da un hook ui.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 hotkey numerico 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 action né un hotkey premono un pulsante al suo interno
• Due pulsanti sullo stesso hotkey: quando due pulsanti nello stesso disegno indicano lo stesso hotkey, lo ottiene quello successivo
• variant: primary o secondary, e qualsiasi altro valore genera un'eccezione. Nel terminale, un pulsante primary viene disegnato nel colore di accento, a meno che non sia plain.
• role: dismiss contrassegna un pulsante di chiusura, e qualsiasi altro valore genera un'eccezione. Esegui la chiusura nel tuo onPress. In una banda che contiene testo e una riga di pulsanti, l'app Desktop può disegnare il primo pulsante dismiss della riga come un proprio controllo di chiusura. Il terminale disegna il pulsante come farebbe senza role.

Un 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 un Button.
• Assegnare un nome al pulsante: la label assegna il nome al pulsante e, per impostazione predefinita, corrisponde al testo dei suoi children. Assegna una key o una label a 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

[!NOTE]

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: position con i relativi top, left, right e bottom, alignSelf, borderDimColor e hover
• Text: size, mono, tabular e hover
• Button: hotkey, plain, autoFocus, action e hover, quindi lì l'utente preme un pulsante con un clic, oppure con Invio quando ha il focus. L'estensione ignora anche variant e role.
• Code: language, path, startLine, format e wrap, quindi il codice viene disegnato senza colori né numeri di riga, e un blocco format: 'diff' mostra il testo grezzo del diff
• Input e Select: autoFocus, e rows su un Input
• Svg: 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 celle Raster 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 comandi claude 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.