Lição 5: Sondas nas comportas: hooks e um fluxo de depuração

Objetivos de aprendizado:

• Explicar o que são hooks: handlers definidos por você que executam automaticamente em pontos fixos do ciclo de vida do agente, organizados em três cadências (uma vez por sessão / uma vez por turno / a cada chamada de ferramenta dentro do loop), e conseguir escolher o evento certo para uma necessidade de observabilidade, escrever o matcher correto e identificar quais campos do payload usar
• Evitar duas armadilhas que mordem de verdade: subprocessos de hook não herdam a configuração de exportação OTel do harness, e os arquivos de transcrição são escritos de forma assíncrona, então podem não conter as mensagens recentes quando o hook dispara
• Aplicar um fluxo de cinco etapas para localizar problemas sob não determinismo: estreitar pelo id do prompt, achar a primeira divergência, reexecutar com entradas idênticas, martelar repetidamente o mesmo componente e retomar do ponto de falha depois de corrigir

Pré-requisitos: Lições 1–4 concluídas (não determinismo e o “não dá para dizer por quê”, registros brutos como evidência de primeira mão, logs estruturados e métricas, árvores de trace e armadilhas do pipeline de telemetria) | Anterior: << Lição 4 | Próxima: Lição 6 >>

Você quer registrar antes e depois de cada execução de ferramenta

A lição 3 ensinou você a escrever uma entrada de log estruturada para cada chamada de ferramenta no seu próprio harness. A lição 4 ensinou a costurar esses registros em uma árvore de trace. Aquele loop era seu, você tinha o código-fonte, podia enfiar uma chamada de log() onde quisesse. Mas agora você está rodando o Claude Code em produção — você não tem o runToolUses dele. O que você quer não é complicado: registrar uma vez antes da execução da ferramenta (com que parâmetros ela vai rodar) e uma vez depois (o que ela devolveu). Só que os pontos de inserção estão no processo de outra pessoa.

O produto previu isso. A resposta se chama hooks.

Hooks são comandos de shell, endpoints HTTP ou prompts de LLM definidos por você que executam automaticamente em pontos específicos do ciclo de vida do Claude Code¹. Em bom português: você declara na configuração “em tal e tal momento, rode este script para mim”, e quando o Claude Code chega naquele momento ele roda. E não chega de mãos vazias — quando um evento dispara e um matcher casa, o Claude Code passa um contexto JSON sobre o evento para o seu handler¹.

No curso 7 desta série, você escreveu uma comporta de aprovação no loop do seu harness — quando ele encontrava uma ferramenta HIGH_IMPACT, parava e esperava a confirmação humana antes de executar. Aquilo era um ponto de interceptação feito à mão. Os hooks fazem a mesma coisa, mas organizaram “quais posições do loop valem uma pausa” numa lista nomeada em que cada posição tem um payload fixo e confiável. Para observabilidade, o valor dessa lista não é que você “consegue mudar o comportamento” — é que você consegue enxergar sem mudar o comportamento.

Três cadências: sessão, turno, chamada de ferramenta

Os eventos se dividem em três cadências¹:

• Uma vez por sessão: SessionStart e SessionEnd
• Uma vez por turno: UserPromptSubmit, Stop e StopFailure (pelos nomes, StopFailure corresponde à saída em que o turno não terminou normalmente — a citação oficial só deu a classificação por cadência; consulte a sua página de referência para a semântica precisa)
• A cada chamada de ferramenta dentro do loop agêntico: PreToolUse e PostToolUse

Alinhe isso com a anatomia do loop do curso 7 e as três camadas casam na hora:

SessionStart                       ← a sessão começa (o runAgent inteiro começa)  UserPromptSubmit                 ← o turno começa (o usuário envia o prompt)    while (stop_reason === "tool_use") {       ... requisição de modelo ...       PreToolUse                  ← dentro do corpo do loop, parâmetros gerados, ainda não executados       ... execução da ferramenta ...       PostToolUse                 ← dentro do corpo do loop, a ferramenta terminou de executar    }  Stop / StopFailure               ← o turno terminaSessionEnd                         ← a sessão termina

