Solucionar problemas de un mod

Descubre por qué un mod de Claude Code no hace nada: relaciona el síntoma o mensaje con su causa, consulta los mensajes de rechazo y lee el registro de depuración.

Cuando el módulo de un mod o uno de sus hooks falla, Claude Code lo omite y la sesión continúa, por lo que un mod defectuoso puede parecer uno que no hace nada. Empieza por comprobar qué leyó Claude Code de tu mod y dónde informa de un problema; luego busca el síntoma o mensaje que tienes.

Averigua por qué un mod no hace nada

Cuando un mod no hace nada, revisa lo que Claude Code lee de los archivos del mod y la línea que escribe cuando omite algo. Para lo primero, en tu shell ejecuta claude plugin validate con el directorio del mod, como en claude plugin validate ./first-mod. Detecta un evento mal escrito, un manifiesto incorrecto y un módulo que Claude Code no puede leer, sin iniciar una sesión.

Cuando un módulo no se carga, se omite un hook u otro mod rechaza el tuyo, Claude Code escribe una línea que nombra tu mod. Dónde lees esa línea depende de la sesión:

• Una sesión que recarga en caliente un directorio de plugin: una línea atenuada en la transcripción. Es una sesión interactiva que iniciaste con --plugin-dir, o una en la que la recarga en caliente está activada para los mods que escribió Claude.
• Cualquier otra sesión interactiva, como una que ejecuta un mod que instalaste desde un marketplace: solo el registro de depuración. Para obtenerlo, inicia la sesión con claude --debug.
• Una ejecución de claude -p con --plugin-dir: stderr, en el formato de salida de texto predeterminado. Un rechazo por parte de otro mod va solo al registro de depuración.

Comprobar si los mods pueden cargarse

Para comprobar si tu configuración permite que los mods se carguen, sin instalar ninguno, ejecuta claude plugin test en tu shell, desde un directorio que no contenga un mod. No necesitas una sesión. El mensaje que imprime te indica el estado:

Una organización también puede establecer allowManagedModsOnly para permitir solo sus propios mods, algo que este comando no informa. En ese caso, Claude Code rechaza un mod que instales, y un mensaje indica el motivo.

El mod no se carga

No aparece nada de lo que agrega el mod: ningún comando, ningún dibujo y ningún cambio de comportamiento.

Tu versión es demasiado antigua

Consulta qué versión usar y cómo comprobar la tuya.

La línea mods active no nombra el mod

No aparece nada de lo que agrega el mod, y la línea mods active en /plugin no lo nombra. El módulo de hooks no se cargó. Cuando Claude Code lo rechazó, el registro de depuración tiene una línea que empieza con hooks module, el nombre del mod y not loaded:, como en hooks module first-mod@inline not loaded: disableAllHooks in managed settings para un mod cargado con --plugin-dir.

Lee el motivo que aparece después de los dos puntos. La sección mensajes de rechazo enumera cada uno. Si el registro no tiene una línea así, revisa las demás entradas de este grupo.

Algunos ajustes detienen un mod y dejan funcionando el resto de su plugin. Activar o desactivar mods los nombra.

Una ejecución de claude -p muestra hooks module not loaded

La línea empieza con el nombre del mod y va a stderr. El módulo de hooks fue rechazado. Una ejecución no interactiva no tiene transcripción, así que el mensaje va a stderr.

Lee el motivo que aparece después de los dos puntos. La sección mensajes de rechazo enumera cada uno.

Mensajes de rechazo

Cada uno de estos aparece después de hooks module, el nombre del mod y not loaded: en el registro de depuración.

Mensajes de la protección integrada

Donde se carga la protección integrada, puede rechazar un mod o una de sus respuestas. Cada mensaje nombra la opción que el administrador de tu organización establece para cambiar la regla.

validate pasa y no muestra ninguna línea hooks

hooks/hooks.json no tiene una clave modules, o la clave está mal escrita.

Agrega "modules": ["./register.js"].

hooks module did not load

La línea empieza con el nombre del mod, luego hooks module did not load: y un motivo, que indica el archivo y la línea cuando el problema está en tu código. Claude Code no pudo cargar el módulo, por ejemplo porque su código de nivel superior lanzó una excepción.

