Gerenciar mods para sua organização

Controle mods do Claude Code com configurações gerenciadas: interrompa mods instalados pelo usuário, permita apenas os seus, revise o que um mod pode fazer e aplique política com seu próprio mod.

Um mod é um plugin que executa código dentro do Claude Code com as permissões do usuário que o instalou. Mods não são sandboxed. Através de configurações gerenciadas, você decide se mods são executados nas máquinas dos seus usuários, quais são e em que ordem. Você também pode instalar um mod seu que monitora ou recusa o que outros mods fazem.

Esta página é para a pessoa que implanta configurações gerenciadas para Claude Code, seja como um arquivo, através de MDM ou do console de administração do claude.ai. Mods estão ativados por padrão no Claude Code v2.1.286 e posterior. Comece com a seção que corresponde ao que você veio fazer:

• Mantenha os mods próprios dos usuários fora, com ou sem mods seus: Interrompa mods instalados pelo usuário de serem carregados
• Veja o que seus usuários obtêm quando você não muda nada: Saiba o que acontece por padrão
• Deixe mods ativados com outras limitações: Escolha quanto permitir

[!NOTE]

Estes casos são cobertos em outras páginas:

• Você não implantou configurações gerenciadas antes: comece com Implantar configurações gerenciadas
• Você quer controlar quais plugins os usuários podem instalar: veja Gerenciar plugins para sua organização

Interrompa mods instalados pelo usuário de serem carregados

Para impedir que cada mod que seus usuários tragam execute seus hooks, defina a opção allowManagedModsOnly na guarda integrada, um mod de política que Claude Code carrega antes de cada mod que um usuário instala. A opção vai em configurações gerenciadas sob pluginConfigs, com chave cc-plugin-sec-default@builtin:

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

Com a opção definida em configurações gerenciadas:

• Nenhum mod que um usuário traz executa seus hooks: isso cobre um mod em um plugin que o usuário instalou, um mod carregado com --plugin-dir e um mod que Claude escreveu durante uma sessão
• Os mods da sua organização ainda são executados: um mod que conta como da sua organização não é verificado. Todos os outros mods contam como de um usuário e são recusados. Isso inclui um mod em um plugin que você habilita de um GitHub ou outro marketplace remoto, e um que sua organização ativa para seus membros no claude.ai. Se nenhum contar como seu, nenhum mod instalado executa seus hooks.
• Os usuários não podem desfazer: a guarda lê a opção apenas de configurações gerenciadas, então a mesma entrada em um arquivo de configurações de usuário, projeto ou local, ou em um arquivo passado com --settings, não muda nada
• Um arquivo ou política MDM cobre cada provedor: quando você entrega a opção como um arquivo ou através de MDM, funciona da mesma forma no Amazon Bedrock, na Agent Platform do Google Cloud e no Microsoft Foundry. Para entrega do console de administração do claude.ai, veja Disponibilidade de plataforma
• As outras personalizações dos usuários continuam funcionando: seus hooks em arquivos de configurações e no hooks/hooks.json dos plugins, linhas de status e /goal não são afetados
• Mods integrados continuam em execução: mods integrados ao Claude Code, como suporte a AGENTS.md, cada um tem seu próprio switch

Para confirmar a opção na máquina de um usuário, inicie Claude Code lá com --plugin-dir e o caminho de um diretório que contém um mod, como claude --plugin-dir ./first-mod. Os hooks do mod não são executados, e a transcrição e o log de depuração têm a mensagem da guarda, que nomeia o mod e allowManagedModsOnly. Se a mensagem não estiver lá, veja Verificar que uma política está em vigor e as regras que decidem se uma opção entra em vigor.

Se você definiu CLAUDE_CODE_ENABLE_FUNCTION_HOOKS como 0 durante acesso antecipado, substitua-o por esta opção. Claude Code v2.1.287 e posterior ignora a variável em qualquer valor, então um 0 lá deixa mods ativados.

Saiba o que acontece por padrão

Sem suas próprias configurações de mod, isto é o que seus usuários obtêm:

• Mods estão ativados. Um usuário pode instalar um plugin que contém um mod de qualquer marketplace que suas configurações de plugin permitam, ou carregar um de um diretório com --plugin-dir.

