SpyBara
Go Premium

plugins/mods/admin.md 2026-10-01 23:59 UTC to 2026-10-02 08:03 UTC

This page contains 106 additions and 55 deletions.

2026
Thu 1 23:59 Fri 2 09:02

Gestire i mod per la vostra organizzazione

Controllare i mod di Claude Code con impostazioni gestite: bloccare i mod installati dagli utenti, consentire solo i vostri, esaminare cosa può fare un mod e applicare la politica con il vostro 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 sandboxed. Attraverso le impostazioni gestite, voi decidete se i mod vengono eseguiti sulle macchine dei vostri utenti, quali e in quale ordine. Potete anche installare un mod vostro che osserva o rifiuta quello che fanno gli altri mod.

Questa pagina è per la persona che distribuisce le impostazioni gestite per Claude Code, sia come file, tramite MDM, che dalla console di amministrazione di claude.ai. I mod sono attivati per impostazione predefinita in Claude Code v2.1.287 e versioni successive. Iniziate con la sezione che corrisponde a quello che siete venuti a fare:

Impedire il caricamento dei mod installati dagli utenti

Per impedire il caricamento di ogni mod che i vostri utenti portano, impostate l'opzione allowManagedModsOnly sulla guardia incorporata, un mod di politica che Claude Code carica prima di ogni mod che un utente installa. 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 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

Per confermare l'opzione sulla macchina di un utente, avviate Claude Code lì con --plugin-dir e il percorso di una directory che contiene un mod, come claude --plugin-dir ./first-mod. Gli hook del mod non vengono eseguiti, e la trascrizione e il log di debug hanno il messaggio della guardia, che nomina il mod e allowManagedModsOnly. Se il mod viene caricato, vedere Verificare che una politica sia in vigore e le regole che decidono se un'opzione ha effetto.

Se avete impostato CLAUDE_CODE_ENABLE_FUNCTION_HOOKS a 0 durante l'accesso anticipato, sostituirlo con questa opzione. Claude Code v2.1.287 e versioni successive ignora la variabile a qualsiasi valore, quindi uno 0 lì lascia i mod attivi.

Sapere cosa accade per impostazione predefinita

Senza impostazioni mod proprie, questo è quello che i vostri utenti ottengono:

  • 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 tuoi 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 dal file di impostazioni che contiene la regola. Anche un blocco da parte di un hook PreToolUse nelle impostazioni gestite è definitivo. Entrambi si applicano alle chiamate agli strumenti di Claude. Nessuno dei due si applica 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 queste chiamate, impedisci il caricamento del mod oppure gestisci la chiamata in un mod di policy.

  • 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.

La fonte della guardia è pubblica nella directory mods/sec-default del repository di Claude Code.

Sapere quali controlli si applicano ancora

I mod non sostituiscono i controlli che avete già:

  • 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.

Nessuno di questi controlli sandboxes un mod. Un mod che consentite viene eseguito come l'utente, con l'accesso dell'utente a file, processi e la rete.

Decidere se lasciare i mod attivi

Un mod può fare più di altre parti di un plugin perché viene eseguito all'interno di Claude Code. Vede ogni prompt e chiamata di strumento, può cambiarli, e può consentire o negare una chiamata di strumento prima che un prompt di permesso appaia.

Quello che un utente può caricare come mod dipende dai controlli dei plugin che avete già:

I vostri controlli di plugin oggi Quello che un utente può caricare come mod
Nessuno Un mod da qualsiasi marketplace, da qualsiasi directory con --plugin-dir, o che Claude scrive durante una sessione
Una lista di consentiti del marketplace Un mod dai marketplace che consentite, o da qualsiasi directory con --plugin-dir. Un mod che Claude scrive durante una sessione viene caricato solo quando la lista di consentiti include skills-dir.
Una lista di consentiti del marketplace e disableSideloadFlags Un mod dai marketplace che consentite

Gestire i plugin per la tua organizzazione elenca i modi in cui un plugin viene caricato e l'impostazione che controlla ciascuno.

Per controllare i mod in un marketplace prima che i vostri utenti li installino, vedere Esaminare cosa può fare un mod. Per tenere fuori i mod degli utenti finché non lo avete fatto, vedere Impedire il caricamento dei mod installati dagli utenti.

Esaminare cosa può fare un mod

Potete vedere cosa un mod è in grado di fare senza eseguirlo. Nel vostro shell, eseguite claude plugin validate sulla directory del plugin:

claude plugin validate ./some-mod

Due righe nell'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, è come un mod raggiunge file, processi e la rete. Claude Code rifiuta di caricare un mod che usa l'API dei mod in un modo che questo comando non può leggere.

Guardate la riga calls: per questi:

