SpyBara
Go Premium

plugins/mods/admin.md 2026-09-30 23:00 UTC to 2026-10-01 21:59 UTC

This page contains 375 additions and 0 deletions.

2026
Thu 1 23:02

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.287 e posterior. Comece com a seção que corresponde ao que você veio fazer:

Interrompa mods instalados pelo usuário de serem carregados

Para impedir que cada mod que seus usuários tragam seja carregado, defina a opção allowManagedModsOnly no guard integrado, 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 é carregado: 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 carregados: um mod que conta como da sua organização não é verificado. Todos os outros mods contam como de um usuário e não são carregados. 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 é carregado.
  • Os usuários não podem desfazer: o guard 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, 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 do guard, que nomeia o mod e allowManagedModsOnly. Se o mod for carregado, 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.

  • Um guard integrado é executado 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á-lo. /plugin e o log de depuração o listam como cc-plugin-sec-default. O guard é carregado quando qualquer um destes é verdadeiro:

    • A máquina tem configurações gerenciadas
    • O usuário está conectado ao Claude Code com 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 o guard apenas em uma máquina que tem configurações gerenciadas.

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

  • Tudo mais é permitido. O guard não adiciona outras restrições. Um mod de um usuário ainda pode ler e escrever arquivos, iniciar processos, fazer solicitações de rede, reescrever chamadas de ferramentas e prompts, negar uma chamada de ferramenta, aprovar uma que de outra forma solicitaria, e desenhar na interface, tudo com as permissões desse usuário.

  • Regras de negação e seus hooks gerenciados 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, qualquer que seja o arquivo de configurações que contém a regra. Um bloqueio de um hook PreToolUse em configurações gerenciadas também é final. Ambos se aplicam às chamadas de ferramentas do Claude. Nenhum se aplica às chamadas próprias $.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 essas chamadas, impeça o mod de ser carregado ou hook a chamada em um mod de política.

  • Outras verificações de permissão podem ser substituídas. Um mod de um usuário que aprova chamadas de ferramentas pode aprovar uma chamada que uma regra ask solicitaria, ou que um hook PreToolUse fora de configurações gerenciadas bloqueou. Em modo automático, uma chamada que o mod aprova é executada sem uma verificação de classificador.

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ções 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. Nada sobre eles está descontinuado.
  • 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 de qualquer mod ver a chamada de ferramenta, e seu bloqueio é final. Se um mod então reescrever a chamada, seus hooks gerenciados são executados novamente na chamada reescrita, então um bloqueio ainda se aplica. Hooks PreToolUse de outros arquivos de configurações e de plugins são executados após o último mod, então um mod que retorna seu próprio resultado no lugar de executar a ferramenta impede que aqueles sejam executados. Veja A ordem em que mods são executados.
  • Política de rede cobre $.http.fetch. Se sua organização desativa busca na web, ou tráfego de rede não essencial é desativado para a sessão, Claude Code recusa uma solicitação de rede que um mod faz com $.http.fetch. A política não cobre um programa que o mod inicia com $.process.run. Esse programa 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.

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:

Seus controles de plugin hoje O que um usuário pode carregar como um mod
Nenhum Um mod de qualquer marketplace, de qualquer diretório com --plugin-dir, ou que Claude escreve durante uma sessão
Uma lista de permissão de marketplace Um mod dos marketplaces que você permite, ou de qualquer diretório com --plugin-dir. Um mod que Claude escreve durante uma sessão é carregado apenas quando a lista de permissão inclui skills-dir.
Uma lista de permissão de marketplace e disableSideloadFlags Um mod dos marketplaces que você permite

Gerenciar plugins para sua organização lista cada forma 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

Duas linhas 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:

Chamada O que significa
$.fs.read, $.fs.write Lê ou escreve arquivos em qualquer lugar que o usuário possa
$.process.run, $.process.spawn Inicia programas como o usuário
$.http.fetch Faz solicitações de rede
$.env.get, $.settings.read Lê variáveis de ambiente e configurações, que podem conter chaves de API. Uma linha env reads: na saída nomeia cada variável.
$.env.set Define uma variável de ambiente para Claude Code e para cada comando e servidor MCP que ele inicia depois, o que pode mudar o que esses programas executam. Uma linha env writes: nomeia cada variável.
$.mcp.call Chama uma ferramenta em um servidor MCP conectado, sob as regras de permissão da sessão
$.model.complete Usa o plano ou chave de API do usuário para chamadas de modelo
$.prompt.submit Envia um prompt e pode enviá-lo como as próprias palavras do usuário
$.session.send Envia uma mensagem que outra sessão ou subagente do Claude lê

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. 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 você quer Configurações
Nenhum mod instalado, com hooks intocados Defina allowManagedModsOnly e não implante mods seus
Nenhum mod instalado e nenhum hook, incluindo seus hooks gerenciados Defina disableAllHooks como true
Apenas mods da sua organização Defina a opção allowManagedModsOnly do guard, e instale seus mods para que contem como seus
Qualquer mod de marketplaces que você aprova Mantenha suas restrições de marketplace, e defina disableSideloadFlags como true
Qualquer mod, com seu próprio mod verificando os outros Instale seu mod, e liste-o com sec-default@builtin em prependPlugins

O que cada configuração faz:

  • allowManagedModsOnly: uma opção no guard integrado. Mods próprios dos usuários não são carregados, e seus hooks de configurações, linhas de status e /goal 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, então ninguém carrega um mod de um diretório, 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 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 do guard integrado tem a linha para allowManagedModsOnly.

Defina opções no guard integrado

O guard integrado leva duas 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:

Opção Não definida true
allowManagedModsOnly Mods próprios dos usuários são carregados Apenas mods da sua organização, e mods integrados ao Claude Code, são carregados. Claude Code recusa cada outro mod, incluindo um que um usuário instalou ou nomeou com --plugin-dir.
allowModsToOverrideDenyRules Regras de negação têm precedência sobre mods dos usuários Um mod de um usuário que aprova chamadas de ferramentas pode aprovar uma chamada que uma regra deny recusa

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

  • O id tem uma ortografia 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 afrouxe uma
  • O guard tem que ser carregado: se você definir prependPlugins, nomeie o guard na lista. Onde o guard não é carregado, nenhuma opção se aplica.
  • O guard falha fechado: se o guard não conseguir ler configurações gerenciadas, ele 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, ele recusa a chamada.

As mensagens do guard integrado 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, e ele não é carregado sob allowManagedModsOnly ou allowManagedHooksOnly. 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 o guard integrado 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 o guard integrado 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 o guard integrado. O guard é integrado 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 três condições para um mod da organização
  • Repositórios não podem defini-los: Claude Code lê ambas as configurações apenas 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 não estão conectados com um plano 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 o guard integrado.

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 admitir 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 fazer hook de qualquer chamada de 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:

// Os métodos que nenhum mod de um usuário pode chamar, cada um soletrado namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // É executado cada vez que outro mod está prestes a ser carregado
  on('plugin.register', async ($, e, next) => {
    // Mantenha as chamadas naquele código do mod que estão na lista bloqueada
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Retornar refuse impede o mod de ser carregado, e o texto é a razão
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Deixe cada outro mod ser carregado
    return next(e)
  })

  // Registre cada chamada de ferramenta, então deixe-a prosseguir inalterada
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Registre qual mod escreveu um arquivo, então o caminho, entre aspas porque o mod o escolheu
  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 soletrado 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. Teste um mod que julga outros mods 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 passa 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']

// A mesma verificação de antes, movida para uma função de sua própria
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) {
  // O manipulador é executado apenas quando checkMod lança ou passa seu limite de tempo
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Deixe mods da sua organização e mods integrados serem carregados
    if (e.tier !== 'user') return next(e)
    // Recuse o mod do usuário que não pôde ser verificado
    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