Gerenciar mods para sua organização

• 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

​

Interrompa mods instalados pelo usuário de serem carregados

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

• 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

​

Saiba o que acontece por padrão

• 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
  • A sessão é executada com credenciais de /login de um plano Team ou Enterprise
  Um usuário que se autentica com uma chave de API, ou através do Amazon Bedrock, da Agent Platform do Google Cloud ou do Microsoft Foundry, obtém a guarda apenas em uma máquina que tem configurações gerenciadas. 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.

​

Saiba quais controles ainda se aplicam

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

​

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

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

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

​

Decida se deixa mods ativados

​

Revise o que um mod pode fazer

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

​

Escolha quanto permitir

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

​

Permita apenas os mods da sua organização

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

• 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

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

​

Aplique seus controles de plugin aos mods

• 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

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

​

Execute mods próprios da sua organização

​

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

• 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

/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: 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

{
  "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: 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.

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

• 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 defini-los: Claude Code lê ambas as configurações de configurações gerenciadas e nunca de um arquivo de configurações de um repositório. Um usuário pode defini-los em ~/.claude/settings.json para ordenar seus próprios mods apenas em uma máquina sem configurações gerenciadas, 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

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

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

• 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

​

Recuse mods quando sua verificação falha

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

​

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