Chiamata Cosa significa
$.fs.read, $.fs.write Legge o scrive file ovunque l'utente possa
$.process.run, $.process.spawn Avvia programmi come l'utente
$.http.fetch Fa richieste di rete
$.env.get, $.settings.read Legge variabili di ambiente e impostazioni, che possono contenere chiavi API. Una riga env reads: nell'output nomina ogni variabile.
$.env.set Imposta una variabile di ambiente per Claude Code e per ogni comando e server MCP che avvia dopo, che può cambiare quello che quei programmi eseguono. Una riga env writes: nomina ogni variabile.
$.mcp.call Chiama uno strumento su un server MCP connesso, secondo le regole di permesso della sessione
$.model.complete Usa il piano o la chiave API dell'utente per le chiamate di modello
$.prompt.submit Invia un prompt, e può inviarlo come le proprie parole dell'utente
$.session.send Invia un messaggio che un'altra sessione o subagent di Claude legge

Nella riga hooks:, tool.call e prompt.submit significano che il mod vede ogni chiamata di strumento e ogni prompt, e può cambiarli. session.append significa che il mod può riscrivere ogni riga della conversazione prima che sia archiviata. ui.render{component=AskUserQuestion} significa che il mod può ridisegnare il dialogo che Claude usa per chiedere all'utente una domanda. tool.check significa che il mod può approvare o negare una chiamata di strumento prima che un prompt di permesso appaia. Sapere cosa accade per impostazione predefinita elenca quale dei vostri regole e hook ha la precedenza sulla sua risposta.

Scegliere quanto consentire

Le politiche dei mod vanno da nessun mod installato affatto a qualsiasi mod che un utente sceglie, con il vostro mod che controlla gli altri, e ognuna è poche impostazioni gestite. Trovate la politica che volete nella prima colonna e impostate quello che la seconda colonna nomina. Distribuire impostazioni gestite copre dove vivono le impostazioni gestite.

Quello che volete Impostazioni
Nessun mod installato, con hook intatti Impostate allowManagedModsOnly e non distribuite mod vostri
Nessun mod installato e nessun hook affatto, inclusi i vostri hook gestiti Impostate disableAllHooks a true
Solo i mod della vostra organizzazione Impostate l'opzione allowManagedModsOnly della guardia, e installate i vostri mod in modo che contino come vostri
Qualsiasi mod dai marketplace che approvate Mantenete le vostre restrizioni del marketplace, e impostate disableSideloadFlags a true
Qualsiasi mod, con il vostro mod che controlla gli altri Installate il vostro mod, e elencatelo con sec-default@builtin in prependPlugins

Quello che ogni impostazione fa:

  • 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, e impedisce ai mod che Claude scrive durante una sessione di caricarsi. L'impostazione rifiuta anche --agents e --mcp-config. Leggi disableSideloadFlags prima di impostarla.

I mod incorporati in Claude Code, come il supporto AGENTS.md, non sono interessati da queste impostazioni. Ognuno ha il suo interruttore.

Un utente il cui mod non è stato caricato trova il motivo nel suo log di debug. Messaggi di rifiuto elenca le righe per allowManagedHooksOnly e disableAllHooks, e Messaggi dalla guardia incorporata ha la riga per allowManagedModsOnly.

Consentire solo i mod della tua organizzazione

Per eseguire i mod della tua organizzazione e bloccare quelli che portano gli utenti, distribuisci le impostazioni della riga Solo i mod della tua organizzazione della tabella delle politiche, più disableSideloadFlags. Con questo managed-settings.json completo, Claude Code rifiuta i mod propri degli utenti, quindi nessuno dei loro hook viene eseguito, e il tuo mod di politica 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 conti come tuo, e lo eseguono per primo con la guardia dopo di esso. Installare i mod della tua organizzazione e impostare l'ordine descrive la directory a cui puntano queste chiavi.
  • pluginConfigs: imposta l'opzione allowManagedModsOnly della guardia, così Claude Code rifiuta i mod propri degli utenti. I loro hook di impostazioni, righe di stato e /goal continuano a funzionare.
  • disableSideloadFlags: consulta disableSideloadFlags per i flag che rifiuta all'avvio

Per confermare la politica 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 che l'utente ha installato: 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 quali marketplace gli utenti possono aggiungere, combina questo file con le tue restrizioni del 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:

Impostare le opzioni sulla guardia incorporata

La guardia incorporata accetta delle opzioni. Impostale nelle impostazioni gestite sotto pluginConfigs, con chiave cc-plugin-sec-default@builtin, come fa l'esempio in Impedire il caricamento dei mod installati dagli utenti.

La tabella dà quello che i vostri utenti ottengono con ogni opzione non impostata e con essa impostata a true:

Opzione Non impostata true
allowManagedModsOnly I mod propri degli utenti vengono caricati Solo i mod della vostra organizzazione, e i mod incorporati in Claude Code, vengono caricati. Claude Code rifiuta ogni altro mod, incluso uno che un utente ha installato o nominato con --plugin-dir.
allowModsToOverrideDenyRules Le regole di negazione hanno la precedenza sui mod degli utenti Un mod di un utente che approva le chiamate di strumenti può approvare una chiamata che una regola deny rifiuta

Queste regole decidono 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, 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.

I messaggi dalla guardia incorporata sono quello che i vostri utenti vedono quando una delle due opzioni si applica.

Eseguire i mod propri della tua organizzazione

