Solucionar problemas de um mod

Descubra por que um mod Claude Code não faz nada: corresponda o sintoma ou mensagem à sua causa, procure mensagens de recusa e leia o log de depuração.

Quando um módulo de um mod ou um de seus hooks falha, Claude Code o ignora e a sessão continua, então um mod quebrado pode parecer um que não faz nada. Comece verificando o que Claude Code leu do seu mod e onde ele relata um problema, depois encontre o sintoma ou mensagem que você tem.

Descubra por que um mod não faz nada

Quando um mod não faz nada, verifique o que Claude Code lê dos arquivos do mod e a linha que ele escreve quando ignora algo. Para a primeira, em seu shell execute claude plugin validate com o diretório do mod, como em claude plugin validate ./first-mod. Isso detecta um evento digitado incorretamente, um manifesto ruim e um módulo que Claude Code não consegue ler, sem iniciar uma sessão.

Quando um módulo não carrega, um hook é ignorado ou outro mod recusa o seu, Claude Code escreve uma linha que nomeia seu mod. Onde você lê essa linha depende da sessão:

• Uma sessão que recarrega dinamicamente um diretório de plugin: uma linha fraca na transcrição. Essa é uma sessão interativa que você iniciou com --plugin-dir, ou uma onde o recarregamento dinâmico está ativado para mods que Claude escreveu.
• Qualquer outra sessão interativa, como uma que executa um mod que você instalou de um marketplace: o log de depuração apenas. Para obter um, inicie a sessão com claude --debug.
• Uma execução claude -p com --plugin-dir: stderr, no formato de saída de texto padrão. Uma recusa por outro mod vai apenas para o log de depuração.

Verifique se os mods podem carregar

Para verificar se sua configuração permite que os mods carreguem, sem instalar um, execute claude plugin test em seu shell, a partir de um diretório que não contenha um mod. Você não precisa de uma sessão. A mensagem que ele imprime informa o estado:

Uma organização também pode definir allowManagedModsOnly para permitir apenas seus próprios mods, o que este comando não relata. Nesse caso, o Claude Code recusa um mod que você instala, e uma mensagem diz por quê.

O mod não carrega

Nada que o mod adiciona aparece: nenhum comando, nenhum desenho e nenhuma mudança de comportamento.

Sua versão é antiga demais

Consulte qual versão usar e como verificar a sua.

A linha mods active não nomeia o mod

Nada que o mod adiciona aparece, e a linha mods active em /plugin não o nomeia. O módulo hooks não carregou. Quando Claude Code o recusou, o log de depuração tem uma linha que começa com hooks module, o nome do mod e not loaded:, como em hooks module first-mod@inline not loaded: disableAllHooks in managed settings para um mod carregado com --plugin-dir.

Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma. Se o log não tiver tal linha, trabalhe através das outras entradas neste grupo.

Algumas configurações interrompem um mod e deixam o restante do seu plugin funcionando. Ativar ou desativar mods as nomeia.

Uma execução claude -p imprime hooks module not loaded

A linha começa com o nome do mod e vai para stderr. O módulo hooks foi recusado. Uma execução não interativa não tem transcrição, então a mensagem vai para stderr.

Leia o motivo após os dois pontos. A seção mensagens de recusa lista cada uma.

Mensagens de recusa

Cada uma delas segue hooks module, o nome do mod e not loaded: no log de depuração.

Mensagens do guarda integrado

Onde a guarda integrada é carregada, ela pode recusar um mod ou uma de suas respostas. Cada mensagem nomeia a opção que o administrador de sua organização define para alterar a regra.

validate passa e não lista nenhuma linha hooks

hooks/hooks.json não tem uma chave modules, ou a chave está digitada incorretamente.

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

hooks module did not load

A linha começa com o nome do mod, depois hooks module did not load: e um motivo, que fornece o arquivo e a linha quando o problema está em seu código. Claude Code não conseguiu carregar o módulo, por exemplo porque seu código de nível superior lançou.

