Mods de Claude Code: en qué se diferencian de los hooks, qué pueden hacer y qué permisos revisar primero

Los mods de Claude Code (oficialmente, Claude Mods) son plugins que ejecutan dentro de Claude Code funciones que tú escribes en JavaScript o TypeScript. Llegaron oficialmente con la v2.1.287 el 1 de octubre de 2026 y permiten añadir paneles propios a la interfaz, reescribir llamadas a herramientas y crear /comandos que se ejecutan sin esperar. La trampa: un mod se ejecuta con tus permisos, fuera del sandbox. En un plan personal, puede incluso aprobar llamadas que una regla deny de settings.json había rechazado. Este artículo explica qué pueden hacer los mods, en qué se diferencian de los hooks y qué comprobar antes de instalar uno, a partir del texto original de la documentación oficial leído el 5 de octubre de 2026 y de la lectura del código de los tres mods de ejemplo oficiales de Anthropic.

Fuentes: Mods overview, Changelog (2.1.287, 1 de octubre de 2026, «Added Claude Mods»). Consultado el 5 de octubre de 2026.

1. Qué son los mods: un pequeño plugin de tres archivos

Un mod es un tipo de plugin. Su núcleo es un archivo JavaScript (o TypeScript) que registra qué función llamar ante qué evento. La documentación oficial llama a este archivo hooks module (módulo de hooks) y a cada función que contiene, hook. Tu función se llama justo antes de que Claude Code use una herramienta, cuando recibe un prompt, cuando dibuja el indicador de carga, etc.

Aquí es donde el nombre se presta a confusión. Los hooks tradicionales que escribes en settings.json también son «hooks», así que las páginas de los mods los llaman settings hooks para distinguirlos. Los settings hooks no están obsoletos. La página oficial para administradores afirma claramente que nada de ellos ha quedado obsoleto.

El mod más pequeño consta de estos tres archivos.

Como ejemplo, este es el archivo principal de un mod que cuenta cuántas veces ha editado Claude archivos y muestra el recuento cuando escribes /edits (un ejemplo escrito por el autor siguiendo los patrones oficiales).

// hooks/register.js
let edits = 0  // compartido por los dos hooks de abajo

export function register(on) {
  // Registra /edits al empezar la sesión
  on('session.start', async ($, e, next) => {
    const r = await next(e)
    await $.command.register({ name: 'edits', description: 'Muestra cuántas ediciones' })
    return r
  })

  // Cuando terminan Edit y Write, cuenta solo las que salieron bien
  on('tool.call', { tool: ['Edit', 'Write'] }, async ($, e, next) => {
    const result = await next(e)  // espera a la comprobación de permisos y a la ejecución
    if (!result.deny && !result.isError) edits += 1
    return result                 // devuelve el resultado a Claude sin cambios
  })

  // Responde cuando se escribe /edits (no empieza un turno de Claude)
  on('command.run', { command: 'edits' }, async ($, e) => {
    return { text: 'Ediciones de Claude en esta sesión: ' + edits }
  })
}

Hay tres puntos importantes. (1) Llamar a next(e) pasa al comportamiento normal de Claude Code (la comprobación de permisos y la ejecución de la herramienta). (2) Devolver un valor sin llamar a next significa que has respondido en el acto, y el comportamiento normal no se produce. (3) Todo lo que actúa sobre el mundo exterior, como leer y escribir archivos, dibujar en la interfaz o registrar comandos, pasa por $ (la API de mods). Gracias a la regla (3), Claude Code puede enumerar lo que hace un mod sin ejecutar su código (sección 4).

Fuentes: Mods reference, «Files», React to events with a mod, Use the mods API, «Add a command», Manage mods for your organization.

2. En qué se diferencian los mods de los hooks, las skills y MCP

Con los mods, ya hay cuatro formas de personalizar Claude Code. Así se elige entre ellas, según la tabla comparativa oficial.

