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

Administrar mods para su organización

Controle los mods de Claude Code con configuración administrada: detenga los mods instalados por usuarios, permita solo los suyos, revise qué puede hacer un mod e implemente políticas con su propio mod.

Un mod es un plugin que ejecuta código dentro de Claude Code con los permisos del usuario que lo instaló. Los mods no están sandboxed. A través de configuración administrada, usted decide si los mods se ejecutan en las máquinas de sus usuarios, cuáles y en qué orden. También puede instalar un mod propio que supervise o rechace lo que hacen otros mods.

Esta página es para la persona que implementa la configuración administrada para Claude Code, ya sea como archivo, a través de MDM o desde la consola de administrador de claude.ai. Los mods están activados de forma predeterminada en Claude Code v2.1.287 y posteriores. Comience con la sección que coincida con lo que vino a hacer:

Detenga la carga de mods instalados por usuarios

Para evitar que se cargue cada mod que traen sus usuarios, establezca la opción allowManagedModsOnly en el guard integrado, un mod de política que Claude Code carga antes de cada mod que instala un usuario. La opción va en la configuración administrada bajo pluginConfigs, con clave cc-plugin-sec-default@builtin:

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

Con la opción establecida en la configuración administrada:

  • Ningún mod que traiga un usuario se carga: eso cubre un mod en un plugin que el usuario instaló, un mod cargado con --plugin-dir, y un mod que Claude escribió durante una sesión
  • Los mods de su organización aún se cargan: un mod que cuenta como de su organización no se verifica. Todos los demás mods cuentan como de un usuario y no se cargan. Eso incluye un mod en un plugin que habilita desde un marketplace remoto de GitHub u otro, y uno que su organización activa para sus miembros en claude.ai. Si ninguno cuenta como suyo, no se carga ningún mod instalado.
  • Los usuarios no pueden deshacerlo: el guard lee la opción solo de la configuración administrada, por lo que la misma entrada en un archivo de configuración de usuario, proyecto o local, o en un archivo pasado con --settings, no cambia nada
  • Un archivo o política MDM cubre cada proveedor: cuando entrega la opción como archivo o a través de MDM, funciona de la misma manera en Amazon Bedrock, Agent Platform de Google Cloud y Microsoft Foundry. Para la entrega desde la consola de administrador de claude.ai, consulte Disponibilidad de plataforma
  • Las personalizaciones de otros usuarios siguen funcionando: sus hooks en archivos de configuración, líneas de estado y /goal no se ven afectados
  • Los mods integrados siguen ejecutándose: los mods integrados en Claude Code, como el soporte de AGENTS.md, cada uno tiene su propio interruptor

Para confirmar la opción en la máquina de un usuario, inicie Claude Code allí con --plugin-dir y la ruta de un directorio que contenga un mod, como claude --plugin-dir ./first-mod. Los hooks del mod no se ejecutan, y la transcripción y el registro de depuración tienen el mensaje del guard, que nombra el mod y allowManagedModsOnly. Si el mod se carga, consulte Verifique que una política esté en vigor y las reglas que deciden si una opción tiene efecto.

Si estableció CLAUDE_CODE_ENABLE_FUNCTION_HOOKS en 0 durante el acceso temprano, reemplácelo con esta opción. Claude Code v2.1.287 y posteriores ignora la variable en cualquier valor, por lo que un 0 allí deja los mods activados.

Sepa qué sucede de forma predeterminada