Corrija o erro que o motivo nomeia.

Se o motivo terminar com ; the version loaded before is unloaded, nenhuma versão do mod está em execução agora. Depois de corrigir o erro, execute /reload-plugins na sessão para carregar o mod novamente. Se você instalou o mod e não o escreveu, peça ao autor que corrija o erro.

options do not fit plugin.json userConfig

A linha começa com o nome do mod, depois hooks module did not load: options do not fit plugin.json userConfig: e um motivo. Uma opção falha na validação em relação ao seu campo userConfig, como um número acima do max do campo, ou um campo obrigatório não tem valor.

Defina ou altere o valor. O final da linha nomeia sua entrada pluginConfigs em settings.json.

code nested too deep to scan: more than 2000 scopes

A linha começa com o nome do mod, depois hooks module did not load:, o arquivo e code nested too deep to scan: more than 2000 scopes. Um arquivo em um módulo de hooks não pode aninhar escopos, como funções, blocos e loops, com mais de 2.000 níveis de profundidade. claude plugin validate informa o mesmo motivo.

Reescreva o código para que seus escopos fiquem menos profundamente aninhados.

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

O código no módulo de hooks está aninhado profundamente demais, ou sua cadeia de importações é longa demais, para que Claude Code consiga carregá-lo. A linha começa com o nome do mod e hooks module did not load:, depois fornece o nome de um arquivo e este motivo.

Procure nesse arquivo e nos arquivos alcançados por meio de suas importações a parte mais profundamente aninhada e reescreva-a para que fique menos aninhada, ou encurte a cadeia de importações. Se você não escreveu o mod, peça ao autor que o corrija.

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

O código em um arquivo do módulo de hooks está aninhado tão profundamente que Claude Code ficou sem pilha ao lê-lo. A linha começa com o nome do mod e hooks module did not load:, depois fornece o nome desse arquivo e um destes 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>

O motivo não fornece número de linha e não diz que tipo de código está aninhado, então procure você mesmo no arquivo a parte mais profundamente aninhada. Reescreva essa parte para que fique menos aninhada. Se você instalou o mod e não o escreveu, peça ao autor que faça isso.

Nenhum mod carrega em um diretório que você abriu pela primeira vez

Você não respondeu ao prompt de confiança para o diretório.

Inicie uma sessão interativa nesse diretório com claude e aceite o prompt de confiança que ele abre.

Nenhum plugin instalado carrega

Você iniciou Claude Code com --safe-mode.

Inicie sem a flag.

Claude Code para de perguntar se deve ativar o recarregamento dinâmico

Claude escreve um mod em uma sessão interativa, nada carrega, e Claude Code não pergunta novamente se deve ativar o recarregamento dinâmico. Se a pergunta terminar três vezes sem que uma resposta seja escolhida, o recarregamento dinâmico permanece desativado. Por exemplo, a pergunta termina dessa forma quando você define askUserQuestionTimeout e o tempo passa antes de você responder. Essa configuração se aplica aqui porque Claude Code pergunta no mesmo diálogo de pergunta que AskUserQuestion usa. Uma pergunta que você mesmo descarta não conta para as três.

Para executar o mod, copie seu diretório para fora da pasta de mods e, em seguida, no seu shell, inicie uma nova sessão com --plugin-dir, como em claude --plugin-dir ~/mods/git-branch.

Um hook é ignorado ou um mod é descarregado

O mod carregou e então Claude Code ignorou um de seus hooks ou o descarregou.

hook skipped

A linha nomeia o mod e o evento, depois diz hook skipped: e um motivo, como em first-mod: tool.call hook skipped: threw Error: boom. Um hook lançou, executou além de seu limite de tempo, ou retornou um resultado de forma incorreta. A linha aparece uma vez para cada evento e tipo de falha até o mod recarregar.

Corrija o erro. O log de depuração tem uma linha para cada ocorrência.

no command.run hook answered it