Corrige el error que indica el motivo.

Si el motivo termina con ; the version loaded before is unloaded, ninguna versión del mod se está ejecutando ahora. Una vez que corrijas el error, ejecuta /reload-plugins en la sesión para volver a cargar el mod. Si instalaste el mod y no lo escribiste tú, pídele a su autor que corrija el error.

options do not fit plugin.json userConfig

La línea empieza con el nombre del mod, luego hooks module did not load: options do not fit plugin.json userConfig: y un motivo. Una opción no pasa la validación contra su campo userConfig, como un número por encima del max del campo, o un campo obligatorio no tiene valor.

Establece o cambia el valor. El final de la línea nombra su entrada pluginConfigs en settings.json.

code nested too deep to scan: more than 2000 scopes

La línea empieza con el nombre del mod, luego hooks module did not load:, el archivo y code nested too deep to scan: more than 2000 scopes. Un archivo de un módulo de hooks no puede anidar alcances, como funciones, bloques y bucles, a más de 2000 niveles de profundidad. claude plugin validate informa el mismo motivo.

Reescribe el código para que sus alcances se aniden con menos profundidad.

the engine ran out of stack linking the file and its imports

El código del módulo de hooks está anidado con demasiada profundidad, o su cadena de importaciones es demasiado larga, para que Claude Code pueda cargarlo. La línea empieza con el nombre del mod y hooks module did not load:, y luego indica el nombre de un archivo y este motivo.

Revisa ese archivo y los archivos a los que se llega a través de sus importaciones para encontrar la parte más profundamente anidada y reescríbela para que se anide menos, o acorta la cadena de importaciones. Si no escribiste el mod, pídele a su autor que lo corrija.

the parser stopped o the engine ran out of stack loading the file

El código de un archivo del módulo de hooks está anidado con tanta profundidad que Claude Code se quedó sin pila al leerlo. La línea empieza con el nombre del mod y hooks module did not load:, y luego indica el nombre de ese archivo y uno de estos motivos:

• code nested too deep to scan (the parser stopped: <message>)
• the engine ran out of stack loading the file (code nested too deep): <message>

El motivo no indica ningún número de línea ni dice qué tipo de código está anidado, así que revisa tú mismo el archivo para encontrar su parte más profundamente anidada. Reescribe esa parte para que se anide menos. Si instalaste el mod y no lo escribiste tú, pídele a su autor que lo haga.

Ningún mod se carga en un directorio que abriste por primera vez

No respondiste la solicitud de confianza del directorio.

Inicia una sesión interactiva en ese directorio con claude y acepta la solicitud de confianza con la que se abre.

No se carga ningún plugin instalado

Iniciaste Claude Code con --safe-mode.

Inicia sin el flag.

Claude Code deja de preguntar si quieres habilitar la recarga en caliente

Claude escribe un mod en una sesión interactiva, no se carga nada y Claude Code no vuelve a preguntar si quieres habilitar la recarga en caliente. Si la pregunta termina tres veces sin que se elija una respuesta, la recarga en caliente permanece desactivada. Por ejemplo, la pregunta termina así cuando estableces askUserQuestionTimeout y el tiempo se agota antes de que respondas. Ese ajuste se aplica aquí porque Claude Code pregunta en el mismo cuadro de diálogo de preguntas que usa AskUserQuestion. Una pregunta que descartas tú mismo no cuenta para las tres.

Para ejecutar el mod, copia su directorio fuera de la carpeta de mods y luego, en tu shell, inicia una nueva sesión con --plugin-dir, como en claude --plugin-dir ~/mods/git-branch.

Un hook se omite o un mod se descarga

El mod se cargó y luego Claude Code omitió uno de sus hooks o lo descargó.

hook skipped

La línea nombra el mod y el evento, luego dice hook skipped: y un motivo, como en first-mod: tool.call hook skipped: threw Error: boom. Un hook lanzó una excepción, superó su límite de tiempo o devolvió un resultado con una forma incorrecta. La línea aparece una vez por cada evento y tipo de fallo hasta que el mod se recarga.

Corrige el error. El registro de depuración tiene una línea por cada ocurrencia.

no command.run hook answered it

