Gestire i mod per la tua organizzazione

Controlla i mod di Claude Code con le impostazioni gestite: blocca i mod installati dagli utenti, consenti solo i tuoi, verifica cosa può fare un mod e applica le policy con un tuo mod.

Un mod è un plugin che esegue codice all'interno di Claude Code con i permessi dell'utente che lo ha installato. I mod non sono isolati in una sandbox. Tramite le impostazioni gestite, decidi se i mod vengono eseguiti sui computer dei tuoi utenti, quali e in quale ordine. Puoi anche installare un tuo mod che osserva o rifiuta ciò che fanno gli altri mod.

Questa pagina è rivolta a chi distribuisce le impostazioni gestite per Claude Code, sia come file, tramite MDM o dalla console di amministrazione di claude.ai. I mod sono attivi per impostazione predefinita in Claude Code v2.1.286 e versioni successive. Inizia dalla sezione che corrisponde a ciò che vuoi fare:

• 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

[!NOTE]

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'opzione allowManagedModsOnly 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:

{
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": {
        "allowManagedModsOnly": true
      }
    }
  }
}

Con l'opzione impostata nelle impostazioni gestite:

• 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-dir e 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 in un plugin che abiliti da GitHub o da un altro marketplace remoto, e uno 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.json dei plugin, le righe di stato e /goal non 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

Per verificare l'opzione sul computer di un utente, avvia lì Claude Code con --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@builtin prima di ogni mod installato da un utente. Gli utenti non possono disattivarlo. /plugin e il log di debug lo elencano come cc-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 /login di un piano Team o Enterprise

  Un utente che si autentica con una chiave API, oppure tramite Amazon Bedrock, Agent Platform di Google Cloud o Microsoft Foundry, ottiene la protezione solo su una macchina che ha impostazioni gestite o managed-mcp.json. Nemmeno una sessione eseguita con un CLAUDE_CODE_OAUTH_TOKEN di lunga durata conta come quell'accesso, anche quando sulla macchina è memorizzato un accesso Team o Enterprise.

• 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, il tuo CLAUDE.md gestito e le altre istruzioni gestite, ciò che qualsiasi mod legge come impostazioni, né gli strumenti e le descrizioni dei tuoi server MCP gestiti.

• 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 e disegnare nell'interfaccia.

• Le regole di permesso e gli hook PreToolUse hanno 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 regola deny rifiuta o per cui una regola ask chiede conferma, qualunque sia il file di impostazioni che contiene la regola. Il mod non può nemmeno approvare una chiamata che un qualsiasi hook PreToolUse ha bloccato.

  Le regole di permesso e gli hook PreToolUse si applicano alle chiamate agli strumenti di Claude, non alle chiamate $.fs e $.process di un mod. Con Read(.env) negato, un mod può comunque leggere quel file con $.fs.read o avviare un programma che lo fa. Per limitare le chiamate $.fs e $.process del 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-tool o un callback canUseTool dell'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.

Il codice sorgente della protezione è pubblico nella directory 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.json dei 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 deny rifiuta, a meno che tu non imposti allowModsToOverrideDenyRules.

• Gli hook gestiti vengono eseguiti per primi. Un hook PreToolUse nelle impostazioni gestite viene eseguito prima dell'hook tool.call di qualsiasi mod, e quando quell'hook gestito blocca una chiamata a uno strumento, nessun hook tool.call dei 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 hook PreToolUse provenienti 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.fetch di qualsiasi mod. Consulta Disponibilità di WebFetch.

  • Disattivi lo strumento WebFetch con CLAUDE_CODE_DISABLE_WEB_FETCH o una regola deny WebFetch, 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 aggancia http.fetch in un mod di criteri e rifiuta le richieste provenienti dai mod degli utenti. Assegna a quell'hook un gestore .catch che 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.fetch che include le credenziali Anthropic della sessione. Prima della v2.1.288, la variabile bloccava ogni richiesta $.http.fetch di qualsiasi mod.

  Nessuno di questi casi copre un programma che il mod avvia con $.process.run, che raggiunge la rete con l'accesso dell'utente stesso.

• 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-mode disattiva i mod installati, compresi i tuoi. Avvia una sessione con claude --safe-mode per verificare se un mod ha causato un problema.

Nessuno di questi controlli esegue un mod in una sandbox. Un mod che consenti viene eseguito come l'utente, con l'accesso dell'utente a file, processi e rete.

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:

Its hooks on classic.Stop, prompt.section do not run here: where an organization manages Claude Code, these events pass over the plugins you install
Only a plugin that counts as your organization's own runs hooks on these events. An administrator sets that up in managed settings