Você executa um comando que seu mod adicionou, e a resposta nomeia o mod e o comando, como em first-mod registered /tally but no command.run hook answered it, depois diz para você adicionar um hook. Claude Code imprime essa resposta quando o comando chega ao final da cadeia sem uma resposta, o que acontece em dois casos:

• Nenhum hook respondeu ao comando: o módulo não tem um hook command.run, o filtro do hook nomeia um comando diferente, ou o hook retornou next(e)
• Claude Code ignorou o hook: hook skipped lista os motivos. Passar focus: false para $.ui.open é uma forma de chegar lá.

Se o módulo já tiver o hook que a resposta descreve, procure por uma linha hook skipped que nomeie command.run, que fornece o motivo. Um teste que executa o comando falha pelo mesmo motivo.

it crashed the hooks worker

A linha começa com o nome do mod, como em first-mod was unloaded: it crashed the hooks worker. Os mods instalados compartilham um thread de worker. O worker parou de responder ou travou, e Claude Code rastreou isso para este mod e o descarregou. Um hook que bloqueia a thread, como um loop que nunca aguarda, é uma causa.

Corrija o hook.

its session.start ran again in a fresh copy

A linha começa com o nome do mod e nomeia uma chamada $.prompt.submit, $.command.run ou $.agent.spawn, como em 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 carregou o módulo do mod novamente, por exemplo depois que o hooks worker travou e foi substituído, e o hook session.start da nova cópia foi executado. A chamada que a linha nomeia foi resolvida com o resultado de sua primeira execução em vez de ser executada novamente, então seu mod não envia o prompt, não executa o comando nem inicia o subagente duas vezes. O restante do hook foi executado normalmente.

Não há nada a corrigir.

Antes da v2.1.292, a chamada era executada uma segunda vez, então o prompt era enviado, o comando executado ou o subagente iniciado duas vezes.

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

Uma alteração em um mod que Claude escreveu nesta sessão não pôde ser carregada. A linha da transcrição começa com o nome do mod e termina com o 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 não vê essa linha, então cole-a na sua próxima mensagem quando pedir uma correção ao Claude.

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

A linha começa com o nome do seu mod, como em first-mod: $.agent.register refused: the hooks module that made the call is no longer loaded (it was reloaded or removed), e o agente não é registrado. Seu mod foi recarregado ou descarregado antes da chamada. Um recarregamento carrega uma nova cópia do módulo de hooks, e essa chamada veio de código ainda em execução na cópia antiga, como um hook que ainda não havia retornado.

Se esse hook não capturar a rejeição, ele falha e Claude Code o ignora. Para registrar o agente a partir da cópia que permanece carregada, faça a chamada no seu hook session.start, que é executado novamente em cada nova cópia após um recarregamento.

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

A linha lê hooks: mods that run in the hooks worker are off for this session: it crashed 3 times. O worker parou três vezes e Claude Code não conseguiu rastrear as paradas para um mod, então descarregou cada mod que não é integrado, incluindo mods que sua organização instala. Esta linha chega à transcrição em cada sessão interativa.

Execute /reload-plugins para carregá-los novamente.

Uma chamada de ferramenta é recusada

O mod carregou e seus hooks executam, e uma chamada de ferramenta que ele tocou é recusada.

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

Em modo automático, uma chamada de ferramenta recusada fornece este motivo. Um hook alterou a entrada da chamada de ferramenta após o classificador do lado do servidor revisá-la, então essa revisão não cobre o que seria executado. O hook pode ser um tool.call ou turn.step hook do mod, ou um hook de configurações PreToolUse. A mensagem não diz qual.

A mensagem diz a Claude para emitir a chamada novamente conforme registrado. Se isso também for recusado, o hook altera a entrada toda vez, então desative o mod ou hook, ou saia do modo automático e aprove a chamada você mesmo.

[!NOTE]

