← Voltar ao curso
Nível 3 — Automação e escala · Módulo 3.2 — Hooks: da recomendação à garantia

3.2.2 · Os eventos que importam

5 min de vídeo TEC BASIS

Objetivo: ao final, o consultor escolhe o evento certo para cada necessidade entre os 30 disponíveis, e sabe qual é o único caminho para reinjetar contexto depois de uma compactação.

O que você precisa levar desta aula

  1. Existem 30 eventos de hook. Oito resolvem quase todo caso de projeto; a pergunta que escolhe o evento é sempre "em que momento do ciclo de vida eu preciso interferir?".
  2. PreToolUse é o único que impede (roda antes da ferramenta). PostToolUse reage depois do sucesso. Stop permite recusar o encerramento do turno.
  3. Para reinjetar contexto depois de uma compactação, o caminho é SessionStart com matcher compact — PostCompact existe, mas serve para detectar o fim da compactação (log, limpeza) e não consegue injetar contexto.

Os oito que resolvem quase tudo

Evento Quando dispara Para que serve na prática
PreToolUse Antes de uma chamada de ferramenta Impedir ou reescrever a chamada — o primitivo de aplicação de política (aula 3.2.3)
PostToolUse Depois do sucesso da ferramenta Formatação, lint, type-check; reescrever a saída antes de o Claude ver
Stop O Claude quer encerrar o turno Recusar o encerramento — portão de teste (módulo 3.4)
SubagentStop Um subagente quer encerrar O mesmo portão, na borda da delegação
SessionStart Início de sessão, e também em compact, resume e fork Injetar contexto — inclusive reinjetar depois de compactar (aula 3.2.5)
PreCompact Antes da compactação Salvar estado que a compactação vai descartar
PostCompact Depois da compactação Detectar que compactou: log, limpeza. Não injeta contexto
InstructionsLoaded Quando arquivos de instrução carregam Auditar o que entrou no contexto e quando — resolve "por que a regra não pegou?"

Os outros 22, por categoria

Não precisa memorizar. Precisa saber que existem, para procurar antes de improvisar:

Categoria Eventos
Prompt UserPromptSubmit, UserPromptExpansion
Permissão PermissionRequest, PermissionDenied
Falha de ferramenta e lote PostToolUseFailure, PostToolBatch
Subagente e tarefa SubagentStart, TaskCreated, TaskCompleted, TeammateIdle
Encerramento StopFailure, SessionEnd
Ambiente e arquivo FileChanged, CwdChanged, ConfigChange
Worktree (aula 2.6.4) WorktreeCreate, WorktreeRemove
Interface e setup Notification, MessageDisplay, Setup
Elicitação Elicitation, ElicitationResult

A pegadinha da compactação, em detalhe

O erro é natural: existe um evento chamado PostCompact, o objetivo é fazer algo depois de compactar, então parece obviamente o evento certo. Não é.

PostCompact SessionStart + matcher compact
Dispara depois de compactar Sim Sim
Consegue injetar contexto Não — só mostra stderr Sim — o stdout dele entra no contexto
Uso certo Log, limpeza, telemetria Reinjetar o estado do trabalho

O motivo técnico é a aula 3.2.4: SessionStart é um dos três eventos cujo stdout puro vai para o contexto. PostCompact não é um deles.

Bônus: SessionStart também dispara em resume e em fork, então o mesmo hook reexecuta e atualiza informação que envelhece — carimbo de data, SHA do commit atual.

Regra Wayon O hook de política de ambiente do Meridiano é PreToolUse — é o único que impede antes de acontecer. Política implementada em PostToolUse não é política: o comando já rodou em QAS quando o hook dispara. Se a regra é "não pode acontecer", só PreToolUse serve.

📖 Referência de eventos de hook

Quiz — 5 questões

1.Você precisa garantir que nenhum comando toque o ambiente QAS do MRD, em nenhuma circunstância. Qual evento?
  • a)PreToolUse

    Correto. É o único que roda antes da ferramenta e consegue impedir a execução.

  • b)PostToolUse

    Dispara depois do sucesso — quando ele roda, o comando já tocou o QAS. Serve para reagir, não para impedir.

  • c)PermissionDenied

    Dispara após uma negação já ter ocorrido; é observação do que aconteceu, não o portão que decide.