Per consentire l'esecuzione di questi hook, modifica le impostazioni gestite in uno di due modi:

• 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 e deve trovarsi in una directory che posizioni su ogni macchina. Se lo elenchi in prependPlugins, mantieni sec-default@builtin nell'elenco.
• Rimuovere la protezione: escludi sec-default@builtin da prependPlugins. 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.

Se distribuisci un elenco senza la protezione tramite le impostazioni gestite dal server, la protezione resta caricata finché il server non conferma le impostazioni per la sessione. Per confermare una delle due modifiche su una macchina che esegue la v2.1.299 o successiva, apri /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, esegui claude plugin validate sulla directory del plugin:

claude plugin validate ./some-mod

Le righe hooks: e calls: dell'output descrivono il codice del mod:

  ❯ ./register.js hooks: session.start, tool.call, ui.render{component=Pane}
  ❯ ./register.js calls: $.fs.read, $.http.fetch, $.store.set, $.ui.open

La riga hooks: elenca gli eventi che il mod riceve. La riga calls: elenca i metodi dell'API dei mod che il suo codice chiama. L'API dei mod, scritta $ 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.

Cerca questi elementi nella riga calls::

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 /goal continuano 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 con allowManagedHooksOnly prima 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 hook PreToolUse nelle tue impostazioni gestite non blocca più nulla. Anche le righe di stato personalizzate e /goal smettono di funzionare. Leggi disableAllHooks prima di impostarla.
• disableSideloadFlags: rifiuta --plugin-dir e --plugin-url all'avvio, e impedisce il caricamento dei mod che Claude scrive durante una sessione. L'impostazione rifiuta anche --agents e --mcp-config. Leggi disableSideloadFlags prima di impostarla.

I mod integrati in Claude Code, come il supporto per 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:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"],
  "pluginConfigs": {
    "cc-plugin-sec-default@builtin": {
      "options": { "allowManagedModsOnly": true }
    }
  },
  "disableSideloadFlags": true
}

Ogni gruppo di chiavi svolge un compito:

• extraKnownMarketplaces, enabledPlugins e prependPlugins: 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'opzione allowManagedModsOnly della protezione, così Claude Code rifiuta i mod degli utenti. I loro hook delle impostazioni, le righe di stato e /goal continuano a funzionare.
• disableSideloadFlags: consulta disableSideloadFlags per i flag che rifiuta all'avvio

Per verificare il criterio su una macchina di test, nella tua shell avvia una sessione con claude --debug e leggi il log di debug:

• Il tuo mod: la sua riga hooks module contiene tier 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-mod termina con un messaggio che inizia con --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)

Per limitare anche i marketplace che gli utenti possono aggiungere, combina questo file con le tue restrizioni sui marketplace.

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, non della tua organizzazione.

Impostare le opzioni della protezione integrata

La protezione integrata accetta delle opzioni. Impostale nelle impostazioni gestite sotto pluginConfigs, 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. prependPlugins accetta anche sec-default@builtin, mentre pluginConfigs no.
• 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 deny per una chiamata approvata dal mod di un utente, rifiuta la chiamata.

I messaggi dalla protezione integrata sono ciò che vedono i tuoi utenti quando si applica una delle due opzioni.

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. Considera un mod come appartenente alla tua organizzazione solo quando tutte queste condizioni sono vere:

• L'impostazione gestita enabledPlugins imposta il plugin del mod su true
• Le impostazioni gestite indicano il marketplace del plugin come una directory sulla macchina dell'utente, tramite percorso assoluto. Una voce extraKnownMarketplaces fa 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

Per soddisfarle, fai in modo che il tuo sistema di gestione dei dispositivi copi la directory del marketplace nello stesso percorso su ogni macchina. Rendi la directory e ogni directory sovrastante scrivibili solo da un amministratore, come il file delle impostazioni gestite. Chiunque possa scrivere lì può riscrivere il tuo mod. Le impostazioni gestite che distribuisci dalla console di amministrazione di claude.ai possono contenere le chiavi, ma non possono collocare la directory su una macchina.

La directory contiene il manifest del marketplace e il plugin:

/opt/acme/claude-plugins/
├── .claude-plugin/
│   └── marketplace.json
└── plugins/
    └── acme-guard/
        ├── .claude-plugin/
        │   └── plugin.json
        └── hooks/
            ├── hooks.json
            └── register.js

Il manifest elenca il plugin tramite il suo percorso relativo a quella directory:

{
  "name": "acme-tools",
  "owner": { "name": "Acme" },
  "plugins": [
    { "name": "acme-guard", "source": "./plugins/acme-guard", "description": "Acme policy mod" }
  ]
}