Ejecutas un comando que agregó tu mod y la respuesta nombra el mod y el comando, como en first-mod registered /tally but no command.run hook answered it, y luego te indica que agregues un hook. Claude Code imprime esa respuesta cuando el comando llega al final de la cadena sin respuesta, lo cual ocurre en dos casos:

• Ningún hook respondió al comando: el módulo no tiene un hook command.run, el filtro del hook nombra un comando diferente, o el hook devolvió next(e)
• Claude Code omitió el hook: hook skipped enumera los motivos. Pasar focus: false a $.ui.open es una forma de llegar a esto.

Si el módulo ya tiene el hook que describe la respuesta, busca una línea hook skipped que nombre command.run, la cual indica el motivo. Una prueba que ejecuta el comando falla con el mismo motivo.

it crashed the hooks worker

La línea comienza con el nombre del mod, como en first-mod was unloaded: it crashed the hooks worker. Los mods instalados comparten un único hilo worker. El worker dejó de responder o falló, y Claude Code lo atribuyó a este mod y lo descargó. Un hook que bloquea el hilo, como un bucle que nunca usa await, es una de las causas.

Corrige el hook.

its session.start ran again in a fresh copy

La línea comienza con el nombre del mod y nombra una llamada a $.prompt.submit, $.command.run o $.agent.spawn, como en first-mod: its session.start ran again in a fresh copy; the $.prompt.submit call it had already made was not made again. Claude Code volvió a cargar el módulo del mod, por ejemplo después de que el hooks worker falló y fue reemplazado, y se ejecutó el hook session.start de la copia nueva. La llamada que nombra la línea se resolvió con el resultado de su primera ejecución en lugar de ejecutarse de nuevo, así que tu mod no envía el prompt, no ejecuta el comando ni inicia el subagente dos veces. El resto del hook se ejecutó como de costumbre.

No hay nada que corregir.

Antes de la v2.1.292, la llamada se ejecutaba una segunda vez, por lo que el prompt se enviaba, el comando se ejecutaba o el subagente se iniciaba dos veces.

This mod's change didn't load o the earlier version is no longer running

Un cambio en un mod que Claude escribió en esta sesión no pudo cargarse. La línea de la transcripción comienza con el nombre del mod y termina con el motivo:

• This mod's change didn't load, so the earlier version is still running: <reason>.
• This mod didn't load, and the earlier version is no longer running: <reason>.

Claude no ve esta línea, así que pégala en tu siguiente mensaje cuando le pidas a Claude una corrección.

$.agent.register refused: the hooks module that made the call is no longer loaded

La línea comienza con el nombre de tu mod, como en first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), y el agente no queda registrado. Tu mod se recargó o se descargó antes de la llamada. Una recarga carga una copia nueva del módulo de hooks, y esta llamada provino de código que aún se ejecutaba en la copia anterior, como un hook que aún no había retornado.

Si ese hook no captura el rechazo, falla y Claude Code lo omite. Para registrar el agente desde la copia que permanece cargada, haz la llamada en tu hook session.start, que se ejecuta de nuevo en cada copia nueva después de una recarga.

mods that run in the hooks worker are off for this session

La línea dice hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. El worker se detuvo tres veces y Claude Code no pudo atribuir las detenciones a un solo mod, así que descargó todos los mods que no son integrados, incluidos los mods que instala tu organización. Esta línea llega a la transcripción en cada sesión interactiva.

Ejecuta /reload-plugins para cargarlos de nuevo.

Se deniega una llamada a herramienta

El mod se cargó y sus hooks se ejecutan, y una llamada a herramienta que tocó es rechazada.

a hook changed this call's input after the model wrote it

En modo automático, una llamada a herramienta denegada da este motivo. Un hook cambió la entrada de la llamada a herramienta después de que el clasificador del lado del servidor la revisara, por lo que esa revisión no cubre lo que se ejecutaría. El hook puede ser un hook tool.call o turn.step de un mod, o un hook de configuración PreToolUse. El mensaje no dice cuál.

El mensaje le indica a Claude que emita la llamada una vez más tal como quedó registrada. Si también se deniega, el hook cambia la entrada cada vez, así que desactiva el mod o el hook, o sal del modo automático y aprueba la llamada tú mismo.

[!NOTE]