Sin configuración de mods propia, esto es lo que obtienen sus usuarios:

  • Los mods están activados. Un usuario puede instalar un plugin que contenga un mod desde cualquier marketplace que su configuración de plugins permita, o cargar uno desde un directorio con --plugin-dir.

  • Un guard integrado se ejecuta primero. Claude Code carga un mod integrado llamado sec-default@builtin antes de cada mod que instala un usuario. Los usuarios no pueden desactivarlo. /plugin y el registro de depuración lo enumeran como cc-plugin-sec-default. El guard se carga cuando cualquiera de estos es verdadero:

    • La máquina tiene configuración administrada
    • El usuario ha iniciado sesión en Claude Code con un plan de Team o Enterprise

    Un usuario que se autentica con una clave API, o a través de Amazon Bedrock, Agent Platform de Google Cloud o Microsoft Foundry, obtiene el guard solo en una máquina que tiene configuración administrada.

  • El guard protege lo que usted administra. El mod de un usuario no puede cambiar lo que sus hooks administrados reciben o deciden, el prompt del sistema, su CLAUDE.md administrado y otras instrucciones administradas, lo que cualquier mod lee como configuración, o las herramientas y descripciones de sus servidores MCP administrados.

  • Todo lo demás está permitido. El guard no agrega otras restricciones. El mod de un usuario aún puede leer y escribir archivos, iniciar procesos, hacer solicitudes de red, reescribir llamadas de herramientas y prompts, negar una llamada de herramienta, aprobar una que de otro modo solicitaría, y dibujar en la interfaz, todo con los permisos de ese usuario.

  • Las reglas de negación y sus hooks administrados tienen prioridad. Donde se carga el guard, el mod de un usuario no puede aprobar una llamada que una regla deny rechaza, cualquiera que sea el archivo de configuración que contenga la regla. Un bloqueo de un hook PreToolUse en la configuración administrada también es final. Ambos se aplican a las llamadas de herramientas de Claude. Ninguno se aplica a las llamadas propias de $.fs y $.process de un mod: con Read(.env) denegado, un mod aún puede leer ese archivo con $.fs.read o iniciar un programa que lo haga. Para limitar esas llamadas, evite que el mod se cargue o enganche la llamada en un mod de política.

  • Otras comprobaciones de permisos pueden ser anuladas. El mod de un usuario que aprueba llamadas de herramientas puede aprobar una llamada que una regla ask solicitaría, o que un hook PreToolUse fuera de la configuración administrada bloqueó. En modo automático, una llamada que el mod aprueba se ejecuta sin una comprobación de clasificador.

El código fuente del guard es público en el directorio mods/sec-default del repositorio de Claude Code.

Sepa qué controles aún se aplican

Los mods no reemplazan los controles que ya tiene:

  • Los hooks de configuración siguen funcionando. Los hooks de comando, HTTP, prompt y agente en archivos de configuración y en hooks/hooks.json de plugins se ejecutan como antes, junto con mods. Nada sobre ellos está deprecado.
  • Las reglas de negación tienen prioridad donde se carga el guard. El mod de un usuario no puede aprobar una llamada que una regla deny rechaza, a menos que establezca allowModsToOverrideDenyRules.
  • Los hooks administrados se ejecutan primero. Un hook PreToolUse en la configuración administrada se ejecuta antes de que cualquier mod vea la llamada de herramienta, y su bloqueo es final. Si un mod luego reescribe la llamada, sus hooks administrados se ejecutan nuevamente en la llamada reescrita, por lo que un bloqueo aún se aplica. Los hooks PreToolUse de otros archivos de configuración y de plugins se ejecutan después del último mod, por lo que un mod que devuelve su propio resultado en lugar de ejecutar la herramienta evita que se ejecuten. Consulte El orden en que se ejecutan los mods.
  • La política de red cubre $.http.fetch. Si su organización desactiva la obtención web, o el tráfico de red no esencial se desactiva para la sesión, Claude Code rechaza una solicitud de red que un mod hace con $.http.fetch. La política no cubre un programa que el mod inicia con $.process.run. Ese programa alcanza la red con el acceso propio del usuario.
  • Los controles de plugins cubren mods. Un mod es un plugin, por lo que la configuración que restringe lo que los usuarios pueden instalar, como strictKnownMarketplaces, decide si puede instalarse en absoluto.
  • Los mods no pueden cambiar el prompt de permiso. Un mod puede cambiar el estilo de gran parte de la interfaz de Claude Code, pero no el prompt de permiso, por lo que no puede cambiar lo que muestra un prompt. Un mod aún puede aprobar o negar una llamada de herramienta antes de que aparezca el prompt, como describe Sepa qué sucede de forma predeterminada.
  • Los prompts de confianza vienen primero. En una sesión interactiva en un directorio que el usuario aún no ha confiado, ningún mod se carga hasta que responda el prompt de confianza.
  • --safe-mode desactiva los mods instalados, incluidos los suyos. Inicie una sesión con claude --safe-mode para verificar si un mod causó un problema.