• Uma guarda integrada é executada primeiro. Claude Code carrega um mod integrado chamado sec-default@builtin antes de cada mod que um usuário instala. Os usuários não podem desativá-la. /plugin e o log de depuração a listam como cc-plugin-sec-default. A guarda é carregada quando qualquer um destes é verdadeiro:

  • A máquina tem configurações gerenciadas ou um arquivo managed-mcp.json
  • A sessão é executada com credenciais de /login de um plano Team ou Enterprise

  Um usuário com uma chave de API, ou no Amazon Bedrock, na Agent Platform do Google Cloud ou no Microsoft Foundry, obtém a guarda apenas em uma máquina que tem configurações gerenciadas ou managed-mcp.json. Uma sessão executada com um CLAUDE_CODE_OAUTH_TOKEN de longa duração também não conta como esse login, mesmo quando um login Team ou Enterprise está armazenado na máquina.

• O guard protege o que você gerencia. Um mod de um usuário não pode mudar o que seus hooks gerenciados recebem ou decidem, o prompt do sistema, seu CLAUDE.md gerenciado e outras instruções gerenciadas, o que qualquer mod lê como configurações, ou as ferramentas e descrições de seus servidores MCP gerenciados.

• Fora do que você gerencia, um mod de um usuário age como esse usuário. O mod mantém as permissões desse usuário: ainda pode ler e escrever arquivos, iniciar processos e fazer requisições de rede. Também pode reescrever chamadas de ferramenta e prompts, negar uma chamada de ferramenta e desenhar na interface.

• Regras de permissão e hooks PreToolUse têm precedência sobre o mod de um usuário. Com a guarda carregada, por padrão um mod de um usuário não pode aprovar uma chamada que uma regra deny recusa ou para a qual uma regra ask pede confirmação, qualquer que seja o arquivo de configurações que contém a regra. O mod também não pode aprovar uma chamada que qualquer hook PreToolUse bloqueou.

  Regras de permissão e hooks PreToolUse se aplicam às chamadas de ferramenta do Claude, não às chamadas $.fs e $.process de um mod. Com Read(.env) negado, um mod ainda pode ler esse arquivo com $.fs.read ou iniciar um programa que o faça. Para limitar as próprias chamadas $.fs e $.process de um mod, impeça o mod de ser carregado ou trate-as em um mod de política.

• Um mod de um usuário ainda pode ignorar alguns prompts. No modo auto, uma chamada que o mod aprova é executada sem uma verificação de classificador, a menos que a guarda esteja carregada e a sessão seja executada com --permission-prompt-tool ou um callback canUseTool do Agent SDK. Nesse caso, o classificador verifica a chamada primeiro. Para os prompts que a aprovação de um mod não ignora, veja Estender permissões com hooks.

A fonte do guard é pública no diretório mods/sec-default do repositório Claude Code.

Saiba quais controles ainda se aplicam

Mods não substituem os controles que você já tem:

• Hooks de configuração continuam funcionando. Hooks de comando, HTTP, prompt e agente em arquivos de configurações e em hooks/hooks.json de plugins são executados como antes, ao lado de mods.

• Regras de negação têm precedência onde o guard é carregado. Um mod de um usuário não pode aprovar uma chamada que uma regra deny recusa, a menos que você defina allowModsToOverrideDenyRules.

• Hooks gerenciados são executados primeiro. Um hook PreToolUse em configurações gerenciadas é executado antes do hook tool.call de qualquer mod, e quando esse hook gerenciado bloqueia uma chamada de ferramenta, nenhum hook tool.call de mod é executado para essa chamada. Se a chamada prosseguir e um mod a reescrever, seus hooks gerenciados são executados novamente na chamada reescrita, então, por padrão, ainda podem bloqueá-la.

  Hooks PreToolUse de outros arquivos de configurações e de plugins são executados após o último mod. Se um mod responder à própria chamada de ferramenta, a ferramenta nunca é executada, nem esses hooks. Veja A ordem em que mods são executados.

