> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia de mods

> Referencia completa de los mods de Claude Code: estructura del módulo de hooks, eventos, métodos de la API de mods, puntos de renderizado, elementos por superficie, límites y configuración.

Consulta cualquier evento que un [mod](https://code.claude.com/docs/es/plugins/mods/overview.md) puede manejar, cualquier método de la API de mods que puede llamar o cualquier punto de renderizado en el que puede dibujar. Las entradas cubren la CLI de Claude Code y la app de escritorio a partir de la v2.1.290, y la extensión de VS Code a partir de la v2.1.299. Cada entrada indica el nombre y una descripción de una línea, y enlaza a la sección de la guía que lo explica cuando existe.

> [!NOTE]
>
> La referencia completa son las [declaraciones de TypeScript para mods](https://github.com/anthropics/claude-code/blob/main/mods/types/claude-code.d.ts) de Claude Code, que describen cada evento, método y elemento, con ejemplos. La copia en GitHub puede ser más antigua que la versión de Claude Code que tienes instalada. Cuando ambas no coincidan, confía en [la copia que Claude Code escribe para tu versión](https://code.claude.com/docs/es/plugins/mods/create.md#get-the-types-for-your-build).

## Archivos

Un mod es un directorio de plugin con estos archivos:

| Archivo | Obligatorio | Contenido |
| :- | :- | :- |
| `.claude-plugin/plugin.json` | Sí | El [manifiesto](https://code.claude.com/docs/es/plugins/manifest-reference.md) del plugin. Los mods no añaden campos obligatorios. |
| `hooks/hooks.json` | Sí | `modules`: un array con una ruta, relativa a este archivo, al módulo de hooks, como en `"modules": ["./register.js"]`. También puede contener [hooks de configuración](https://code.claude.com/docs/es/hooks.md) en `hooks`. |
| El módulo de hooks, como [`hooks/register.js`](https://code.claude.com/docs/es/plugins/mods/create#write-a-mod-yourself) | Sí | El punto de entrada del mod. Exporta `register(on, options)`. Con nombre `.js`, `.mjs`, `.cjs`, `.jsx`, `.ts`, `.mts`, `.cts` o `.tsx`. Un módulo ES. |
| [`types/index.d.ts`](https://code.claude.com/docs/es/plugins/mods/interface#declare-the-values), a menos que `types` en el manifiesto indique otra ruta | Cuando el mod usa `$.state` o añade un namespace a la API de mods | Declara los valores de `PluginState` y cualquier namespace que añada el mod. Para omitir `types` del manifiesto, necesitas la v2.1.299 o posterior. |
| Archivos cuyos nombres terminan en `.test.ts` o `.test.tsx` | No | Pruebas que ejecuta [`claude plugin test`](https://code.claude.com/docs/es/plugins/mods/test#write-a-test) |

`register` recibe `on` y `options`. `options` contiene los valores de los campos de [`userConfig`](https://code.claude.com/docs/es/plugins/components#user-configuration) que declara el manifiesto, con los valores predeterminados ya completados.

## La función del hook

Un mod registra cada uno de sus hooks, que son controladores de eventos, llamando a `on` dentro de `register`. `on` recibe el nombre del evento, un [matcher](https://code.claude.com/docs/es/plugins/mods/events.md#filter-which-events-a-hook-handles) opcional, que es un filtro sobre los campos del evento, y el hook, como en `on('tool.call', { tool: 'Bash' }, async ($, e, next) => next(e))`. `on` devuelve un registro con un método, `.catch(handler)`, que establece el [controlador de errores](https://code.claude.com/docs/es/plugins/mods/events.md#handle-a-hook-that-fails) del hook.

| Argumento | Qué es |
| :- | :- |
| [`$`](https://code.claude.com/docs/es/plugins/mods/events#how-a-hook-handles-an-event) | La API de mods: todos los métodos de [métodos de la API de mods](#mods-api-methods). Escribe cada llamada completa, primero el espacio de nombres y luego el método, como en `$.fs.read('notes.md')`. |
| [`e`](https://code.claude.com/docs/es/plugins/mods/events#how-a-hook-handles-an-event) | La entrada del evento, como datos simples congelados en profundidad. Para cambiarla, pasa una copia a `next`. |
| [`next(e)`](https://code.claude.com/docs/es/plugins/mods/events#how-a-hook-handles-an-event) | El siguiente controlador, como en un middleware. Ejecuta los hooks posteriores a este y luego el comportamiento de Claude Code. Se resuelve con el resultado del evento. |
| [`next.signal`](https://code.claude.com/docs/es/plugins/mods/api#stop-background-work) | Un `AbortSignal` que se aborta cuando el evento se abandona |
| `next.origin` | `{ plugin, tier }` de quien disparó el evento. El propio Claude Code es `{ plugin: 'engine', tier: 'core' }`. El `tier` de un mod es su grupo de prioridad en el [orden en que se ejecutan los mods](https://code.claude.com/docs/es/plugins/mods/events.md#the-order-mods-run-in): `prepend`, `user`, `append` o `builtin`. |
| `next.budget` | El límite de tiempo del hook en milisegundos: `next.budget.ms` es el límite completo y `next.budget.remainingMs` es lo que queda en este momento |
| `next.to(e, tier)` | Salta a un tier posterior, que es `append`, `builtin` o `core`. `next.to(e, 'append')` omite los mods que instaló un usuario. Solo un mod en `prependPlugins` o `appendPlugins` puede llamarlo. |
| `next.error` | Solo en un controlador `.catch`. `kind` es `throw` o `timeout`, y `message` es el texto del error. |
| `next.called` | Solo en un controlador `.catch`. `true` cuando el hook había llamado a `next`. |

## Eventos

Los eventos se agrupan según lo que conciernen, cada uno con cuándo se dispara y qué puede devolver un hook sobre él. Los hooks de `turn.step` y `process.spawn` son generadores asíncronos, y los demás hooks son funciones asíncronas.

La última columna de cada tabla usa una notación abreviada. `next(e)` pasa el evento sin cambios. `next({ ...e, text })` pasa una copia con el campo indicado cambiado, como en `next({ ...e, text: e.text.trim() })`. Un objeto responde al evento sin llamar a `next`, y una palabra como `reason` representa una cadena que tú escribes, como en `{ deny: 'Use the file tools.' }`.

### Herramientas

Los eventos de herramientas se disparan alrededor de cada llamada a herramienta que hace Claude, desde la descripción que lee Claude hasta la decisión sobre si la llamada se ejecuta:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`tool.call`](https://code.claude.com/docs/es/plugins/mods/events#guard-or-change-a-tool-call) | Una herramienta está a punto de ejecutarse | `next(e)`, `{ deny: reason }` o `{ result }` |
| [`tool.check`](https://code.claude.com/docs/es/plugins/mods/events#where-settings-hooks-run-in-the-order) | Claude Code decide si una llamada a herramienta puede ejecutarse, después de los hooks `tool.call` y `PreToolUse`. `next(e)` se resuelve en la decisión a la que llegaron las reglas, el modo de permisos y esos hooks. | `next(e)` o `{ decision }`, con `decision` establecido en `allow`, `ask` o `deny` y un `reason` opcional |
| `tool.describe` | Una vez por cada herramienta, cuando su descripción se envía por primera vez a Claude. Una segunda vez para una herramienta MCP cuando Claude la carga mediante la [búsqueda de herramientas](https://code.claude.com/docs/es/mcp.md#scale-with-mcp-tool-search), con `e.description` establecido en el texto que lee Claude para la herramienta cargada. | `{ description }`, opcionalmente con `isDeferred` establecido en `true` para poner la herramienta detrás de la búsqueda de herramientas o en `false` para cargarla desde el inicio. Agrega [`breakPromptCache: true`](#break-prompt-cache) para enviar una descripción cambiada en el siguiente turno. |

#### Campos de agente y organización en `tool.check`

En un hook de `tool.check`, lee estos campos para distinguir la llamada de un subagente de la de la conversación principal, y para ver si tu organización requiere aprobación para una herramienta de conector:

* **`e.agentId`**: se establece cuando un [subagente](https://code.claude.com/docs/es/sub-agents.md) o un [compañero en proceso](https://code.claude.com/docs/es/agent-teams.md#choose-a-display-mode) hace la llamada, y está ausente cuando la hace la conversación principal
* **`e.ceiling`**: `ask` para una herramienta de conector que tu organización estableció en `ask`, en [sesiones en las que ese ajuste llega a Claude Code](https://code.claude.com/docs/es/mcp.md#organization-controls-on-connector-tools)

En `tool.check`, `e.agentId` y `e.ceiling` requieren Claude Code v2.1.290 o posterior.

#### El campo `e.isReadOnly` en `tool.check`

En un hook de `tool.check`, `e.isReadOnly` es `true` cuando la herramienta informa que esta llamada es de solo lectura. En caso contrario, el campo está ausente, no es `false`. El valor es el propio informe de la herramienta, así que lee [Comprobar si una llamada a herramienta es de solo lectura](https://code.claude.com/docs/es/plugins/mods/events.md#check-whether-a-tool-call-is-read-only) antes de aprobar una llamada basándote solo en este campo.

En `tool.check`, `e.isReadOnly` requiere Claude Code v2.1.304 o posterior.

### Prompts y lo que lee Claude

Los eventos de prompt abarcan el texto que escribe el usuario y el texto que Claude Code envía a Claude por su cuenta, como el prompt del sistema y los recordatorios:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`prompt.submit`](https://code.claude.com/docs/es/plugins/mods/events#rewrite-or-add-to-a-prompt) | Se envía un prompt | `next({ ...e, text })`, `next({ ...e, context })` o `{ drop: reason }` |
| `prompt.fill`, `prompt.suggest` | Un texto está a punto de entrar en el cuadro del prompt como borrador o como sugerencia atenuada | `next(e)` con el texto cambiado |
| `prompt.edit` | El usuario edita el cuadro del prompt | `next(e)` |
| `prompt.autocomplete` | El usuario escribe en el cuadro del prompt y una palabra termina en el cursor. `e.token` es esa palabra. Claude Code no espera al hook: sus propias filas de autocompletado se muestran primero. | `{ suggestions }`, una lista de filas `{ text, label, description }` que se muestran debajo de las propias de Claude Code. Elegir una fila escribe su `text` sobre la palabra. |
| `prompt.compose` | Claude Code genera un prompt del sistema | `{ sections }`, una lista de `{ id, text, scope }` en el orden en que se envían |
| [`prompt.section`](https://code.claude.com/docs/es/plugins/mods/events#rewrite-or-add-to-a-prompt) | Una vez por cada sección con nombre del prompt del sistema. `e.name` es el `id` de la sección en `prompt.compose`. | `{ text }`, o `{ text: null }` para omitir la sección. Agrega [`breakPromptCache: true`](#break-prompt-cache) para enviar una sección cambiada en el siguiente turno. |
| [`prompt.context`](https://code.claude.com/docs/es/plugins/mods/events#rewrite-or-add-to-a-prompt) | Una vez por cada conversación, para el contexto enviado con el primer mensaje | `{ blocks }` |
| `prompt.attachment` | Claude Code agrega un mensaje propio para Claude, como un recordatorio. `e.type` indica el tipo y, para los tipos que declaran las definiciones de tipos, `e.detail` contiene los datos a partir de los cuales se escribió el texto. | `{ text }`, o `{ text: null }` para omitirlo |
| `prompt.mention` | Claude Code está a punto de leer un archivo que un prompt menciona con @. Requiere Claude Code v2.1.290 o posterior. | `next({ ...e, path })` para leer un archivo diferente, o `{ deny: reason }` |
| [`skill.prompt`](https://code.claude.com/docs/es/plugins/mods/events#rewrite-or-add-to-a-prompt) | El texto de un skill se expande para Claude | `{ text }` |
| `attribution.text` | Claude Code compone el texto de atribución de un commit o pull request | `{ text }` |

#### Campos de origen y frontmatter en `skill.prompt`

En un hook de `skill.prompt`, puedes leer estos campos junto con el nombre del skill en `e.skill` y el texto que lee Claude en `e.text`:

| Campo | Tipo | Qué contiene |
| :- | :- | :- |
| `e.source` | string | Quién proporciona el skill: `policySettings`, `userSettings` o `projectSettings` para un skill en la [ubicación](https://code.claude.com/docs/es/skills.md#where-skills-live) empresarial, personal o de proyecto, respectivamente. Otros orígenes dan una palabra como `plugin`, `mcp`, `syncedSkills` o `built-in`. |
| `e.pluginName` | string | El nombre del plugin, para un skill cuyo `e.source` es `plugin` |
| `e.path` | string | La ruta absoluta del archivo `SKILL.md` del skill, o de su archivo `.md` para un skill escrito como [archivo de comando](https://code.claude.com/docs/es/skills.md#where-skills-live). Está ausente cuando el skill no tiene ningún archivo en esta máquina, como ocurre con un skill integrado. |
| `e.frontmatter` | object | El frontmatter del archivo del skill, como datos simples |
| `e.frontmatterProblem` | string | El motivo por el que a `e.frontmatter` le falta el frontmatter del archivo o una de sus claves, como en `is a list or a single value, not a table`. Está ausente cuando `e.frontmatter` contiene todo el frontmatter o el skill no tiene ninguno. |

Un hook puede pasar un `text` o `frontmatter` cambiado a `next`: los hooks posteriores leen ambos, y Claude lee el `text` final. Un hook que cambia cualquier otro campo [falla](https://code.claude.com/docs/es/plugins/mods/events.md#handle-a-hook-that-fails).

En `skill.prompt`, `e.source`, `e.pluginName`, `e.path`, `e.frontmatter` y `e.frontmatterProblem` requieren Claude Code v2.1.299 o posterior.

#### Enviar una sección del prompt del sistema o una descripción de herramienta cambiada con `breakPromptCache`

Para cambiar una sección o una descripción de herramienta en una conversación en curso, llama a `$.ui.invalidate('prompt.section')` o `$.ui.invalidate('tool.describe')` para que tu hook se ejecute de nuevo. Devuelve `{ text, breakPromptCache: true }` o `{ description, breakPromptCache: true }` desde él. Sin el campo, Claude sigue leyendo el texto [guardado con la conversación](https://code.claude.com/docs/es/cli-reference.md#system-prompt-flags-in-resumed-conversations) para una sección o una herramienta cargada desde el inicio hasta una nueva conversación o una [compactación](https://code.claude.com/docs/es/prompt-caching.md#compacting-the-conversation).

El texto cambiado llega a Claude en el siguiente turno, y la [caché de prompts](https://code.claude.com/docs/es/prompt-caching.md) empieza de nuevo, por lo que ese turno es más lento y más costoso. El campo requiere Claude Code v2.1.321 o posterior. Desde v2.1.299 hasta v2.1.321, una conversación en curso recibía el texto cambiado en el siguiente turno.

### Comandos y configuración

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`command.run`](https://code.claude.com/docs/es/plugins/mods/api#add-a-command) | Un comando está a punto de ejecutarse | `{ text }`, `{}` o `next(e)` |
| `command.describe` | Una vez por cada comando, para la lista de comandos | `{ description, argumentHint, isHidden }` |
| `config.set` | Una fila de `/config` está a punto de cambiar | `next({ ...e, value })` o `{ deny: reason }` |
| `config.describe` | Una vez por cada fila de `/config` | `{ label, description, isHidden }` |
| [`settings.read`](https://code.claude.com/docs/es/plugins/mods/events#settings-read-hook) | Un mod llama a [`$.settings.read`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network), o Claude Code genera la configuración combinada de la sesión. Requiere Claude Code v2.1.304 o posterior en la lectura propia de Claude Code y para `e.layers` | `next(e)`, `{ value }` o `{ deny: reason }` |

#### `e.layers` y `e.source` en `settings.read`

* **`e.layers`**: un objeto `{ source, settings }` por cada origen en uso que contiene configuración, empezando por el de menor [precedencia](https://code.claude.com/docs/es/settings.md#settings-precedence). Consulta [Qué recibe un hook de `settings.read`](https://code.claude.com/docs/es/plugins/mods/events#settings-read-receives).
* **`e.source`**: el único origen que pidió un mod, como en `$.settings.read({ source: 'policy' })`. Está ausente en la lectura propia de Claude Code y en una lectura de la configuración combinada

### Turnos

Los eventos de turno siguen una respuesta de principio a fin, incluida cada solicitud al modelo dentro de ella:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`turn.start`](https://code.claude.com/docs/es/plugins/mods/events#follow-a-turn) | Comienza un turno | `next(e)` |
| [`turn.step`](https://code.claude.com/docs/es/plugins/mods/events#follow-a-turn) | Una solicitud está a punto de enviarse al modelo | `yield* next(e)`, o `next({ ...e, model })`, `next({ ...e, effort })` |
| [`turn.complete`](https://code.claude.com/docs/es/plugins/mods/events#follow-a-turn) | Terminó un turno | `next(e)`, o `{ text }` para mostrar una línea debajo de la respuesta |

### Sesión

Los eventos de sesión marcan el inicio, el fin y la compactación de la sesión, y el intercambio de mensajes con otras sesiones:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`session.start`](https://code.claude.com/docs/es/plugins/mods/api#add-a-command-or-a-tool) | Una vez por cada mod cargado, antes del primer prompt, y de nuevo tras recargar ese mod. No después de `/clear`, `/resume` o `/branch`. | `next(e)` |
| `session.end` | La sesión termina, o se ejecuta `/clear`, `/resume` o `/branch`. `e.reason` es `clear`, `resume`, `logout`, `prompt_input_exit` u `other`. `/branch` informa `resume`. | `next(e)` |
| `session.compact` | La conversación está a punto de compactarse | `{ skip: reason }` |
| [`session.receive`](https://code.claude.com/docs/es/plugins/mods/api#send-and-receive-messages-between-sessions), [`session.send`](https://code.claude.com/docs/es/plugins/mods/api#send-and-receive-messages-between-sessions) | Llega un mensaje de otro agente o sesión, o está a punto de enviarse a uno. Consulta [Enviar y recibir mensajes entre sesiones](https://code.claude.com/docs/es/plugins/mods/api.md#send-and-receive-messages-between-sessions). | `{ consumed: reason }` para `receive`, `{ isDelivered: false, reason }` para `send` |
| `session.append` | Una vez por cada fila que conserva la conversación, como un prompt, un bloque de respuesta, un resultado de herramienta o un aviso, antes de almacenarla | `next({ ...e, message })` con un `message.content` cambiado, para reescribir los bloques de texto de la fila o el `content` de un bloque `tool_result` que contenga |
| `session.attach`, `session.detach` | Otra aplicación se conecta a la sesión o se desconecta de ella | `next(e)` |
| `session.measure` | Después de cada turno, y cuando cambia el porcentaje usado de un límite del plan | `next(e)` |

### Subagentes

Los eventos de subagentes se disparan cuando se ofrece un tipo de subagente a Claude y cuando un subagente o un compañero de un equipo de agentes está a punto de iniciarse:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| `agent.offer` | Se ofrece un tipo de subagente a Claude | `{ isOffered: false }` para ocultarlo |
| `agent.spawn` | Un subagente o un compañero de un [equipo de agentes](https://code.claude.com/docs/es/agent-teams.md) está a punto de iniciarse, o un subagente que terminó o se detuvo está a punto de ejecutarse de nuevo. Para un compañero, `e.isTeammate` es `true`. Para una ejecución reanudada, se establece `e.resume`. | `next({ ...e, model })` para elegir el modelo de uno que se está iniciando, o `{ deny: reason }` |

Tu hook de `agent.spawn` también se ejecuta cuando un subagente que terminó o se detuvo está a punto de ejecutarse de nuevo, por ejemplo cuando Claude le envía un mensaje con la herramienta [`SendMessage`](https://code.claude.com/docs/es/sub-agents#resume-subagents). En ese evento, `e.resume` es `{ agentId }`. Si tu hook cuenta subagentes, omite los eventos en los que `e.resume` está establecido, para que un subagente reanudado no se cuente de nuevo.

Devuelve `{ deny: reason }` para rechazar una ejecución reanudada. La ejecución no se inicia y el subagente se queda como estaba. Cuando una llamada a `SendMessage` solicitó la ejecución, Claude lee `a plugin declined the resume:` seguido de tu motivo como resultado de esa llamada. Si pasas un evento cambiado a `next` para una ejecución reanudada, como un `model` diferente, Claude Code ignora el cambio.

> [!NOTE]
>
> El evento para una ejecución reanudada requiere Claude Code v2.1.299 o posterior. Antes de v2.1.299, tu hook de `agent.spawn` no se ejecutaba cuando se reanudaba un subagente. En esas versiones, para rechazar las llamadas a `SendMessage` que reanudan un subagente, haz coincidir esa herramienta en un hook de [`tool.call`](https://code.claude.com/docs/es/plugins/mods/events#guard-or-change-a-tool-call).

### Interfaz

Los eventos de interfaz se disparan cuando Claude Code dibuja un punto de renderizado y cuando el usuario usa un control que dibujó un mod. [Dibujar en la interfaz](https://code.claude.com/docs/es/plugins/mods/interface.md) muestra lo que devuelve un hook de `ui.render`:

| Evento | Se dispara cuando |
| :- | :- |
| [`ui.render`](https://code.claude.com/docs/es/plugins/mods/interface#pick-where-to-draw) | Un [punto de renderizado](#render-sites) está a punto de dibujarse |
| `ui.resolve` | Se cargan los mods, una vez por cada aplicación, punto de renderizado y mod. El resultado es la tabla de elementos que lee `$.ui.resolve(e)`. |
| [`ui.press`](https://code.claude.com/docs/es/plugins/mods/interface#respond-to-presses-and-typing), [`ui.input`](https://code.claude.com/docs/es/plugins/mods/interface#respond-to-presses-and-typing), [`ui.select`](https://code.claude.com/docs/es/plugins/mods/interface#respond-to-presses-and-typing) | Se usa un `Button`, `Input` o `Select` que dibujó un mod |
| `ui.focus`, `ui.scroll` | El control enfocado o la posición de desplazamiento de un panel o de la banda está a punto de cambiar |
| `ui.close` | Un panel está a punto de cerrarse. `e.id` es el panel y `e.origin.kind` es `plugin`, `person` o `unload`. |
| [`ui.message`](https://code.claude.com/docs/es/plugins/mods/interface#build-a-tree-from-elements) | Un elemento `Client` publica datos en su mod |
| [`ui.fault`](https://code.claude.com/docs/es/plugins/mods/interface#redraw-when-something-changes) | Un elemento `Client` que dibujó tu mod no pudo cargarse, dibujarse o ejecutarse. `e.phase` es `load`, `render` o `run`, y `e.reason` es el mensaje de error. Requiere Claude Code v2.1.289 o posterior. |

### Otros mods

Estos eventos permiten que un mod actúe sobre otros mods mientras se cargan, para rechazar uno o cambiar la API de mods que recibe:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| [`plugin.register`](https://code.claude.com/docs/es/plugins/mods/admin#enforce-a-policy-with-a-mod-of-your-own) | Un módulo de hooks está a punto de cargarse. `e.uses` enumera sus eventos, llamadas a la API de mods, variables de entorno y estado, tal como los imprime `claude plugin validate`. Cada llamada se escribe sin el prefijo `$.`, como `fs.read`. | `{ refuse: reason }` |
| `engine.create` | Se está construyendo la API de mods para este mod | Una API de mods modificada, para agregar un espacio de nombres. Un mod fuera del [nivel](#the-hook-function) `user` también puede ocultar uno. |

Cuando el hook de otro mod llama a un método de un espacio de nombres que agregaste en `engine.create`, las llamadas a `$` de tu método se ejecutan en el contexto de ese hook hasta que todos los hooks de ese evento devuelven. Por ejemplo, una ruta relativa se resuelve respecto al directorio de trabajo de ese hook, y `$.prompt.submit` se rechaza mientras el turno está esperando a ese hook. Las llamadas que tu método hace después de eso se ejecutan en el contexto propio de tu mod.

### Telemetría

Los eventos de telemetría se disparan para los registros de uso que Claude Code registra:

| Evento | Se dispara cuando | Un hook puede devolver |
| :- | :- | :- |
| `telemetry.log`, `telemetry.mark` | Un registro de telemetría está a punto de registrarse, o se marca un uso de una funcionalidad. En un mod que instales, dale a un hook de telemetría el filtro `{ to: 'collector' }`, como en `on('telemetry.log', { to: 'collector' }, hook)`. Sin el filtro, el mod no pasa `claude plugin validate`. `*` no coincide con estos eventos. | `next(e)` o `{ deny: reason }` |

### Eventos de hooks de configuración

Cada [evento de hook de configuración](https://code.claude.com/docs/es/hooks.md#hook-events) es un evento llamado `classic.<Event>`, como `classic.Stop` o `classic.PostToolUse`. `e` es el JSON de stdin del hook.

### Llamadas a la API de mods

Cada [método de la API de mods](#mods-api-methods) también es un evento, nombrado según su espacio de nombres y su método, como `fs.read`, `model.complete` o `ui.open`. Un hook sobre uno puede devolver `next(e)`, `{ deny: reason }` o `{ value }`.

Algunos de estos eventos también se disparan para las acciones propias de Claude Code, así que comprueba si `next.origin.plugin` es `engine` antes de rechazar uno.

#### Campos en las solicitudes `http.fetch` propias de Claude Code

En un hook de `http.fetch`, un [`next.origin`](#the-hook-function) de `{ plugin: 'engine', tier: 'core' }` marca una de las solicitudes propias de Claude Code, como una solicitud al modelo, y no una llamada a `$.http.fetch` de un mod. Donde está cargada la [protección integrada](https://code.claude.com/docs/es/plugins/mods/admin.md#know-what-happens-by-default), tu hook no recibe estos eventos, salvo que tu mod [cuente como uno de tu organización](https://code.claude.com/docs/es/plugins/mods/admin.md#install-your-organizations-mods).

En estos eventos, `e.init` y el `value` en el que se resuelve `next(e)` pueden contener estos campos, entre otros:

| Campo | Qué significa |
| :- | :- |
| `e.init.compress` | Se establece cuando Claude Code comprime el cuerpo después de tu hook. `e.init.body` contiene el cuerpo sin comprimir. Para enviar el cuerpo sin comprimir, llama a `next({ ...e, init: { ...e.init, compress: undefined } })`. |
| `value.isStreaming` | Se establece en `true` porque Claude Code lee el cuerpo de la respuesta por sí mismo, así que `value.text` está vacío. Lee `value.status` y `value.headers` en su lugar. Para responder con tu propio `text`, devuelve un `value` sin `isStreaming`. |

Estos eventos y campos requieren Claude Code v2.1.321 o posterior.

## Métodos de la API de mods

La API de mods es el argumento `$` que recibe cada hook. Sus métodos están agrupados en espacios de nombres, como `$.ui`. Esta tabla enumera los métodos de cada espacio de nombres por su nombre, de modo que `open` en la fila de `$.ui` es la llamada `$.ui.open(...)`. Las guías muestran los más comunes en uso, y [los tipos para tu compilación](https://code.claude.com/docs/es/plugins/mods/create.md#get-the-types-for-your-build) documentan cada método con un ejemplo.

| Espacio de nombres | Métodos |
| :- | :- |
| `$.plugin` | `name`, `root`: el nombre y el directorio de este plugin |
| [`$.ui`](https://code.claude.com/docs/es/plugins/mods/interface#pick-where-to-draw) | `resolve`, `invalidate`, `open`, `close`, `panes`, [`place`](https://code.claude.com/docs/es/plugins/mods/interface#place-a-row-in-the-transcript), `focus`, `scroll`, `toast`, `notify`, `status`, `log`, `notice`, `ask`, `copy`, `selection`, `blit`, `view`. `view` requiere Claude Code v2.1.300 o posterior y `place`, v2.1.314 o posterior. |
| [`$.theme`](https://code.claude.com/docs/es/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `set`, `clear`: establece un fondo para que lo dibuje la app de escritorio o móvil, y quita el fondo. Requiere Claude Code v2.1.319 o posterior. |
| [`$.command`](https://code.claude.com/docs/es/plugins/mods/api#add-a-command) | `register`, `run`, `list` |
| [`$.tool`](https://code.claude.com/docs/es/plugins/mods/api#add-a-tool) | `register`, `call`, `check`, `list`. Cuando una `call` necesita la aprobación de una persona, como una que un hook o tu organización responde con `ask`, se resuelve con `{ deny: "<tool> wasn't run: this call needs a person's approval, and a mod's own call can't ask for it." }`, donde `<tool>` es el nombre de la herramienta. |
| `$.agent` | `register`, `spawn`, `list`. `list()` devuelve los subagentes y compañeros de equipo de esta sesión, cada uno con un `status` de `pending`, `running`, `waiting`, `idle`, `completed`, `failed` o `killed`, donde `idle` y `waiting` requieren Claude Code v2.1.289 o posterior. |
| [`$.model`](https://code.claude.com/docs/es/plugins/mods/api#call-a-model) | `complete`, `fork`, `classify` |
| [`$.prompt`](https://code.claude.com/docs/es/plugins/mods/api#start-a-turn-from-a-background-job) | `submit`, `read`, `fill`, `suggest`, `compose`. Claude lee el texto de `submit({ text })` después de una oración que nombra a tu mod como remitente. `submit({ text, asUser: true })` envía el texto como las propias palabras del usuario, sin esa oración. |
| `$.turn` | `abort` |
| [`$.session`](https://code.claude.com/docs/es/plugins/mods/api#send-and-receive-messages-between-sessions) | `messages`, `cwd`, `root`, `model`, `turns`, `id`, `repo`, `surfaces`, `usage`, `version`, `compact`, `send`, `append`, `authorize`. `usage()` devuelve `{ startedAt, context, rateLimits, cost }`: `context` tiene `tokens`, `window` y `percent`, y `rateLimits` es una lista de `{ kind, percentUsed, resetsAt }`. |
| `$.config` | `list`, `set` |
| [`$.settings`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `read` |
| [`$.env`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `get`, `set` |
| [`$.fs`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `read`, `write`, `list`, `exists`, `stat`, `ancestors`. `write` no es atómico: reemplaza el contenido del archivo en el lugar, por lo que otro proceso puede leer un archivo escrito parcialmente. Guarda en `$.store` los datos que varias sesiones modifican. |
| [`$.store`](https://code.claude.com/docs/es/plugins/mods/interface#keep-state) | `get`, `set`, `delete`, `keys`. Un almacén de clave-valor que comparten todas las sesiones de la máquina. Consulta [Guardar desde más de una sesión](https://code.claude.com/docs/es/plugins/mods/interface.md#save-from-more-than-one-session). |
| [`$.state`](https://code.claude.com/docs/es/plugins/mods/interface#keep-a-value-in-\$-state) | Estado reactivo: `get`, `set`, con los helpers `atom`, `read`, `update`, `derive` y `memberOf` importados de `claude-code` |
| [`$.clock`](https://code.claude.com/docs/es/plugins/mods/api#run-work-in-the-background) | `now`, `sleep`, `after`, `every` |
| [`$.http`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `fetch` |
| [`$.process`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `run`, `spawn` |
| [`$.mcp`](https://code.claude.com/docs/es/plugins/mods/api#reach-files-processes-and-the-network) | `call`, `connect`. `connect(server)` conecta un servidor MCP que el manifiesto de tu propio plugin enumera. |
| `$.audio` | `play`, `speak` |
| `$.telemetry` | `log`, `mark`. Un registro se envía solo cuando Claude Code o un mod integrado hace la llamada. |

## Puntos de renderizado

Un punto de renderizado es un punto de extensión en la interfaz de Claude Code. Cada fila es un valor de `e.component` en un hook `ui.render`, con los campos de `e.props` y las apps que lo renderizan. `e.surface` indica la app que está dibujando, como `terminal`, `desktop` o `vscode`. [Cambiar lo que Claude Code ya dibuja](https://code.claude.com/docs/es/plugins/mods/interface.md#change-what-claude-code-already-draws) muestra lo que un hook puede hacer en un punto de renderizado, con un ejemplo de cada opción.

Renderizar en la extensión de VS Code requiere la versión 2.1.299 o posterior de la extensión. Una sesión que [no obtiene los feature flags](https://code.claude.com/docs/es/env-vars.md#features-that-need-feature-flag-fetching) necesita la versión 2.1.304 o posterior. [Dibujar en la extensión de VS Code](https://code.claude.com/docs/es/plugins/mods/interface.md#draw-in-the-vs-code-extension) enumera lo que la extensión dibuja de forma diferente.

| Punto de renderizado | `e.props` | `e.requestId` | Se renderiza en |
| :- | :- | :- | :- |
| [`Pane`](https://code.claude.com/docs/es/plugins/mods/interface#pick-where-to-draw) | `title`, `isFocused`, `bodyColumns`, `placement`, `scroll`, `view` | El `id` del panel | Terminal, Desktop, VS Code |
| [`AbovePrompt`](https://code.claude.com/docs/es/plugins/mods/interface#pick-where-to-draw) | `hasSurvey`, [`isCollapsed`](https://code.claude.com/docs/es/plugins/mods/interface#when-the-user-collapses-the-band), `isWorking`, `maxRows`, `bodyColumns`, `scroll`, `view` | Una instancia | Terminal, Desktop |
| `AbovePromptList`, la pila de filas de `AbovePrompt` | `rows`, una lista con un `{ plugin, tree }` por cada fila de mod, además de las props de `AbovePrompt` | Una instancia | Terminal, Desktop. Requiere Claude Code v2.1.323 o posterior. |
| [`Placed`](https://code.claude.com/docs/es/plugins/mods/interface#place-a-row-in-the-transcript) | `id`, `plugin`, `onScreen` | El `requestId` que devolvió `$.ui.place` | Terminal |
| [`Backdrop`](https://code.claude.com/docs/es/plugins/mods/interface#put-a-backdrop-behind-the-conversation) | `scene`, `plugin`, `glass`, `overrideColorScheme`. Antes de v2.1.323, `scene` era `id` y `overrideColorScheme` era `colorScheme`. | `backdrop` | Superficies `desktop` y `mobile`. Tu hook se ejecuta cuando la app Desktop o la app móvil solicita dibujar un fondo. |
| `UserMessage` | `text`, `origin`, `isExpanded`, y `task` o `from` según el origen | El id de la fila dibujada | Terminal, Desktop, VS Code |
| `AssistantMessage` | El texto de la respuesta | El id de la fila dibujada | Terminal, Desktop, VS Code |
| `ToolUse`, `ToolResult`, `ToolGroup` | El nombre, la entrada y el resultado de la herramienta | El id de la llamada a herramienta | Terminal, Desktop, VS Code |
| `CommandOutput` | `command`, `text` | El id de la fila dibujada | Terminal, Desktop |
| [`AskUserQuestion`](https://code.claude.com/docs/es/plugins/mods/interface#change-what-claude-code-already-draws) | La pregunta y las opciones | El id de la llamada a herramienta | Terminal, Desktop, VS Code |
| `ToolProgress` | `kind` | El id de la llamada a herramienta | Terminal |
| [`Spinner`](https://code.claude.com/docs/es/plugins/mods/interface#change-what-claude-code-already-draws) | `word`, `message`, `suffix`, `mode` | El id del agente | Terminal, Desktop, VS Code |
| `TurnDuration` | `word`, `durationMs` | El id de la fila dibujada | Terminal |
| `InfoNotice` | `text`, `command` | El `text` del aviso con el prefijo `notice:` | Terminal |
| `SessionMode` | `modes` | Una instancia | Terminal, Desktop |
| `PromptHint` | `isDraft`, `isWorking`, `hint` | Una instancia | Terminal, Desktop |

`e.viewport` contiene `columns`, `rows` e `isFullscreen`. En la terminal y en la app Desktop, no está presente hasta que la app ha medido su ventana. Ahí, su `rows` es la altura de toda la ventana, no la de tu panel. En la extensión de VS Code, siempre está presente.

Para ajustar un árbol a su punto de renderizado, lee estas props en el hook:

* **Ancho de un `Pane` o de la banda**: dibuja según `e.props.bodyColumns`
* **Altura de un `Pane` junto a la transcripción**: cuando `e.props.placement` es `'dock'`, `e.props.scroll.bodyRows` es el número de filas que tiene el panel para tu árbol
* **Altura de un `Pane` encima del prompt**: cuando `e.props.placement` es `'inline'`, el panel crece con tu árbol hasta un límite, y `bodyRows` es ese límite. Para solicitar un límite distinto, consulta el [campo `rows` de `$.ui.open`](https://code.claude.com/docs/es/plugins/mods/interface#open-a-pane-at-the-right-time).

Un árbol más alto que el panel se desplaza como un todo.

## Elementos

Los elementos son los bloques de construcción de un árbol que devuelve un hook `ui.render`, y los obtienes de `$.ui.resolve(e)`. [Crea un árbol a partir de elementos](https://code.claude.com/docs/es/plugins/mods/interface.md#build-a-tree-from-elements) muestra los más comunes junto con cómo los dibuja la terminal, y la [galería de interfaces](https://code.claude.com/docs/es/plugins/mods/gallery.md) tiene capturas de pantalla de la mayoría. Una marca de verificación significa que la aplicación puede dibujar el elemento.

| Elemento | Props principales | Terminal | Escritorio | VS Code |
| :- | :- | :-: | :-: | :-: |
| [`Box`](https://code.claude.com/docs/es/plugins/mods/interface#build-a-tree-from-elements) | `key`, diseño flex, [`gap`, `padding`, `margin`](#box-spacing-steps), `width`, `height`, `minWidth`, `minHeight`, [`borderStyle`](#box-border-styles), `borderColor`, `borderDimColor`, `backgroundColor`, `position`, `top`, `left`, `right`, `bottom`, `overflow`, `display`, `hover` | ✓ | ✓ | ✓ |
| [`Text`](https://code.claude.com/docs/es/plugins/mods/interface#build-a-tree-from-elements) | `color`, `backgroundColor`, [`bold`](#text-bold), `italic`, `underline`, `strikethrough`, `dimColor`, `inverse`, `wrap`, [`size`, `weight`, `mono`, `tabular`](#text-typography), `hover` | ✓ | ✓ | ✓ |
| [`Button`](https://code.claude.com/docs/es/plugins/mods/interface#respond-to-presses-and-typing) | `key`, `label`, `children`, `onPress`, `hotkey`, `plain`, `dimColor`, `autoFocus`, `action`, `variant`, `role`, `hover` | ✓ | ✓ | ✓ |
| [`Link`](https://code.claude.com/docs/es/plugins/mods/interface#link-in-the-desktop-app) | `href`, `label`. Consulta [Límites](#limits). | ✓ | ✓ | ✓ |
| [`Code`](https://code.claude.com/docs/es/plugins/mods/gallery#show-code-and-changes) | `source`, `language`, `path`, `startLine`, `format`, `wrap` | ✓ | ✓ | ✓ |
| `Markdown` | `text`, `key`, `dimColor`, `onLinkPress`, `pressableLinks` | ✓ | ✓ | ✓ |
| [`Input`](https://code.claude.com/docs/es/plugins/mods/interface#take-typed-input-and-draw-a-row-for-each-item) | `key`, `label`, `placeholder`, `value`, `submitLabel`, [`rows`](https://code.claude.com/docs/es/plugins/mods/gallery#input), `onSubmit`, `onInput`, `autoFocus` | ✓ | ✓ | ✓ |
| `Select` | `key`, `label`, `options`, `value`, `onSelect`, `autoFocus` | ✓ | ✓ | ✓ |
| `Svg` | un `source` de marcado SVG de hasta 131,072 caracteres, texto `alt`, `width`, `height` e `isInteractive` | | ✓ | ✓ |
| [`Client`](https://code.claude.com/docs/es/plugins/mods/interface#build-a-tree-from-elements) | `module`, `key`, `props`, `width`, `height`, `flexGrow` | ✓ | ✓ | |
| [`Raster`](https://code.claude.com/docs/es/plugins/mods/interface#draw-a-grid-of-colored-cells) | `key`, `columns` hasta 512, `rows` hasta 256, `cells`. Consulta [Dibuja una cuadrícula de celdas de colores](https://code.claude.com/docs/es/plugins/mods/interface.md#draw-a-grid-of-colored-cells). | ✓ | | |
| `Image` | `key`, un `source` como bytes PNG o RGBA de hasta 2 MiB, o una ruta de archivo, `columns` y `rows` hasta 255, y texto `alt`. Consulta [qué terminales lo dibujan](https://code.claude.com/docs/es/plugins/mods/gallery.md#image-and-client). | ✓ | | |

Más reglas de `Button`:

* **`action`**: nombra una de las propias [acciones de atajos de teclado](https://code.claude.com/docs/es/keybindings.md) de Claude Code, y el atajo del usuario para ella presiona el botón cuando ese atajo es un acorde o una tecla con modificador
* **Hotkeys de dígito en la banda**: un `hotkey` de dígito en un botón de la banda también se activa cuando el usuario escribe solo ese dígito en un prompt vacío y hace una pausa
* **Una banda contraída**: mientras la banda está [contraída](https://code.claude.com/docs/es/plugins/mods/interface.md#when-the-user-collapses-the-band), ni un atajo de `action` ni un hotkey presionan un botón en ella
* **Dos botones con un mismo hotkey**: cuando dos de tus botones de un mismo dibujo nombran el mismo `hotkey`, el último se queda con él. Para el botón de otro mod con la misma tecla, consulta [Los hotkeys no hacen nada](https://code.claude.com/docs/es/plugins/mods/troubleshoot.md#hotkeys-do-nothing).
* **`variant`**: `primary` o `secondary`, y cualquier otro valor lanza un error. En la terminal, un botón `primary` se dibuja con el color de acento a menos que sea `plain`.
* **`role`**: `dismiss` marca un botón de cierre, y cualquier otro valor lanza un error. Haz el cierre en tu `onPress`. En una banda que contiene texto y una fila de botones, la aplicación de escritorio puede dibujar el primer botón `dismiss` de la fila como su propio control de cierre. La terminal dibuja el botón como lo haría sin `role`.

Un `Button` puede contener `children` en lugar de un `label`:

* **Qué pueden ser los children**: cadenas y elementos `Text`, como un nombre seguido de un detalle atenuado o una etiqueta de color. Claude Code rechaza cualquier otro elemento dentro de un `Button`.
* **Nombrar el botón**: el `label` nombra el botón y, de forma predeterminada, es el texto de sus children. Dale un `key` o un `label` a un botón cuyos children no sean una sola cadena.
* **En la terminal**: los children se dibujan donde estaría el label, y una pulsación en cualquier parte de ellos cuenta como una sola pulsación, así que puedes hacer que cada fila de una lista sea un único botón
* **En la aplicación de escritorio y la extensión de VS Code**: el botón dibuja su `label`

> [!NOTE]
>
> Un `Button` con children que no sean una sola cadena requiere Claude Code v2.1.295 o posterior.

`autoFocus` solo acepta `true` en cualquier control, así que omite la prop para dejarla desactivada.

La extensión de VS Code ignora algunas props de los elementos y dibuja el elemento como si las hubieras omitido:

* **`Box`**: `position` con sus `top`, `left`, `right` y `bottom`, `alignSelf`, `borderDimColor` y `hover`
* **`Text`**: `size`, `mono`, `tabular` y `hover`
* **`Button`**: `hotkey`, `plain`, `autoFocus`, `action` y `hover`, así que allí el usuario presiona un botón con un clic, o con Enter una vez que tiene el foco. La extensión también ignora `variant` y `role`.
* **`Code`**: `language`, `path`, `startLine`, `format` y `wrap`, así que el código se dibuja sin colores ni números de línea, y un bloque `format: 'diff'` muestra el texto sin procesar del diff
* **`Input` y `Select`**: `autoFocus`, y `rows` en un `Input`
* **`Svg`**: `isInteractive`

### Estilos de borde de `Box`

Para dibujar un borde alrededor de un `Box`, establece su `borderStyle` en uno de estos nombres, como en `borderStyle: 'round'`. Cada fila indica lo que dibuja la terminal para ese nombre y muestra el borde superior.

| `borderStyle` | Lo que dibuja la terminal | Borde superior |
| :- | :- | :- |
| `'single'` | Líneas finas con esquinas cuadradas | `┌──┐` |
| `'double'` | Líneas dobles | `╔══╗` |
| `'round'` | Líneas finas con esquinas redondeadas | `╭──╮` |
| `'bold'` | Líneas gruesas | `┏━━┓` |
| `'singleDouble'` | Líneas finas arriba y abajo, líneas dobles en los lados | `╓──╖` |
| `'doubleSingle'` | Líneas dobles arriba y abajo, líneas finas en los lados | `╒══╕` |
| `'classic'` | Los caracteres ASCII `+`, `-` y `\|` | `+--+` |
| `'arrow'` | Flechas que apuntan hacia el interior del `Box` | `↘↓↓↙` |
| `'dashed'` | Líneas discontinuas con esquinas en blanco | `╌╌` |
| `'quote'` | Una barra, `▎`, a lo largo del lado izquierdo y celdas en blanco en los otros tres lados | En blanco |

Un `Box` cuyo `borderStyle` nombra cualquier otra cosa, como `'rounded'`, se dibuja sin borde.

### Pasos de espaciado de `Box`

Las props de espaciado de `Box` son `gap`, `columnGap`, `rowGap`, `padding`, `margin` y las formas de un solo lado y de un solo eje de `padding` y `margin`, como `paddingX` y `marginTop`. Cada una acepta un número de celdas de la terminal, como `gap: 1`, o un nombre de paso, como `gap: 'md'`. En la terminal y en la extensión de VS Code, cada paso equivale a esta cantidad de celdas:

| Paso | Celdas en horizontal | Celdas en vertical |
| :- | :- | :- |
| `'xs'` | 1 | 0 |
| `'sm'` | 1 | 0 |
| `'md'` | 2 | 1 |
| `'lg'` | 3 | 1 |
| `'xl'` | 4 | 2 |

Si estableces `gap`, `padding` o `margin` en un paso, el paso se aplica en horizontal y en vertical a la vez. Por ejemplo, en la terminal y en la extensión de VS Code, `padding: 'md'` equivale a dos celdas a cada lado y una fila arriba y abajo.

Los nombres de paso requieren Claude Code v2.1.299 o posterior. En una versión anterior, un árbol que usa un nombre de paso no se dibuja.

### Props tipográficas de `Text`

Establece `size`, `weight`, `mono` o `tabular` en un `Text` para pedirle a la aplicación que dibuja tu árbol un tamaño de texto, un grosor, una tipografía monoespaciada o dígitos de ancho uniforme. Antes de depender de una prop, comprueba qué hacen con ella la terminal y la extensión de VS Code. Si una aplicación ignora una prop que estableciste, tu árbol se sigue dibujando allí, con el texto como si hubieras omitido esa prop.

| Prop | Valores | En la terminal | En la extensión de VS Code |
| :- | :- | :- | :- |
| `size` | `'caption'`, `'footnote'`, `'body'`, `'heading'` o `'title'` | Se ignora: la terminal tiene un solo tamaño de texto | Se ignora |
| `weight` | `'regular'`, `'medium'`, `'semibold'` o `'bold'` | `semibold` y `bold` se dibujan como texto en negrita | `semibold` y `bold` se dibujan como texto en negrita |
| `mono` | `true` para pedir la tipografía monoespaciada de la aplicación | Se ignora: la terminal siempre es monoespaciada | Se ignora, así que el texto conserva la tipografía propia de la extensión |
| `tabular` | `true` para pedir dígitos de ancho uniforme, de modo que un número que se actualiza en su lugar o una columna de números se mantenga alineada | Se ignora: los dígitos de la terminal ya ocupan una celda de ancho | Se ignora |

Estas cuatro props requieren Claude Code v2.1.299 o posterior. En una versión anterior, un árbol que establece `size`, `weight`, `mono` o `tabular` no se dibuja.

#### Reemplaza `bold` por `weight`

`bold` en un `Text` está obsoleto en favor de `weight` y sigue funcionando. Para reemplazarlo en un `Text` sin `weight`, cambia `bold: true` por `weight: 'semibold'` para obtener el mismo resultado en Claude Code v2.1.299 o posterior.

En una versión anterior a v2.1.299, un árbol que establece `weight` no se dibuja. Si estableces tanto `bold` como `weight` en un `Text`, `bold` no tiene efecto.

## Límites

Las llamadas a la API de hooks y mods se ejecutan con límites de tiempo y de tamaño. Claude Code omite un hook que supera un límite de tiempo. Un árbol que supera el límite de anidamiento, de elementos, de celdas de `Raster` o de bytes de `Image` [no se dibuja](https://code.claude.com/docs/es/plugins/mods/troubleshoot.md#a-pane-or-band-is-empty).

| Límite | Valor |
| :- | :- |
| El tiempo de ejecución propio de un hook para un evento, sin contar el tiempo dentro de `next` ni de una llamada a la API de mods distinta de `$.clock.sleep` | 10 segundos, o 50 milisegundos para un hook `prompt.edit` |
| El tiempo de ejecución de un controlador `.catch` | 1 segundo |
| Todos los hooks `session.end` en conjunto | Lo mismo que el [presupuesto del hook SessionEnd](https://code.claude.com/docs/es/hooks.md#sessionend-input), 1.5 segundos a menos que lo cambies, contado desde que terminan los hooks `SessionEnd` de tu configuración |
| Tiempo de espera de `$.process.run` | 30 segundos de forma predeterminada, 10 minutos como máximo |
| `stdout` y `stderr` de `$.process.run` | 4 MiB cada uno. `isStdoutTruncated` o `isStderrTruncated` es `true` cuando se cortó uno de ellos. |
| `maxTokens` de `$.model.complete` | 1024 de forma predeterminada, hasta 64,000 o el límite de salida del modelo |
| `$.fs.read` y `$.fs.write` | 4 MiB por archivo |
| El cuerpo de una solicitud de `$.http.fetch` | 4 MiB, contados en caracteres. Una llamada con un cuerpo más grande se rechaza. |
| El cuerpo de una respuesta de `$.http.fetch` | 4 MiB. `text` contiene los primeros 4 MiB y el resto no se lee. Cuando el encabezado `Content-Length` declara más, la llamada se rechaza en su lugar, con un motivo que termina en `is over the 4194304-byte limit`, excepto cuando la última solicitud después de cualquier redirección usa el método `HEAD`. La exención de `HEAD` requiere Claude Code v2.1.296 o posterior. |
| Una llamada a `$.http.fetch`, incluidos las redirecciones y el cuerpo | 30 segundos |
| Redirecciones que sigue una llamada a `$.http.fetch` | 5 |
| El motivo de `drop` de un hook o el motivo de `deny` de `config.set` | 4,096 caracteres. Se corta el final de un motivo más largo, y el drop o deny se sigue aplicando. El corte requiere Claude Code v2.1.292 o posterior, y en versiones anteriores el hook [falla](https://code.claude.com/docs/es/plugins/mods/events.md#handle-a-hook-that-fails) en su lugar. |
| Texto en un árbol | Se dibujan los primeros 100,000 caracteres |
| El `language` o `path` de un `Code`, el `value` de una opción de `Select` o el `module` de un `Client` | 10,000 caracteres. Si alguno es más largo, el hook `ui.render` que lo devolvió [falla](https://code.claude.com/docs/es/plugins/mods/events.md#handle-a-hook-that-fails). |
| El `href` de un `Link` | 2,048 caracteres. Si es más largo, el hook `ui.render` que lo devolvió [falla](https://code.claude.com/docs/es/plugins/mods/events.md#handle-a-hook-that-fails). |
| Profundidad de anidamiento de un árbol | 32 niveles por debajo del elemento raíz |
| Elementos e hijos de texto en un árbol | 20,000 |
| Celdas de `Raster` en un árbol, las `columns` de cada `Raster` multiplicadas por sus `rows` | 262,144 |
| Las filas encima del prompt, apiladas | Los elementos, las celdas de `Raster` y los bytes de `Image` se suman entre todas las filas y se comparan con los límites de un árbol |
| Bytes PNG o RGBA de todas las `Image` de un árbol | 2 MiB |
| `$.store` | 4 MiB de JSON en total |
| `$.session.messages()` | Las 4,096 entradas más recientes |
| Redibujados de `$.ui.invalidate('ui.render')` | Limitados a 10 por segundo, o 30 en la terminal para el panel visible, la banda expandida y la línea de sugerencia debajo del prompt. Las llamadas que llegan antes se agrupan. |
| `$.ui.toast` | Se muestra durante 4 segundos a menos que pases `{ timeoutMs }`. En el [renderizador clásico](https://code.claude.com/docs/es/fullscreen.md#enable-fullscreen-rendering), un toast más reciente de un mod puede [ocupar el lugar de uno anterior del mismo mod](https://code.claude.com/docs/es/plugins/mods/troubleshoot.md#a-toast-doesn’t-appear) que se está mostrando o esperando para mostrarse. |
| Un panel abierto sin que el usuario lo pida | Se coloca a partir de 144 columnas de la terminal, 110 después de que lo haya abierto una vez |
| Filas de `$.ui.place` que un mod tiene en una conversación al mismo tiempo | 500. En el límite, una llamada con un `id` nuevo se resuelve como `{ isPlaced: false, reason: 'a plugin holds at most 500 placed rows' }`. |
| Profundidad de anidamiento de los argumentos de una llamada a la API de mods | 28,000 niveles. A partir de ahí, la llamada se rechaza con un mensaje que termina en `nesting deeper than 28000 levels is not supported`. Requiere Claude Code v2.1.299 o posterior. |
| Profundidad de anidamiento de un evento modificado que se pasa a `next`, fuera de los [hooks de generador asíncrono](#events) como uno en `turn.step` | 28,000 niveles. A partir de ahí, `next` se rechaza con un mensaje que termina en `nesting deeper than 28000 levels is not supported`. Requiere Claude Code v2.1.299 o posterior. |
| Profundidad de anidamiento del valor de retorno de un hook, fuera de `ui.render`, `ui.resolve` y los hooks de generador asíncrono | 28,000 niveles. A partir de ahí, se rechaza el resultado del hook, y [la notificación que lo informa](https://code.claude.com/docs/es/plugins/mods/troubleshoot.md#find-out-why-a-mod-does-nothing) incluye `nesting deeper than 28000 levels is not supported`. Requiere Claude Code v2.1.299 o posterior. |
| Alcances, como funciones, bloques y bucles, anidados unos dentro de otros en un archivo de un módulo de hooks | 2,000 |
| Nombres de comandos, herramientas, tipos de subagente y paneles, el `id` de una fila colocada y la `scene` de un fondo | Letras, dígitos, `_` y `-`, hasta 64 caracteres |
| Una prueba de `claude plugin test` | 5 segundos a menos que la prueba establezca `timeoutMs` |

## Configuración y variables de entorno

Estos son los ajustes y las variables de entorno que afectan a los mods. La columna Dónde indica desde qué archivo de configuración o entorno se lee cada uno:

| Nombre | Dónde | Qué hace |
| :- | :- | :- |
| `CLAUDE_CODE_PLUGIN_DIRS` | Entorno, o `env` en `~/.claude/settings.json` | Directorios de plugins que se cargan como lo hace `--plugin-dir`, para aplicaciones a las que no puedes pasar un flag. Rutas absolutas separadas por `:`, o por `;` en Windows. |
| `CLAUDE_CODE_PLUGIN_DIR_WATCH` | Entorno | Si los mods se recargan al guardar. Consulta la [referencia de variables de entorno](https://code.claude.com/docs/es/env-vars.md) para ver los valores predeterminados y los valores posibles |
| `prependPlugins`, `appendPlugins` | Configuración administrada. Configuración de usuario solo en una máquina sin configuración administrada ni archivo [`managed-mcp.json`](https://code.claude.com/docs/es/managed-mcp#deploy-managed-mcp-json), en una sesión cuya credencial no sea un `/login` de Team o Enterprise. | Listas de ids de plugins, como `acme-guard@acme-tools`. Los mods en `prependPlugins` se ejecutan antes de cada mod que instala un usuario, y los mods en `appendPlugins` se ejecutan después, en el orden indicado. Consulta [El orden en que se ejecutan los mods](https://code.claude.com/docs/es/plugins/mods/events.md#the-order-mods-run-in). |
| `allowManagedModsOnly` | Configuración administrada, como una [opción de la protección integrada](https://code.claude.com/docs/es/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Solo los mods que [cuentan como de tu organización](https://code.claude.com/docs/es/plugins/mods/admin.md#install-your-organizations-mods) y los mods integrados en Claude Code ejecutan sus hooks. Los hooks de configuración de los usuarios siguen ejecutándose. |
| `allowModsToOverrideDenyRules` | Configuración administrada, como una [opción de la protección integrada](https://code.claude.com/docs/es/plugins/mods/admin.md#set-options-on-the-built-in-guard) | Permite que un mod instalado por un usuario apruebe una llamada a herramienta pasando por encima de la mayoría de [los resultados que se mantienen por defecto](https://code.claude.com/docs/es/permissions.md#precedence-among-rules-hooks-and-mods), incluida una regla `deny` |
| `allowManagedHooksOnly` | Configuración administrada | Bloquea los hooks y los mods instalados que no son de tu organización. Consulta [qué sigue ejecutándose](https://code.claude.com/docs/es/settings-reference.md#what-runs-under-allowmanagedhooksonly). |
| `disableAllHooks` | Cualquier archivo de configuración | En la configuración administrada, no se ejecuta ningún mod ni hook de un plugin instalado. En tu propia configuración, lo que administra tu organización sigue ejecutándose. Consulta [`disableAllHooks`](https://code.claude.com/docs/es/settings-reference#disableallhooks). |
| `disableSideloadFlags` | Configuración administrada | Rechaza `--plugin-dir` y `--plugin-url` al inicio |
| `pluginConfigs` | Configuración de usuario o administrada | Contiene los valores de `userConfig` de un mod, indexados por el id del plugin, como `acme-guard@acme-tools`, o por su nombre y `@inline`, como `first-mod@inline`, para uno cargado con `--plugin-dir` |

`sec-default@builtin` es una protección integrada en Claude Code, que aparece como `cc-plugin-sec-default` en `/plugin` y en el registro de depuración. [Donde se carga](https://code.claude.com/docs/es/plugins/mods/admin.md#know-what-happens-by-default), se ejecuta antes de cada mod que una persona instala. Si se establece `prependPlugins` en la configuración administrada, la protección solo se carga cuando esa lista la nombra, en la posición indicada.

Su código fuente está en el [directorio `mods/sec-default` del repositorio de Claude Code](https://github.com/anthropics/claude-code/tree/main/mods/sec-default).

## Comandos

Estos comandos y flags cargan, inspeccionan y prueban un mod. Los comandos `claude` se ejecutan en tu shell y los comandos `/` en el prompt de Claude Code. En la tabla, `<directory>` representa una ruta que escribes, como en `claude plugin validate ./first-mod`. Los corchetes marcan un argumento opcional.

| Comando | Qué hace |
| :- | :- |
| [`/plugin`](https://code.claude.com/docs/es/plugins/mods/overview#see-which-mods-a-session-loaded) | Muestra una línea como `1 mod active · first-mod` debajo de sus pestañas cuando se ha cargado un mod que no viene integrado |
| [`claude plugin validate <directory>`](https://code.claude.com/docs/es/plugins/mods/create#check-what-claude-code-reads-from-your-mod) | Lee el manifiesto y el módulo de hooks de un plugin e informa los errores, los eventos que maneja y las llamadas a la API de mods que realiza. `--strict` trata las advertencias como errores y `--json` imprime un informe legible por máquina. |
| [`claude plugin test [directory]`](https://code.claude.com/docs/es/plugins/mods/test#write-a-test) | Ejecuta cada archivo dentro del directorio, o del directorio actual cuando no indicas ninguno, cuyo nombre termina en `.test.ts` o `.test.tsx`. Sale con estado 1 cuando una prueba falla. |
| [`claude --plugin-dir <directory>`](https://code.claude.com/docs/es/plugins/mods/create#write-a-mod-yourself) | Carga un directorio de plugin durante una sesión y vuelve a cargar su módulo de hooks cuando guardas. Repite el flag para cargar varios. |
| `/reload-plugins` | Vuelve a cargar los plugins cuando lo ejecutas |