Em algumas sessões interativas de terminal e sessões do VS Code, a mesma recusa fornece o motivo a hook changed this call's input after auto mode reviewed it. A chamada repetida ali carrega a primeira alteração do mod, e um hook tool.call ainda é executado nela, mas uma alteração adicional é descartada. Você não precisa alterar seu mod, a menos que Claude informe em sua resposta que o modo auto não conseguiu verificar a chamada.

Uma mensagem sobre as regras de negação em suas configurações

tried to lift a deny rule in your settings e the deny rules in your settings could not be checked for this call, so it is refused ambas vêm do guarda integrado.

Procure-as em Mensagens do guarda integrado.

Um toast aparece depois que um turno é interrompido

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

Este toast significa que, depois que você interrompeu o turno, por exemplo com Esc, um mod tentou iniciar trabalho por conta própria e o Claude Code não permitiu. Nada precisa ser corrigido. Após sua próxima mensagem, os mods podem iniciar trabalho novamente e parte desse trabalho retorna por conta própria. Se o que você esperava do mod não retornar, peça novamente ou execute o comando do mod novamente.

Se você escreveu o mod, consulte Chamadas e trabalho em segundo plano depois que o usuário interrompe um turno.

Um desenho não aparece ou responde

O mod carregou e seu painel, banda, toast ou controles não se comportam como você espera.

A banda de outro mod aparece e a sua não

Há uma única banda acima do prompt, e todos os mods a compartilham. Um mod que executa antes do seu substitui a sua banda quando retorna uma árvore sem o resultado de next(e) nela. Para mostrar as duas bandas, altere o hook desse mod, ou peça ao autor dele que o faça:

• Manter as bandas depois dele: coloque o resultado de await next(e) entre os filhos de um Box na árvore dele, como na aba Banda acima do prompt de Escolher onde desenhar
• Manter a árvore válida: não dê a esse Box, nem a nenhum Box ao redor dele, uma prop width, height, minWidth, minHeight, position, top, left, right, bottom, display ou overflow

Para encontrar esse mod, grave um log de depuração e procure nele por answered ui.render without next(). Uma linha como other-mod (user) answered ui.render without next() nomeia um mod que retornou sua árvore sem chamar next(e). Ela não nomeia o ponto de renderização, então um mod que desenha apenas em um painel também pode aparecer. Um mod que chama next(e) e descarta o resultado não gera nenhuma linha, então verifique também os hooks que executam antes do seu.

A banda de um mod também fica ausente quando a árvore que o próprio hook dele retornou não valida, e as bandas dos outros mods permanecem. Para descobrir qual mod e por quê, grave um log de depuração e procure nele por ui.render hook skipped.

Um painel ou banda está vazio ou mostra o conteúdo usual de Claude Code

A árvore que seu hook retornou não validou. Uma linha hook skipped na transcrição ou no log de depuração nomeia seu mod e o motivo, como nesta para um Box em um painel:

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)

Corrija o que o motivo nomeia. Se o motivo estiver cortado, grave um log de depuração e procure nele por a hook returned a tree that does not validate para ler o restante.

Se, em vez disso, a linha disser refused: logo após o nome do ponto, como em ui.render (Pane) refused:, consulte Uma linha ui.render diz refused.

Uma linha ui.render diz refused

ui.render (<site>) refused:, ou ui.render (<site>): the chain settled on a tree that does not validate no log de depuração, significa que a árvore nesse ponto excede um limite de tamanho. Qualquer uma das linhas nomeia o ponto de renderização e depois o motivo, e o motivo nomeia o limite.

Altere os mods que desenham nesse ponto para que seus hooks ui.render retornem árvores menores, ou peça aos autores deles que o façam. Se a linha da transcrição começar com hooks, mais de um mod carregado tem um hook ui.render para esse ponto, então verifique as árvores de cada um desses mods. Para vários mods cujas bandas acima do prompt se aninham em uma árvore com mais de 32 níveis de profundidade, a linha diz:

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

