Gestire i mod per la vostra organizzazione

• Tenere fuori i mod propri degli utenti, con o senza mod vostri: Impedire il caricamento dei mod installati dagli utenti
• Vedere cosa ottengono i vostri utenti quando non cambiate nulla: Sapere cosa accade per impostazione predefinita
• Lasciare i mod attivi con altri limiti: Scegliere quanto consentire

​

Impedire il caricamento dei mod installati dagli utenti

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

• Nessun mod che un utente porta viene caricato: questo copre un mod in un plugin che l’utente ha installato, un mod caricato con --plugin-dir, e un mod che Claude ha scritto durante una sessione
• I mod della vostra organizzazione continuano a caricarsi: un mod che conta come della vostra organizzazione non viene controllato. Ogni altro mod conta come di un utente e non viene caricato. Questo include un mod in un plugin che abilitate da un marketplace GitHub o altro remoto, e uno che la vostra organizzazione attiva per i suoi membri su claude.ai. Se nessuno conta come vostro, nessun mod installato viene caricato.
• Gli utenti non possono annullarlo: la guardia legge l’opzione solo dalle impostazioni gestite, quindi la stessa voce in un file di impostazioni utente, progetto o locale, o in un file passato con --settings, non cambia nulla
• Un file o una politica MDM copre ogni provider: quando consegnate l’opzione come file o tramite MDM, funziona allo stesso modo su Amazon Bedrock, Agent Platform di Google Cloud e Microsoft Foundry. Per la consegna dalla console di amministrazione di claude.ai, vedere Disponibilità della piattaforma
• Le altre personalizzazioni degli utenti continuano a funzionare: i loro hook nei file di impostazioni, le righe di stato e /goal non sono interessati
• I mod incorporati continuano a funzionare: i mod incorporati in Claude Code, come il supporto AGENTS.md, hanno ciascuno il loro interruttore

​

Sapere cosa accade per impostazione predefinita

• I mod sono attivi. Un utente può installare un plugin che contiene un mod da qualsiasi marketplace che le vostre impostazioni di plugin consentono, o caricarne uno da una directory con --plugin-dir.
• Una guardia incorporata viene eseguita per prima. Claude Code carica un mod incorporato denominato sec-default@builtin prima di ogni mod che un utente installa. Gli utenti non possono disattivarla. /plugin e il log di debug la elencano come cc-plugin-sec-default. La guardia viene caricata quando una di queste è vera:
  • La macchina ha impostazioni gestite
  • L’utente è connesso a Claude Code con un piano Team o Enterprise
  Un utente che si autentica con una chiave API, o tramite Amazon Bedrock, Agent Platform di Google Cloud, o Microsoft Foundry, ottiene la guardia solo su una macchina che ha impostazioni gestite.
• La guardia protegge quello che gestite. Un mod di un utente non può cambiare quello che i vostri hook gestiti ricevono o decidono, il prompt di sistema, il vostro CLAUDE.md gestito e altre istruzioni gestite, quello che qualsiasi mod legge come impostazioni, o gli strumenti e le descrizioni dei vostri server MCP gestiti.
• Tutto il resto è consentito. La guardia non aggiunge altre restrizioni. Un mod di un utente può comunque leggere e scrivere file, avviare processi, fare richieste di rete, riscrivere chiamate di strumenti e prompt, negare una chiamata di strumento, approvare una che altrimenti richiederebbe un prompt, e disegnare nell’interfaccia, tutto con i permessi di quell’utente.
• Le regole di negazione e i vostri hook gestiti hanno la precedenza. Dove la guardia viene caricata, un mod di un utente non può approvare una chiamata che una regola deny rifiuta, indipendentemente da quale file di impostazioni contiene la regola. Un blocco da un hook PreToolUse nelle impostazioni gestite è definitivo anche. Entrambi si applicano alle chiamate di strumenti di Claude. Nessuno si applica alle chiamate proprie di un mod $.fs e $.process: con Read(.env) negato, un mod può comunque leggere quel file con $.fs.read o avviare un programma che lo fa. Per limitare quelle chiamate, impedire al mod di caricarsi o agganciare la chiamata in un mod di politica.
• Altri controlli di permesso possono essere ignorati. Un mod di un utente che approva le chiamate di strumenti può approvare una chiamata che una regola ask richiederebbe un prompt, o che un hook PreToolUse al di fuori delle impostazioni gestite ha bloccato. In modalità automatica, una chiamata che il mod approva viene eseguita senza un controllo del classificatore.

​

Sapere quali controlli si applicano ancora