Fuente: Mods overview, «Compare mods, settings hooks, skills, and MCP servers», resumido por el autor.

Una regla práctica: si solo necesitas bloquear o registrar, bastan los hooks tradicionales. Puedes escribirlos como scripts de shell y nunca actúan en el sentido de relajar permisos, así que son seguros. Si quieres mostrar algo en la interfaz, necesitas un comando que se ejecute sin esperar o quieres retener a medias una llamada a una herramienta para preguntar al usuario, ahí entran los mods. Si pegas una y otra vez las mismas instrucciones, recurre primero a las skills; si quieres conectar sistemas internos, recurre primero a MCP. Un mismo plugin también puede agrupar un mod, skills y un servidor MCP.

3. Cinco cosas que pueden hacer los mods y sus límites fijos

La página oficial de introducción enumera cinco cosas que solo puede hacer un mod.

1. Dibujar una interfaz utilizable: poner pestañas, botones y campos de texto en un panel junto a la conversación o en una banda sobre el prompt.
2. Redibujar la propia interfaz de Claude Code: sustituir o cambiar el estilo de las filas de llamadas a herramientas, el indicador de carga, el diálogo en el que Claude hace preguntas y más. Sin embargo, el aviso de permisos es lo único que no se puede cambiar.
3. Intervenir en llamadas a herramientas y peticiones: retener una llamada para preguntar al usuario, devolver una respuesta sin ejecutar la herramienta o enviar una petición concreta a otro modelo.
4. Ejecutar tu propio código con un comando: al escribir un /comando, tu función se ejecuta al instante, sin consumir un turno de Claude. Si lo registras con immediate: true, se ejecuta incluso mientras Claude está trabajando.
5. Compartir datos entre hooks: los hooks comparten las variables del mismo archivo, así que un valor que cuenta un hook puede mostrarlo otro. El ejemplo de la sección 1 hace exactamente eso.

Además, la API de mods permite a un mod llamar a un modelo ($.model.complete), ejecutarse periódicamente con un temporizador, enviar mensajes a otra sesión y usar archivos, procesos y la red. Las llamadas a modelos se descuentan del uso de tu plan o de tu clave de API.

La referencia oficial detalla los límites dentro de los que funcionan los mods. Estos son los principales.

Fuentes: Mods overview, «What a mod can do», Use the mods API, Mods reference, «Limits». Consultado el 5 de octubre de 2026.

4. Los permisos que hay que entender primero: en los planes personales, los mods pueden anular las reglas deny

Esta es la parte del artículo que más quiero que te lleves. La página oficial de introducción dice que, una vez instalado, un mod puede hacer lo siguiente.

• Actuar en tu equipo como si fueras tú: leer y escribir archivos en cualquier lugar al que llegue tu cuenta, iniciar programas y conectarse a la red
• Leer secretos: variables de entorno y archivos de configuración (incluidas las claves de API que guardes en ellos)
• Ver y cambiar tu sesión: cada prompt que envías y cada llamada a herramientas que hace Claude, lo que incluye reescribir prompts y llamadas, y enviar prompts como si los hubieras escrito tú
• Aprobar sin preguntar: aprobar una llamada a una herramienta antes de que se te pregunte
• Gastar tu uso: llamar a modelos con tu plan o tu clave de API

Por si fuera poco, los mods no están en un sandbox. Aunque actives el sandbox, este solo aísla los comandos Bash que ejecuta Claude, y los programas que inicia un mod se ejecutan fuera de él.

Luego están las decisiones de permisos. Al manejar un evento llamado tool.check, un mod puede sustituir la respuesta después de que las reglas y los hooks hayan decidido. Qué se impone a un mod y qué pierde frente a él depende de cómo uses Claude Code. En la tabla siguiente, «Uso personal» significa iniciar sesión con Pro o Max, o usar una clave de API, en un equipo sin managed settings (configuración gestionada). «Gestionado por la organización» significa que el equipo tiene managed settings o que has iniciado sesión con un plan Team o Enterprise.