Antes da v2.1.307, uma linha refused: para qualquer ponto relatava qualquer árvore que não validava e, para Pane e AbovePrompt, terminava com ; the engine drew its own. Nessas versões, corrija o que o motivo nomeia.

needs a key, is drawn twice ou key each once

Um elemento na árvore que seu hook ui.render retorna não tem uma key válida, ou dois elementos compartilham a mesma. Encontre a mensagem que você recebeu:

• <Input> needs a key ou <Select> needs a key: o elemento não tem a prop key, ou sua key está vazia ou não é uma string, como em key: 3. Dê a ele uma string não vazia como key.
• <Button> needs a key: dê ao botão uma string não vazia como key
• is drawn twice; each takes its own key: dois elementos do tipo que a mensagem nomeia têm a mesma key, como em Input "size" is drawn twice; each takes its own key. Dê a cada elemento sua própria key.
• key each once vindo de press em um teste: o desenho tem mais de um botão com a key que você passou. Botões com o mesmo rótulo e sem a prop key compartilham esse rótulo como key. Dê a cada botão sua própria key.

Uma linha ui.render diz threw while drawn

A linha nomeia o ponto de renderização, depois diz threw while drawn: e o erro, como em first-mod: ui.render (ToolUse) threw while drawn: <error>; the engine drew its own. Claude Code encontrou esse erro ao desenhar a árvore que seu hook ui.render retornou, ou ao desenhar o ponto a partir das props que seu hook passou para next. O final the engine drew its own significa que o ponto mostra o conteúdo usual de Claude Code.

Leia o erro e corrija o valor no seu hook que o causou.

Antes da v2.1.289, esse erro em uma linha da transcrição encerrava a sessão com Claude Code exited after an unrecoverable interface error.

the module failed without a message

Um Client falhou com um erro que não tem mensagem, como throw new Error(). A linha em seu lugar aparece como my-mod: Client client/spinner.js: the module failed without a message.

Encontre o throw no código do seu Client e dê uma mensagem ao erro. A linha então mostra essa mensagem.

Antes da v2.1.289, a linha mostrava Error como motivo.

$.ui.open executa e nenhum painel aparece

A chamada não veio de algo que o usuário fez, e o terminal é mais estreito que a largura de que esse painel precisa.

Abra o painel a partir de um comando ou botão, ou verifique o resultado isPlaced da chamada. Veja Abrir um painel no momento certo.

Um toast não aparece

Seu mod chama $.ui.toast em uma sessão interativa do terminal e você não vê o toast. Para confirmar que a chamada foi executada, procure no log de depuração uma linha com o nome do seu mod e o texto do toast, como em $.ui.toast (first-mod): build finished. Depois, verifique causas como estas:

• A linha da chamada está ausente: procure uma linha que diga por que Claude Code recusou a chamada, como em first-mod: $.ui.toast dropped: timeoutMs is a whole number of ms, 1 to 60000.
• Um painel está retendo os toasts: seu mod ou outro passou holdToasts ao abrir o painel que está sendo exibido. Feche o painel para encerrar a retenção. Se o painel for seu e deve permanecer aberto, remova holdToasts da chamada $.ui.open dele e abra o painel novamente.
• O toast está abaixo do prompt: no renderizador clássico, olhe à direita, abaixo do prompt. Um toast ali é uma linha que começa com o nome do mod, em vez de uma caixa no canto superior direito.
• Seu mod gerou um toast mais recente: no renderizador clássico, um toast mais recente do seu mod pode tomar o lugar de um que está sendo exibido ou aguardando para ser exibido. O log de depuração tem outra linha para o toast mais antigo, que termina com gave way, cut short quando ele estava sendo exibido, ou gave way, unseen quando nunca apareceu. Para mostrar as duas mensagens, coloque-as em um único toast.
• O tempo do toast esgotou antes de ser desenhado: na renderização em tela cheia, Claude Code desenha no máximo três toasts por vez, então o tempo de um toast pode se esgotar antes de ele ser desenhado. O log de depuração tem outra linha para esse toast, que termina com left the stack, never drawn. Quando seu mod gerar vários ao mesmo tempo, coloque as mensagens em um único toast.