• Política de rede cobre $.http.fetch.

  • A política da sua organização não permite WebFetch: Claude Code também recusa toda requisição $.http.fetch de qualquer mod. Veja Disponibilidade do WebFetch.

  • Você desativa a ferramenta WebFetch com CLAUDE_CODE_DISABLE_WEB_FETCH ou uma regra de negação WebFetch, em configurações gerenciadas ou em qualquer outro arquivo de configurações: mods ainda podem fazer requisições $.http.fetch.

    Para impedi-las para todo mod que seus usuários instalam, impeça que mods instalados pelo usuário sejam carregados, ou faça hook de http.fetch em um mod de política e recuse requisições dos mods dos usuários. Dê a esse hook um handler .catch que também recuse, porque o Claude Code ignora um hook que falha e a requisição então prossegue. Se você apenas restringir quais plugins os usuários podem instalar, menos mods são carregados, mas os que você permite ainda fazem essas requisições.

  • Você define CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: um mod que você ou seus usuários instalam ainda pode fazer essas requisições. A variável bloqueia apenas os mods integrados ao Claude Code, além de qualquer requisição $.http.fetch que carregue as credenciais da Anthropic da sessão. Antes da v2.1.288, a variável bloqueava toda requisição $.http.fetch de qualquer mod.

  Nenhum desses casos cobre um programa que o mod inicia com $.process.run, que alcança a rede com o acesso próprio do usuário.

• Controles de plugin cobrem mods. Um mod é um plugin, então as configurações que restringem o que os usuários podem instalar, como strictKnownMarketplaces, decidem se ele pode ser instalado.

• Mods não podem mudar o prompt de permissão. Um mod pode restylar muito da interface do Claude Code, mas não o prompt de permissão, então não pode mudar o que um prompt mostra. Um mod ainda pode aprovar ou negar uma chamada de ferramenta antes do prompt aparecer, como Saiba o que acontece por padrão descreve.

• Prompts de confiança vêm primeiro. Em uma sessão interativa em um diretório que o usuário ainda não confiou, nenhum mod é carregado até que ele responda ao prompt de confiança.

• --safe-mode desativa mods instalados, incluindo os seus. Inicie uma sessão com claude --safe-mode para verificar se um mod causou um problema.

Nenhum desses controles faz sandbox de um mod. Um mod que você permite é executado como o usuário, com o acesso do usuário a arquivos, processos e a rede.

Saiba quais hooks do mod de um usuário não são executados

Onde a guarda integrada é carregada, um hook que o mod de um usuário registra em um destes eventos nunca é executado, e /plugin informa isso a esse usuário em uma nota. Nas linhas de session.append, door é o tipo de linha armazenada ao qual o hook é filtrado.

A guarda também ignora os hooks de um usuário em alguns outros casos, como as descrições das ferramentas da sua organização, em tool.describe, e a linha armazenada do texto de uma skill. /plugin não mostra nenhuma nota para esses casos. Se um hook em outro evento não faz nada, veja Descobrir por que um mod não faz nada.

A nota aparece nos detalhes do plugin e na aba Errors de /plugin. Ela requer o Claude Code v2.1.299 ou posterior. Ela nomeia cada hook da tabela como o mod o registrou, como neste exemplo:

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

Para permitir que esses hooks sejam executados, altere as configurações gerenciadas de uma de duas maneiras:

• Execute o mod como sendo da sua organização: instale o mod de modo que ele conte como seu. Seus hooks nesses eventos passam então a ser executados, e a guarda permanece carregada para todos os outros mods. O mod é ativado para todos que recebem essas configurações, e ele precisa ficar em um diretório que você coloca em cada máquina. Se você o listar em prependPlugins, mantenha sec-default@builtin na lista.
• Remova a guarda: deixe sec-default@builtin fora de prependPlugins. Uma lista vazia, "prependPlugins": [], é suficiente. Você perde a guarda inteira, não apenas esses eventos. O mod de um usuário pode então fazer o que a guarda de outra forma o impede de fazer, e as opções da guarda não se aplicam.

Se você entregar uma lista sem a guarda por meio de configurações gerenciadas pelo servidor, a guarda permanece carregada até que o servidor confirme as configurações para a sessão. Para confirmar qualquer uma das alterações em uma máquina que executa a v2.1.299 ou posterior, abra /plugin em uma sessão nela e verifique se a nota desapareceu.

Um hook session.append sem filtro door ainda é executado e não recebe nenhuma nota, mas as linhas armazenadas da tabela não chegam até ele.