Fuentes: Configure permissions, «Extend permissions with hooks», Manage mods for your organization, «Know what happens by default». Consultado el 5 de octubre de 2026.

Las reglas deny se mantienen en la columna de la derecha porque un mod guardián integrado llamado sec-default (cc-plugin-sec-default) se carga antes que cualquier otro mod. Este guardián solo se carga cuando el equipo tiene managed settings o has iniciado sesión con un plan Team o Enterprise. Si usas una clave de API o Amazon Bedrock y similares, tampoco se carga salvo que haya managed settings. Dicho de otro modo, si usas Pro o Max como particular, un mod que instales puede aprobar incluso llamadas que una regla deny había rechazado.

Enumera lo que hace un mod antes de instalarlo

Cuando tengas los archivos de un mod en local (por ejemplo, tras clonar un repositorio), ejecuta el siguiente comando antes de cargarlo. No se ejecuta ningún código.

claude plugin validate ./some-mod

La línea hooks: de la salida muestra los eventos que recibe el mod, y la línea calls:, las API de mods a las que llama. Un mod que usa la API de mods de una forma que la validación no puede leer se rechaza al cargarlo. Esto es lo que la documentación oficial dice que hay que buscar, agrupado por significado.

Fuente: Manage mods for your organization, «Review what a mod can do», resumido por el autor.

5. Leyendo el código de los tres ejemplos oficiales

Anthropic ha publicado tres mods de ejemplo en el repositorio claude-code-playground (añadidos el 1 de octubre de 2026, sin soporte). El autor (Claude, la IA que escribió este artículo) leyó el código fuente de los tres en GitHub el 5 de octubre de 2026 y contó qué eventos recibe cada uno y a qué API de mods llama cada uno. Son resultados de leer el código, no de ejecutar claude plugin validate. Los ejemplos no se cargaron en local.

Fuente: claude-code/mods en anthropics/claude-code-playground (código leído el 5 de octubre de 2026; el número de líneas corresponde a cada archivo del módulo de hooks).

Leerlos me enseñó tres cosas.

(1) El «mod de seguridad» es el que usa los permisos más fuertes. blast-radius es un mod que aumenta la seguridad: detiene comandos como rm -rf, git reset --hard y git push --force y muestra los botones «Proceed» (continuar) y «Cancel» (cancelar). Sin embargo, para medir lo que se perdería, ejecuta un script de bash con $.process.run. Aunque el propósito sea la seguridad, la línea calls: de validate dirá «inicia programas». Por eso un mod se juzga por las API a las que realmente llama, no por su descripción.

(2) Usa los mods de bloqueo dando por hecho que algo se cuela. El propio README de blast-radius enumera las formas que no puede detectar: $(...), alias, eval, bash -c "...", xargs rm, find -delete, scripts que llaman a rm y envoltorios como timeout 5 rm. Y como solo vigila Bash, no detiene las ediciones de archivos. Los mods de este tipo son herramientas útiles para reducir accidentes, no una frontera de seguridad.

(3) Dependen del entorno. El README de blast-radius exige bash, git, find y du en el PATH. En Windows con solo PowerShell a secas, tienes que comprobar que están presentes antes de instalarlo. Según el README de los ejemplos, los tres se crearon y probaron en la v2.1.280, y se confirmó que pasan validate en la v2.1.285.

6. Cómo probar uno, pedirle a Claude que cree uno y desactivarlos

Requisito: v2.1.287 o posterior

Los mods requieren Claude Code v2.1.287 o posterior y están activados por defecto. Compruébalo con claude --version. Para saber si tu configuración actual puede cargar mods, ejecuta claude plugin test en una carpeta sin ningún mod. no hooks module to load significa que los mods pueden cargarse; hooks modules are turned off here significa que tu propia configuración o la política de tu organización los ha desactivado.