Antes da v2.1.290, Claude Code descartava um toast gerado dentro de dois segundos após o último que exibiu para o seu mod, e a linha do log de depuração para o toast descartado dizia within 2000ms of the last; dropped.

A banda mostra plugin panel hidden

A banda está recolhida. Ela é recolhida quando você pressiona Ctrl+X depois Ctrl+A, ou as teclas que você associou no lugar delas, e, na renderização em tela cheia, quando você clica no [-] da primeira linha dela. Ela permanece recolhida até que você a expanda ou inicie Claude Code novamente e, enquanto isso, nenhuma hotkey ou associação action pressiona um botão nela.

Para expandir a banda, pressione as teclas que a linha indica, Ctrl+X depois Ctrl+A por padrão, ou, na renderização em tela cheia, clique na linha.

Hotkeys não fazem nada

Seu painel ou banda não tem foco de teclado, seu botão está em uma banda recolhida, ou o desenho está na extensão do VS Code, onde os botões não têm hotkeys. Faça o que corresponder ao seu caso:

• Sem foco de teclado: pressione Ctrl+X depois Tab ou, na renderização em tela cheia, clique no painel ou na banda. Para que o painel receba o foco ao abrir, abra-o com focus: true a partir de um comando.
• O botão está em uma banda recolhida: a banda mostra uma linha esmaecida que começa com ▸ plugin panel hidden. Pressione as teclas que a linha indica, Ctrl+X depois Ctrl+A por padrão, para expandi-la.
• Na extensão do VS Code: clique no botão, ou pressione Enter sobre ele quando estiver com o foco

Um desenho funciona no terminal e não no aplicativo Desktop ou no VS Code

Ou esse aplicativo não desenha o ponto de renderização ou o elemento, ou a sessão é uma em que a extensão do VS Code não desenha nada para mods. Os outros hooks do mod continuam sendo executados. Verifique estas causas:

• O ponto de renderização ou elemento não é desenhado nesse aplicativo: procure seu ponto na tabela de pontos de renderização e seus elementos na tabela de elementos. Para um elemento que o aplicativo não tem, verifique e.surface no hook e retorne uma árvore que o aplicativo consiga desenhar.
• A extensão do VS Code é anterior à 2.1.299: o painel de chat desenha para mods a partir da versão da extensão 2.1.299. Verifique a versão na visualização Extensions do VS Code e atualize a extensão ali.
• A extensão é anterior à 2.1.304 e a sessão não busca feature flags: atualize a extensão ou, em vez disso, execute claude no terminal integrado do VS Code. Sessões no Amazon Bedrock, no Agent Platform do Google Cloud ou no Microsoft Foundry pulam essa busca. Para as outras que a pulam, como uma sessão de gateway de aplicativos Claude, consulte Recursos que precisam da busca de feature flags.

Uma edição ou um valor é perdido

O mod executa e uma mudança que você fez ou um valor que ele manteve não está lá.

Suas edições não entram em vigor

Você está editando um plugin que instalou. Claude Code executa a cópia em cache para a versão instalada.

Desenvolva com --plugin-dir apontado para sua cópia de trabalho, como em claude --plugin-dir ./first-mod, que recarrega quando você salva.

Um valor é redefinido quando o módulo recarrega

Variáveis de nível de módulo são reinicializadas em cada recarregamento.

Mantenha o valor em $.state ou $.store.

Um valor é redefinido após /clear, /resume ou /branch

Um valor é redefinido, ou um valor salvo é substituído por seu padrão. Cada um desses comandos redefine $.state para seus padrões, e session.start não dispara novamente.

Carregue o valor salvo novamente em um hook classic.SessionStart.

Uma chave que seu hook settings.read retorna não entra em vigor