Decida se deixa mods ativados

Um mod pode fazer mais do que as outras partes de um plugin porque é executado dentro do Claude Code. Ele vê cada prompt e chamada de ferramenta, pode mudá-los e pode permitir ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer.

O que um usuário pode carregar como um mod depende dos controles de plugin que você já tem:

Gerenciar plugins para sua organização lista as formas como um plugin é carregado e a configuração que controla cada uma.

Para verificar os mods em um marketplace antes de seus usuários instalá-los, veja Revise o que um mod pode fazer. Para manter os mods dos usuários fora até ter feito isso, veja Interrompa mods instalados pelo usuário de serem carregados.

Revise o que um mod pode fazer

Você pode ver o que um mod é capaz de fazer sem executá-lo. Em seu shell, execute claude plugin validate no diretório do plugin:

claude plugin validate ./some-mod

As linhas hooks: e calls: na saída descrevem o código do mod:

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

A linha hooks: lista os eventos que o mod recebe. A linha calls: lista os métodos da API de mods que seu código chama. A API de mods, escrita como $ no código de um mod, é como um mod alcança arquivos, processos e a rede. Claude Code recusa carregar um mod que usa a API de mods de uma forma que este comando não consegue ler.

Procure na linha calls: por estes:

Na linha hooks:, tool.call e prompt.submit significam que o mod vê cada chamada de ferramenta e cada prompt, e pode mudá-los. session.append significa que o mod pode reescrever cada linha da conversa antes de ser armazenada, exceto as linhas que a proteção ignora. ui.render{component=AskUserQuestion} significa que o mod pode redesenhar o diálogo que Claude usa para fazer uma pergunta ao usuário. tool.check significa que o mod pode aprovar ou negar uma chamada de ferramenta antes de um prompt de permissão aparecer. Saiba o que acontece por padrão lista quais de suas regras e hooks têm precedência sobre sua resposta.

Escolha quanto permitir

Políticas de mod variam de nenhum mod instalado a qualquer mod que um usuário escolha, com seu próprio mod verificando os outros, e cada uma é algumas configurações gerenciadas. Encontre a política que você quer na primeira coluna e defina o que a segunda coluna nomeia. Implantar configurações gerenciadas cobre onde as configurações gerenciadas vivem.

O que cada configuração faz:

• allowManagedModsOnly: uma opção na guarda integrada. Claude Code recusa os mods próprios dos usuários, então nenhum dos hooks deles é executado. Os hooks de configuração, linhas de status e /goal dos usuários continuam funcionando. Interrompa mods instalados pelo usuário de serem carregados lista o que cobre.
• allowManagedHooksOnly: uma configuração mais ampla. Apenas mods da sua organização e mods integrados ao Claude Code são carregados. Um mod que um usuário instalou por si só não é. A configuração também bloqueia hooks em arquivos de configurações próprios dos usuários. Leia O que é executado sob allowManagedHooksOnly antes de defini-la.
• disableAllHooks: a configuração mais ampla. Em configurações gerenciadas, ela interrompe os mods em cada plugin instalado, incluindo os seus, e desativa cada hook em arquivos de configurações, então um hook PreToolUse em suas configurações gerenciadas não bloqueia mais nada. Linhas de status personalizadas e /goal também param de funcionar. Leia disableAllHooks antes de defini-la.
• disableSideloadFlags: rejeita --plugin-dir e --plugin-url na inicialização, e impede que mods que Claude escreve durante uma sessão sejam carregados. A configuração também rejeita --agents e --mcp-config. Leia disableSideloadFlags antes de defini-la.

Mods integrados ao Claude Code, como suporte a AGENTS.md, não são afetados por essas configurações. Cada um tem seu próprio switch.

Um usuário cujo mod foi recusado ou não foi carregado encontra a razão em seu log de depuração. Mensagens de recusa lista as linhas para allowManagedHooksOnly e disableAllHooks, e Mensagens da guarda integrada tem a linha para allowManagedModsOnly.

Permita apenas os mods da sua organização

Para executar os mods da sua organização e bloquear os que os usuários trazem, implante as configurações da linha Apenas mods da sua organização da tabela de políticas, mais disableSideloadFlags. Com este managed-settings.json completo, Claude Code recusa os mods próprios dos usuários, então nenhum dos hooks deles é executado, e seu mod de política é executado antes dos outros mods:

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