Puoi distribuire mod tuoi a ogni utente, scegliere dove vengono eseguiti rispetto ai mod degli utenti e usarne uno per applicare una politica.

Installare i mod della tua organizzazione e impostare l'ordine

I mod della tua organizzazione vengono caricati dove i mod degli utenti non lo fanno e possono essere eseguiti prima di loro, quindi Claude Code deve essere in grado di capire che un mod viene da te. Lo tratta come della tua organizzazione solo quando tutte queste condizioni sono vere:

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

Per soddisfarle, fai in modo che la tua gestione dei dispositivi copi la directory del marketplace nello stesso percorso su ogni macchina. Rendi la directory e ogni directory sopra di essa 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 mettere la directory su una macchina.

La directory contiene il manifesto 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 manifesto 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 conta come di un utente, anche quando le impostazioni gestite enabledPlugins lo abilitano. Questo riguarda ogni plugin da una fonte GitHub, git, URL o npm. Il suo mod viene eseguito tra i mod degli utenti, prependPlugins e appendPlugins lo saltano, e non viene caricato con allowManagedModsOnly o allowManagedHooksOnly. Il log di debug dell'utente ha 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 agire, ad esempio eseguire uno strumento, e lo passa a ogni mod a turno. Un mod che conta come tuo viene eseguito prima dei mod degli utenti anche quando non lo elenchi da nessuna parte. Per impostare la sua posizione, elenca il suo id in una di due impostazioni. L'id è il nome del plugin, @, e il nome del marketplace, come acme-guard@acme-tools.

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

Questo esempio dichiara il marketplace acme-tools in /opt/acme/claude-plugins, abilita acme-guard da esso ed esegue quel mod per primo, con la guardia incorporata dopo di esso:

{
  "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 per primo e la guardia incorporata per seconda, entrambi prima di qualsiasi mod che un utente installa. Claude Code segue l'ordine in cui li elenchi.

Per confermare che la macchina di un utente abbia ricevuto le impostazioni, consulta Verificare che una politica sia in vigore.

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

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

Queste regole decidono quali id nelle due liste hanno effetto:

  • La lista sostituisce il valore predefinito: quando imposti prependPlugins nelle impostazioni gestite, includi sec-default@builtin per mantenere la guardia incorporata. La guardia è incorporata e non ha bisogno di una voce enabledPlugins.
  • I tuoi id devono contare come tuoi: nelle impostazioni gestite, Claude Code salta un id il cui plugin non soddisfa le condizioni per un mod di un'organizzazione
  • I repository non possono impostarle: Claude Code legge entrambe le impostazioni dalle impostazioni gestite e mai dal file di impostazioni di un repository. Un utente può impostarle in ~/.claude/settings.json per ordinare i propri mod solo su una macchina senza impostazioni gestite, e solo quando non ha effettuato l'accesso con un piano Team o Enterprise. In qualsiasi altro caso, Claude Code ignora entrambe le chiavi nelle impostazioni dell'utente. Una lista lì non aggiunge né rimuove la guardia incorporata.

Applicare una politica con un mod tuo

Per tenere fuori ogni mod degli utenti, non hai bisogno di un mod tuo. Imposta allowManagedModsOnly. Scrivi un mod di politica quando vuoi ammettere alcuni mod degli utenti e rifiutarne altri, o per registrare ciò che fanno i mod.

Ogni volta che un altro mod sta per caricarsi, il tuo mod riceve la lista che claude plugin validate stampa, in un evento denominato plugin.register. Un mod in prependPlugins può leggere quella lista e rifiutare il mod. Può anche gestire qualsiasi chiamata dell'API dei mod per nome per registrare o rifiutare quella chiamata per ogni altro mod. Il nome è il metodo senza il $., quindi un hook su fs.write vede ogni chiamata $.fs.write.

Questo mod di politica 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 che un mod scrive. Poiché viene eseguito per primo, il log registra ciò che è stato richiesto, prima che qualsiasi mod di un utente 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, e non modifica nulla
  • fs.write: scrive una riga come audit fs.write by reader "/tmp/notes.md" per ogni chiamata $.fs.write che un altro mod effettua, e non modifica nulla. Il nome del mod viene per primo e il percorso è tra virgolette, quindi 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 che una persona installa è user.
  • e.uses.calls: i metodi dell'API dei mod che il mod chiama, ciascuno scritto namespace.method come 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 ha una riga che termina con refused by acme-guard: e il tuo motivo. Il rifiuto raggiunge anche la 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ò funzionare 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 che non è incorporato, incluso il tuo, finché l'utente non esegue /reload-plugins o non avvia una nuova sessione. E un utente che avvia Claude Code con --safe-mode lavora senza mod installati, incluso il tuo.

Creare un mod descrive i file di cui un mod ha bisogno. Testare un mod di politica contiene un file di test per questo mod di politica.

Rifiutare 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 restituisce 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 attivo, un mod che era in fase di controllo quando il controllo ha generato un'eccezione o è andato in timeout 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 tier user, quindi un controllo fallito non blocca i mod che la tua organizzazione elenca. Gestire un hook che fallisce descrive .catch per altri eventi.

Prossimi passi