En algunas sesiones interactivas de terminal y sesiones de VS Code, la misma denegación da el motivo a hook changed this call's input after auto mode reviewed it. Allí, la llamada repetida lleva el primer cambio del mod, y un hook tool.call todavía se ejecuta sobre ella, pero cualquier cambio adicional se descarta. No necesitas cambiar tu mod, a menos que Claude te diga en su respuesta que el modo automático no pudo revisar la llamada.

Un mensaje sobre las reglas de denegación en tu configuración

tried to lift a deny rule in your settings y the deny rules in your settings could not be checked for this call, so it is refused provienen ambos de la protección integrada.

Búscalos en Mensajes de la protección integrada.

Aparece un aviso después de detener un turno

Stopped: type a message to continue; a mod cannot resume work after Stop

Este aviso significa que, después de que detuviste el turno, por ejemplo con Esc, un mod intentó iniciar trabajo por su cuenta y Claude Code no se lo permitió. No hay nada que corregir. Después de tu siguiente mensaje, los mods pueden volver a iniciar trabajo y parte de ese trabajo se reanuda por sí solo. Si lo que esperabas del mod no se reanuda, vuelve a pedirlo o ejecuta de nuevo el comando del mod.

Si tú escribiste el mod, consulta Llamadas y trabajo en segundo plano después de que el usuario interrumpe un turno.

Un dibujo no aparece o no responde

El mod se cargó, y su panel, banda, toast o controles no se comportan como esperas.

Se muestra la banda de otro mod y no la tuya

Hay una sola banda encima del prompt, y todos los mods la comparten. Un mod que se ejecuta antes que el tuyo reemplaza tu banda cuando devuelve un árbol que no incluye el resultado de next(e). Para mostrar ambas bandas, cambia el hook de ese mod, o pídele a su autor que lo haga:

• Conservar las bandas posteriores: coloca el resultado de await next(e) entre los hijos de un Box en su árbol, como en la pestaña Banda encima del prompt de Elegir dónde dibujar
• Mantener el árbol válido: no le des a ese Box, ni a ningún Box que lo rodee, una prop width, height, minWidth, minHeight, position, top, left, right, bottom, display u overflow

Para encontrar ese mod, escribe un registro de depuración y busca en él answered ui.render without next(). Una línea como other-mod (user) answered ui.render without next() nombra un mod que devolvió su árbol sin llamar a next(e). No nombra el punto de renderizado, así que también puede aparecer un mod que solo dibuja un panel. Un mod que llama a next(e) y descarta el resultado no genera ninguna línea, así que revisa también los hooks que se ejecutan antes del tuyo.

La banda de un mod también falta cuando el árbol que devolvió su propio hook no pasa la validación, y las bandas de los demás mods se mantienen. Para saber qué mod y por qué, escribe un registro de depuración y busca en él ui.render hook skipped.

Un panel o una banda está vacío o muestra el contenido habitual de Claude Code

El árbol que devolvió tu hook no pasó la validación. Una línea hook skipped en la transcripción o en el registro de depuración nombra tu mod y el motivo, como en esta para un Box en un panel:

first-mod: ui.render hook skipped: returned the wrong shape (a tree Pane refuses: Box prop "flexDirection" must be one of row, column, row-reverse, column-reverse)

Corrige lo que indica el motivo. Si el motivo aparece recortado, escribe un registro de depuración y busca en él a hook returned a tree that does not validate para leer el resto.

Si, en cambio, la línea dice refused: justo después del nombre del punto de renderizado, como en ui.render (Pane) refused:, consulta Una línea de ui.render dice refused.

Una línea de ui.render dice refused

ui.render (<site>) refused:, o ui.render (<site>): the chain settled on a tree that does not validate en el registro de depuración, significa que el árbol en ese punto de renderizado supera un límite de tamaño. Cualquiera de las dos líneas nombra el punto de renderizado y luego el motivo, y el motivo nombra el límite.

Cambia los mods que dibujan en ese punto de renderizado para que sus hooks ui.render devuelvan árboles más pequeños, o pídeles a sus autores que lo hagan. Si la línea de la transcripción empieza con hooks, más de un mod cargado tiene un hook ui.render para ese punto de renderizado, así que revisa los árboles de cada uno de esos mods. Para varios mods cuyas bandas encima del prompt se anidan en un árbol de más de 32 niveles de profundidad, la línea dice:

hooks: ui.render (AbovePrompt) refused: deeper than 32; nothing was drawn

Antes de v2.1.307, una línea refused: para cualquier punto de renderizado informaba de cualquier árbol que no pasara la validación, y para Pane y AbovePrompt terminaba con ; the engine drew its own. En esas versiones, corrige lo que indica el motivo.

needs a key, is drawn twice o key each once

Un elemento del árbol que devuelve tu hook ui.render no tiene una key válida, o dos elementos comparten una. Busca el mensaje que recibiste:

• <Input> needs a key o <Select> needs a key: el elemento no tiene la prop key, o su key está vacía o no es una cadena, como en key: 3. Dale una cadena no vacía como su key.
• <Button> needs a key: dale al botón una cadena no vacía como su key
• is drawn twice; each takes its own key: dos elementos del tipo que nombra el mensaje tienen la misma key, como en Input "size" is drawn twice; each takes its own key. Dale a cada elemento su propia key.
• key each once de press en una prueba: el dibujo tiene más de un botón con la clave que pasaste. Los botones con la misma etiqueta y sin la prop key comparten esa etiqueta como clave. Dale a cada botón su propia key.

Una línea de ui.render dice threw while drawn

La línea nombra el punto de renderizado, luego dice threw while drawn: y el error, como en first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code encontró ese error al dibujar el árbol que devolvió tu hook ui.render, o al dibujar el punto de renderizado a partir de las props que tu hook pasó a next. El final the engine drew its own significa que el punto de renderizado muestra el contenido habitual de Claude Code.

Lee el error y corrige el valor de tu hook que lo causó.

Antes de v2.1.289, este error en una fila de la transcripción terminaba la sesión con Claude Code exited after an unrecoverable interface error.

the module failed without a message

Un Client falló con un error que no tiene mensaje, como throw new Error(). La línea que aparece en su lugar se ve así: my-mod: Client client/spinner.js: the module failed without a message.

Busca el throw en el código de tu Client y dale un mensaje al error. Así, la línea muestra ese mensaje.

Antes de v2.1.289, la línea mostraba Error como motivo.

$.ui.open se ejecuta y no aparece ningún panel

La llamada no provino de algo que hizo el usuario, y la terminal es más estrecha que el ancho que necesita ese panel.

Abre el panel desde un comando o un botón, o revisa el resultado isPlaced de la llamada. Consulta Abrir un panel en el momento adecuado.

Un toast no aparece

Tu mod llama a $.ui.toast en una sesión interactiva de la terminal y no ves el toast. Para confirmar que la llamada se ejecutó, busca en el registro de depuración una línea con el nombre de tu mod y el texto del toast, como en $.ui.toast (first-mod): build finished. Luego revisa causas como estas:

• Falta la línea de la llamada: busca una que diga por qué Claude Code rechazó la llamada, como en first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• Un panel está reteniendo los toasts: tu mod u otro pasó holdToasts al abrir el panel que se está mostrando. Cierra el panel para terminar la retención. Si el panel es tuyo y debe permanecer abierto, quita holdToasts de su llamada a $.ui.open y vuelve a abrir el panel.
• El toast está debajo del prompt: en el renderizador clásico, mira a la derecha, debajo del prompt. Un toast ahí es una línea que empieza con el nombre del mod, en lugar de un recuadro en la esquina superior derecha.
• Tu mod lanzó un toast más reciente: en el renderizador clásico, un toast más reciente de tu mod puede ocupar el lugar de uno que se está mostrando o que espera para mostrarse. El registro de depuración tiene otra línea para el toast anterior, que termina con gave way, cut short si se estaba mostrando, o con gave way, unseen si nunca apareció. Para mostrar ambos mensajes, ponlos en un solo toast.
• Al toast se le acabó el tiempo sin dibujarse: en el renderizado de pantalla completa, Claude Code dibuja como máximo tres toasts a la vez, así que a un toast se le puede acabar el tiempo antes de dibujarse. El registro de depuración tiene otra línea para ese toast, que termina con left the stack, never drawn. Cuando tu mod lance varios a la vez, pon los mensajes en un solo toast.