Cada grupo de chaves faz um trabalho:

• extraKnownMarketplaces, enabledPlugins e prependPlugins: instalam seu mod para que ele conte como seu, e o executam primeiro com a guarda integrada depois dele. Instale os mods da sua organização e defina a ordem cobre o diretório para o qual essas chaves apontam.
• pluginConfigs: define a opção allowManagedModsOnly da guarda integrada, então Claude Code recusa os mods próprios dos usuários. Os hooks de configuração, linhas de status e /goal deles continuam funcionando.
• disableSideloadFlags: consulte disableSideloadFlags para ver as flags que ela rejeita na inicialização

Para confirmar a política em uma máquina de teste, no seu shell inicie uma sessão com claude --debug e leia o log de depuração:

• Seu mod: sua linha hooks module tem tier prepend
• Um mod que o usuário instalou: uma linha diz refused by cc-plugin-sec-default: mods are limited to your organization's by policy (allowManagedModsOnly). Uma linha anterior diz que o módulo de hooks desse mod foi loaded, então procure a recusa.
• Um diretório de plugin: claude --plugin-dir ./any-mod sai com uma mensagem que começa com --plugin-dir is disabled by your organization's managed settings (disableSideloadFlags)

Para também limitar quais marketplaces os usuários podem adicionar, combine este arquivo com suas restrições de marketplace.

Aplique seus controles de plugin aos mods

Um mod é um plugin, então as formas como você gerencia plugins para sua organização também se aplicam a um plugin que contém um mod:

• Veja quais plugins são carregados em toda a sua frota: Auditar e revisar
• Decida quando um plugin que você revisou pode ser atualizado: Definir política de atualização
• Dê a um grupo uma política diferente, como um piloto: Planeje para o que as configurações gerenciadas não podem impor
• Verifique quais apps e tipos de sessão aplicam as chaves de plugin: Quando cada superfície aplica as chaves de plugin
• Configure CI e contêineres: Preparar contêineres e CI
• Ofereça mods que seus usuários podem instalar: Hospedar um marketplace. Um mod que Claude Code copia de uma fonte GitHub, git, URL ou npm conta como de um usuário, não como da sua organização.

Defina opções na guarda integrada

A guarda integrada aceita opções. Defina-as em configurações gerenciadas sob pluginConfigs, com chave cc-plugin-sec-default@builtin, como o exemplo em Interrompa mods instalados pelo usuário de serem carregados faz.

A tabela fornece o que seus usuários obtêm com cada opção não definida e com ela definida como true:

Estas regras decidem se uma opção entra em vigor:

• O id tem uma forma aqui: Claude Code lê as opções apenas sob cc-plugin-sec-default@builtin. prependPlugins aceita sec-default@builtin também, e pluginConfigs não.
• Apenas configurações gerenciadas contam: a mesma entrada em um arquivo de configurações de usuário, projeto ou local, ou em um arquivo passado com --settings, nem define uma opção nem afrouxa uma
• A guarda integrada tem que ser carregada: se você definir prependPlugins, nomeie a guarda integrada na lista. Onde a guarda integrada não é carregada, nenhuma opção se aplica.
• A guarda integrada falha fechada: se a guarda integrada não conseguir ler configurações gerenciadas, ela recusa cada mod de um usuário ao carregar. Se não conseguir verificar as regras de negação para uma chamada que um mod de um usuário aprovou, ela recusa a chamada.

As mensagens da guarda integrada são o que seus usuários veem quando qualquer opção se aplica.

Execute mods próprios da sua organização

Você pode implantar mods seus para cada usuário, escolher onde são executados em relação aos mods dos usuários, e usar um para aplicar uma política.

Instale mods da sua organização e defina a ordem

Os mods da sua organização são carregados onde mods dos usuários não são e podem ser executados antes deles, então Claude Code tem que ser capaz de dizer que um mod veio de você. Ele trata um mod como da sua organização apenas quando todos estes são verdadeiros:

• enabledPlugins gerenciado define o plugin do mod como true
• Configurações gerenciadas nomeiam o marketplace do plugin como um diretório na máquina do usuário, por caminho absoluto. Uma entrada extraKnownMarketplaces faz isso e registra o marketplace para o usuário também.
• O marketplace lista o plugin por um caminho relativo, então Claude Code o carrega no lugar daquele diretório

Para atender a eles, tenha seu gerenciamento de dispositivo copiar o diretório do marketplace para o mesmo caminho em cada máquina. Faça o diretório e cada diretório acima dele graváveis apenas por um administrador, como o arquivo de configurações gerenciadas é. Qualquer um que possa escrever lá pode reescrever seu mod. Configurações gerenciadas que você entrega do console de administração do claude.ai podem carregar as chaves, mas não podem colocar o diretório em uma máquina.

O diretório contém o manifesto do marketplace e o plugin:

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

O manifesto lista o plugin por seu caminho relativo àquele diretório:

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

Um plugin que Claude Code copia em seu cache conta como de um usuário, mesmo quando enabledPlugins gerenciado o habilita. Isso cobre cada plugin de uma fonte GitHub, git, URL ou npm. Seu mod é executado entre mods dos usuários, prependPlugins e appendPlugins o pulam, allowManagedModsOnly o recusa, e allowManagedHooksOnly impede que ele seja carregado. O log de depuração do usuário tem uma linha que começa com o id do plugin e is enabled by managed settings, but.

Claude Code levanta um evento cada vez que está prestes a agir, como executar uma ferramenta, e o passa para cada mod por sua vez. Um mod que conta como seu é executado antes dos mods dos usuários mesmo quando você não o lista em lugar nenhum. Para definir seu lugar, liste seu id em uma de duas configurações. O id é o nome do plugin, @, e o nome do marketplace, como acme-guard@acme-tools.

• prependPlugins: seu mod vê cada evento antes de qualquer mod de um usuário e cada resultado depois. Pode mudar o evento, recusá-lo ou pular os mods dos usuários.
• appendPlugins: seu mod é executado após cada mod de um usuário, então vê apenas os eventos que aqueles mods passam, na forma que os passam

Este exemplo declara o marketplace acme-tools em /opt/acme/claude-plugins, habilita acme-guard dele, e executa esse mod primeiro, com a guarda integrada depois:

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

Cada chave faz um trabalho:

• extraKnownMarketplaces: nomeia o diretório que contém o marketplace acme-tools. path é o caminho absoluto do diretório que contém .claude-plugin/marketplace.json.
• enabledPlugins: ativa acme-guard para cada usuário que recebe essas configurações gerenciadas
• prependPlugins: coloca acme-guard primeiro e a guarda integrada em segundo, ambos antes de qualquer mod que um usuário instala. Claude Code segue a ordem que você lista.

Para confirmar que a máquina de um usuário recebeu as configurações, veja Verificar que uma política está em vigor.

Para confirmar onde o mod é executado, inicie uma sessão naquela máquina com claude --debug e procure no log de depuração pelo id do mod:

• hooks module acme-guard@acme-tools loaded, com tier prepend: o mod conta como da sua organização e é executado primeiro
• A mesma linha com tier user: Claude Code o trata como um mod de um usuário. Uma segunda linha, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, diz que a lista o pulou.

Estas regras decidem quais ids nas duas listas entram em vigor:

• A lista substitui o padrão: quando você define prependPlugins em configurações gerenciadas, nomeie sec-default@builtin nela para manter a guarda integrada. A guarda é integrada e não precisa de uma entrada enabledPlugins.
• Seus próprios ids devem contar como seus: em configurações gerenciadas, Claude Code pula um id cujo plugin não atende às condições para um mod da organização
• Repositórios não podem definir nenhuma das listas: Claude Code ignora ambas no arquivo de configurações de um repositório, então defina-as em configurações gerenciadas.
• Um usuário pode defini-las para ordenar seus próprios mods: em ~/.claude/settings.json, apenas em uma máquina sem configurações gerenciadas ou arquivo managed-mcp.json, e apenas quando a credencial da sessão não é um /login Team ou Enterprise. Em qualquer outro lugar, Claude Code ignora ambas as chaves em configurações de usuário. Uma lista lá nem adiciona nem remove a guarda integrada.

Aplique uma política com um mod seu