Escolher a cadência errada dá números difíceis de explicar: se você quer contar “quantas chamadas de ferramenta esta tarefa usou” mas engancha na comporta por turno, vai receber só zero. Antes de escolher um evento, pergunte: quantas vezes por sessão acontece a coisa que estou contando?

Um detalhe que vale destacar: SessionStart dispara quando você abre uma sessão nova e também quando você retoma uma existente¹. O curso 9 cobriu --resume — da perspectiva do loop aquilo não é “começar do zero”, mas ainda assim toca a campainha do SessionStart. Se você escrever “inicializar um log novo quando a sessão começa”, na primeira vez que usar resume vai sobrescrever o trecho anterior.

Detalhes das comportas úteis para observabilidade

PreToolUse roda depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada da ferramenta¹. Essa brecha importa: os parâmetros estão fechados (você vê exatamente o que o modelo pretende usar), mas a ferramenta ainda não rodou. A lição 2 cobriu um caso real — o time descobriu que o Claude acrescentava desnecessariamente 2025 ao parâmetro de consulta da ferramenta de busca, enviesando os resultados². A evidência desse tipo de bug mora nos parâmetros que o PreToolUse consegue ver.

Os hooks de PostToolUse disparam depois que uma ferramenta já executou com sucesso. A entrada inclui tanto tool_input, os argumentos enviados à ferramenta, quanto tool_response, o resultado que ela devolveu¹. Um disparo te dá um registro completo da chamada; você não precisa juntar por conta própria “qual requisição vai com qual resposta”. O princípio que a lição 2 enfatizou — a ida e volta completa é a evidência de primeira mão² — chega aqui entregue campo por campo. Note que a condição de disparo é “já executou com sucesso”¹; se você quiser cobrir os casos em que os parâmetros foram gerados mas a execução não deu certo, precisa emparelhar com PreToolUse e comparar os dois lados.

Como escrever matchers: para rodar um hook depois que qualquer ferramenta terminar com sucesso, omita o matcher ou defina-o como "*"¹. Cenários de observabilidade querem exatamente esse comportamento de um-hook-registra-tudo — você não sabe qual ferramenta vai quebrar, então registra todas.

Como os handlers enviam e recebem dados: hooks de comando recebem dados JSON via stdin e comunicam resultados por códigos de saída, stdout e stderr¹. Ou seja, um handler mínimo de observabilidade é só “leia JSON da stdin, escolha alguns campos para acrescentar a um arquivo, saia com código 0” — nada de mágica envolvida.

Isto é o log JSON Lines da lição 3, só que quem escreve o log mudou de “o seu harness” para “um scriptzinho que você pendurou no loop de outra pessoa”. Consulte a página de referência da sua versão para a estrutura exata da configuração e os nomes dos campos.

O payload inclui duração, mas confira a definição: o payload carrega um campo opcional com o tempo de execução da ferramenta em milissegundos, que exclui o tempo passado em prompts de permissão e em hooks PreToolUse¹. A segunda metade é a chave: o “quanto tempo esperei por esta etapa” percebido pelo usuário inclui o tempo em que ele ficou clicando em confirmar, mas esse número tira isso fora. Usá-lo para responder “a ferramenta está lenta” está correto; usá-lo para responder “quanto o usuário esperou” vai ficar sistematicamente baixo. A lição 4 mencionou a mesma coisa por outro caminho — o span da ferramenta tem dois spans filhos embaixo, um para a espera pela decisão de permissão e outro para a execução em si³. Eles são gravados separadamente justamente porque esses dois trechos não deveriam ser misturados.

Os próprios hooks também estão no trace: cada prompt do usuário inicia um span raiz claude_code.interaction. Chamadas de API, chamadas de ferramenta e execuções de hook são gravadas como filhos dele³. O mecanismo de observabilidade é ele mesmo um objeto observado.

