🗺️ O mapa de eventos

O arquivo de tipos lista mais de cem eventos. Parece muito até você notar o padrão: todo nome é noun.ação. O noun diz de que parte da sessão se trata. A ação diz o que aconteceu.

Então a primeira pergunta nunca é "qual evento?". É "de que parte?". Ferramenta é tool.*. Tela é ui.*. O que você digitou é prompt.*. Achou o noun, a lista encolhe para meia dúzia de nomes.

O que olhar na tabela: nove nouns cobrem quase tudo o que um mod faz. Os outros (agent, skill, telemetry, config...) aparecem quando você precisar deles, e seguem a mesma regra de nome.

O Rafa digita "corrija o teste que quebrou" e aperta Enter. Até o Claude responder, cinco eventos passam pela cadeia, sempre na mesma ordem. Saber essa ordem é saber onde pendurar cada coisa.

O miolo se repete: o modelo responde um pedaço (turn.step), pede uma ferramenta (tool.call), lê o resultado e responde de novo. Um turno de verdade dá várias voltas nesse laço antes de terminar.

Como ler o desenho: leia da esquerda para a direita. Os dois blocos azuis formam o laço: cada pedido de ferramenta gera um tool.call, e o resultado volta para o modelo num novo turn.step. Quando o modelo para de pedir ferramentas, o turno termina.

Você já viu o matcher no módulo 1.1: o objeto entre o nome do evento e o hook. Agora a regra completa. O matcher é um pedaço do próprio e: o hook só roda quando os campos que você escreveu batem com os do evento.

Por isso o campo muda de evento para evento. No tool.call, o e tem tool. No command.run, tem command. No ui.render, tem component. O matcher usa os mesmos nomes.

// templates/starter-mod/hooks/starter.mjs
on("tool.call", { tool: "Read" }, hook)

// inema-mods/mods/recibo-sessao/hooks/register.tsx
on('command.run', { command: 'recibo' }, hook)
on('ui.render', { component: 'Pane', requestId: PAINEL }, hook)

// plugin-authoring/examples/band.tsx
on('ui.render', { component: 'AbovePrompt' }, hook)

O que olhar na tabela: as quatro formas vêm do comentário do tipo Matcher nos tipos. Não existe startsWith nem outra função: para prefixo, use a expressão regular.

Dois eventos não chegam inteiros: turn.step (a resposta do modelo, pedaço por pedaço) e process.spawn (a saída de um programa, pedaço por pedaço). Neles o hook tem outra forma.

Em vez de async ($, e, next) =>, é um gerador assíncrono: async function* ($, e, next). É a única forma que carrega nesses dois eventos. Uma função comum dá erro de tipo, mesmo que só devolva next(e).

// turn.step é um fluxo: o hook é um gerador assíncrono que repassa tudo e,
// no fim, lê o resultado (modelo, esforço e ferramentas pedidas nesse passo).
on('turn.step', async function* ($, e, next) {
  const r = yield* next(e)
  if (e.agentId !== undefined) return r
  const modelo = r.usage?.model ?? e.model
  const esforco = esforcoEmTexto(e.effort)
  const usadas = r.toolUses.map(u => tipoDaFerramenta(u.name))
  // ... grava modelo, esforço e ferramentas no estado ...
  return r
})

Como ler o desenho: cada barrinha é um pedaço do stream. Na primeira linha os pedaços saem iguais. Na segunda saem de outra cor: o hook mudou cada um. Na terceira, nada vem de baixo: o hook inventa os próprios pedaços e responde sozinho.

Os hooks clássicos do settings.json têm 33 eventos: Stop, PreToolUse, FileChanged, PreCompact... Um mod enxerga todos com o prefixo classic., mesmo que nenhum hook clássico esteja configurado.

O e é exatamente o JSON que um hook clássico receberia na entrada padrão, com transcript_path, cwd e os outros campos de base. A exceção é classic.PreToolUse: ali o e é o mesmo envelope do tool.call.

import type { Register } from 'claude-code'

export const register: Register = (on, options) => {
  on('classic.Stop', async ($, e, next) => {
    // e é o JSON do hook Stop: stop_hook_active, last_assistant_message...
    if (!e.stop_hook_active) $.ui.toast('O Claude terminou. Confira o resultado.')
    return next(e)
  })
}

O que olhar na tabela: quando existe evento nativo, prefira ele: o e é mais rico e o resultado é mais fácil de usar. O clássico serve para o que só os hooks de settings anunciam.

A lista deste módulo vale para a 2.1.289. A da sua máquina pode ser outra. A autoridade é um arquivo que o próprio Claude Code escreve dentro da pasta do mod, a cada carga e recarga: .claude-plugin/types/claude-code/index.d.ts.

Ele tem cerca de 20 mil linhas. Ninguém lê de cima a baixo. Você busca o nome do evento entre aspas seguido de dois-pontos, por exemplo 'turn.step':, no editor ou com grep. O comentário logo acima diz quando o evento dispara, o que next(e) devolve e o que você pode devolver.

ls .claude-plugin/types/

Leia .claude-plugin/types/claude-code/index.d.ts e me mostre o comentário
do evento 'turn.complete': quando dispara, o que next(e) devolve e o que
um hook pode devolver no lugar. Não edite nada.

Outro atalho: o claude plugin validate lista os eventos que o seu mod pendura, com o matcher entre chaves. É a prova de que o engine leu o que você quis dizer.

  ❯ ./starter.mjs hooks: session.start, tool.call{tool=Read}, command.run{command=readcount}
  ❯ ./starter.mjs calls: $.command.register

✔ Validation passed