Para manter cada mod de um usuário fora, você não precisa de um mod seu. Defina allowManagedModsOnly. Escreva um mod de política quando você quer permitir alguns mods dos usuários e recusar outros, ou para registrar o que mods fazem.

Cada vez que outro mod está prestes a ser carregado, seu mod recebe a lista que claude plugin validate imprime, em um evento nomeado plugin.register. Um mod em prependPlugins pode ler essa lista e recusar o mod. Também pode tratar qualquer chamada da API de mods por nome para registrar ou recusar essa chamada para cada outro mod. O nome é o método sem o $., então um hook em fs.write vê cada chamada $.fs.write.

Este mod de política recusa qualquer mod de um usuário cujo próprio código chama $.process.run ou $.process.spawn. Também mantém um log de auditoria, escrevendo cada chamada de ferramenta e cada arquivo que um mod escreve no log de depuração. Porque é executado primeiro, o log registra o que foi solicitado, antes de qualquer mod de um usuário mudá-lo. Salve-o como 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)
  })
}

O arquivo registra três hooks:

• plugin.register: decide se outro mod é carregado. Recusa um mod de um usuário que chama um método bloqueado e passa cada outro mod adiante.
• tool.call: escreve uma linha como audit tool.call Bash no log de depuração para cada chamada de ferramenta, e não muda nada
• fs.write: escreve uma linha como audit fs.write by reader "/tmp/notes.md" para cada chamada $.fs.write que outro mod faz, e não muda nada. O nome do mod vem primeiro e o caminho é entre aspas, então um caminho que um mod escolhe não pode passar por outro campo da linha.

O hook plugin.register lê dois campos do evento:

• e.tier: onde o mod seria executado, um de prepend, user, append ou builtin. Cada mod que uma pessoa instala é user.
• e.uses.calls: os métodos da API de mods que o mod chama, cada um escrito namespace.method como process.run, sem o $. que claude plugin validate imprime

Quando um usuário instala um mod que chama $.process.run, o mod não é carregado, e seu log de depuração tem uma linha que termina com refused by acme-guard: e sua razão. A recusa também alcança a transcrição em uma sessão que recarrega a quente um diretório de plugin. Para bloquear uma chamada sem recusar o mod inteiro, retorne { deny: 'your reason' } de um hook no nome daquela chamada.

Para enviar as linhas de auditoria para algum lugar que não seja o log de depuração, chame $.http.fetch dos mesmos hooks.

Uma sessão pode ser executada sem seu mod. Se a thread de trabalho que executa mods instalados falhar três vezes, Claude Code descarrega cada mod que não é integrado, incluindo o seu, até que o usuário execute /reload-plugins ou inicie uma nova sessão. E um usuário que inicia Claude Code com --safe-mode é executado sem mods instalados, incluindo os seus.

Criar um mod cobre os arquivos que um mod precisa. Testar um mod de política tem um arquivo de teste para este mod de política.

Recuse mods quando sua verificação falha

Se seu hook plugin.register lança ou excede seu limite de tempo, Claude Code pula o hook, então a verificação falha aberta e o mod que estava verificando é carregado. Para falhar fechado e recusar mods dos usuários, mova a verificação para uma função nomeada e adicione um manipulador .catch que retorna a recusa. Esta versão do arquivo mostra apenas o hook plugin.register, então mantenha os dois hooks de auditoria da primeira versão em register:

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' }
  })
}

Com o manipulador em vigor, um mod que estava sendo verificado quando a verificação lançou ou expirou não é carregado, e a linha de recusa carrega a segunda razão, como em refused by acme-guard: Acme policy check failed, so this mod was not loaded. O manipulador passa cada mod fora do tier user para next(e), então uma verificação falhada não interrompe os mods que sua organização lista. Manipule um hook que falha cobre .catch para outros eventos.

Próximos passos

• Segurança de plugin: o que qualquer plugin pode fazer na máquina de um usuário e como revisar um antes de ser instalado
• Visão geral de mods: o que é um mod e como se compara a hooks, skills e servidores MCP
• A ordem em que mods são executados: como prependPlugins e appendPlugins se encaixam com mods dos usuários
• Configurações e variáveis de ambiente: cada configuração nomeada nesta página em uma tabela