• Gli hook di impostazioni continuano a funzionare. Gli hook di comando, HTTP, prompt e agente nei file di impostazioni e nel hooks/hooks.json dei plugin vengono eseguiti come prima, insieme ai mod. Nulla di loro è deprecato.
• Le regole di negazione hanno la precedenza dove la guardia viene caricata. Un mod di un utente non può approvare una chiamata che una regola deny rifiuta, a meno che non impostiate allowModsToOverrideDenyRules.
• Gli hook gestiti vengono eseguiti per primi. Un hook PreToolUse nelle impostazioni gestite viene eseguito prima che qualsiasi mod veda la chiamata di strumento, e il suo blocco è definitivo. Se un mod poi riscrive la chiamata, i vostri hook gestiti vengono eseguiti di nuovo sulla chiamata riscritta, quindi un blocco si applica comunque. Gli hook PreToolUse da altri file di impostazioni e dai plugin vengono eseguiti dopo l’ultimo mod, quindi un mod che restituisce il suo proprio risultato al posto di eseguire lo strumento impedisce a quelli di funzionare. Vedere L’ordine in cui i mod vengono eseguiti.
• La politica di rete copre $.http.fetch. Se la vostra organizzazione disattiva il recupero web, o il traffico di rete non essenziale è disattivato per la sessione, Claude Code rifiuta una richiesta di rete che un mod fa con $.http.fetch. La politica non copre un programma che il mod avvia con $.process.run. Quel programma raggiunge la rete con l’accesso proprio dell’utente.
• I controlli dei plugin coprono i mod. Un mod è un plugin, quindi le impostazioni che limitano quello che gli utenti possono installare, come strictKnownMarketplaces, decidono se può essere installato affatto.
• I mod non possono cambiare il prompt di permesso. Un mod può ridisegnare gran parte dell’interfaccia di Claude Code, ma non il prompt di permesso, quindi non può cambiare quello che un prompt mostra. Un mod può comunque approvare o negare una chiamata di strumento prima che il prompt appaia, come Sapere cosa accade per impostazione predefinita descrive.
• I prompt di fiducia vengono per primi. In una sessione interattiva in una directory che l’utente non ha ancora fiducia, nessun mod viene caricato finché non rispondono al prompt di fiducia.
• --safe-mode disattiva i mod installati, inclusi i vostri. Avviate una sessione con claude --safe-mode per verificare se un mod ha causato un problema.

​

Decidere se lasciare i mod attivi

​

Esaminare cosa può fare un mod

claude plugin validate ./some-mod

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

​

Scegliere quanto consentire

• allowManagedModsOnly: un’opzione sulla guardia incorporata. I mod propri degli utenti non vengono caricati, e i loro hook di impostazioni, righe di stato e /goal continuano a funzionare. Impedire il caricamento dei mod installati dagli utenti elenca quello che copre.
• allowManagedHooksOnly: un’impostazione più ampia. Solo i mod della vostra organizzazione e i mod incorporati in Claude Code vengono caricati. Un mod che un utente ha installato da solo non lo fa. L’impostazione blocca anche gli hook nei file di impostazioni propri degli utenti. Leggete Quello che viene eseguito sotto allowManagedHooksOnly prima di impostarla.
• disableAllHooks: l’impostazione più ampia. Nelle impostazioni gestite, ferma i mod in ogni plugin installato, incluso il vostro, e disattiva ogni hook nei file di impostazioni, quindi un hook PreToolUse nelle vostre impostazioni gestite non blocca più nulla. Le righe di stato personalizzate e /goal smettono di funzionare anche. Leggete disableAllHooks prima di impostarla.
• disableSideloadFlags: rifiuta --plugin-dir e --plugin-url all’avvio, quindi nessuno carica un mod da una directory, e impedisce ai mod che Claude scrive durante una sessione di caricarsi. L’impostazione rifiuta anche --agents e --mcp-config. Leggete disableSideloadFlags prima di impostarla.

​

Impostare le opzioni sulla guardia incorporata

• L’id ha una sola ortografia qui: Claude Code legge le opzioni solo sotto cc-plugin-sec-default@builtin. prependPlugins accetta anche sec-default@builtin, e pluginConfigs no.
• Solo le impostazioni gestite contano: la stessa voce in un file di impostazioni utente, progetto o locale, o in un file passato con --settings, né imposta un’opzione né ne allenta una
• La guardia deve caricarsi: se impostate prependPlugins, nominate la guardia nella lista. Dove la guardia non viene caricata, nessuna opzione si applica.
• La guardia fallisce chiusa: se la guardia non può leggere le impostazioni gestite, rifiuta ogni mod di un utente al caricamento. Se non può controllare le regole di negazione per una chiamata che un mod di un utente ha approvato, rifiuta la chiamata.