Ninguno de estos controles sandboxea un mod. Un mod que permite se ejecuta como el usuario, con el acceso del usuario a archivos, procesos y la red.

Decida si dejar los mods activados

Un mod puede hacer más que las otras partes de un plugin porque se ejecuta dentro de Claude Code. Ve cada prompt y llamada de herramienta, puede cambiarlos, y puede permitir o negar una llamada de herramienta antes de que aparezca un prompt de permiso.

Lo que un usuario puede cargar como mod depende de los controles de plugins que ya tiene:

Sus controles de plugins hoy Lo que un usuario puede cargar como mod
Ninguno Un mod de cualquier marketplace, de cualquier directorio con --plugin-dir, o que Claude escriba durante una sesión
Una lista de permitidos de marketplace Un mod de los marketplaces que permite, o de cualquier directorio con --plugin-dir. Un mod que Claude escribe durante una sesión se carga solo cuando la lista de permitidos incluye skills-dir.
Una lista de permitidos de marketplace y disableSideloadFlags Un mod de los marketplaces que permite

Administrar plugins para su organización enumera cada forma en que se carga un plugin y la configuración que controla cada una.

Para verificar los mods en un marketplace antes de que sus usuarios los instalen, consulte Revise qué puede hacer un mod. Para mantener los mods de los usuarios fuera hasta que lo haya hecho, consulte Detenga la carga de mods instalados por usuarios.

Revise qué puede hacer un mod

Puede ver qué puede hacer un mod sin ejecutarlo. En su shell, ejecute claude plugin validate en el directorio del plugin:

claude plugin validate ./some-mod

Dos líneas en la salida describen el código 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 línea hooks: enumera los eventos que recibe el mod. La línea calls: enumera los métodos de la API de mods que llama su código. La API de mods, escrita como $ en el código de un mod, es cómo un mod alcanza archivos, procesos y la red. Claude Code se niega a cargar un mod que usa la API de mods de una manera que este comando no puede leer.

Mire la línea calls: para estos:

Llamada Lo que significa
$.fs.read, $.fs.write Lee o escribe archivos en cualquier lugar donde el usuario pueda
$.process.run, $.process.spawn Inicia programas como el usuario
$.http.fetch Realiza solicitudes de red
$.env.get, $.settings.read Lee variables de entorno y configuración, que pueden contener claves API. Una línea env reads: en la salida nombra cada variable.
$.env.set Establece una variable de entorno para Claude Code y para cada comando y servidor MCP que inicia después, lo que puede cambiar lo que esos programas ejecutan. Una línea env writes: nombra cada variable.
$.mcp.call Llama a una herramienta en un servidor MCP conectado, bajo las reglas de permiso de la sesión
$.model.complete Usa el plan o clave API del usuario para llamadas de modelo
$.prompt.submit Envía un prompt, y puede enviarlo como las propias palabras del usuario
$.session.send Envía un mensaje que otro Claude de sesión o subagente lee