Ver resposta e por quê
✅a) Correto. É o único que roda antes da ferramenta e consegue impedir a execução.
❌b) Dispara depois do sucesso — quando ele roda, o comando já tocou o QAS. Serve para reagir, não para impedir.
❌c) Dispara após uma negação já ter ocorrido; é observação do que aconteceu, não o portão que decide.
2.Depois de cada edição em arquivo .cds do projeto CAP, você quer rodar o linter automaticamente.
  • a)PreToolUse, para preparar o ambiente antes da edição

    Rodaria antes da edição existir, então não há o que lintar ainda.

  • b)PostToolUse

    Correto. Dispara depois do sucesso da ferramenta — é o lugar canônico de formatação, lint e type-check.

  • c)FileChanged

    Existe e reage a mudança de arquivo, mas o gancho ligado ao ciclo da ferramenta que o Claude acabou de usar é o PostToolUse.

Ver resposta e por quê
❌a) Rodaria antes da edição existir, então não há o que lintar ainda.
✅b) Correto. Dispara depois do sucesso da ferramenta — é o lugar canônico de formatação, lint e type-check.
❌c) Existe e reage a mudança de arquivo, mas o gancho ligado ao ciclo da ferramenta que o Claude acabou de usar é o PostToolUse.
3.Você quer que o Claude não consiga encerrar o turno enquanto o teste de regressão do RICEFW estiver falhando.
  • a)SessionEnd, que dispara ao fim da sessão

    Dispara no encerramento da sessão inteira e não bloqueia — tarde demais e sem poder de recusa.

  • b)PostToolUse, verificando o resultado do último comando

    Reage a uma chamada de ferramenta específica, não ao momento em que o Claude decide que terminou.

  • c)Stop, que permite recusar o encerramento e devolver o motivo

    Correto. É o portão de teste que o módulo 3.4 constrói.

Ver resposta e por quê
❌a) Dispara no encerramento da sessão inteira e não bloqueia — tarde demais e sem poder de recusa.
❌b) Reage a uma chamada de ferramenta específica, não ao momento em que o Claude decide que terminou.
✅c) Correto. É o portão de teste que o módulo 3.4 constrói.
4.Uma regra com paths: do módulo 2.3.6 não parece estar sendo aplicada, e você quer confirmar se ela entrou no contexto e quando.
  • a)SessionStart, que lista tudo que carrega no início

    Injeta contexto no início, mas não é o evento que relata quais arquivos de instrução foram carregados.

  • b)InstructionsLoaded

    Correto. É o evento feito para auditar quais arquivos de instrução entraram no contexto, quando e por quê.

  • c)ConfigChange, que reage a mudança de configuração

    Reage a alteração de configuração, não ao carregamento de instrução numa sessão.

Ver resposta e por quê
❌a) Injeta contexto no início, mas não é o evento que relata quais arquivos de instrução foram carregados.
✅b) Correto. É o evento feito para auditar quais arquivos de instrução entraram no contexto, quando e por quê.
❌c) Reage a alteração de configuração, não ao carregamento de instrução numa sessão.
5.Depois de uma compactação numa sessão longa do Meridiano, você quer reimprimir no contexto o resumo dos arquivos em trabalho. Qual é o caminho correto? ---
  • a)PostCompact, que dispara exatamente depois da compactação

    Dispara no momento certo, mas não consegue injetar contexto — só mostra stderr. Serve para log e limpeza.

  • b)PreCompact, salvando o estado antes de a compactação apagar

    Bom para salvar o estado, mas não reinjeta nada depois: quando a sessão volta, é preciso outro evento para escrever no contexto.

  • c)SessionStart com matcher compact

    Correto. É o único caminho de reinjeção, porque o stdout de SessionStart vai direto para o contexto.

Ver resposta e por quê
❌a) Dispara no momento certo, mas não consegue injetar contexto — só mostra stderr. Serve para log e limpeza.
❌b) Bom para salvar o estado, mas não reinjeta nada depois: quando a sessão volta, é preciso outro evento para escrever no contexto.
✅c) Correto. É o único caminho de reinjeção, porque o stdout de SessionStart vai direto para o contexto.