Dois avisos que mordem

Primeiro: subprocessos de hook não herdam as variáveis de exportador OTEL_*. Um conjunto de variáveis não é herdado: o Claude Code remove as variáveis de exportador OTEL_* de todo subprocesso que ele gera, inclusive hooks¹.

Essa frase mata diretamente uma ideia muito natural: “O harness já tem endpoint, protocolo e cabeçalhos de autenticação configurados. Vou só importar um SDK do OTel no meu hook e as variáveis de ambiente vão funcionar de cara.” — Não vão. Quando o processo do handler inicia, essas variáveis já foram removidas. Os dados ou não vão ser exportados, ou vão bater no endpoint padrão e sumir. Não espere que alguém grite para te avisar: a lição 4 cobriu que a exportação da própria CLI falha em silêncio⁴, e por padrão o exportador que você mesmo montar no hook não vai ser mais barulhento — quando nenhum dado chega ao backend, os dois lados ficam quietos.

Você tem dois caminhos à frente: ou o hook carrega a própria configuração completa de exportação (escreva o endpoint e a autenticação explicitamente no script, não conte com herança), ou não emita telemetria do hook de jeito nenhum — deixe-o escrever um log estruturado e alinhe com a telemetria no backend usando ids. O segundo caminho tem apoio oficial: o UUID que identifica o prompt de usuário sendo processado no payload do hook coincide com o atributo prompt.id dos eventos do OpenTelemetry, de modo que você pode correlacionar a saída do hook com a telemetria de um único prompt¹. Cada lado escreve o seu, e no fim você faz a junção pelo mesmo id de prompt — o mesmo truque de “costurar numa árvore usando IDs de correlação” da lição 4, só que desta vez entre duas fontes de dados.

Segundo: o arquivo de transcrição é escrito de forma assíncrona. O payload te dá um caminho para o JSON da conversa, mas esse arquivo é escrito de forma assíncrona e pode ficar atrasado em relação à conversa em memória, então pode ainda não incluir as mensagens mais recentes do turno atual quando o hook dispara¹.

A armadilha é que isso não dá erro, só entrega dado velho. Alguém pode pensar “os campos do payload não bastam, vou ler a transcrição direto, ela tem tudo”, e acabar com registros que perdem metade do conteúdo de forma intermitente. Se você quer tool_input e tool_response, use os campos do payload — eles são o que o PostToolUse garante explicitamente fornecer¹. Transcrições servem para olhar para trás depois, não para usar como fonte de dados em tempo real no instante em que o hook dispara.

Um lembrete ligado à sua máquina: hooks de comando executam comandos de shell com todas as suas permissões de usuário. Eles podem modificar, apagar ou acessar qualquer arquivo que a sua conta de usuário consiga acessar. Revise e teste todos os comandos de hook antes de adicioná-los à sua configuração¹.

Quando os hooks não fazem o trabalho

Você pendurou um hook, o arquivo de log está vazio. Ele não disparou? O matcher não casou? Ou o próprio script quebrou? Neste momento o objeto que você precisa observar é o próprio mecanismo de observabilidade. O princípio da lição 4 vale de novo aqui: verifique a sonda primeiro.

Os detalhes de execução dos hooks — quais hooks casaram, seus códigos de saída e a stdout e a stderr completas — são escritos no arquivo de log de depuração¹. Obtenha-o de dois jeitos: use claude --debug-file <caminho> para escrever num local que você escolhe, ou rode claude --debug e depois leia ~/.claude/debug/<session-id>.txt¹. Para detalhes mais granulares de casamento de hooks, defina CLAUDE_CODE_DEBUG_LOG_LEVEL=verbose para ver linhas de log adicionais, como as contagens de matcher de hook¹.

Sequência de investigação: o arquivo de log está vazio └─ O log de depuração tem um registro de casamento para este hook?      Não  → o matcher está errado; confirme primeiro que ele dispara com o matcher omitido      Sim  → O código de saída é 0?               Não → leia a stderr, provavelmente caminho do script, permissões ou parse de JSON               Sim → rodou mas não escreveu no lugar certo; verifique o caminho de escrita e a existência do diretório