En la línea hooks:, tool.call y prompt.submit significan que el mod ve cada llamada de herramienta y cada prompt, y puede cambiarlos. session.append significa que el mod puede reescribir cada fila de la conversación antes de que se almacene. ui.render{component=AskUserQuestion} significa que el mod puede redibujar el diálogo que Claude usa para hacer una pregunta al usuario. tool.check significa que el mod puede aprobar o negar una llamada de herramienta antes de que aparezca un prompt de permiso. Sepa qué sucede de forma predeterminada enumera cuál de sus reglas y hooks tiene prioridad sobre su respuesta.

Elija cuánto permitir

Las políticas de mods van desde ningún mod instalado en absoluto hasta cualquier mod que un usuario elija, con su propio mod verificando los otros, y cada una es una pocas configuraciones administradas. Encuentre la política que desea en la primera columna y establezca lo que la segunda columna nombra. Implementar configuración administrada cubre dónde vive la configuración administrada.

Lo que desea Configuración
Sin mods instalados, con hooks sin tocar Establezca allowManagedModsOnly y no implemente mods propios
Sin mods instalados y sin hooks en absoluto, incluidos sus hooks administrados Establezca disableAllHooks en true
Solo los mods de su organización Establezca la opción allowManagedModsOnly del guard, e instale sus mods para que cuenten como suyos
Cualquier mod de marketplaces que apruebe Mantenga sus restricciones de marketplace, y establezca disableSideloadFlags en true
Cualquier mod, con su propio mod verificando los otros Instale su mod, y enumérelo con sec-default@builtin en prependPlugins

Lo que hace cada configuración:

  • allowManagedModsOnly: una opción en el guard integrado. Los mods propios de los usuarios no se cargan, y sus hooks de configuración, líneas de estado y /goal siguen funcionando. Detenga la carga de mods instalados por usuarios enumera lo que cubre.
  • allowManagedHooksOnly: una configuración más amplia. Solo los mods de su organización y los mods integrados en Claude Code se cargan. Un mod que un usuario instaló por sí mismo no. La configuración también bloquea los hooks en los archivos de configuración propios de los usuarios. Lea Lo que se ejecuta bajo allowManagedHooksOnly antes de establecerlo.
  • disableAllHooks: la configuración más amplia. En la configuración administrada, detiene los mods en cada plugin instalado, incluidos los suyos, y desactiva cada hook en archivos de configuración, por lo que un hook PreToolUse en su configuración administrada ya no bloquea nada. Las líneas de estado personalizadas y /goal también dejan de funcionar. Lea disableAllHooks antes de establecerlo.
  • disableSideloadFlags: rechaza --plugin-dir y --plugin-url al inicio, por lo que nadie carga un mod desde un directorio, y evita que se carguen los mods que Claude escribe durante una sesión. La configuración también rechaza --agents y --mcp-config. Lea disableSideloadFlags antes de establecerlo.

Los mods integrados en Claude Code, como el soporte de AGENTS.md, no se ven afectados por estas configuraciones. Cada uno tiene su propio interruptor.

Un usuario cuyo mod no se cargó encuentra la razón en su registro de depuración. Mensajes de rechazo enumera las líneas para allowManagedHooksOnly y disableAllHooks, y Mensajes del guard integrado tiene la línea para allowManagedModsOnly.

Establezca opciones en el guard integrado

El guard integrado toma dos opciones. Establézcalas en la configuración administrada bajo pluginConfigs, con clave cc-plugin-sec-default@builtin, como hace el ejemplo en Detenga la carga de mods instalados por usuarios.

La tabla da lo que obtienen sus usuarios con cada opción sin establecer y con ella establecida en true:

Opción Sin establecer true
allowManagedModsOnly Los mods propios de los usuarios se cargan Solo los mods de su organización, y los mods integrados en Claude Code, se cargan. Claude Code rechaza todos los demás mods, incluido uno que un usuario instaló o nombró con --plugin-dir.
allowModsToOverrideDenyRules Las reglas de negación tienen prioridad sobre los mods de los usuarios El mod de un usuario que aprueba llamadas de herramientas puede aprobar una llamada que una regla deny rechaza

