🔍 Depurar e as pegadinhas

A referência oficial dá o conselho em uma linha: rode com claude --debug enquanto desenvolve. O log de depuração tem uma linha para cada vez que algo deu errado e para cada resultado que o engine recusou.

Sem o debug você ainda vê parte disso, mas só em certas sessões. A tabela mostra onde cada sinal aparece.

O que olhar na tabela: o lugar mais completo é sempre o log. Desenvolva com --plugin-dir e --debug juntos e você vê os dois sinais.

Um hook que lança erro, estoura o orçamento de tempo ou devolve uma forma errada é pulado. A cadeia segue sem ele: os hooks de baixo e o núcleo rodam no lugar, ou vale o último resultado do next que ele chegou a chamar.

Por isso o sintoma é silencioso: o Claude Code continua normal, só que sem o seu mod. A exceção é o .catch do registro, que responde no lugar do hook que falhou (módulo 2.2).

Como ler o desenho: o X vermelho não derruba a sessão; a seta passa por cima. O que sobra é a linha pontilhada no log. Pela referência, ela traz o nome do erro e o tamanho da mensagem no lugar do texto; o texto do primeiro erro, cortado, fica na linha apagada da conversa.

Pior que um hook pulado é um módulo que nem carrega: nenhum hook entra, nenhum comando aparece. As causas conhecidas são poucas e quase sempre estruturais, não de lógica.

O claude plugin validate lê o manifesto e o código como o engine vai ler e relata o que o engine recusaria, antes de você abrir uma sessão. Rode-o primeiro, sempre.

export const register: Register = on => {
  // função que recebe $, DENTRO do register
  const avisar = async ($: EngineInterface, t: string) =>
    $.ui.toast(t)
  on('session.start', async ($, e, next) => {
    await avisar($, 'mod pronto')
    return next(e)
  })
}

// no TOPO do arquivo
async function avisar($: EngineInterface, t: string) {
  $.ui.toast(t)
}

export const register: Register = on => {
  on('session.start', async ($, e, next) => {
    await avisar($, 'mod pronto')
    return next(e)
  })
}

Quando um ui.render devolve uma árvore que não valida (um elemento que a superfície não tem, uma prop que ele não aceita, um filho onde não cabe filho), o engine não desenha a árvore. Ele desenha a dele no lugar e registra o motivo.

No log de depuração a linha começa assim, seguida do motivo:

ui.render (<Component>): a hook returned a tree that does not validate

Numa sessão que recarrega a pasta do mod a quente, a conversa mostra também, uma vez por carga, componente e motivo:

<plugin>: ui.render (<Component>) refused: <reason>; the engine drew its own

Como ler o desenho: o caminho vermelho não quebra a sessão, mas o seu desenho some. Segundo a referência, quando o engine não tem o que desenhar, a faixa fica vazia e a linha termina em nothing was drawn; um painel é fechado e a linha termina em the pane was closed.

O docs/COMO-FAZER-UM-MOD.md do inema-mods lista 23 pegadinhas que custaram tempo na construção dos 18 mods. Abaixo, o sentido de cada uma, agrupado. O número é o do arquivo (lá a 17 aparece por último).

Os testes provam a lógica. O teste de fumaça prova que o mod carrega de verdade numa sessão real. Um comando de mod responde sem chamar o modelo, então custa zero de cota.

O inema-mods junta os três controles anteriores num script só, scripts/checar-mod.sh: validate, tsc contra os tipos do engine e test. O Rafa roda os dois antes de dizer "pronto".

TSC=<caminho do tsc> scripts/checar-mod.sh mods/recibo-sessao
claude -p "/recibo" --plugin-dir mods/recibo-sessao

== recibo-sessao
  validate: ok
  tsc: ok
  test: ok (6 linhas de aprovação)

recibo-sessao: Nesta sessão: nenhum arquivo criado ou alterado.