Instalar o probar una vez

• Instalar desde un marketplace: dentro de una sesión, /plugin install name@marketplace; en una shell, claude plugin install name@marketplace. Si lo instalaste desde la shell con una sesión abierta, ejecuta /reload-plugins.
• Probarlo solo durante una sesión: claude --plugin-dir ./mod-folder. Los ejemplos oficiales también recomiendan probarlos así.
• Comprobar que se ha cargado: abre /plugin y, bajo las pestañas, aparece una línea como 1 mod active · first-mod.

Pedirle a Claude que cree uno

En una sesión interactiva, pide algo como «haz un mod que muestre el nombre de la rama actual sobre el prompt», y Claude lo escribe con la skill integrada plugin-authoring. Lo escribe en una carpeta por sesión dentro de ~/.claude/dev-mods/. Al guardarse el primer archivo, se te pregunta si quieres activar la recarga en caliente para esta sesión; elige «Enable for this session» (activar para esta sesión) y el mod se recarga al final de cada turno.

• ~/.claude es una ruta protegida, así que en los modos default y acceptEdits recibes un aviso por cada archivo que crea.
• Un mod creado por Claude solo se carga en esa sesión. La carpeta se borra pasados cleanupPeriodDays, así que, para conservarlo, cópialo a una ubicación tuya y cárgalo con --plugin-dir.
• No se carga en claude -p ni en el modo dontAsk, donde no hay nadie para aprobar, ni en carpetas en las que no has confiado.

Desactivarlos

La variable de entorno CLAUDE_CODE_ENABLE_FUNCTION_HOOKS que se usaba en la época de la versión preliminar se ignora a partir de la v2.1.287. Ponerla a 0 no detiene los mods.

Fuentes: Mods overview, «Turn mods on or off», Create a mod, «Ask Claude for a mod», Troubleshoot a mod.

7. Dónde se ejecutan los mods y los mods integrados de serie

Los hooks de un mod se ejecutan en cualquier sesión que cargue el plugin. Sin embargo, lo que dibuja solo aparece en la terminal y en la aplicación de escritorio.

Lo que se pasa por alto con facilidad es que los hooks también se ejecutan en claude -p y en el Agent SDK. Aunque no haya interfaz, la reescritura y la aprobación de llamadas a herramientas siguen produciéndose. Si llevas un plugin que contiene un mod a un entorno de automatización, los problemas de permisos de la sección 4 se aplican por completo.

Además, algunas funciones de Claude Code vienen como mods de serie. Aparecen en «Built-in» en la pestaña Installed de /plugin.

• cc-plugin-agents-md: carga AGENTS.md como instrucciones del proyecto
• cc-plugin-diff: dibuja el panel de /diff
• cc-plugin-plugin-authoring: la skill para escribir mods (no tiene código de mod)
• cc-plugin-sec-default: el guardián de la sección 4, que los usuarios no pueden desactivar
• cc-plugin-telemetry: envía telemetría de uso
• cc-plugin-you-should-know: vigila en paralelo las tareas largas y señala sobre el prompt cosas que podrían pasársete (desactivado por defecto; actívalo con /plugin enable cc-plugin-you-should-know@builtin)

Los mods integrados no se detienen con disableAllHooks, --bare ni --safe-mode. Para detener uno, usa su propio interruptor.

Fuente: Mods overview, «Where mods run» y «Mods built into Claude Code». Consultado el 5 de octubre de 2026.

Para administradores de organizaciones

Si administras Team o Enterprise, pasar allowManagedModsOnly: true al mod guardián mediante pluginConfigs en las managed settings impide que se cargue cualquier mod que traigan los usuarios (instalado desde un marketplace, cargado con --plugin-dir o creado por Claude). Los usuarios no pueden deshacerlo con sus propios archivos de configuración ni con --settings. Los hooks tradicionales y la línea de estado siguen funcionando. Para más detalles, consulta la página oficial Manage mods for your organization.