Estas reglas deciden si una opción tiene efecto:

  • El id tiene una ortografía aquí: Claude Code lee las opciones solo bajo cc-plugin-sec-default@builtin. prependPlugins acepta sec-default@builtin también, y pluginConfigs no.
  • Solo la configuración administrada cuenta: la misma entrada en un archivo de configuración de usuario, proyecto o local, o en un archivo pasado con --settings, ni establece una opción ni afloja una
  • El guard tiene que cargarse: si establece prependPlugins, nombre el guard en la lista. Donde el guard no se carga, ninguna opción se aplica.
  • El guard falla cerrado: si el guard no puede leer la configuración administrada, rechaza cada mod de usuario al cargar. Si no puede verificar las reglas de negación para una llamada que un mod de usuario aprobó, rechaza la llamada.

Los mensajes del guard integrado son lo que ven sus usuarios cuando cualquiera de las opciones se aplica.

Ejecute los mods propios de su organización

Puede implementar mods propios para cada usuario, elegir dónde se ejecutan en relación con los mods de los usuarios, y usar uno para hacer cumplir una política.

Instale los mods de su organización y establezca el orden

Los mods de su organización se cargan donde los mods de los usuarios no y pueden ejecutarse antes que ellos, por lo que Claude Code tiene que poder decir que un mod vino de usted. Lo trata como de su organización solo cuando todos estos son verdaderos:

  • enabledPlugins administrado establece el plugin del mod en true
  • La configuración administrada nombra el marketplace del plugin como un directorio en la máquina del usuario, por ruta absoluta. Una entrada extraKnownMarketplaces hace eso y también registra el marketplace para el usuario.
  • El marketplace enumera el plugin por una ruta relativa, por lo que Claude Code lo carga en su lugar desde ese directorio

Para cumplirlos, haga que su administración de dispositivos copie el directorio del marketplace a la misma ruta en cada máquina. Haga que el directorio y cada directorio por encima de él sean escribibles solo por un administrador, como lo es el archivo de configuración administrada. Cualquiera que pueda escribir allí puede reescribir su mod. La configuración administrada que entrega desde la consola de administrador de claude.ai puede llevar las claves, pero no puede poner el directorio en una máquina.

El directorio contiene el manifiesto del marketplace y el plugin:

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

El manifiesto enumera el plugin por su ruta relativa a ese directorio:

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

Un plugin que Claude Code copia en su caché cuenta como de un usuario, incluso cuando enabledPlugins administrado lo habilita. Eso cubre cada plugin de una fuente de GitHub, git, URL o npm. Su mod se ejecuta entre los mods de los usuarios, prependPlugins y appendPlugins lo omiten, y no se carga bajo allowManagedModsOnly o allowManagedHooksOnly. El registro de depuración del usuario tiene una línea que comienza con el id del plugin y is enabled by managed settings, but.

Claude Code genera un evento cada vez que está a punto de actuar, como ejecutar una herramienta, y lo pasa a cada mod a su vez. Un mod que cuenta como suyo se ejecuta antes que los mods de los usuarios incluso cuando no lo enumera en ningún lugar. Para establecer su lugar, enumere su id en una de dos configuraciones. El id es el nombre del plugin, @, y el nombre del marketplace, como acme-guard@acme-tools.

  • prependPlugins: su mod ve cada evento antes que cualquier mod de usuario y cada resultado después. Puede cambiar el evento, rechazarlo u omitir los mods de los usuarios.
  • appendPlugins: su mod se ejecuta después de cada mod de usuario, por lo que solo ve los eventos que esos mods pasan, en la forma en que los pasan

Este ejemplo declara el marketplace acme-tools en /opt/acme/claude-plugins, habilita acme-guard desde él, y ejecuta ese mod primero, con el guard integrado después:

{
  "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 clave hace un trabajo:

  • extraKnownMarketplaces: nombra el directorio que contiene el marketplace acme-tools. path es la ruta absoluta del directorio que contiene .claude-plugin/marketplace.json.
  • enabledPlugins: activa acme-guard para cada usuario que recibe esta configuración administrada
  • prependPlugins: pone acme-guard primero y el guard integrado segundo, ambos antes de cualquier mod que instale un usuario. Claude Code sigue el orden que enumera.

Para confirmar que la máquina de un usuario recibió la configuración, consulte Verifique que una política esté en vigor.

Para confirmar dónde se ejecuta el mod, inicie una sesión en esa máquina con claude --debug y busque en el registro de depuración el id del mod:

  • hooks module acme-guard@acme-tools loaded, con tier prepend: el mod cuenta como de su organización y se ejecuta primero
  • La misma línea con tier user: Claude Code lo trata como un mod de usuario. Una segunda línea, prependPlugins names acme-guard@acme-tools, which is not an enabled managed plugin with a hooks module; skipped, dice que la lista lo omitió.

Estas reglas deciden qué ids en las dos listas tienen efecto:

  • La lista reemplaza el predeterminado: cuando establece prependPlugins en la configuración administrada, nombre sec-default@builtin en ella para mantener el guard integrado. El guard está integrado y no necesita una entrada enabledPlugins.
  • Sus propios ids deben contar como suyos: en la configuración administrada, Claude Code omite un id cuyo plugin no cumple las tres condiciones para un mod de una organización
  • Los repositorios no pueden establecerlos: Claude Code lee ambas configuraciones de la configuración administrada y nunca de un archivo de configuración de un repositorio. Un usuario puede establecerlos en ~/.claude/settings.json para ordenar solo sus propios mods en una máquina sin configuración administrada, y solo cuando no han iniciado sesión con un plan de Team o Enterprise. En cualquier otro lugar, Claude Code ignora ambas claves en la configuración del usuario. Una lista allí ni agrega ni elimina el guard integrado.

Haga cumplir una política con un mod propio

Para mantener cada mod de usuario fuera, no necesita un mod propio. Establezca allowManagedModsOnly. Escriba un mod de política cuando desee admitir algunos mods de usuarios y rechazar otros, o para registrar lo que hacen los mods.

Cada vez que otro mod está a punto de cargarse, su mod recibe la lista que claude plugin validate imprime, en un evento llamado plugin.register. Un mod en prependPlugins puede leer esa lista y rechazar el mod. También puede enganchar cualquier llamada de API de mods por nombre para registrar o rechazar esa llamada para cada otro mod. El nombre es el método sin el $., por lo que un gancho en fs.write ve cada llamada $.fs.write.

Este mod de política rechaza cualquier mod de usuario cuyo propio código llama a $.process.run o $.process.spawn. También mantiene un registro de auditoría, escribiendo cada llamada de herramienta y cada archivo que un mod escribe en el registro de depuración. Porque se ejecuta primero, el registro registra lo que se solicitó, antes de que cualquier mod de usuario lo cambie. Guárdelo como acme-guard/hooks/register.js:

// Los métodos que ningún mod de usuario puede llamar, cada uno deletreado namespace.method
const BLOCKED_CALLS = ['process.run', 'process.spawn']

export function register(on) {
  // Se ejecuta cada vez que otro mod está a punto de cargarse
  on('plugin.register', async ($, e, next) => {
    // Mantenga las llamadas en el código de ese mod que están en la lista bloqueada
    const blocked = e.uses.calls.filter((call) => BLOCKED_CALLS.includes(call))
    if (e.tier === 'user' && blocked.length > 0) {
      // Devolver refuse evita que el mod se cargue, y el texto es la razón
      return { refuse: 'Acme policy: mods may not call ' + blocked.join(', ') }
    }
    // Deje que cada otro mod se cargue
    return next(e)
  })

  // Registre cada llamada de herramienta, luego déjela avanzar sin cambios
  on('tool.call', async ($, e, next) => {
    $.ui.log('audit tool.call ' + e.tool, { to: 'debug' })
    return next(e)
  })

  // Registre qué mod escribió un archivo, luego la ruta, entrecomillada porque el mod la eligió
  on('fs.write', async ($, e, next) => {
    $.ui.log('audit fs.write by ' + next.origin.plugin + ' ' + JSON.stringify(e.path), { to: 'debug' })
    return next(e)
  })
}

El archivo registra tres hooks:

  • plugin.register: decide si otro mod se carga. Rechaza un mod de usuario que llama a un método bloqueado y pasa cada otro mod.
  • tool.call: escribe una línea como audit tool.call Bash en el registro de depuración para cada llamada de herramienta, y no cambia nada
  • fs.write: escribe una línea como audit fs.write by reader "/tmp/notes.md" para cada llamada $.fs.write que hace otro mod, y no cambia nada. El nombre del mod viene primero y la ruta está entrecomillada, por lo que una ruta que un mod elige no puede pasar por otro campo de la línea.

El hook plugin.register lee dos campos del evento:

  • e.tier: dónde se ejecutaría el mod, uno de prepend, user, append, o builtin. Cada mod que una persona instala es user.
  • e.uses.calls: los métodos de la API de mods que llama el mod, cada uno deletreado namespace.method como process.run, sin el $. que claude plugin validate imprime

Cuando un usuario instala un mod que llama a $.process.run, el mod no se carga, y su registro de depuración tiene una línea que termina con refused by acme-guard: y su razón. El rechazo también llega a la transcripción en una sesión que recarga en caliente un directorio de plugins. Para bloquear una llamada sin rechazar el mod completo, devuelva { deny: 'your reason' } de un gancho en el nombre de esa llamada.

Para enviar las líneas de auditoría a algún lugar que no sea el registro de depuración, llame a $.http.fetch desde los mismos hooks.

Una sesión puede ejecutarse sin su mod. Si el hilo de trabajo que ejecuta mods instalados falla tres veces, Claude Code descarga cada mod que no está integrado, incluido el suyo, hasta que el usuario ejecute /reload-plugins o inicie una nueva sesión. Y un usuario que inicia Claude Code con --safe-mode se ejecuta sin mods instalados, incluidos los suyos.

Crear un mod cubre los archivos que necesita un mod. Pruebe un mod que juzga otros mods tiene un archivo de prueba para este mod de política.

Rechace mods cuando su verificación falla

Si su hook plugin.register lanza o se ejecuta más allá de su límite de tiempo, Claude Code omite el gancho, por lo que la verificación falla abierta y el mod que estaba verificando se carga. Para fallar cerrado y rechazar los mods de los usuarios, mueva la verificación a una función nombrada y agregue un controlador .catch que devuelva el rechazo. Esta versión del archivo muestra solo el hook plugin.register, así que mantenga los dos hooks de auditoría de la primera versión en register:

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

// La misma verificación que antes, movida a una función propia
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) {
  // El controlador se ejecuta solo cuando checkMod lanza o se ejecuta más allá de su límite de tiempo
  on('plugin.register', checkMod).catch(async ($, e, next) => {
    // Deje que los mods de su organización y los mods integrados se carguen
    if (e.tier !== 'user') return next(e)
    // Rechace el mod de usuario que no pudo ser verificado
    return { refuse: 'Acme policy check failed, so this mod was not loaded' }
  })
}

Con el controlador en su lugar, un mod que estaba siendo verificado cuando la verificación lanzó o se agotó el tiempo no se carga, y la línea de rechazo lleva la segunda razón, como en refused by acme-guard: Acme policy check failed, so this mod was not loaded. El controlador pasa cada mod fuera del tier user a next(e), por lo que una verificación fallida no detiene los mods que su organización enumera. Maneje un gancho que falla cubre .catch para otros eventos.

Próximos pasos