​

Eseguire i mod propri della vostra organizzazione

​

Installare i mod della vostra organizzazione e impostare l’ordine

• Le impostazioni gestite enabledPlugins impostano il plugin del mod a true
• Le impostazioni gestite nominano il marketplace del plugin come una directory sulla macchina dell’utente, per percorso assoluto. Una voce extraKnownMarketplaces fa questo e registra il marketplace per l’utente anche.
• Il marketplace elenca il plugin per un percorso relativo, quindi Claude Code lo carica in place da quella directory

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

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

• prependPlugins: il vostro mod vede ogni evento prima di qualsiasi mod di un utente e ogni risultato dopo. Può cambiare l’evento, rifiutarlo, o saltare i mod degli utenti.
• appendPlugins: il vostro mod viene eseguito dopo ogni mod di un utente, quindi vede solo gli eventi che quei mod passano, nella forma che li passano

{
  "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"]
}

• extraKnownMarketplaces: nomina 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 per primo e la guardia incorporata per secondo, entrambi prima di qualsiasi mod che un utente installa. Claude Code segue l’ordine che elencate.

• hooks module acme-guard@acme-tools loaded, con tier prepend: il mod conta come della vostra 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, dice che la lista lo ha saltato.

• La lista sostituisce il valore predefinito: quando impostate prependPlugins nelle impostazioni gestite, nominate sec-default@builtin in essa per mantenere la guardia incorporata. La guardia è incorporata e non ha bisogno di una voce enabledPlugins.
• I vostri id devono contare come vostri: nelle impostazioni gestite, Claude Code salta un id il cui plugin non soddisfa le tre condizioni per un mod di un’organizzazione
• I repository non possono impostarli: Claude Code legge entrambe le impostazioni dalle impostazioni gestite e mai da un file di impostazioni di un repository. Un utente può impostarli in ~/.claude/settings.json per ordinare i loro mod propri solo su una macchina senza impostazioni gestite, e solo quando non sono connessi con un piano Team o Enterprise. Ovunque altro, Claude Code ignora entrambe le chiavi nelle impostazioni dell’utente. Una lista lì né aggiunge né rimuove la guardia incorporata.

​

Applicare una politica con un mod vostro

// I metodi che nessun mod di un utente può chiamare, ognuno scritto namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Viene eseguito ogni volta che un altro mod sta per caricarsi
  on('plugin.register', async ($, e, next) => {
    // Mantieni le chiamate in quel mod il cui codice è sulla lista bloccata
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Restituire refuse impedisce al mod di caricarsi, e il testo è il motivo
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Lascia caricare ogni altro mod
    return next(e)
  })

  // Registra ogni chiamata di strumento, poi lasciala andare avanti invariata
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Registra quale mod ha scritto un file, poi il percorso, tra virgolette perché il mod lo ha scelto
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

• plugin.register: decide se un altro mod viene caricato. Rifiuta un mod di un utente che chiama un metodo bloccato e passa ogni altro mod.
• tool.call: scrive una riga come audit tool.call Bash nel log di debug per ogni chiamata di strumento, e non cambia nulla
• fs.write: scrive una riga come audit fs.write by reader "/tmp/notes.md" per ogni chiamata $.fs.write che un altro mod fa, e non cambia nulla. Il nome del mod viene per primo e il percorso è tra virgolette, quindi un percorso che un mod sceglie non può passare per un altro campo della riga.

• e.tier: dove il mod verrebbe eseguito, uno di prepend, user, append, o builtin. Ogni mod che una persona installa è user.
• e.uses.calls: i metodi dell’API dei mod che il mod chiama, ognuno scritto namespace.method come process.run, senza il $. che claude plugin validate stampa

​

Rifiutare i mod quando il vostro controllo fallisce

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

// Lo stesso controllo di prima, spostato in una funzione propria
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) {
  // Il gestore viene eseguito solo quando checkMod genera un'eccezione o supera il suo limite di tempo
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Lascia caricare i mod della vostra organizzazione e i mod incorporati
    if (e.tier !== 'user') return next(e)
    // Rifiuta il mod dell'utente che non poteva essere controllato
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

​

Prossimi passi

• Sicurezza dei plugin: quello che qualsiasi plugin può fare sulla macchina di un utente, e come esaminarne uno prima che sia installato
• Panoramica dei mod: cosa è un mod e come si confronta con hook, skills e server MCP
• L’ordine in cui i mod vengono eseguiti: come prependPlugins e appendPlugins si adattano ai mod degli utenti
• Impostazioni e variabili di ambiente: ogni impostazione nominata su questa pagina in una tabella