Se você retornar regras de permissão ou env na leitura do próprio Claude Code, as regras não são verificadas nas chamadas de ferramenta e as entradas env não se tornam variáveis de ambiente. Use um arquivo de configurações para ambos, ou $.env.set para env.

Para outra chave, verifique quais mods recebem settings.read e a partir de qual versão, depois pesquise settings.read no log de depuração e procure uma destas linhas:

Se nenhuma linha explicar a chave, verifique nos mods que executam antes do seu se há um hook settings.read que altera a chave. Desative esse mod ou peça ao administrador da sua organização que o faça. Se nenhum hook a alterar, defina a chave em um arquivo de configurações.

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

Esta linha do log de depuração significa que Claude Code recusou o valor que um hook settings.read retornou para a chave nomeada, e somente para essa chave:

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

O valor retornado para a chave nomeada não se ajustou ao esquema dessa chave, por exemplo, por tipo ou por intervalo.

• Seu valor não se ajusta ao esquema da chave: retorne um que a entrada da chave na referência de configurações permita.
• Seu valor se ajusta: o valor que não se ajusta veio do hook settings.read de outro mod. Para encontrar esse mod, siga as etapas para desativar os mods um de cada vez. Pesquise esta linha em cada novo log em vez de refused to the engine.

Enquanto o valor não se ajustar, a chave mantém o valor mesclado das fontes de configurações antes de qualquer hook responder. A linha o chama de valor próprio das configurações.

settings.read: refused to the engine

Você vê esta linha no log de depuração quando a leitura do próprio Claude Code é recusada, e Claude Code descarta o valor de todos os hooks. Quando um hook settings.read recusa essa leitura com { deny: reason }, a linha traz o motivo desse hook:

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

Pesquise no seu código o motivo entre parênteses:

• Seu código o contém: seu hook recusou a leitura. Faça-o retornar { value } quando next.origin indicar a leitura do próprio Claude Code.
• Seu código não o contém: desative seus outros mods um de cada vez. Se sua organização implantou um mod, peça ao administrador dela que o desative. Após cada um:
  1. Inicie a sessão a partir do seu shell com claude --debug-file ./settings-read-2.log, seguido das flags com que ela foi iniciada. Use um novo caminho a cada vez.
  2. Pesquise refused to the engine nesse arquivo. Se a linha estiver lá, desative o próximo mod. Se não estiver, o último mod que você desativou recusou a leitura, então mantenha-o desativado.

Se a linha permanecer sem nenhum outro mod restante, defina as chaves que seu hook retorna em um arquivo de configurações. Os valores dele se mantêm enquanto a leitura é recusada.

Leia o log de depuração

O log de depuração tem uma linha para cada módulo que Claude Code carrega ou recusa, cada hook que falha e cada resultado que recusa, então é onde procurar quando a transcrição não mostra nada. Para escrever um, em seu shell inicie Claude Code com --debug, ou com --debug-file <path> para escolher onde ele vai:

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

Em outro terminal, siga o arquivo e filtre pelo nome do seu mod:

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

Um mod que carregou tem uma linha que o nomeia e lista os eventos que ele trata. Um mod carregado com --plugin-dir aparece sob seu nome seguido por @inline:

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

Para escrever suas próprias linhas no log, chame $.ui.log com um segundo argumento, como em $.ui.log('message', { to: 'debug' }). Sem o segundo argumento, $.ui.log adiciona uma linha fraca à transcrição.

Enquanto você edita um mod carregado com --plugin-dir, a transcrição mostra uma linha para cada recarregamento que nomeia o mod e lista seus hooks. Se um salvamento quebrar o módulo, a linha diz reload failed, the previous version stays loaded: com o motivo, e a última versão de trabalho continua executando até que Claude Code recarregue os plugins novamente, como quando você executa /reload-plugins.

Próximas etapas

• Teste um mod: detecte problemas antes que eles cheguem a uma sessão
• Solucionar problemas de plugins: problemas com instalação e carregamento de um plugin que não são específicos de mods