on(eventName, handler).
Crea tu primer mod antes de empezar aquí. Para ver cada evento y sus campos exactos, consulta la referencia o lee los tipos para tu compilación.
Cómo un hook gestiona un evento
Un hook se sitúa entre un evento y lo que Claude Code haría al respecto, por lo que puede observar el evento, reescribirlo o responderlo por sí mismo. Recibe tres argumentos: la API de mods como$, el evento como e y el siguiente manejador como next. Los manejadores de un evento forman una cadena de middleware. next(e) llama al siguiente manejador, que es el hook de otro mod o, al final de la cadena, el comportamiento propio de Claude Code, y se resuelve con el resultado. Lo que tu hook haga con next decide cuál de las tres cosas hace.
Observar un evento
Para observar un evento sin cambiarlo, haz tu trabajo y devuelvenext(e). Este hook registra cada herramienta que Claude está a punto de usar:
● my-mod: Claude is about to use Bash, donde my-mod es el nombre de tu plugin. La herramienta se ejecuta como lo haría sin el mod.
Para actuar después del evento, usa await next(e), haz tu trabajo y devuelve el resultado. Este hook registra cada herramienta después de que se ha ejecutado:
next(e).
Reescribir un evento
Para cambiar aquello sobre lo que actúa Claude Code, como el texto de un prompt, llama anext con una copia modificada del evento. El evento en sí es inmutable: está congelado en profundidad, y asignar un valor a un campo lanza una excepción. Este hook recorta cada prompt antes de enviarlo:
await next(e) y luego devuelve una copia del resultado con un campo reemplazado.
Responder un evento
Para gestionar un evento tú mismo, devuelve un resultado sin llamar anext. Eso interrumpe la cadena, por lo que los mods posteriores y el comportamiento propio de Claude Code no se ejecutan. Este hook rechaza todos los comandos de Bash:
deny como el resultado de la herramienta. Cada evento tiene su propia forma de resultado, que se indica en la referencia de eventos.
Filtrar qué eventos gestiona un hook
Para ejecutar un hook solo para algunos eventos, pasa un filtro como segundo argumento deon. Claude Code llama al filtro un matcher. Es un objeto cuyos campos se comparan con los del evento, y el hook se ejecuta solo cuando todos los campos coinciden. Un campo puede ser un valor, un array de valores permitidos o una expresión regular.
Cada línea de este ejemplo registra la misma función, hook, para un conjunto más reducido de llamadas a herramientas:
hook se ejecuta una vez para una llamada a Bash, Edit o Write, y una vez para una llamada a una herramienta cuyo nombre empieza por mcp__github__. Una llamada a cualquier otra herramienta, como Read, no coincide con ninguna de las tres, por lo que hook no se ejecuta para ella.
El nombre del evento puede ser un comodín. 'classic.*' coincide con todos los eventos de hooks de configuración. '*' coincide con todos los eventos excepto los eventos de telemetría, que requieren su propio nombre y un filtro { to: 'collector' }.
Registra cada evento una sola vez por matcher. Si llamas a on dos veces para session.start sin matcher, el módulo no se carga y muestra on("session.start") is registered twice without a matcher. Pon todo lo que tu mod hace al inicio de la sesión en un solo hook.
Enganchar los dibujos y controles de otros mods
Para enganchar los controles, paneles o la fila sobre el prompt de otro mod, pasa un matcher conplugin. Usa el nombre del mod sin su marketplace, como en { plugin: 'other-mod' }, o { plugin: '*' } para todos los mods. Sin plugin, un hook en ui.press, ui.input, ui.select o ui.focus no se ejecuta para los controles de otros mods, y un hook de ui.render omite sus paneles y sus filas sobre el prompt.
Un hook en un comodín sin matcher, como on('*', hook) o on('ui.*', hook), sigue ejecutándose para todos los mods. Un comodín con matcher también necesita plugin.
{ plugin: '*' } requiere Claude Code v2.1.323 o posterior. Antes de v2.1.323, un hook sin plugin se ejecutaba para todos los mods, y un hook con { plugin: '*' } no se ejecutaba. Para coincidir con todos los mods en ambas versiones, usa { plugin: /./ } en ui.press, ui.input y ui.select. Para ui.focus y ui.render, usa on('ui.*', hook) y comprueba el nombre del evento en next.event, como en if (next.event !== 'ui.focus') return next(e).Engancha lo que Claude está haciendo
Maneja estos eventos para ver o cambiar una llamada a herramienta, un prompt, un turno o una lectura de la configuración mientras ocurre. Para ver cada evento y lo que un hook puede devolver, consulta la referencia de eventos.Proteger o cambiar una llamada a herramienta
Un hooktool.call ve cada herramienta que Claude está a punto de usar, así que puede rechazar la llamada, cambiar sus argumentos o dejarla pasar. tool.call se dispara cuando Claude Code está a punto de ejecutar una herramienta, incluidas las llamadas que hace un subagente y las llamadas a herramientas MCP. e.tool es el nombre de la herramienta y los argumentos de la herramienta son campos de e, como e.command para Bash. Cuando llamas a next(e), Claude Code ejecuta la verificación de permisos y luego la herramienta.
Este hook rechaza un comando de Bash que hace un force push y le dice a Claude por qué:
git push --force, el comando no se ejecuta y no aparece ninguna solicitud de permiso, porque el hook nunca llama a next. Claude lee el texto de deny como el resultado de la herramienta, así que escríbelo como una instrucción sobre la que Claude pueda actuar. Cualquier otro comando de Bash se ejecuta como lo haría sin el mod.
Si este hook lanza una excepción o agota el tiempo, Claude Code lo omite y el comando continúa como lo haría sin el mod. Para rechazar el comando en su lugar, agrega un manejador .catch al hook.
Para actuar después de que una herramienta se haya ejecutado, usa await next(e), haz tu trabajo y devuelve lo que next te dio. Este hook registra cada archivo .mdx que Claude cambia, con $.ui.log, que agrega a la transcripción una línea atenuada que Claude no lee:
.mdx, una línea atenuada en la transcripción nombra el archivo. No se registra nada para otro tipo de archivo, ni para una llamada que fue rechazada o falló. La vista que Claude tiene de la llamada no cambia, porque el hook devuelve el resultado que recibió.
Tu hook también puede cambiar una llamada, reintentarla, responderla por sí mismo o retener su resultado:
- Cambiar la llamada: pasa argumentos modificados a
next. - Reintentar la llamada: vuelve a llamar a
next(e). Un hook que veisErroren el primer resultado puede ejecutar la herramienta una segunda vez y devolver ese resultado. - Responder tú mismo a la llamada: devuelve un objeto con un campo
result, sin llamar anext, y, para una herramienta integrada, dale aresultla forma que tiene el resultado propio de esa herramienta en los tipos de tu compilación. No aparece ninguna solicitud de permiso y la herramienta no se ejecuta, así que el resultado que devuelves es todo lo que Claude sabe sobre lo que pasó. - Ocultarle el resultado a Claude: devuelve
{ deny: reason }después deawait next(e). Claude lee tu motivo en lugar de lo que devolviónext. Cuando la herramienta se ejecutó, el deny le oculta su resultado a Claude y no deshace nada de lo que hizo la herramienta. Cuando la herramienta se ejecutó correctamente, el motivo va después de una nota comoBash ran, and a plugin withheld its result:.
tool.call de cualquier mod. Cuando un hook administrado bloquea la llamada, no se ejecuta el hook tool.call de ningún mod para esa llamada.
Retener una llamada a herramienta hasta que el usuario decida
Un hook puede pausar una llamada a herramienta y preguntarle al usuario qué hacer antes de que continúe. Un hooktool.call puede usar await antes de llamar a next o de devolver un valor, y la llamada a herramienta queda pendiente hasta entonces. Para plantearle la pregunta al usuario, llama a $.ui.ask. Muestra tu pregunta sobre una lista numerada de tus opciones, en el diálogo que Claude usa para preguntarte algo, y se resuelve con la etiqueta que elige el usuario. Después de tus opciones, el diálogo agrega una fila para escribir una respuesta diferente y una fila Chat about this.
El patrón RISKY de este ejemplo coincide con rm -r, rm -rf, git reset --hard y git push con --force, y no detecta otras formas de escribirlos, como git push -f. Este módulo pregunta antes de ejecutar un comando de Bash que coincide con el patrón:
rm -rf build, aparece la pregunta con el comando incluido, y el comando espera la respuesta:
- El usuario elige Run it: el hook llama a
next(e), y la verificación de permisos habitual se sigue ejecutando después - El usuario elige Refuse: el comando no se ejecuta, y Claude lee el texto de
deny - El usuario escribe una respuesta:
$.ui.askse resuelve con el texto escrito. El hook lo compara conRun it, así que cualquier otro texto rechaza el comando. - Nadie responde:
$.ui.askse rechaza cuando el usuario descarta la pregunta o elige Chat about this, y en una ejecución declaude -p, así que el bloquecatchdeja la respuesta enRefuse
$.ui.ask, porque ese tiempo no cuenta para el límite de tiempo del hook. El tiempo dedicado a esperar una promesa propia sí cuenta.
Claude Code omite un hook que agota el tiempo, así que el comando retenido se ejecutaría. Para rechazarlo en su lugar, encadena un manejador .catch al registro que devuelve on. Ese manejador es independiente del bloque catch dentro del hook.
Aprobar o rechazar una llamada a herramienta antes de preguntarle al usuario
Para decidir si una llamada a herramienta puede ejecutarse, manejatool.check, el evento en el que Claude Code toma esa decisión.
Para un comando o una ruta fijos, usa una regla de permisos como Bash(npm test), que no requiere código. Maneja tool.check cuando la decisión depende de lo que es cierto en ese momento, como la rama de Git actual o un valor que otro hook registró.
- Qué devolver: para decidir tú mismo la llamada, devuelve un objeto propio, como
{ decision: 'allow' }o{ decision: 'deny', reason }. Para no modificar la decisión, devuelve lo que te daawait next(e). - Lo que te da
await next(e): la propia decisión de Claude Code, como un objeto cuyodecisionesallow,askodeny. No aparece ninguna solicitud de permiso mientras se ejecutanext(e). - Argumentos:
e.inputcontiene los argumentos de la herramienta, comocommandpara Bash - Cuándo se dispara
tool.check: después de que se ejecutan los hooksPreToolUse, y antes de la solicitud de permiso, del clasificador del modo automático o de un hookPermissionRequest
git push mientras la rama actual sea main:
git push en main y deja pasar todas las demás llamadas:
- En
main: el hook devuelvedeny, incluso cuando una regla permitegit push - En otra rama, y para otros comandos: la llamada obtiene la decisión que obtendría sin el mod
- El hook lanza una excepción o agota el tiempo: la llamada también obtiene la decisión que obtendría sin el mod. Para rechazar la llamada en su lugar, agrega un manejador
.catchque devuelva{ decision: 'deny', reason: 'the reason' }.
main para todos, protege la rama en tu host de Git.
Un hook
tool.check también puede devolver allow o ask. En modo plan, para una llamada que no es de solo lectura, como la edición de un archivo, tu hook puede endurecer la decisión que devuelve next(e), pero no puede flexibilizarla. Para conocer las reglas de permisos y las decisiones de hooks PreToolUse que el allow de tu hook no puede reemplazar, consulta Extender permisos con hooks.Comprobar si una llamada a herramienta es de solo lectura
En un hooktool.check, e.isReadOnly es true cuando la herramienta informa que la llamada es de solo lectura. En caso contrario, el campo no está presente, en lugar de ser false. e.isReadOnly requiere Claude Code v2.1.304 o posterior.
Algunas herramientas, como Read, Grep, Glob y WebSearch, informan que todas sus llamadas son de solo lectura. Bash y las herramientas MCP informan que una llamada es de solo lectura en estos casos:
- Bash: el comando supera la verificación de comandos de solo lectura integrada de Claude Code
- Una herramienta MCP: el servidor establece la anotación
readOnlyHintde la herramienta entrue
ask para cada llamada mcp__github__ que no es de solo lectura y que no se denegó previamente:
Filtrar un hook tool.check según si la llamada es de solo lectura
Para limitar qué llamadas maneja tu hook según e.isReadOnly, usa el matcher para las llamadas de solo lectura y el cuerpo del hook para el resto:
- Solo llamadas de solo lectura: agrega
isReadOnly: trueal matcher, como enon('tool.check', { tool: 'Bash', isReadOnly: true }, hook) - Llamadas que no son de solo lectura: comprueba
e.isReadOnlyen el cuerpo del hook, como hace el ejemplo demcp__github__. Si ponesisReadOnly: falseen un matcher, tu hook nunca se ejecuta.
Reescribir o agregar contenido a un prompt
Un hookprompt.submit ve cada prompt antes de que comience el turno, así que puede reescribir el texto o agregarle contenido. e.text es lo que se escribió.
Este hook agrega el nombre de la rama actual para Claude siempre que un prompt menciona un pull request:
open a PR for this change, tu mensaje se ve igual en la transcripción, y Claude también lee una línea como Current branch: feature/auth después de él. Un prompt que no menciona un pull request pasa sin cambios, y git no se ejecuta.
Para detener un prompt, devuelve { drop: 'the reason' } sin llamar a next. El texto vuelve al campo de entrada de prompts del usuario, y este ve Prompt dropped by a hook: seguido de tu motivo, así que dirígele el motivo a él. El prompt se envía de todos modos en estos casos:
- Tu hook devuelve un
dropdespués de que su llamada anext(e)dejó pasar el prompt: el turno se ejecuta de todos modos, y el hook falla con un mensaje que incluyea drop after its next() was answered - Tu hook lanza una excepción o agota el tiempo: Claude Code lo omite y envía el prompt. Agrega un manejador
.catchpara que un fallo no envíe un prompt que el hook habría detenido.
prompt.section para cada sección del prompt del sistema, prompt.context para el contexto enviado con el primer mensaje y skill.prompt para el texto de un skill. Para cambiar una sección después de que una conversación ha comenzado, consulta Enviar una sección del prompt del sistema o una descripción de herramienta modificadas. En un hook skill.prompt, también puedes leer de qué plugin o archivo proviene el skill.
Seguir un turno
Un turno es todo lo que Claude hace en respuesta a un prompt. Manejaturn.start, turn.step y turn.complete para seguir uno:
Escribe un hook
turn.step como un generador asíncrono, porque el evento se transmite por streaming. yield* next(e) reenvía la respuesta a medida que se transmite y se evalúa como el resultado terminado. Este hook registra cuánto de cada solicitud sirvió la API de Claude desde la caché de prompts:
result.usage contiene los recuentos de tokens que la API de Claude informa para una solicitud, además del model que respondió: input_tokens, output_tokens, cache_read_input_tokens y cache_creation_input_tokens. El hook también se ejecuta para las solicitudes de los subagentes, así que comprueba e.agentId cuando solo quieras la conversación principal.
Para ver las llamadas a herramientas que la propia API ejecutó durante la solicitud, como las llamadas a la herramienta advisor, lee result.serverToolUses. Claude Code no ejecuta estas llamadas, así que ningún hook tool.call o tool.check se dispara para ellas. El campo no está presente cuando la respuesta no tiene ese tipo de llamadas, y requiere Claude Code v2.1.290 o posterior.
Enviar una solicitud a un modelo diferente
Si una solicitud deturn.step falla con un error de modelo cuando model es un alias como haiku, actualiza a Claude Code v2.1.309 o posterior, o usa un id de modelo completo. Antes de v2.1.309, un alias se enviaba tal como estaba escrito.
Para enviar una solicitud a un modelo diferente, pásale a next el evento con model cambiado, como en yield* next({ ...e, model: 'haiku' }).
Cambiar o rechazar una lectura de la configuración
Usa un hooksettings.read para cambiar o rechazar una lectura de la configuración, ya sea la de un mod o la propia de Claude Code:
- La lectura de un mod: un mod llama a
$.settings.read. - La propia lectura de Claude Code: tu hook se ejecuta por primera vez cuando Claude Code combina la configuración de la sesión, después de que se cargan los mods de la sesión. Tu hook se vuelve a ejecutar cuando cambian la configuración o los plugins cargados.
- La protección integrada: donde se carga la protección integrada, esta puede omitir este hook en un mod que instalas o cargas con
--plugin-dir. Para comprobarlo, buscasettings.read bypassed by cc-plugin-sec-defaulten el registro de depuración. Si una línea con ese texto nombra tu mod, pídele al administrador de tu organización que instale el mod como uno de los mods de la organización. - La versión: que el evento se dispare en la propia lectura de Claude Code, y el campo
e.layers, requieren Claude Code v2.1.304 o posterior.
Qué recibe un hook settings.read
En
e.layers, plugin contiene la configuración que aportan los plugins habilitados, y es solo un nombre de capa, no un source que puedas pasar a $.settings.read. flag contiene la configuración pasada con --settings, y policy contiene la configuración administrada.
Distinguir la propia lectura de Claude Code de la lectura de un mod
Compruebanext.origin:
- La propia lectura de Claude Code:
{ plugin: 'engine', tier: 'core' } - La lectura de un mod:
plugines el nombre del mod que llama
Qué puede devolver un hook settings.read
Devuelve el resultado de next(e) sin cambios para dejar la lectura como está, o devuelve uno de estos:
En la propia lectura de Claude Code, arma tu
{ value } a partir del value de next(e), ya que una clave que omites queda sin definir. Cuando Claude Code lee una clave como env de cada fuente por separado, cambiarla en tu value no tiene efecto.
Qué le da next(e) a un hook settings.read
next(e) se resuelve con { value } o con { deny }:
{ value }:valuees la configuración combinada, o la configuración de una sola fuente cuandoe.sourceestá definido. Si un hook que se ejecuta después del tuyo devolvió un{ value }propio, obtienes elvaluede ese hook en su lugar.{ deny }: un hook que se ejecuta después del tuyo rechazó la lectura. Devuelve ese{ deny }sin cambios.
Cambiar un ajuste desde un hook settings.read
Primero comprueba qué mods reciben este evento y a partir de qué versión.
Para cambiar una clave, expande el value de next(e) y establece esa clave, como hace este hook con spinnerTipsEnabled. El hook no comprueba next.origin, así que cambia la clave tanto en la propia lectura de Claude Code como en la lectura combinada de un mod:
the answer for <key> is no value the key can hold. Si tu valor se ajusta y la clave sigue sin cambiar, consulta por qué una clave no tiene efecto.
Manejar los eventos de los hooks de configuración
Los hooks de configuración son los hooks de comando, HTTP, prompt y agente que configuras en los archivos de configuración. Cada evento de hook de configuración, comoStop, SessionEnd o PostToolUse, también es un evento llamado classic. seguido del nombre del evento del hook de configuración, como classic.Stop. e es el JSON que un hook de configuración recibe por stdin, incluido transcript_path. Donde se carga la protección integrada, un hook en estos eventos en un mod que instalas no se ejecuta.
Este hook usa Stop, que se dispara cuando Claude termina de responder, para registrar dónde se guarda la transcripción de la sesión:
next(e), así que observa el evento y no cambia nada de cómo termina el turno.
Ejecutar junto con otros mods
Varios mods pueden manejar el mismo evento, y cualquiera de ellos puede fallar. Si tu mod bloquea llamadas a herramientas, revisa su posición en la cadena y qué sucede cuando su hook falla.El orden en que se ejecutan los mods
Los hooks de un mismo evento forman una única cadena de middleware. Elnext de cada mod llama al hook del mod siguiente, y el último next llega al comportamiento propio de Claude Code. El primer mod es el más externo: ve el evento antes que los demás y el resultado después de ellos, y decide si los demás se ejecutan o no. Un mod posterior no puede impedir que uno anterior vea un evento.
Claude Code ordena la cadena según el origen de cada mod:
- La protección integrada
sec-default@builtin, un mod integrado en Claude Code que/pluginmuestra comocc-plugin-sec-default, donde se carga, los mods que tu organización incluye enprependPluginsy, luego, cualquier otro mod que se considere de tu organización y que no esté enappendPlugins - Los mods que instalas
- Los mods que tu organización incluye en
appendPlugins - Otros mods integrados en Claude Code
dependencies en su manifiesto. Dentro de un mismo módulo, los hooks se ejecutan en el orden en que register llamó a on.
Dónde se ubican los hooks de configuración en el orden
Los hooksPreToolUse configurados en archivos de configuración también se ejecutan durante una llamada a herramienta, en puntos fijos de la cadena de mods:
- Hooks
PreToolUsede la configuración administrada: se ejecutan antes del hooktool.calldel primer mod. Cuando un hook administrado bloquea la llamada, no se ejecuta el hooktool.callde ningún mod para esa llamada. - Hooks
PreToolUsede cualquier otro archivo de configuración y delhooks/hooks.jsonde los plugins: se ejecutan después de que el último mod llama anext, como parte del comportamiento propio de Claude Code. Un mod que responde atool.callsin llamar anextimpide que se ejecuten, y un mod que llama anextve su decisión en el resultado que devuelve.
tool.check se activa después de que se hayan ejecutado los hooks PreToolUse. Para conocer las reglas de permisos y las decisiones de hooks PreToolUse que el allow de un hook tool.check no puede reemplazar, consulta Ampliar los permisos con hooks.
Manejar un hook que falla
Un hook que falla no interrumpe la sesión, y puedes decidir qué sucede en su lugar. Cuando un hook sin un controlador.catch lanza una excepción, agota el tiempo de espera o devuelve un resultado con una forma incorrecta, lo que sucede a continuación depende de si había llamado a next:
- Falló antes de llamar a
next: Claude Code lo omite, y el siguiente controlador se ejecuta en su lugar - Falló después de que
nextse resolvió: ese resultado se mantiene, y nada se ejecuta por segunda vez
my-mod: tool.call hook skipped: threw Error: boom. Dónde la lees depende de la sesión, como se indica en Averiguar por qué un mod no hace nada. Un hook ui.render cuyo árbol no se valida cuenta como uno que devolvió un resultado con una forma incorrecta.
Para que un hook que bloquea llamadas falle de forma cerrada, agrega un controlador de errores .catch que responda en su lugar. Aquí, guard es tu función de hook, y el controlador comprueba next.called para saber si guard ya había llamado a next cuando falló:
guard lanza una excepción o agota el tiempo de espera en una llamada a Bash, Claude Code llama al controlador con el mismo evento:
guardfalló antes de llamar anext: el comando no se ejecuta, y Claude lee el texto dedenycon el tipo al finalguardfalló después de llamar anext: elnext(e)del controlador se resuelve en el resultado que produjo la llamada deguardsin volver a ejecutar el comando, y Claude lee ese resultado
guard no había llamado a next, el comando continúa entonces como lo haría sin el mod.
La misma forma de controlador sirve para una protección en prompt.submit o config.set. Cuando next.called es false, devuelve el rechazo que la referencia de eventos indica para ese evento: { drop: 'the reason' } para prompt.submit, { deny: 'the reason' } para config.set.
En tool.check y plugin.register, un rechazo devuelto después de que next se resolvió sigue siendo válido, así que devuélvelo sin comprobar next.called:
tool.check: devuelve{ decision: 'deny', reason: 'the reason' }plugin.register: devuelve{ refuse: 'the reason' }, como se muestra en Rechazar mods cuando tu comprobación falla
tool.call, un deny devuelto después de que next se resolvió oculta el resultado a Claude.
Próximos pasos
- Usa la API de mods: agrega comandos y herramientas, llama a un modelo y ejecuta trabajo con un temporizador
- Dibuja en la interfaz: muestra lo que recopilan tus hooks en un panel o encima del prompt
- Prueba un mod: dispara cualquiera de estos eventos desde una prueba
- Referencia de mods: cada evento, cada método de la API de mods y los límites