Un plugin che Claude Code copia nella sua cache viene considerato di un utente, anche quando l'impostazione gestita enabledPlugins lo abilita. Questo vale per ogni plugin proveniente da una sorgente GitHub, git, URL o npm. Il suo mod viene eseguito tra i mod degli utenti, prependPlugins e appendPlugins lo ignorano, allowManagedModsOnly lo rifiuta e allowManagedHooksOnly ne impedisce il caricamento. 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 viene considerato tuo 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 ogni evento prima di qualsiasi mod degli utenti e ogni risultato dopo. Può modificare l'evento, rifiutarlo o saltare i mod degli utenti.
• 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

Questo esempio dichiara il marketplace acme-tools in /opt/acme/claude-plugins, abilita acme-guard da esso ed esegue quel mod per primo, seguito dalla protezione integrata:

{
  "extraKnownMarketplaces": {
    "acme-tools": {
      "source": { "source": "directory", "path": "/opt/acme/claude-plugins" }
    }
  },
  "enabledPlugins": { "acme-guard@acme-tools": true },
  "prependPlugins": ["acme-guard@acme-tools", "sec-default@builtin"]
}

Ogni chiave svolge un compito:

• extraKnownMarketplaces: indica la directory che contiene il marketplace acme-tools. path è il percorso assoluto della directory che contiene .claude-plugin/marketplace.json.
• enabledPlugins: attiva acme-guard per ogni utente che riceve queste impostazioni gestite
• prependPlugins: mette acme-guard al primo posto e la protezione integrata al secondo, entrambi prima di qualsiasi mod installato da un utente. Claude Code segue l'ordine che elenchi.

Per verificare che la macchina di un utente abbia ricevuto le impostazioni, consulta Verifica che un criterio sia in vigore.

Per verificare dove viene eseguito il mod, avvia una sessione su quella macchina con claude --debug e cerca l'id del mod nel log di debug:

• hooks module acme-guard@acme-tools loaded, con tier 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.

Queste regole stabiliscono quali id nei due elenchi hanno effetto:

• L'elenco sostituisce il valore predefinito: quando imposti prependPlugins nelle impostazioni gestite, includi sec-default@builtin per mantenere la protezione integrata. La protezione è integrata e non richiede una voce enabledPlugins.
• 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é file managed-mcp.json, e solo quando la credenziale della sessione non proviene da un /login Team 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. Imposta allowManagedModsOnly. 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.

Questo mod di criteri rifiuta qualsiasi mod di un utente il cui codice chiama $.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:

// The methods no user's mod may call, each spelled namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Runs each time another mod is about to load
  on('plugin.register', async ($, e, next) => {
    // Keep the calls in that mod's code that are on the blocked list
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Returning refuse keeps the mod from loading, and the text is the reason
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Let every other mod load
    return next(e)
  })

  // Record each tool call, then let it go ahead unchanged
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Record which mod wrote a file, then the path, quoted because the mod chose it
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

Il file registra tre hook:

• 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 come audit tool.call Bash per ogni chiamata a uno strumento, senza modificare nulla
• fs.write: scrive una riga come audit fs.write by reader "/tmp/notes.md" per ogni chiamata $.fs.write effettuata 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.

L'hook plugin.register legge due campi dell'evento:

• e.tier: dove verrebbe eseguito il mod, uno tra prepend, user, append o builtin. Ogni mod installato da una persona è user.
• e.uses.calls: i metodi dell'API dei mod che il mod chiama, ciascuno scritto come namespace.method, ad esempio process.run, senza il $. che claude plugin validate stampa

Quando un utente installa un mod che chiama $.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.

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 hook plugin.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:

const BLOCKED_CALLS = ['process.run', 'process.spawn']

// The same check as before, moved into a function of its own
async function checkMod($, e, next) {
  const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
  if (e.tier === 'user' && blocked.length > 0) {
    return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
  }
  return next(e)
}

export function register(on) {
  // The handler runs only when checkMod throws or exceeds its time limit
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Let your organization's mods and built-in mods load
    if (e.tier !== 'user') return next(e)
    // Refuse the user's mod that couldn't be checked
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

Con il gestore in funzione, un mod che era in fase di controllo quando il controllo ha generato un'eccezione o è scaduto non viene caricato, e la riga di rifiuto riporta il secondo motivo, come in 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 prependPlugins e appendPlugins si combinano con i mod degli utenti
• Impostazioni e variabili d'ambiente: tutte le impostazioni citate in questa pagina in un'unica tabella