Um fluxo de depuração: como caçar um problema sob não determinismo

A primeira metade da lição cobriu onde colocar as sondas. A segunda metade cobre como de fato usar esses dados para caçar um problema real.

Comece enunciando a dificuldade com clareza. A lição 1 disse: agentes tomam decisões dinâmicas e são não determinísticos entre execuções, mesmo com prompts idênticos. Isso torna a depuração mais difícil⁵. A etapa um da depuração tradicional é “reproduzir”, e essa etapa não se sustenta aqui — você roda de novo e ele pode seguir um caminho completamente diferente, porém igualmente válido.

As cinco etapas abaixo são arranjo próprio deste curso, não a metodologia oficial de ninguém; mas cada etapa se apoia em uma fonte.

Etapa um: estreitar

Nos registros que você acumulou ao longo das lições 1–4, primeiro estreite o escopo para “este único prompt problemático”. A lição 4 te deu o método: para rastrear toda a atividade disparada por um único prompt, filtre seus eventos por um valor específico de prompt.id³.

O significado desta etapa não é técnico, é psicológico. “O agente quebrou” é uma proposição que você não consegue depurar; “um destes 11 eventos sob este id de prompt está errado” é uma proposição que você consegue depurar.

Etapa dois: achar a primeira divergência

Leia do começo para a frente e ache a primeira etapa em que o comportamento começa a se desviar das expectativas. Por que insistir no “primeiro”? Porque uma etapa falhando pode fazer os agentes explorarem trajetórias completamente diferentes, levando a resultados imprevisíveis⁵. Os absurdos que você vê no fim (referenciar arquivos inexistentes, errar repetidamente, dar voltas enormes) são em geral ruído a jusante. Você conserta o evento #8 e provavelmente está só limpando a bagunça do erro do evento #4.

Julgar “desvio” tem alguns formatos úteis²: chamou uma ferramenta que não deveria ter chamado, chamou a ferramenta certa com parâmetros errados, chamou a ferramenta certa poucas vezes demais ou processou a resposta da ferramenta incorretamente. O último tipo é o mais difícil de perceber, porque a própria ferramenta devolveu sucesso, está tudo verde nos logs — o que está errado é a interpretação que o agente fez daquele resultado bem-sucedido.

Etapa três: reexecutar e observar

A abordagem oficial: para entender os efeitos dos prompts, eles construíram simulações usando exatamente os prompts e as ferramentas do sistema e então observaram os agentes trabalhando etapa por etapa; isso revelou imediatamente modos de falha como agentes que continuavam mesmo já tendo resultados suficientes, que usavam consultas de busca prolixas demais ou que selecionavam ferramentas incorretas⁵.

O “revelou imediatamente” merece reflexão. Esses mesmos bugs são invisíveis em métricas agregadas (a taxa de sucesso está bem alta), exigem leitura linha a linha para serem notados em logs post-mortem, mas quando você assiste à execução etapa por etapa, o olho humano identifica em segundos que “ele já tem o suficiente e continua buscando”. Duas coisas a controlar durante a reexecução: a entrada precisa ser idêntica (prompts e definições de ferramenta inalterados) e a observação precisa ser etapa por etapa.

Etapa quatro: martelar repetidamente o mesmo componente

Se a suspeita recai sobre uma ferramenta específica, rodá-la algumas vezes provavelmente não vai mostrar nada — o não determinismo faz os bugs aparecerem e sumirem.

O time construiu um agente de teste de ferramentas: dê a ele uma ferramenta MCP defeituosa, ele tenta usá-la e então reescreve a descrição da ferramenta para evitar as falhas. Testando a ferramenta dezenas de vezes, esse agente encontrou nuances e bugs importantes⁵.

