- Escludere i mod degli utenti, con o senza mod tuoi: Impedisci il caricamento dei mod installati dagli utenti
- Vedere cosa ottengono i tuoi utenti se non modifichi nulla: Scopri cosa succede per impostazione predefinita
- Lasciare attivi i mod con altri limiti: Scegli quanto consentire
Questi casi sono trattati in altre pagine:
- Non hai mai distribuito impostazioni gestite: inizia da Distribuire le impostazioni gestite
- Vuoi controllare quali plugin possono installare gli utenti: consulta Gestire i plugin per la tua organizzazione
Impedire il caricamento dei mod installati dagli utenti
Per impedire a tutti i mod portati dai tuoi utenti di eseguire i propri hook, imposta l’opzioneallowManagedModsOnly sulla protezione integrata, un mod di criteri che Claude Code carica prima di ogni mod installato da un utente. L’opzione va nelle impostazioni gestite sotto pluginConfigs, con chiave cc-plugin-sec-default@builtin:
managed-settings.json
- Nessun mod portato da un utente esegue i propri hook: questo include un mod in un plugin installato dall’utente, un mod caricato con
--plugin-dire un mod scritto da Claude durante una sessione - I mod della tua organizzazione vengono comunque eseguiti: un mod che conta come appartenente alla tua organizzazione non viene controllato. Ogni altro mod conta come appartenente a un utente e viene rifiutato. Questo include un mod che la tua organizzazione attiva per i propri membri su claude.ai. Se nessuno conta come tuo, nessun mod installato esegue i propri hook.
- Gli utenti non possono annullarlo: la protezione integrata legge l’opzione solo dalle impostazioni gestite, quindi la stessa voce in un file di impostazioni utente, di progetto o locale, o in un file passato con
--settings, non cambia nulla - Un file o un criterio MDM copre ogni provider: quando distribuisci l’opzione come file o tramite MDM, funziona allo stesso modo su Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry. Per la distribuzione dalla console di amministrazione di claude.ai, consulta Disponibilità delle piattaforme
- Le altre personalizzazioni degli utenti continuano a funzionare: i loro hook nei file di impostazioni e nel file
hooks/hooks.jsondei plugin, le righe di stato e/goalnon sono interessati - I mod integrati continuano a funzionare: i mod integrati in Claude Code, come il supporto per
AGENTS.md, hanno ciascuno il proprio interruttore
--plugin-dir e il percorso di una directory che contiene un mod, ad esempio claude --plugin-dir ./first-mod. Gli hook del mod non vengono eseguiti, e la trascrizione e il log di debug contengono il messaggio della protezione integrata, che indica il nome del mod e allowManagedModsOnly. Se il messaggio non è presente, consulta Verificare che un criterio sia in vigore e le regole che determinano se un’opzione ha effetto.
Se durante l’accesso anticipato hai impostato CLAUDE_CODE_ENABLE_FUNCTION_HOOKS su 0, sostituiscila con questa opzione. Claude Code v2.1.287 e versioni successive ignorano la variabile con qualsiasi valore, quindi un 0 lascia i mod attivi.
Sapere cosa succede per impostazione predefinita
Senza impostazioni dei mod tue, ecco cosa ottengono i tuoi utenti:-
I mod sono attivi. Un utente può installare un plugin che contiene un mod da qualsiasi marketplace consentito dalle tue impostazioni dei plugin, oppure caricarne uno da una directory con
--plugin-dir. -
Una protezione integrata viene eseguita per prima. Claude Code carica un mod integrato chiamato
sec-default@builtinprima di ogni mod installato da un utente. Gli utenti non possono disattivarlo./plugine il log di debug lo elencano comecc-plugin-sec-default. La protezione viene caricata quando è vera una di queste condizioni:- La macchina ha impostazioni gestite o un file
managed-mcp.json - La sessione viene eseguita con le credenziali di
/logindi un piano Team o Enterprise
managed-mcp.json. Nemmeno una sessione eseguita con unCLAUDE_CODE_OAUTH_TOKENdi lunga durata conta come quell’accesso, anche quando sulla macchina è memorizzato un accesso Team o Enterprise. - La macchina ha impostazioni gestite o un file
-
La protezione tutela ciò che gestisci. Il mod di un utente non può modificare ciò che i tuoi hook gestiti ricevono o decidono, il prompt di sistema, né il tuo
CLAUDE.mdgestito e le altre istruzioni gestite. Non può nemmeno modificare ciò che qualsiasi mod legge come impostazioni, né gli strumenti e le descrizioni dei tuoi server MCP gestiti una volta che si sono connessi. -
Dalla v2.1.323 in poi, il mod di un utente può impedire a un server MCP gestito di connettersi. Nella sessione di quell’utente,
/mcpelenca il server come bloccato da quel mod. Per evitarlo, impedisci il caricamento dei mod installati dagli utenti. - Al di fuori di ciò che gestisci, il mod di un utente agisce come quell’utente. Il mod mantiene i permessi di quell’utente: può comunque leggere e scrivere file, avviare processi ed effettuare richieste di rete. Può anche riscrivere chiamate agli strumenti e prompt, negare una chiamata a uno strumento, aggiungere o rimuovere strumenti e disegnare nell’interfaccia.
-
Le regole di permesso e gli hook
PreToolUsehanno la precedenza sul mod di un utente. Con la protezione caricata, per impostazione predefinita il mod di un utente non può approvare una chiamata che una regoladenyrifiuta o per cui una regolaaskchiede conferma, qualunque sia il file di impostazioni che contiene la regola. Il mod non può nemmeno approvare una chiamata che un qualsiasi hookPreToolUseha bloccato. Le regole di permesso e gli hookPreToolUsesi applicano alle chiamate agli strumenti di Claude, non alle chiamate$.fse$.processdi un mod. ConRead(.env)negato, un mod può comunque leggere quel file con$.fs.reado avviare un programma che lo fa. Per limitare le chiamate$.fse$.processdel mod stesso, impedisci il caricamento del mod oppure gestiscile in un mod di criteri. -
Il mod di un utente può comunque saltare alcune richieste di conferma. In modalità auto, una chiamata approvata dal mod viene eseguita senza un controllo del classificatore, a meno che la protezione non sia caricata e la sessione venga eseguita con
--permission-prompt-toolo un callbackcanUseTooldell’Agent SDK. In quel caso il classificatore controlla prima la chiamata. Per le richieste di conferma che l’approvazione di un mod non salta, consulta Estendere i permessi con gli hook.
mods/sec-default del repository di Claude Code.
Sapere quali controlli continuano ad applicarsi
I mod non sostituiscono i controlli che hai già:-
Gli hook delle impostazioni continuano a funzionare. Gli hook di tipo command, HTTP, prompt e agent nei file di impostazioni e in
hooks/hooks.jsondei plugin vengono eseguiti come prima, insieme ai mod. -
Le regole deny hanno la precedenza dove la protezione viene caricata. Il mod di un utente non può approvare una chiamata che una regola
denyrifiuta, a meno che tu non impostiallowModsToOverrideDenyRules. -
Gli hook gestiti vengono eseguiti per primi. Un hook
PreToolUsenelle impostazioni gestite viene eseguito prima dell’hooktool.calldi qualsiasi mod, e quando quell’hook gestito blocca una chiamata a uno strumento, nessun hooktool.calldei mod viene eseguito per quella chiamata. Se la chiamata procede e un mod la riscrive, i tuoi hook gestiti vengono eseguiti di nuovo sulla chiamata riscritta, quindi per impostazione predefinita possono comunque bloccarla. Gli hookPreToolUseprovenienti da altri file di impostazioni e dai plugin vengono eseguiti dopo l’ultimo mod. Se un mod risponde direttamente alla chiamata allo strumento, lo strumento non viene mai eseguito e nemmeno quegli hook. Consulta L’ordine in cui vengono eseguiti i mod. -
La policy di rete copre
$.http.fetch.-
La policy della tua organizzazione non consente WebFetch: Claude Code rifiuta anche ogni richiesta
$.http.fetchdi qualsiasi mod. Consulta Disponibilità di WebFetch. -
Disattivi lo strumento WebFetch con
CLAUDE_CODE_DISABLE_WEB_FETCHo una regola denyWebFetch, nelle impostazioni gestite o in qualsiasi altro file di impostazioni: i mod possono comunque effettuare richieste$.http.fetch. Per bloccarle per ogni mod installato dai tuoi utenti, impedisci il caricamento dei mod installati dagli utenti, oppure agganciahttp.fetchin un mod di criteri e rifiuta le richieste provenienti dai mod degli utenti. Assegna a quell’hook un gestore.catchche a sua volta rifiuti, perché Claude Code salta un hook che fallisce e la richiesta procede comunque. Se ti limiti a restringere quali plugin gli utenti possono installare, vengono caricati meno mod, ma quelli che consenti effettuano comunque queste richieste. -
Imposti
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: un mod installato da te o dai tuoi utenti può comunque effettuare queste richieste. La variabile blocca solo i mod integrati in Claude Code, più qualsiasi richiesta$.http.fetchche include le credenziali Anthropic della sessione. Prima della v2.1.288, la variabile bloccava ogni richiesta$.http.fetchdi qualsiasi mod.
$.process.run, che raggiunge la rete con l’accesso dell’utente stesso. -
La policy della tua organizzazione non consente WebFetch: Claude Code rifiuta anche ogni richiesta
-
I controlli dei plugin coprono i mod. Un mod è un plugin, quindi le impostazioni che limitano ciò che gli utenti possono installare, come
strictKnownMarketplaces, decidono se può essere installato o meno. - I mod non possono modificare la richiesta di permesso. Un mod può cambiare lo stile di gran parte dell’interfaccia di Claude Code, ma non della richiesta di permesso, quindi non può modificare ciò che una richiesta mostra. Un mod può comunque approvare o negare una chiamata a uno strumento prima che compaia la richiesta, come descritto in Sapere cosa succede per impostazione predefinita.
- Le richieste di attendibilità vengono prima. In una sessione interattiva in una directory che l’utente non ha ancora considerato attendibile, nessun mod viene caricato finché l’utente non risponde alla richiesta di attendibilità.
-
--safe-modedisattiva i mod installati, compresi i tuoi. Avvia una sessione conclaude --safe-modeper verificare se un mod ha causato un problema.
Sapere quali hook del mod di un utente non vengono eseguiti
Dove viene caricata la protezione integrata, un hook che il mod di un utente registra su uno di questi eventi non viene mai eseguito, e/plugin lo comunica a quell’utente in una nota. Nelle righe di session.append, door è il tipo di riga memorizzata su cui è filtrato l’hook.
La protezione ignora gli hook di un utente anche in alcuni altri casi, come le descrizioni degli strumenti della tua organizzazione, su
tool.describe, e la riga memorizzata per il testo di una skill. Per questi /plugin non mostra alcuna nota. Se un hook su un altro evento non fa nulla, consulta Scoprire perché un mod non fa nulla.
La nota compare nei dettagli del plugin e nella scheda Errors di /plugin. Richiede Claude Code v2.1.299 o successivo. Nomina ogni hook della tabella così come il mod lo ha registrato, come in questo esempio:
- Eseguire il mod come mod della tua organizzazione: installa il mod in modo che conti come tuo. I suoi hook su questi eventi vengono quindi eseguiti, e la protezione resta caricata per ogni altro mod. Il mod si attiva per chiunque riceva queste impostazioni. Se lo elenchi in
prependPlugins, mantienisec-default@builtinnell’elenco. - Rimuovere la protezione: escludi
sec-default@builtindaprependPlugins. Basta un elenco vuoto,"prependPlugins": []. Perdi l’intera protezione, non solo questi eventi. Il mod di un utente può quindi fare ciò che la protezione altrimenti gli impedisce di fare, e le opzioni della protezione non si applicano.
/plugin in una sessione su quella macchina e verifica che la nota non ci sia più.
Un hook session.append senza filtro door viene comunque eseguito e non riceve alcuna nota, ma le righe memorizzate nella tabella non lo raggiungono.
Decidi se lasciare attivi i mod
Un mod può fare più delle altre parti di un plugin perché viene eseguito all’interno di Claude Code. Vede ogni prompt e ogni chiamata a uno strumento, può modificarli e può consentire o negare una chiamata a uno strumento prima che compaia una richiesta di permesso. Ciò che un utente può caricare come mod dipende dai controlli sui plugin che hai già:
Gestire i plugin per la tua organizzazione elenca i modi in cui un plugin viene caricato e l’impostazione che controlla ciascuno di essi.
Per controllare i mod in un marketplace prima che i tuoi utenti li installino, consulta Verifica cosa può fare un mod. Per impedire il caricamento dei mod degli utenti finché non l’hai fatto, consulta Impedisci il caricamento dei mod installati dagli utenti.
Verifica cosa può fare un mod
Puoi vedere cosa è in grado di fare un mod senza eseguirlo. Nella tua shell, eseguiclaude plugin validate sulla directory del plugin:
hooks: e calls: dell’output descrivono il codice del mod:
hooks:: gli eventi che il mod riceve. Una notadefault matcher key: pluginindica che l’hook che la precede salta i controlli e i disegni degli altri mod.calls:: i metodi dell’API dei mod che il suo codice chiama
$ nel codice di un mod, è il modo in cui un mod accede a file, processi e rete. Claude Code si rifiuta di caricare un mod che usa l’API dei mod in un modo che questo comando non riesce a leggere.
Non approvare un mod per cui questo comando non riesce, perché alcuni errori non ne impediscono il caricamento. Esegui il comando su Claude Code v2.1.323 o successivo, dove un elenco lungo prosegue su più righe con la stessa etichetta, e leggi ogni riga hooks: e calls:. Nelle righe calls:, cerca questi elementi:
Nella riga
hooks:, tool.call e prompt.submit indicano che il mod vede ogni chiamata a uno strumento e ogni prompt, e può modificarli. session.append indica che il mod può riscrivere ogni riga della conversazione prima che venga memorizzata, eccetto le righe che la protezione tralascia. ui.render{component=AskUserQuestion} indica che il mod può ridisegnare la finestra di dialogo che Claude usa per porre una domanda all’utente. tool.check indica che il mod può approvare o negare una chiamata a uno strumento prima che compaia una richiesta di permesso. Sapere cosa succede per impostazione predefinita elenca quali delle tue regole e dei tuoi hook hanno la precedenza sulla sua risposta.
Scegli quanto consentire
I criteri per i mod vanno dal non consentire alcun mod installato fino a consentire qualsiasi mod scelto da un utente, con il tuo mod che controlla gli altri, e ciascuno corrisponde a poche impostazioni gestite. Trova il criterio che desideri nella prima colonna e imposta ciò che indica la seconda colonna. Distribuire le impostazioni gestite spiega dove si trovano le impostazioni gestite.
Cosa fa ciascuna impostazione:
allowManagedModsOnly: un’opzione della protezione integrata. Claude Code rifiuta i mod degli utenti, quindi nessuno dei loro hook viene eseguito. Gli hook delle impostazioni degli utenti, le righe di stato e/goalcontinuano a funzionare. Impedire il caricamento dei mod installati dagli utenti elenca cosa copre.allowManagedHooksOnly: un’impostazione più ampia. Vengono caricati solo i mod della tua organizzazione e i mod integrati in Claude Code. Un mod installato da un utente non viene caricato. L’impostazione blocca anche gli hook nei file di impostazioni degli utenti. Leggi Cosa viene eseguito conallowManagedHooksOnlyprima di impostarla.disableAllHooks: l’impostazione più ampia. Nelle impostazioni gestite, blocca i mod in ogni plugin installato, inclusi i tuoi, e disattiva ogni hook nei file di impostazioni, quindi un hookPreToolUsenelle tue impostazioni gestite non blocca più nulla. Anche le righe di stato personalizzate e/goalsmettono di funzionare. LeggidisableAllHooksprima di impostarla.disableSideloadFlags: rifiuta--plugin-dire--plugin-urlall’avvio, e impedisce il caricamento dei mod che Claude scrive durante una sessione. L’impostazione rifiuta anche--agentse--mcp-config. LeggidisableSideloadFlagsprima di impostarla.
AGENTS.md, non sono interessati da queste impostazioni. Ognuno ha il proprio interruttore.
Un utente il cui mod è stato rifiutato o non è stato caricato trova il motivo nel proprio log di debug. Messaggi di rifiuto elenca le righe per allowManagedHooksOnly e disableAllHooks, e Messaggi dalla protezione integrata riporta la riga per allowManagedModsOnly.
Consentire solo i mod della tua organizzazione
Per eseguire i mod della tua organizzazione e bloccare quelli portati dagli utenti, distribuisci le impostazioni della riga Solo i mod della tua organizzazione della tabella dei criteri, piùdisableSideloadFlags. Con questo managed-settings.json completo, Claude Code rifiuta i mod degli utenti, quindi nessuno dei loro hook viene eseguito, e il tuo mod di criteri viene eseguito prima degli altri mod:
managed-settings.json
extraKnownMarketplaces,enabledPluginseprependPlugins: installano il tuo mod in modo che venga considerato tuo, e lo eseguono per primo con la protezione subito dopo. Installare i mod della tua organizzazione e impostare l’ordine descrive la directory a cui puntano queste chiavi.pluginConfigs: imposta l’opzioneallowManagedModsOnlydella protezione, così Claude Code rifiuta i mod degli utenti. I loro hook delle impostazioni, le righe di stato e/goalcontinuano a funzionare.disableSideloadFlags: consultadisableSideloadFlagsper i flag che rifiuta all’avvio
claude --debug e leggi il log di debug:
- Il tuo mod: la sua riga
hooks modulecontienetier prepend - Un mod installato dall’utente: una riga riporta
refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Una riga precedente indica che il modulo degli hook di quel mod èloaded, quindi cerca il rifiuto. - Una directory di plugin:
claude --plugin-dir ./any-modtermina con un messaggio che inizia con--plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)
Applicare i controlli sui plugin ai mod
Un mod è un plugin, quindi i modi in cui gestisci i plugin per la tua organizzazione si applicano anche a un plugin che contiene un mod:- Vedere quali plugin vengono caricati nella tua flotta: Verifica e revisione
- Decidere quando un plugin che hai revisionato può aggiornarsi: Impostare il criterio di aggiornamento
- Assegnare a un gruppo un criterio diverso, ad esempio un gruppo pilota: Pianificare ciò che le impostazioni gestite non possono imporre
- Verificare quali app e tipi di sessione applicano le chiavi dei plugin: Quando ciascuna superficie applica le chiavi dei plugin
- Configurare CI e container: Predisporre container e CI
- Offrire mod che i tuoi utenti possono installare: Ospitare un marketplace. Un mod che Claude Code copia da una sorgente GitHub, git, URL o npm viene considerato di un utente, a meno che tu non lo installi come mod della tua organizzazione.
Impostare le opzioni della protezione integrata
La protezione integrata accetta delle opzioni. Impostale nelle impostazioni gestite sottopluginConfigs, con la chiave cc-plugin-sec-default@builtin, come fa l’esempio in Impedire il caricamento dei mod installati dagli utenti.
La tabella indica cosa ottengono i tuoi utenti con ciascuna opzione non impostata e impostata su true:
Queste regole stabiliscono se un’opzione ha effetto:
- L’id ha una sola forma qui: Claude Code legge le opzioni solo sotto
cc-plugin-sec-default@builtin.prependPluginsaccetta anchesec-default@builtin, mentrepluginConfigsno. - Contano solo le impostazioni gestite: la stessa voce in un file di impostazioni utente, di progetto o locale, o in un file passato con
--settings, non imposta né allenta un’opzione - La protezione deve essere caricata: se imposti
prependPlugins, indica la protezione nell’elenco. Dove la protezione non viene caricata, nessuna delle due opzioni si applica. - La protezione fallisce in modo chiuso: se la protezione non riesce a leggere le impostazioni gestite, rifiuta ogni mod degli utenti al caricamento. Se non riesce a verificare le regole
denyper una chiamata approvata dal mod di un utente, rifiuta la chiamata.
Esegui i mod della tua organizzazione
Puoi distribuire i tuoi mod a ogni utente, scegliere dove vengono eseguiti rispetto ai mod degli utenti e usarne uno per applicare un criterio.Installa i mod della tua organizzazione e imposta l’ordine
I mod della tua organizzazione vengono caricati dove quelli degli utenti non lo sono e possono essere eseguiti prima di essi, quindi Claude Code deve essere in grado di capire che un mod proviene da te. Per fare in modo che un mod proveniente da un marketplace remoto, come un repository GitHub, venga considerato tuo dalla v2.1.324 in poi, esegui tutte queste operazioni nelle impostazioni gestite:- Imposta il plugin del mod su
trueinenabledPlugins - Dichiara il marketplace in
extraKnownMarketplaces. Per controllare quando cambia il codice del mod, blocca la versione del marketplace e della voce del mod. - Elenca l’id del mod, ad esempio
acme-guard@acme-tools, inprependPluginsoappendPlugins. ConprependPlugins, elenca anchesec-default@builtinper mantenere la protezione integrata.
- L’impostazione gestita
enabledPluginsimposta il plugin del mod sutrue - Le impostazioni gestite indicano il marketplace del plugin come una directory sulla macchina dell’utente, tramite percorso assoluto. Una voce
extraKnownMarketplacesfa proprio questo e registra anche il marketplace per l’utente. - Il marketplace elenca il plugin tramite un percorso relativo, così Claude Code lo carica sul posto da quella directory
/opt/acme/claude-plugins/.claude-plugin/marketplace.json
enabledPlugins lo abilita. Il suo mod viene eseguito tra i mod degli utenti, prependPlugins e appendPlugins lo ignorano, allowManagedModsOnly lo rifiuta e allowManagedHooksOnly ne impedisce il caricamento. Quando le impostazioni gestite lo abilitano, il log di debug dell’utente contiene una riga che inizia con l’id del plugin e is enabled by managed settings, but.
Claude Code genera un evento ogni volta che sta per compiere un’azione, come eseguire uno strumento, e lo passa a ciascun mod a turno. Un mod che soddisfa le condizioni della directory viene eseguito prima dei mod degli utenti anche se non lo elenchi da nessuna parte. Per impostarne la posizione, elenca il suo id in una delle due impostazioni. L’id è il nome del plugin, @ e il nome del marketplace, ad esempio acme-guard@acme-tools.
prependPlugins: il tuo mod vede un evento prima di qualsiasi mod degli utenti e il risultato dell’evento dopo di essi. Può modificare l’evento, rifiutarlo o saltare i mod degli utenti. Dalla v2.1.323 in poi, verifica che i tuoi hook raggiungano ancora i controlli e i disegni degli altri mod.appendPlugins: il tuo mod viene eseguito dopo ogni mod degli utenti, quindi vede solo gli eventi che quei mod trasmettono, nella forma in cui li trasmettono
acme-tools in /opt/acme/claude-plugins, abilita acme-guard da esso ed esegue quel mod per primo, seguito dalla protezione integrata:
managed-settings.json
extraKnownMarketplaces: indica la directory che contiene il marketplaceacme-tools.pathè il percorso assoluto della directory che contiene.claude-plugin/marketplace.json.enabledPlugins: attivaacme-guardper ogni utente che riceve queste impostazioni gestiteprependPlugins: metteacme-guardal primo posto e la protezione integrata al secondo, entrambi prima di qualsiasi mod installato da un utente. Claude Code segue l’ordine che elenchi.
claude --debug e cerca l’id del mod nel log di debug:
hooks module acme-guard@acme-tools loaded, contier prepend: il mod viene considerato della tua organizzazione e viene eseguito per primo- La stessa riga con
tier user: Claude Code lo tratta come un mod di un utente. Una seconda riga,prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, indica che l’elenco lo ha ignorato.
- L’elenco sostituisce il valore predefinito: quando imposti
prependPluginsnelle impostazioni gestite, includisec-default@builtinper mantenere la protezione integrata. La protezione è integrata e non richiede una voceenabledPlugins. - I tuoi id devono essere considerati tuoi: nelle impostazioni gestite, Claude Code ignora un id il cui plugin non soddisfa le condizioni per un mod dell’organizzazione
- I repository non possono impostare nessuno dei due elenchi: Claude Code li ignora entrambi nel file di impostazioni di un repository, quindi impostali nelle impostazioni gestite.
- Un utente può impostarli per ordinare i propri mod: in
~/.claude/settings.json, solo su una macchina senza impostazioni gestite né filemanaged-mcp.json, e solo quando la credenziale della sessione non proviene da un/loginTeam o Enterprise. In qualsiasi altro caso, Claude Code ignora entrambe le chiavi nelle impostazioni utente. Un elenco lì non aggiunge né rimuove la protezione integrata.
Applica un criterio con un tuo mod
Per escludere tutti i mod degli utenti, non hai bisogno di un tuo mod. ImpostaallowManagedModsOnly. Scrivi un mod di criteri quando vuoi consentire alcuni mod degli utenti e rifiutarne altri, oppure per registrare ciò che fanno i mod.
Ogni volta che un altro mod sta per essere caricato, il tuo mod riceve l’elenco che claude plugin validate stampa, in un evento denominato plugin.register. Un mod in prependPlugins può leggere quell’elenco e rifiutare il mod. Può anche gestire qualsiasi chiamata all’API dei mod per nome per registrare o rifiutare quella chiamata per ogni altro mod. Il nome è il metodo senza $., quindi un hook su fs.write vede ogni chiamata $.fs.write.
Dalla v2.1.323 in poi, un hook
ui.focus richiede un matcher più ampio per ricevere le chiamate $.ui.focus degli altri mod. Consulta Aggancia i disegni e i controlli degli altri mod.$.process.run o $.process.spawn. Mantiene anche un log di audit, scrivendo nel log di debug ogni chiamata a uno strumento e ogni file scritto da un mod. Poiché viene eseguito per primo, il log registra ciò che è stato richiesto, prima che qualsiasi mod degli utenti lo modifichi. Salvalo come acme-guard/hooks/register.js:
acme-guard/hooks/register.js
plugin.register: decide se un altro mod viene caricato. Rifiuta un mod di un utente che chiama un metodo bloccato e lascia passare ogni altro mod.tool.call: scrive nel log di debug una riga comeaudit tool.call Bashper ogni chiamata a uno strumento, senza modificare nullafs.write: scrive una riga comeaudit fs.write by reader "/tmp/notes.md"per ogni chiamata$.fs.writeeffettuata da un altro mod, senza modificare nulla. Il nome del mod viene prima e il percorso è tra virgolette, così un percorso scelto da un mod non può spacciarsi per un altro campo della riga.
plugin.register legge due campi dell’evento:
e.tier: dove verrebbe eseguito il mod, uno traprepend,user,appendobuiltin. Ogni mod installato da una persona èuser.e.uses.calls: i metodi dell’API dei mod che il mod chiama, ciascuno scritto comenamespace.method, ad esempioprocess.run, senza il$.checlaude plugin validatestampa
$.process.run, il mod non viene caricato e il suo log di debug contiene una riga che termina con refused by acme-guard: seguita dal tuo motivo. Il rifiuto compare anche nella trascrizione in una sessione che ricarica a caldo una directory di plugin.
Per bloccare una chiamata senza rifiutare l’intero mod, restituisci { deny: 'your reason' } da un hook sul nome di quella chiamata, dopo aver verificato chi ha effettuato la chiamata.
Per inviare le righe di audit in un posto diverso dal log di debug, chiama $.http.fetch dagli stessi hook.
Una sessione può essere eseguita senza il tuo mod. Se il thread di lavoro che esegue i mod installati si arresta in modo anomalo tre volte, Claude Code scarica ogni mod non integrato, compreso il tuo, finché l’utente non esegue /reload-plugins o avvia una nuova sessione. Inoltre, un utente che avvia Claude Code con --safe-mode lavora senza mod installati, compreso il tuo.
Crea un mod descrive i file di cui un mod ha bisogno. Testa un mod di criteri contiene un file di test per questo mod di criteri.
Rifiuta i mod quando il tuo controllo fallisce
Se il tuo hookplugin.register genera un’eccezione o supera il suo limite di tempo, Claude Code salta l’hook, quindi il controllo fallisce in modo aperto e il mod che stava controllando viene caricato. Per fallire in modo chiuso e rifiutare i mod degli utenti, sposta il controllo in una funzione con nome e aggiungi un gestore .catch che restituisca il rifiuto. Questa versione del file mostra solo l’hook plugin.register, quindi mantieni in register i due hook di audit della prima versione:
acme-guard/hooks/register.js
refused by acme-guard: Acme policy check failed, so this mod was not loaded. Il gestore passa a next(e) ogni mod al di fuori del livello user, quindi un controllo fallito non blocca i mod elencati dalla tua organizzazione. Gestisci un hook che fallisce descrive .catch per altri eventi.
Passaggi successivi
- Sicurezza dei plugin: cosa può fare qualsiasi plugin sul computer di un utente e come esaminarne uno prima che venga installato
- Panoramica dei mod: cos’è un mod e come si confronta con gli hook, le skill e i server MCP
- L’ordine in cui vengono eseguiti i mod: come
prependPluginseappendPluginssi combinano con i mod degli utenti - Impostazioni e variabili d’ambiente: tutte le impostazioni citate in questa pagina in un’unica tabella