⛓️ A cadeia: next, reescrever e responder

O Rafa tem três mods ligados, e os três penduram hook em tool.call. Quando o Claude pede um Edit, os três rodam. Não lado a lado: um dentro do outro, como camadas de cebola.

O evento entra pela camada de fora. Cada hook chama next(e) para entrar na camada seguinte. No miolo está o comportamento do próprio Claude Code. O resultado volta pelo mesmo caminho, de dentro para fora, e cada hook pode olhar para ele na volta.

Como ler o desenho: quanto mais de fora, mais autoridade. Um plugin gerenciado pela empresa (prepend) vê o evento antes do seu mod e pode encerrar a cadeia ali. O seu mod vê o evento antes dos plugins de fábrica e do engine. Na volta, a ordem se inverte.

A maioria dos hooks só observa. Anota, conta, desenha, e devolve o que veio de baixo sem mexer. Existem dois jeitos, e a diferença é quando o hook olha.

Antes do next, ele vê a intenção: o Claude quer editar este arquivo. Depois do await next(e), ele vê o que aconteceu: editou, falhou ou foi negado. Os tipos chamam isso de escrever o hook "em pós-ordem".

// plugin-authoring/examples/band.tsx — olha ANTES e passa
on('prompt.submit', async ($, e, next) => {
  startedAt = await $.clock.now()
  tools = 0

  return next(e)
})

// inema-mods/mods/recibo-sessao/hooks/register.tsx — olha DEPOIS
on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
  const ran = await next(e)
  if (ran.deny === undefined && ran.isError !== true) await registrar($, e.file_path, 'editado')
  return ran
})

O e que você recebe é congelado: não dá para mudar um campo dele. Para mudar o que as camadas de baixo veem, você chama next com uma cópia alterada: next({ ...e, campo: novo }).

Mas só dentro do que o evento permite. Cada evento diz nos tipos o que pode ser reescrito. Mudar um campo travado faz o hook falhar e ser pulado. Mudar o retorno de um evento que só observa não muda nada.

on('agent.spawn', async ($, e, next) => {
  // Respeita o que foi pedido: modelo explícito, fork (sempre herda) e teammate.
  if (e.model !== undefined || e.fork || e.isTeammate === true) return next(e)
  const alvo = destino(await read($, modo), mapa, e.subagentType)
  if (alvo === undefined) return next(e)
  const r = await next({ ...e, model: alvo })
  const id = r.agentId
  if (id !== undefined) await update($, roteados, x => ({ ...x, [id]: alvo }))
  return r
})

O que olhar na tabela: a última linha é tão importante quanto as outras. Antes de reescrever, confira nos tipos se o evento aceita. Se o comentário diz "Observe", ele não aceita.

Um hook que devolve algo sem chamar next responde no lugar de todo o resto. As camadas de baixo não rodam: nem os outros mods, nem o engine. No tool.call, isso inclui o pedido de permissão e a ferramenta.

É assim que um mod barra uma ação. O guarda-colisao do kit INEMA decide antes de qualquer coisa. Se decidiu barrar, devolve a recusa e acabou.

on('tool.call', { tool: 'Edit' }, async ($, e, next) => {
  const barrar = await decidir($, e.file_path, cfg)
  if (barrar) return barrar          // { deny: '...' } e nada abaixo roda
  const ran = await next(e)
  if (ran.deny === undefined && ran.isError !== true) await marcar($, e.file_path, cfg)
  return ran
})

Hook que lança erro, devolve o que o evento não aceita ou passa do tempo é pulado. O engine chama next(e) por ele e a cadeia segue como se ele não existisse. Para um contador, ótimo. Para uma guarda, péssimo: falhar vira deixar passar.

O conserto é o .catch na própria registração: on(...).catch(handler). Se o hook falhar, o handler roda no lugar dele, com a mesma forma ($, e, next), e a resposta dele vale como a do hook.

on("session.append", ($, e, next) => next({ ...e, message: redact(e.message) }))
  .catch(($, e, next) => next({ ...e, message: placeholderFor(e.message) }))

import type { EngineInterface, Register } from 'claude-code'

// recebe $, então fica no topo do arquivo (pegadinha 1)
async function decidir($: EngineInterface, caminho: string) {
  const fora = !caminho.startsWith(await $.session.cwd())
  return fora ? { deny: 'Fora da pasta do projeto.' } : undefined
}

export const register: Register = (on, options) => {
  on('tool.call', { tool: 'Write' }, async ($, e, next) => {
    const barrar = await decidir($, e.file_path)
    return barrar ?? next(e)
  }).catch(($, e, next) => ({ deny: 'A guarda falhou; escrita barrada por segurança.' }))
}

Cada hook tem 10 segundos do próprio tempo por dispatch. O relógio para enquanto ele espera um next ou uma chamada ao $. Uma cadeia lenta abaixo, ou uma chamada longa ao engine, não gastam o orçamento do seu hook.

Com uma exceção: as esperas do relógio. $.clock.sleep conta. Um hook que dorme em laço para "esperar alguma coisa" paga cada soneca do mesmo orçamento. O tempo que resta está em next.budget.remainingMs.

Como ler o desenho: some só os trechos azuis. Esperar o next ou o engine é de graça. Dormir com o relógio não é. Quem chega na linha vermelha perde a vez: o .catch é chamado, se houver, ou o engine segue sem o hook.

O next.signal é um AbortSignal que dispara quando o dispatch é abandonado: a pessoa interrompeu, um hook acima já respondeu, ou o orçamento acabou. Passe esse sinal adiante, para a espera acabar junto.

await $.clock.sleep(500, { signal: next.signal })