“Dezenas de vezes” é o ponto. Um bug que uma execução consegue esconder, dezenas de execuções vão forçar para fora: um formato de retorno esquisito sob entradas de fronteira, uma descrição ambígua, uma mensagem de erro que faz o modelo julgar mal como “é só tentar de novo”. As leituras diagnósticas da lição 3 se conectam aqui — muitas chamadas de ferramenta redundantes podem sugerir que os parâmetros de paginação ou de limite de tokens precisam ser redimensionados; muitos erros de ferramenta por parâmetros inválidos podem sugerir que as ferramentas ganhariam com descrições mais claras ou exemplos melhores². Uma coisa que poupa muitas idas e vindas: quando uma chamada de ferramenta levanta um erro, você pode escrever as respostas de erro como prompts, comunicando com clareza melhorias específicas e acionáveis, em vez de códigos de erro opacos ou tracebacks².

Etapa cinco: retomar do ponto de falha depois de corrigir

Depois de corrigir, não aperte “começar de novo” por reflexo. A fala oficial é direta: quando erros acontecem, não podemos simplesmente reiniciar do começo: reinícios são caros e frustrantes para os usuários. Em vez disso, construímos sistemas capazes de retomar de onde o agente estava quando os erros aconteceram⁵.

O curso 9 cobriu como construir mecanismos de retomada. O cenário daquela lição era “como continuar depois de uma tarefa ser interrompida”. Na depuração o uso é outro: as dezenas de chamadas de ferramenta antes do ponto de falha eram válidas, custaram dinheiro, deram resultados corretos. Rodá-las de novo não te dá nada além de tokens queimados, e introduz um monte de novo não determinismo, de modo que você não consegue dizer se “funcionou desta vez” é porque você corrigiu certo ou porque teve sorte.

Sobre “reprodução”, uma palavra honesta

Você já deve ter visto por aí um conjunto de técnicas para tornar agentes reproduzíveis: fixar a semente aleatória, definir temperature como 0, gravar retornos reais de ferramenta e usá-los como stubs de reexecução.

Essas práticas existem na engenharia. Os laboratórios práticos dos cursos 8 a 10 usam justamente essa abordagem de cliente stub — salve o tool_result de uma execução real, devolva os mesmos dados sempre depois disso, e o lado da ferramenta vira determinístico. Bom para verificar “aquela linha de código que mudei quebrou a lógica de parsing?”.

Mas duas coisas precisam ser ditas. Primeiro, essas técnicas não têm respaldo em nenhuma fonte nativa. Eu dei citações para cada etapa do fluxo de cinco etapas acima. Para este parágrafo não estou dando nenhuma, porque genuinamente não existem. Se você vir alguém afirmar “a recomendação oficial é temperature 0 para reproduzir problemas de agente”, peça o link.

Segundo, elas travam menos do que parecem travar. Usar stubs nos retornos das ferramentas trava o ambiente; o lado do modelo continua não determinístico⁵. Então isso transforma “duas variáveis se mexendo” em “uma variável se mexendo” — o que é valioso, mas não é o tipo de reprodução em que “a mesma entrada tem de dar a mesma saída”. Não trate como garantia, trate como redução de ruído.

Que problemas valem esse fluxo

Percorrer as cinco etapas tem um custo: estreitar exige ler logs, reexecutar exige montar uma simulação, martelar um componente significa dezenas de execuções. Uma divisão grosseira, mas que funciona:

• Tremidas de baixa frequência e inofensivas — tipo aquela vez em que ele chamou a busca uma vez a mais, mas o resultado saiu certo assim mesmo. Registre e acumule. Cada ocorrência isolada não vale investigação; depois que você juntar uma dúzia, muitas vezes dá para ver um padrão comum, e investigar uma vez nesse ponto é bem mais eficiente.
• Alto impacto — deu uma resposta factualmente errada, modificou um arquivo em que não deveria ter tocado, travou sem retornar. Não importa quão baixa seja a frequência, abra um caso. Uma ocorrência já é cara o bastante.
• Recorrente — o mesmo formato de falha aparece pela terceira vez, o que significa que não é sorte, é estrutural. Abra um caso.

