🛡️ Mods que mudam o fluxo

Todo mod que muda o fluxo começa no mesmo lugar: o evento tool.call. Ele dispara quando o Claude Code está prestes a rodar uma ferramenta (Bash, Edit, Write, Read, uma ferramenta MCP).

Os tipos dizem o que acontece por baixo: next(e) roda os hooks dos outros plugins e depois o núcleo, que é o pedido de permissão e a própria ferramenta. O seu hook fica antes de tudo isso, com três saídas possíveis.

Como ler o desenho: o hook âmbar está antes da permissão. Para cima, { deny } encerra a chamada. Para a direita, next(e) segue o caminho de sempre. Para baixo, { result } responde no lugar da ferramenta: é o único caminho que pula o pedido de permissão, por isso fica pontilhado.

import type { Register } from 'claude-code'

const PROTECTED = /(^|\/)\.env(\.|$)/

export const register: Register = on => {
  on('tool.call', { tool: 'Edit' }, ($, e, next) =>
    PROTECTED.test(e.file_path)
      ? { deny: `${$.plugin.name}: ${e.file_path} is protected here.` }
      : next(e),
  )

  on('tool.call', { tool: 'Bash' }, async ($, e, next) => {
    const ran = await next({ ...e, command: e.command.trim() })
    const hasFailed = ran.deny === undefined && ran.isError === true

    $.ui.status(hasFailed ? `failed: ${e.command.slice(0, 40)}` : undefined)

    return ran
  })
}

O texto do deny não é para você: é para o modelo. Ele lê a recusa como resultado de erro da ferramenta e decide o próximo passo com base nela.

Um "negado" seco faz o modelo tentar de novo por outro caminho: find -delete no lugar de rm, um script Python que apaga. Um bom motivo diz quem barrou, o que teria acontecido e o que fazer agora.

    // Cancelar ou texto livre: não roda.
    return {
      deny: `freio-de-mao: o usuário cancelou. O comando faria: ${resumo}. Não tente apagar por outro caminho; pergunte ao usuário como seguir.`,
    }

Entre deixar e negar existe perguntar. $.ui.ask(pergunta, opções) abre o mesmo diálogo que o Claude usa para fazer perguntas e devolve o rótulo escolhido, ou o texto livre digitado em "Other".

Segundo os tipos, a chamada rejeita quando a pessoa dispensa o diálogo e numa execução -p, onde não há ninguém para perguntar. É por isso que todo ui.ask do kit INEMA termina em .catch.

  const resposta = await $.ui
    .ask(`Isso usa serviço pago (${achado.nome}). Autoriza agora?`, {
      header: 'API paga',
      options: [NEGAR, SO_ESTA, POR_HORA],
    })
    .catch(() => undefined)
  if (resposta === undefined) {
    return {
      deny:
        `vigia-api: "${achado.nome}" usa serviço pago e não há ninguém na tela para autorizar. ` +
        'Não tente por outro caminho: peça autorização ao usuário em texto, dizendo qual serviço e para quê. ' +
        `Ele pode liberar com /vigia autorizar ${achado.padrao.trim()}`,
    }
  }

Mudar o fluxo não é só barrar. O Rafa quer que as buscas do subagente Explore rodem num modelo menor, para poupar cota. Os dois kits resolvem isso em pontos diferentes da cadeia.

O roteador-subagente do inema-mods age uma vez, quando o subagente nasce, no evento agent.spawn. O model-router do kit da Prompt Advisers age passo a passo, no stream turn.step.

  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: o agent.spawn é mais simples e basta para "este tipo de subagente usa aquele modelo". O turn.step dá controle fino (até passos do turno principal), mas exige tratar stream, assunto do módulo 2.1.

A pessoa já tem regras: o que o Claude pode rodar sem perguntar, o que sempre pede aprovação, hooks clássicos de PreToolUse. Um mod de controle deve somar a essas regras, nunca contorná-las.

A regra prática sai do desenho do tópico 1: para ferramentas do próprio Claude Code, termine sempre em next(e) ou em { deny }. Uma reescrita (next({ ...e, command: novo })) também passa pela permissão, já com o comando novo.

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

O freio-de-mao junta tudo deste módulo. Antes de um Bash que apaga ou descarta (rm -rf, git reset --hard, git clean, push --force), ele mede o estrago sem apagar e pergunta: Cancelar, Mandar para a lixeira, Fazer backup e prosseguir, ou Prosseguir.

O hook inteiro tem umas 60 linhas em mods/freio-de-mao/hooks/register.tsx. As funções que recebem $ (medir, registrar, fazerBackup) ficam no topo do arquivo, fora do register (pegadinha 1).

Como ler o desenho: o caminho azul só chega ao ui.ask quando há algo a perder. Das quatro saídas, só uma (vermelha) nega; as outras terminam em next, então a permissão da pessoa ainda decide depois.

claude plugin validate mods/freio-de-mao
claude plugin test mods/freio-de-mao

Leia mods/freio-de-mao/hooks/register.tsx e mods/freio-de-mao/tests/freio.test.ts. Para cada saída do hook de tool.call (deny ou next), me diga qual teste a cobre. Não rode nem instale nada.