$, con los métodos agrupados en espacios de nombres como $.ui y $.fs. Los eventos deciden cuándo se ejecuta un hook, y la API de mods es lo que el hook llama una vez que se ejecuta.
Crea tu primer mod antes de empezar aquí. Para ver todos los métodos, consulta métodos de la API de mods o lee los tipos para tu compilación.
Agregar un comando o una herramienta
Un mod puede agregar un comando para que el usuario lo ejecute y una herramienta para que Claude la llame. Registra ambos en un hooksession.start. Claude Code espera a ese hook antes del primer prompt, así que lo que registres está disponible desde el primer turno.
Agregar un comando
Un comando es para el usuario. Regístralo y luego manejacommand.run para su nombre. Este ejemplo agrega un comando /standup que acepta un número opcional de días:
/standup aparece con su descripción en la lista que ves cuando escribes /. El argumentHint se muestra en el prompt después de que escribes el comando y un espacio, como en /standup [days]. Cuando ejecutas /standup 3, el segundo hook devuelve Summary for the last 3 day(s): ..., y la transcripción muestra ese texto después del nombre del plugin. El hook nunca llama a next, porque el comando no tiene otro comportamiento además del tuyo.
El text que devuelves se imprime en la transcripción y Claude lo lee. Para no imprimir nada, como hace un comando que solo abre un panel, devuelve {}. Para permitir que el comando se ejecute mientras Claude está trabajando, agrega immediate: true al registro.
Elige un nombre que no use ningún comando integrado. Escribe / en una sesión para verlos. $.command.register lanza un error para un nombre ya ocupado, con un mensaje como "/focus" refused: it is the built-in /focus. Un hook que lanza un error se omite, así que el resto de tu hook session.start tampoco se ejecuta. Registra los comandos al final de ese hook, o envuelve la llamada en try y catch.
Agregar una herramienta
Una herramienta es para Claude. Regístrala con un nombre, una descripción que Claude lee y un JSON Schema para su entrada. Claude la ve con un nombre más largo formado pormcp__, el nombre de tu plugin, dos guiones bajos y el nombre que registraste. Manejas sus llamadas en un hook tool.call filtrado a ese nombre completo. Este ejemplo, de un plugin llamado my-mod, registra ticket, por lo que el nombre completo es mcp__my-mod__ticket. Le da a Claude una herramienta que busca un ticket en un gestor de incidencias:
mcp__my-mod__ticket con su id. El segundo hook obtiene el ticket y devuelve el cuerpo de la respuesta, que Claude lee como el resultado de la herramienta. Cuando el servidor responde con un código de estado de error, Claude lee Lookup failed with status y el número.
Llamar a un modelo
Un mod puede enviar sus propias solicitudes a un modelo para una tarea pequeña como clasificar o resumir texto.$.model.complete envía tu prompt por sí solo, y $.model.fork({ prompt }) envía la conversación actual con tu prompt al final.
Esta tabla compara lo que contiene cada solicitud:
Un fork repite la última solicitud de la conversación, por lo que la API de Claude sirve la mayor parte desde la caché de prompts mientras la conversación siga en caché.
Ambas llamadas usan las credenciales de la sesión, por lo que se facturan al plan, la clave de API o el proveedor de nube del usuario. Los tipos de tu compilación documentan todos los métodos de
$.model.
Enviar un prompt
Pasamodel y prompt a $.model.complete. prompt se convierte en el mensaje de usuario. Para darle instrucciones al modelo, como un rol o un formato de salida, pasa también system, que se convierte en el prompt del sistema.
Este hook responde a un comando /triage, registrado como comando, pidiéndole a un modelo pequeño que etiquete el texto escrito después de él:
/triage the export button does nothing, el mod envía ese texto al modelo e imprime su respuesta, como Label: bug. Cuando el modelo no responde, la etiqueta es unknown.
Un fallo de la API de Claude no rechaza la llamada, así que comprueba r.isAnswered y lee r.reason cuando sea false. La llamada se rechaza ante una solicitud que Claude Code no enviará, como un modelo que tu organización bloquea.
Los tipos de tu compilación enumeran las demás opciones, como effort, y los límites indican el valor predeterminado de maxTokens.
Usar la caché de prompts
$.model.complete admite la caché de prompts de la API de Claude. La API almacena en caché el inicio de una solicitud, llamado prefijo, hasta un punto de interrupción de caché que tú defines. Cuando todas las llamadas empiezan con el mismo contenido estático extenso, como instrucciones o material de referencia, define un punto de interrupción al final de ese contenido. Así, las llamadas posteriores lo leen desde la caché en lugar de pagar el precio completo de entrada por él.
Para definir un punto de interrupción, pasa prompt como un arreglo de bloques { text } en lugar de una cadena, y agrega cache: true al último bloque del contenido estático. Claude Code envía ese bloque con el campo cache_control de la API. system acepta la misma forma de arreglo. Para decidir entre ambos, consulta Elegir entre prompt y system.
Los arreglos de bloques requieren Claude Code v2.1.292 o posterior. Las versiones anteriores rechazan un arreglo en
prompt con un error que termina en takes { model, prompt } (host check), y omiten de la solicitud un arreglo en system./triage envía un conjunto extenso de reglas de etiquetado antes del texto a etiquetar, con un punto de interrupción después de las reglas. RULES es una cadena propia:
- TTL: una entrada de caché dura cinco minutos después de su último uso. El TTL proviene de la configuración de Claude Code del usuario, no de la llamada. Para una hora, establece
subagentPromptCacheTtlen1h. - Puntos de interrupción por solicitud: la API acepta hasta cuatro, y uno más vuelve como un
api-errorenr.reason
Elegir entre prompt y system
Coloca el contenido estático que comparten tus llamadas al inicio de prompt, a menos que sepas que tus solicitudes van directamente a la API de Claude:
- Directamente a la API de Claude, con una clave de API o una suscripción a Claude: cualquiera de los dos campos funciona
- A través de Amazon Bedrock, Claude Platform on AWS, Agent Platform de Google Cloud, Microsoft Foundry o un gateway de LLM: usa
prompt. Claude Code comienza el prompt del sistema con un bloque de atribución cuya huella digital proviene del inicio del mensaje de usuario. El endpointapi.anthropic.comelimina ese bloque antes de almacenar en caché. Otros endpoints lo reciben como parte del prompt, por lo que un punto de interrupción ensystempuede fallar cuandopromptempieza de forma distinta. - En un mod que ejecutan otras personas: usa
prompt, porque tú no eliges su proveedor
system va antes que prompt en el prefijo, por lo que un punto de interrupción en prompt también cubre system, y una llamada con un system distinto no acierta en la caché.
Comprobar los aciertos de caché
El resultado de$.model.complete tiene un objeto usage con los campos de caché de la API. usage.cache_creation_input_tokens cuenta los tokens que la llamada escribió en la caché, y usage.cache_read_input_tokens cuenta los tokens que leyó de la caché. Espera una escritura en la primera llamada y lecturas en las llamadas posteriores dentro del TTL.
Si todas las llamadas escriben y ninguna lee, el prefijo difiere entre llamadas o las llamadas están más separadas que el TTL. Si el prefijo difiere, consulta Elegir entre prompt y system.
Si ambos campos se quedan en cero en llamadas que el modelo respondió, no se almacenó nada en caché. Comprueba cada una de estas causas:
- El prefijo es demasiado corto: la API no almacena en caché un prefijo por debajo de la longitud mínima del modelo, y no devuelve ningún error
- La caché de prompts está desactivada: cuando una variable
DISABLE_PROMPT_CACHINGse aplica al modelo, Claude Code elimina los puntos de interrupción y envía el texto sin caché - Tu gateway elimina
cache_control: un gateway puede eliminar el campo y aun así devolver éxito - Otro mod reescribe el inicio del texto: Claude Code entonces lo envía sin puntos de interrupción
Qué recibe un hook de model.complete
Si conectas un hook al evento model.complete para inspeccionar o modificar las solicitudes de otros mods, lee el texto desde estos campos:
e.prompt: siempre es una cadena. Cuando quien llama pasó un arreglo, es el texto de los bloques concatenado en orden.e.system: una cadena construida de la misma forma, o ausente cuando quien llama no pasósysteme.promptBlocksye.systemBlocks: los arreglos de quien llama, cada uno presente cuando quien llama pasó un arreglo para ese campo
next y usa los arreglos que pasas con ellas para ubicar los puntos de interrupción de caché. Conserva los bloques iniciales que todavía coinciden con el inicio de la cadena, con sus puntos de interrupción, y envía el resto de la cadena sin punto de interrupción. Por ejemplo, next({ ...e, prompt: e.prompt + NOTE }) conserva los puntos de interrupción de quien llama, y un hook que cambia el inicio de prompt los elimina.
Ejecutar trabajo en segundo plano
El trabajo que dura más que un evento, como revisar algo una vez por minuto, se ejecuta en un temporizador que inicias desdesession.start. Un hook en sí se ejecuta para un evento y tiene un límite de tiempo sobre su propio tiempo de ejecución. El tiempo dedicado a esperar a next o a una llamada a la API de mods no cuenta, excepto un $.clock.sleep. $.clock.every y $.clock.after reemplazan a setInterval y setTimeout, con el retraso en milisegundos primero: $.clock.after(5000, fn) llama a fn una vez, dentro de cinco segundos. Cada uno devuelve un temporizador con un método cancel(), y await $.clock.now() da la hora en milisegundos.
Este hook consulta las comprobaciones de un pull request una vez por minuto y muestra el resultado debajo del prompt. summarize es una función propia que convierte la salida JSON del comando en unas pocas palabras:
⚠, el nombre del mod y luego checks: y tu resumen. Se reemplaza una vez por minuto a partir de entonces. La función de callback del temporizador se ejecuta fuera de cualquier evento, por lo que sigue ejecutándose entre turnos y no inicia ninguno. Si la función de callback lanza una excepción, el error va al registro de depuración y el temporizador se ejecuta de nuevo en el siguiente intervalo.
Mostrar algo sin iniciar un turno
Un trabajo en segundo plano puede mostrarle algo al usuario sin iniciar un turno. Cada una de estas llamadas coloca texto en un lugar diferente:$.ui.notify es la única de estas llamadas que responde. Se resuelve con { isSent: true, channel } cuando el canal del usuario escribió la notificación en su terminal. channel es el valor del ajuste que la envió, como kitty o terminal_bell. El canal terminal_bell hace sonar la campana y no muestra ni tu texto ni el título.
De lo contrario, la llamada se resuelve con { isSent: false, reason }:
La llamada se rechaza en lugar de resolverse cuando
text no es una cadena, cuando el hook de otro mod sobre ui.notify devuelve { deny }, o cuando falla la escritura en la terminal.
Tu mod no puede elegir el canal, y Claude Code no limita la frecuencia con la que un mod envía notificaciones. El ajuste del usuario es el único interruptor.
Cuando la llamada llega a una sesión en ejecución, se ejecutan los hooks de Notification del usuario con el tipo plugin_notification. Se ejecutan incluso cuando la respuesta es disabled, y en una sesión sin terminal, donde la respuesta es no-surface. No se ejecuta ningún hook para una llamada hecha antes de que se inicie la sesión o mientras Claude Code se está cerrando. El hook desde el que tu mod llamó a $.ui.notify queda fuera de esa ejecución, por lo que un hook classic.Notification que envía notificaciones no se vuelve a llamar para su propia notificación.
Una terminal no informa si mostró la notificación, así que isSent: true significa que se envió, no que el usuario la vio.
Este ejemplo envía una notificación cuando el turno de la conversación principal termina sin una interrupción, y recurre a una notificación emergente cuando no salió ninguna notificación con texto. No espera a la notificación antes de pasar el evento, porque los hooks de Notification del usuario se ejecutan primero y pueden tardar un poco:
Iniciar un turno desde un trabajo en segundo plano
Cuando un trabajo en segundo plano encuentra algo que necesita la atención de Claude, puede iniciar un turno enviando un prompt con$.prompt.submit({ text }). Claude lee el texto después de una oración que nombra a tu mod como remitente. Para enviarlo como las propias palabras del usuario, sin esa oración, agrega asUser: true. La llamada espera hasta que la sesión esté inactiva y luego inicia un nuevo turno. Se resuelve cuando ese turno comienza, así que no uses await con ella en un handler que se ejecute mientras Claude está trabajando.
Detener el trabajo en segundo plano
Los temporizadores se detienen después de que el módulo se recarga. Para trabajo de larga duración dentro de un hook,next.signal es un AbortSignal que se aborta cuando se abandona el evento que tu hook está manejando, por ejemplo cuando el usuario interrumpe. Pásalo a cualquier cosa de larga duración.
Llamadas y trabajo en segundo plano después de que el usuario interrumpe un turno
El motivothe session was stopped and nobody has sent input since en un resultado o error significa que el usuario detuvo un turno en ejecución, por ejemplo con Esc o Stop. Después de esa interrupción, las llamadas que inician trabajo nuevo en la sesión se rechazan hasta la siguiente entrada del usuario, como un mensaje en el prompt.
Aparte de $.prompt.submit y $.command.run, este manejo de las llamadas y del trabajo en segundo plano después de una interrupción requiere Claude Code v2.1.304 o posterior.
Reintentar una llamada rechazada o descartada
Vuelve a hacer una llamada rechazada o descartada desde un hook deturn.complete. Las llamadas siguen rechazándose hasta la siguiente entrada del usuario, y nada las pone en cola ni las repite por ti.
Cuando el resultado o el error de una llamada contiene una de estas cadenas, guarda sus argumentos para reintentarla más tarde:
the session was stopped and nobody has sent input since: la llamada se rechazówas removed from the queue before it ran: el prompt o el comando salió de la cola sin ejecutarse y se descartó, por ejemplo cuando el usuario detuvo el turno
submitPrompt desde tu trabajo en segundo plano en lugar de $.prompt.submit. Coloca la variable pendingText y la función submitPrompt encima de register, y el hook de turn.complete dentro de register, porque la validación rechaza $ pasado a una función declarada dentro de register. Cuando el resultado o el error contiene una de esas cadenas, submitPrompt guarda el texto en pendingText para que el hook de turn.complete lo envíe de nuevo:
turn.complete puede dispararse para el propio turno interrumpido y para el turno de un subagente, y las llamadas que se hagan en ese momento se rechazan de nuevo. En ese caso, submitPrompt guarda el texto para un turn.complete posterior.
Para una llamada que se rechaza con un error, como $.command.run, captura el error y comprueba su mensaje de la misma forma en que submitPrompt comprueba reason.
Qué devuelven las llamadas rechazadas
En los resultados,<reason> representa el motivo por el que se rechazó la llamada. Después de una interrupción, ese motivo es the session was stopped and nobody has sent input since. Para otros motivos, consulta Llamadas rechazadas en ejecuciones de claude -p y sesiones del Agent SDK.
Cuando una de estas llamadas a
$.session.send o $.tool.call se rechaza después de una interrupción en una sesión interactiva, el usuario puede ver la notificación emergente Stopped:.
Trabajo que tu mod inició antes de la interrupción
Después de que el usuario detiene un turno en ejecución, por ejemplo con Esc, parte del trabajo que tu mod ya había iniciado se descarta y parte espera a la siguiente entrada del usuario.
Cuando un trabajo programado vence o un monitor genera un evento antes de la siguiente entrada del usuario, el usuario puede ver la notificación emergente
Stopped:.
Llamadas rechazadas en ejecuciones de claude -p y sesiones del Agent SDK
En una ejecución de claude -p o en una sesión del Agent SDK, un resultado como { drop: 'the run reached its --max-turns limit' } significa que la ejecución rechazó la llamada de tu mod.
Un $.prompt.submit rechazado se resuelve con { drop: '<reason>' }. Otras llamadas rechazadas, como $.command.run y $.agent.spawn, dan los resultados que se muestran en Qué devuelven las llamadas rechazadas, con el motivo en lugar de <reason>. Busca tu <reason> a continuación para saber qué hacer:
the run reached its --max-turns limit: los turnos de los prompts de tu mod y de los subagentes que genera cuentan para--max-turnso para el límite de turnos del Agent SDK. Para tener más turnos, inicia la ejecución con un límite más alto. Si no puedes, haz que tu mod deje de hacer la llamada rechazada. Si la ejecución recibe otro prompt del usuario o de la aplicación del SDK, el recuento de turnos se reinicia y la ejecución vuelve a aceptar llamadas.the run is past its --max-budget-usd limit: inicia la ejecución con un--max-budget-usdmás alto, o aumenta el límite de gasto del Agent SDK. Si no puedes, haz que tu mod deje de hacer la llamada rechazada. El límite se aplica al costo total de la ejecución hasta el momento. Ese total sigue sumándose cuando la ejecución recibe otro prompt, así que un reintento devuelve el mismo motivo.the host has ended its input: por ejemplo, la aplicación del SDK terminó su entrada en streaming, o stdin se cerró en una ejecución iniciada con--input-format stream-json. La ejecución está terminando y no acepta más entrada, así que un reintento devuelve el mismo motivo. Haz que tu mod deje de hacer la llamada rechazada. Si inicias la ejecución tú mismo, la próxima vez mantén esa entrada abierta hasta que tu mod no tenga más llamadas que hacer.the session was stopped and nobody has sent input since: la ejecución se interrumpió, por ejemplo coninterrupt()del Agent SDK. Para volver a hacer la llamada después del siguiente mensaje del usuario o de la aplicación del SDK, sigue Reintentar una llamada rechazada o descartada.
Una ejecución de claude -p con tu mod nunca termina
Si tu mod envía un prompt al final de cada turno, cada prompt inicia otro turno. Sin --max-turns ni --max-budget-usd, una ejecución de claude -p que carga el mod continúa hasta que la detengas tú mismo.
Para que la ejecución termine por sí sola, agrega cualquiera de los dos flags al comando en tu shell. Si otras personas inician la ejecución, haz que tu mod deje de enviar prompts una vez que termine su trabajo. Este comando agrega --max-turns:
claude --version en tu shell y actualiza Claude Code si tu versión es anterior a v2.1.304. Los prompts del mod se rechazan al alcanzar el límite a partir de v2.1.299. Si tu mod genera subagentes, sus turnos cuentan para --max-turns a partir de v2.1.304.
Enviar y recibir mensajes entre sesiones
Un mod puede enviar un mensaje de texto sin formato a otra de tus sesiones, a uno de los subagentes de esta sesión o a un compañero de su equipo de agentes. También puede observar los mensajes que llegan y salen. Para enviar uno, llama a$.session.send({ to, text }), que realiza la misma entrega que la herramienta SendMessage. Define to según quién recibe el mensaje:
- Otra de tus sesiones:
{ sessionId } - Un subagente o compañero:
{ agentId }, con un id de$.agent.list() - El remitente de un mensaje que recibiste: la dirección en forma de cadena de la que provino ese mensaje
{ isDelivered: true }. Cuando no se entregó nada, se resuelve con { isDelivered: false, reason }, y reason indica el motivo.
Este hook responde a un comando /ping, registrado como comando, pidiéndole un estado a la sesión cuyo id escribes después:
Status? One line. Cuando no se entregó nada, una notificación emergente indica el motivo.
session.receive y session.send permiten que un mod observe los mensajes. Devuelve next(e) desde ambos para dejar pasar cada mensaje sin cambios:
Una sesión configurada para rechazar mensajes entrantes rechaza un mensaje antes de que se active
session.receive, por lo que un hook nunca lo ve. Un mensaje que queda retenido a la espera de tu aprobación llega primero al hook, así que un mod puede leer un mensaje que aún no has aprobado. El next(e) del hook se rechaza cuando el mensaje no se entrega.
El nombre del remitente en un mensaje recibido es lo que el remitente haya escrito, así que no bases ninguna decisión en él.
Accede a archivos, procesos y la red
Un mod accede al sistema de archivos, a los procesos y a la red a través de la API de mods, con los mismos permisos que el usuario que ejecuta Claude Code. El módulo de hooks en sí no tiene APIs de Node.js, ni globales de temporizador comosetTimeout, ni acceso propio a la red o a los archivos. Están disponibles las API estándar de JavaScript y de la web, como URL, TextEncoder, AbortController y crypto.subtle. Cada espacio de nombres a continuación cubre un tipo de acceso:
Los archivos, los procesos y las solicitudes tienen algunas reglas propias:
- Rutas: una ruta relativa se resuelve con respecto al directorio de trabajo de la sesión, o del subagente cuyo evento está gestionando el hook
$.fs.list: devuelve las entradas de un directorio como{ name, kind, size, isLink }y no es recursivo$.process.run: recibe una lista de argumentos y no usa ningún shell. Se resuelve en{ exitCode, stdout, stderr }sea cual sea el código de salida. Se rechaza si el programa no puede iniciarse o si sigue en ejecución al cumplirse el tiempo de espera, que es de 30 segundos de forma predeterminada, así que envuélvelo entryycatch.$.http.fetch: sigue hasta cinco redirecciones. En una redirección a un origen diferente, conserva solo los encabezados de solicitudaccept,accept-language,content-typeyuser-agentque hayas establecido y descarta el resto, por lo que una solicitud que dependa de otro encabezado, comoAuthorization, puede fallar después de esa redirección. Los límites indican su tiempo de espera y los tamaños del cuerpo.
$., como fs.read para $.fs.read. Un mod anterior en la cadena puede observar, reescribir o rechazar tu llamada, que es la forma en que una organización restringe aquello a lo que acceden los mods.
Un mod puede rechazar tu llamada a $.process.spawn después de que el comando haya producido salida o haya terminado, y nada de lo que hizo el comando se deshace. En ese caso, la llamada se rechaza con un mensaje que termina con una de estas cadenas y el motivo del mod que la rechazó:
$.process.spawn started, and a plugin withheld its result:: el mod que la rechazó no había leído la salida del comando hasta el final. Claude Code detiene el comando si sigue en ejecución.$.process.spawn ran, and a plugin withheld its result:: el mod que la rechazó había leído la salida del comando hasta el final, por lo que el comando ya había terminado
Lee toda la configuración, una fuente o una clave
$.settings.read() se resuelve en un objeto que contiene la configuración de todas las fuentes en uso, combinada según la precedencia. Pasa { source } para leer en cambio una sola fuente, { key } para leer una sola clave, o ambos:
Para
source, pasa el nombre de la única fuente de configuración que se va a leer:
user:~/.claude/settings.jsonproject:.claude/settings.jsonlocal:.claude/settings.local.jsonflag: lo que pasas con--settings, y la configuración en línea del SDKpolicy: configuración administrada
key, pasa el nombre exacto de una clave de nivel superior, no una ruta con puntos hacia un objeto anidado. El argumento key requiere Claude Code v2.1.304 o posterior.
Próximos pasos
- Reaccionar a eventos: intercepta llamadas a herramientas, prompts y turnos
- Dibujar en la interfaz: muestra lo que recopila tu mod en un panel o encima del prompt
- Probar un mod: simula cualquiera de estas llamadas en una prueba
- Referencia de mods: eventos, métodos de la API de mods y límites