A frase da lição 1 é o critério de decisão aqui: por exemplo, usuários relatavam que os agentes “não encontravam informação óbvia”, mas não conseguíamos ver por quê. Os agentes estavam usando consultas de busca ruins? Escolhendo fontes ruins? Batendo em falhas de ferramenta?⁵ Ao decidir não investigar um problema, você está aceitando “não sei qual das causas é” — para tremidas inofensivas tudo bem, para problemas de alto impacto você está apostando.

Esta lição ficou no papel até aqui. A lição 6 junta as duas metades na prática: instale uma camada de observabilidade completa no harness do curso 7 e depois pegue um sintoma do tipo “não dá para dizer por quê” e persiga-o até o fim.

Recapitulação

• Hooks são comandos, endpoints HTTP ou prompts de LLM definidos por você que executam automaticamente em pontos específicos do ciclo de vida do Claude Code; quando um evento dispara e um matcher casa, o Claude Code passa um contexto JSON sobre o evento para o seu handler¹.
• Os eventos se dividem em três cadências — uma vez por sessão (SessionStart/SessionEnd), uma vez por turno (UserPromptSubmit/Stop/StopFailure), a cada chamada de ferramenta dentro do loop (PreToolUse/PostToolUse)¹. Fixe a cadência antes de escolher o evento. SessionStart também dispara ao retomar uma sessão¹.
• PreToolUse roda depois que o Claude cria os parâmetros da ferramenta e antes de processar a chamada; PostToolUse dispara depois da execução bem-sucedida da ferramenta, com a entrada carregando tanto tool_input quanto tool_response, o que te dá um registro completo da chamada em um único disparo¹. Omita o matcher ou defina-o como "*" para o um-hook-registra-tudo¹.
• Hooks de comando recebem JSON via stdin e respondem por códigos de saída, stdout e stderr¹; aquele campo de milissegundos de execução exclui o tempo passado em prompts de permissão e no PreToolUse¹, então não o use como tempo de espera do usuário.
• Duas conclusões negativas: o Claude Code remove as variáveis de exportador OTEL_* de todo subprocesso que ele gera (inclusive hooks)¹, então se você quiser emitir telemetria de um hook precisa carregar a sua própria configuração de exportação; o arquivo de transcrição fornecido no payload é escrito de forma assíncrona e pode ainda não incluir as mensagens mais recentes do turno atual quando o hook dispara¹. Hooks de comando executam com todas as suas permissões de usuário, então revise antes de instalar¹.
• Quando os hooks não funcionam, verifique no log de depuração quais hooks casaram, os códigos de saída e a stdout/stderr completas usando --debug-file¹; para contagens de matcher, coloque o nível de log em verbose¹. O id do prompt no payload do hook e o prompt.id dos eventos de telemetria são o mesmo valor, então as duas fontes de dados podem ser alinhadas¹.
• Fluxo de depuração em cinco etapas (arranjo deste curso): filtre eventos por prompt.id para estreitar até este prompt³ → ache a primeira divergência, porque uma etapa falhando muda a trajetória inteira⁵ → reexecute usando prompts e ferramentas idênticos, observando etapa por etapa⁵ → martele o componente suspeito dezenas de vezes para forçar o bug para fora⁵ → depois de corrigir, retome do ponto de falha em vez de reiniciar do começo⁵.
• Técnicas como semente fixa, temperature 0 e reexecução com retornos de ferramenta gravados não têm respaldo em fontes nativas; este curso as apresenta na voz da prática de engenharia: elas travam o lado do ambiente, mas o modelo continua não determinístico⁵, então são redução de ruído, não garantia de reprodução.
• Nem todo problema merece o fluxo completo: registre as tremidas inofensivas de baixa frequência, acumule para achar padrões e investigue depois; abra casos imediatamente para questões de alto impacto ou recorrentes.

>> Lição 6: Mão na massa: instalando uma camada de observabilidade no harness

💻 Exercícios