8. Lista de comprobación antes de instalar

• ¿Confías en el autor y en el marketplace? Un mod se ejecuta con tus permisos. No instales mods de autores que no conoces.
• ¿Has revisado la lista con claude plugin validate? Si calls: muestra $.process, $.http.fetch o $.env.get, o hooks: muestra tool.check, confirma el motivo en el código.
• ¿Se mantienen las reglas deny en tu configuración? En un plan personal sin managed settings, un mod puede anular deny.
• ¿Estás tratando un mod de bloqueo como una frontera de seguridad? Hay formas de esquivarlo. No sustituye al sandbox ni a las reglas deny.
• ¿Lo vas a llevar a un entorno de automatización? Los hooks también se ejecutan en claude -p y en el Agent SDK.
• ¿Sabes cómo desactivarlo? Si algo parece raro, inicia con claude --safe-mode para averiguar si el culpable es un mod.

Resumen

Los mods de Claude Code son plugins formados por funciones que se ejecutan dentro de Claude Code. Pueden hacer lo que no podían los hooks tradicionales, las skills ni MCP, dibujar en la interfaz, comandos que se ejecutan sin esperar e intervenir en llamadas a herramientas, e incluso puedes pedirle a Claude que escriba el mod por ti. A cambio, un mod se ejecuta con tus permisos fuera del sandbox y puede anular decisiones de permisos. En Team o Enterprise, o en un equipo con managed settings, las reglas deny se mantienen, pero en un plan personal un mod puede aprobar incluso llamadas que una regla deny había rechazado. Antes de instalar, comprueba los eventos que recibe y las API a las que llama con claude plugin validate. Si solo necesitas bloquear cosas, bastan los hooks tradicionales. Ten en cuenta estos dos puntos y podrás probar los mods con tranquilidad.

Para saber cómo escribir hooks tradicionales, consulta «Qué son los hooks de Claude Code»; para instalar plugins, «Qué son los plugins de Claude Code»; y para las diferencias entre los modos de permisos, «Los modos de permisos de Claude Code».

Preguntas frecuentes

P. ¿Debo usar mods o hooks tradicionales?

R. Si solo necesitas bloquear, permitir o registrar, bastan los hooks tradicionales (settings hooks). Puedes escribirlos como scripts de shell y nunca llegan a ser más fuertes que las reglas deny. Elige un mod cuando quieras un panel en la interfaz, un comando que se ejecute sin esperar o retener una llamada para preguntar al usuario. Los hooks tradicionales no están obsoletos y funcionan junto a los mods.

P. Si instalo un mod con un plan Pro personal, ¿se siguen respetando mis reglas deny?

R. No. Las reglas deny tienen prioridad sobre los mods solo cuando el equipo tiene managed settings o has iniciado sesión con un plan Team o Enterprise. En los demás casos, un mod que maneja tool.check puede aprobar incluso llamadas que una regla deny había rechazado. Y en todos los casos, las lecturas de archivos propias del mod ($.fs.read) y los programas que inicia no están cubiertos por las reglas deny (documentación oficial).

P. ¿Puedo usar mods en la aplicación de escritorio?

R. Sí. En la pestaña Code de la aplicación de escritorio, los hooks se ejecutan y aparecen los paneles que dibujan (salvo los componentes exclusivos de la terminal). Sin embargo, los propios plugins no están disponibles en las sesiones WSL, así que los mods no se ejecutan allí. En la vista de chat de la extensión de VS Code, los hooks se ejecutan, pero no aparece nada de lo que dibujan.

P. ¿Cómo desactivo todos los mods que he instalado?

R. Para una sesión, inicia con claude --safe-mode. Para desactivarlos de forma permanente, añade "disableAllHooks": true a ~/.claude/settings.json (también se detienen los hooks tradicionales y la línea de estado). Ninguna de las dos opciones detiene los mods integrados, como el que carga AGENTS.md.