Antes de v2.1.290, Claude Code descartaba un toast lanzado dentro de los dos segundos posteriores al último que mostró para tu mod, y la línea del registro de depuración del toast descartado decía within 2000ms of the last; dropped.

La banda muestra plugin panel hidden

La banda está contraída. Se contrae cuando presionas Ctrl+X y luego Ctrl+A, o las teclas que asignaste en su lugar, y en el renderizado de pantalla completa cuando haces clic en el [-] de su primera fila. Permanece contraída hasta que la expandas o vuelvas a iniciar Claude Code, y mientras tanto ningún atajo de teclado ni asignación action presiona un botón en ella.

Para expandir la banda, presiona las teclas que indica la fila, Ctrl+X y luego Ctrl+A de forma predeterminada, o en el renderizado de pantalla completa haz clic en la fila.

Los atajos de teclado no hacen nada

Tu panel o banda no tiene el foco del teclado, tu botón está en una banda contraída, o el dibujo está en la extensión de VS Code, donde los botones no tienen atajos de teclado. Haz lo que corresponda:

• Sin foco del teclado: presiona Ctrl+X y luego Tab o, en el renderizado de pantalla completa, haz clic en el panel o la banda. Para que el panel tome el foco al abrirse, ábrelo con focus: true desde un comando.
• El botón está en una banda contraída: la banda muestra una fila atenuada que empieza con ▸ plugin panel hidden. Presiona las teclas que indica la fila, Ctrl+X y luego Ctrl+A de forma predeterminada, para expandirla.
• En la extensión de VS Code: haz clic en el botón, o presiona Enter sobre él cuando tenga el foco

Un dibujo funciona en la terminal y no en la app de escritorio ni en VS Code

O bien esa app no dibuja el punto de renderizado o el elemento, o bien la sesión es una en la que la extensión de VS Code no dibuja nada para los mods. Los demás hooks del mod se siguen ejecutando. Revisa estas causas:

• El punto de renderizado o el elemento no se dibuja en esa app: busca tu punto de renderizado en la tabla de puntos de renderizado y tus elementos en la tabla de elementos. Para un elemento que la app no tiene, revisa e.surface en el hook y devuelve un árbol que la app pueda dibujar.
• La extensión de VS Code es anterior a 2.1.299: el panel de chat dibuja para los mods a partir de la versión de la extensión 2.1.299. Revisa la versión en la vista Extensions de VS Code y actualiza la extensión ahí.
• La extensión es anterior a 2.1.304 y la sesión no obtiene los feature flags: actualiza la extensión, o ejecuta claude en la terminal integrada de VS Code en su lugar. Las sesiones en Amazon Bedrock, Agent Platform de Google Cloud o Microsoft Foundry omiten la obtención. Para las demás que la omiten, como una sesión a través de un gateway de apps de Claude, consulta Funciones que necesitan obtener feature flags.

Se pierde una edición o un valor

El mod se ejecuta, y un cambio que hiciste o un valor que conservaba no está.

Tus ediciones no surten efecto

Estás editando un plugin que instalaste. Claude Code ejecuta la copia en caché de la versión instalada.

Desarrolla con --plugin-dir apuntando a tu copia de trabajo, como en claude --plugin-dir ./first-mod, que se recarga cuando guardas.

Un valor se restablece cuando el módulo se recarga

Las variables a nivel de módulo se reinicializan en cada recarga.

Guarda el valor en $.state o $.store.

Un valor se restablece después de /clear, /resume o /branch

Un valor se restablece, o un valor guardado se reemplaza por su valor predeterminado. Cada uno de esos comandos restablece $.state a sus valores predeterminados, y session.start no se vuelve a disparar.

Carga de nuevo el valor guardado en un hook classic.SessionStart.

Una clave que devuelve tu hook settings.read no surte efecto

Si devuelves reglas de permisos o env en la propia lectura de Claude Code, las reglas no se comprueban en las llamadas a herramientas y las entradas env no se convierten en variables de entorno. Usa un archivo de configuración para ambas, o $.env.set para env.

Para cualquier otra clave, comprueba qué mods reciben settings.read y a partir de qué versión, luego busca settings.read en el registro de depuración y localiza una de estas líneas:

Si ninguna línea explica la clave, revisa los mods que se ejecutan antes que el tuyo en busca de un hook settings.read que cambie la clave. Desactiva ese mod, o pide al administrador de tu organización que lo haga. Si ningún hook la cambia, define la clave en un archivo de configuración.

the answer for <key> is no value the key can hold

Esta línea del registro de depuración significa que Claude Code rechazó el valor que un hook settings.read devolvió para la clave nombrada, y solo para esa clave:

settings.read: the answer for <key> is no value the key can hold; the settings' own value stands

El valor devuelto para la clave nombrada no se ajustaba al esquema de esa clave, por ejemplo por tipo o por rango.

• Tu valor no se ajusta al esquema de la clave: devuelve un valor permitido por la entrada de la clave en la referencia de configuración.
• Tu valor se ajusta: el valor que no se ajusta provino del hook settings.read de otro mod. Para encontrar ese mod, sigue los pasos para desactivar los mods uno a uno. Busca esta línea en cada nuevo registro en lugar de refused to the engine.

Mientras el valor no se ajuste, la clave conserva el valor combinado a partir de las fuentes de configuración antes de que respondiera cualquier hook. La línea lo llama el valor propio de la configuración.

settings.read: refused to the engine

Ves esta línea en el registro de depuración cuando se rechaza la propia lectura de Claude Code, y Claude Code descarta el valor de todos los hooks. Cuando un hook settings.read rechaza esa lectura con { deny: reason }, la línea incluye el motivo de ese hook:

settings.read: refused to the engine (engine: $.settings.read: <reason>); the settings' own values stand

Busca en tu código el motivo que aparece entre paréntesis:

• Tu código lo contiene: tu hook rechazó la lectura. Haz que devuelva { value } cuando next.origin indique la propia lectura de Claude Code.
• Tu código no lo contiene: desactiva tus otros mods uno a uno. Si tu organización implementó un mod, pide a su administrador que lo desactive. Después de cada uno:
  1. Inicia la sesión desde tu shell con claude --debug-file ./settings-read-2.log, seguido de los flags con los que se inició. Usa una ruta nueva cada vez.
  2. Busca refused to the engine en ese archivo. Si la línea está, desactiva el siguiente mod. Si no, el último mod que desactivaste rechazó la lectura, así que mantenlo desactivado.

Si la línea persiste sin que quede ningún otro mod, define en un archivo de configuración las claves que devuelve tu hook. Sus valores se mantienen mientras la lectura esté rechazada.

Lee el registro de depuración

El registro de depuración tiene una línea por cada módulo que Claude Code carga o rechaza, cada hook que falla y cada resultado que rechaza, así que es donde debes buscar cuando la transcripción no muestra nada. Para generar uno, en tu shell inicia Claude Code con --debug, o con --debug-file <path> para elegir dónde se guarda:

claude --debug-file ./mod-debug.log --plugin-dir ./first-mod

En otra terminal, sigue el archivo y filtra por el nombre de tu mod:

tail -f ./mod-debug.log | grep first-mod

Un mod que se cargó tiene una línea que lo nombra y enumera los eventos que maneja. Un mod cargado con --plugin-dir aparece con su nombre seguido de @inline:

hooks module first-mod@inline loaded (worker, environment 2, tier user); events: session.start,tool.call,command.run,ui.render

Para escribir tus propias líneas en el registro, llama a $.ui.log con un segundo argumento, como en $.ui.log('message', { to: 'debug' }). Sin el segundo argumento, $.ui.log agrega una línea atenuada a la transcripción.

Mientras editas un mod cargado con --plugin-dir, la transcripción muestra una línea por cada recarga que nombra el mod y enumera sus hooks. Si un guardado rompe el módulo, la línea dice reload failed, the previous version stays loaded: con el motivo, y la última versión que funcionaba sigue ejecutándose hasta que Claude Code vuelva a recargar los plugins, por ejemplo cuando ejecutas /reload-plugins.

Próximos pasos

• Probar un mod: detecta problemas antes de que lleguen a una sesión
• Solución de problemas de plugins: problemas al instalar y cargar un plugin que no son específicos de los mods