Quais são os principais eventos de hook?

O início da sessão, o envio de um prompt, o momento antes de uma ferramenta rodar, o momento depois de ela ter sucesso, e o fim da resposta do agente. Esses cobrem a maioria dos casos úteis. Há muitos outros eventos avançados, mas os principais já bastam para começar.

Qual a diferença entre eventos de antes e de depois?

Um evento de antes dispara com a ação ainda por vir, então pode até bloqueá-la, ideal para prevenir. Um evento de depois dispara com a ação concluída, então reage ao resultado, como rodar o formatador ou registrar o que foi feito. Antes previne; depois responde.

Qual evento uso para uma regra de segurança?

O evento de antes de uma ferramenta. Como ele acontece antes de a ferramenta rodar, você pode inspecionar o que o agente vai fazer e, se for algo proibido, impedir que aconteça. É o evento preferido para bloquear comandos perigosos ou proteger arquivos.

Preciso conhecer todos os eventos?

Não. Domine os principais, início, envio de prompt, antes e depois de ferramentas, e fim, que já cobrem a maioria das automações. Os muitos eventos específicos atendem a casos avançados; quando precisar de um, a documentação oficial lista todos com o momento exato em que disparam.

Como escolho o evento certo?

Pergunte-se quando você quer que a automação aconteça. Sempre que a sessão abrir? Evento de início. Antes de algo perigoso? Evento de antes de uma ferramenta. Depois de uma mudança? Evento de depois. O evento é a expressão do momento em que a regra deve valer.

Módulo 12 - Hooks

Os eventos do ciclo de vida

8 min de leitura · por Cesar Gargiulo, revisado pela equipe ValorFinal e GuardiaSec · Atualizado em 13/07/2026

O que você vai aprender

Conhecer os principais eventos do ciclo de vida.
Saber quando cada evento dispara.
Distinguir eventos que podem bloquear dos que não.
Escolher o evento certo para cada automação.

O ciclo de vida de uma sessão

Um hook precisa de um gatilho, e esse gatilho é um evento. O Claude Code marca vários momentos do ciclo de vida de uma sessão como eventos aos quais você pode ligar hooks. Vale conhecer os principais, que já cobrem a maioria dos casos úteis. Uma sessão começa: esse é o evento de início, bom para preparar o ambiente ou carregar contexto. Você envia um prompt: esse é o evento de envio, que dispara antes de o agente processar o seu pedido. O agente vai usar uma ferramenta: há um evento antes e um evento depois de cada uso. E o agente termina de responder: esse é o evento de fim. Do início ao fim, o ciclo tem pontos de encaixe.

Os eventos mais usados no dia a dia giram em torno das ferramentas, porque é ali que o agente age. O evento de antes de uma ferramenta dispara no instante em que o agente decide usar uma ferramenta, mas antes de ela rodar. O evento de depois dispara quando a ferramenta terminou com sucesso. Essa dupla, antes e depois, é a mais poderosa, porque cobre os dois momentos em que você mais quer intervir: prevenir uma ação indesejada antes que aconteça, ou reagir a uma ação que aconteceu. A maioria das automações úteis de hook usa um desses dois eventos.

Antes previne, depois reage

A distinção entre eventos de antes e de depois define o tipo de automação que você pode fazer. Um evento de antes acontece com a ação ainda por vir, o que dá um poder especial: além de reagir, ele pode BLOQUEAR a ação. É por isso que o evento de antes de uma ferramenta é o preferido para regras de segurança: você inspeciona o que o agente está prestes a fazer e, se for algo proibido, impede que aconteça. Já um evento de depois acontece com a ação concluída, então ele não bloqueia, mas reage: rodar o formatador depois de uma edição, registrar o que foi feito, disparar uma verificação. Antes é para prevenir; depois é para responder.

Evento	Quando dispara	Serve para
Início da sessão	Ao abrir ou retomar	Preparar o ambiente, carregar contexto
Envio de prompt	Antes de processar o seu pedido	Validar ou complementar o pedido
Antes de uma ferramenta	Antes de a ferramenta rodar	Prevenir e bloquear ações indesejadas
Depois de uma ferramenta	Após a ferramenta ter sucesso	Reagir: formatar, registrar, verificar
Fim da resposta	Quando o agente termina	Fechar tarefas, notificar, checar

Os principais eventos e para que servem. Antes previne (pode bloquear); depois reage.

🎮 Jogo da aula

Antes ou depois?

Para cada automação, classifique se ela deve rodar num evento de ANTES (previne) ou de DEPOIS (reage).

Além desses principais, o Claude Code tem muitos outros eventos mais específicos, ligados a coisas como o fim de um subagente, a compactação do contexto, notificações e mudanças de configuração. Você não precisa conhecer todos para começar; eles atendem a casos avançados e específicos. O importante agora é dominar os principais, início, envio de prompt, antes e depois de ferramentas, e fim, porque com eles você já cobre a esmagadora maioria das automações úteis. Quando surgir uma necessidade que os principais não atendem, a documentação oficial lista todos os eventos, e você encontra o momento exato para a sua automação mais fina.

Escolher o momento certo da automação

Escolher o evento certo é escolher o momento em que a sua automação faz sentido. A pergunta a se fazer é: quando eu quero que isso aconteça? Se a resposta é sempre que uma sessão começar, use o evento de início. Se é antes de o agente fazer algo perigoso, use o evento de antes de uma ferramenta. Se é depois que ele mudou um arquivo, use o de depois. O evento não é um detalhe técnico; é a expressão do momento em que a regra deve valer. Definir bem esse momento é metade de configurar um bom hook, e a outra metade é ligar o comando a ele, tema da próxima aula.

Com os eventos entendidos, você tem o vocabulário para saber onde encaixar cada automação. A próxima aula mostra o lado prático: como configurar um hook de verdade, ligando um evento a um comando. Você vai ver que a configuração vive nos mesmos arquivos de ajustes que já conhece, e que a estrutura, embora tenha algumas partes, é lógica quando você entende que ela só diz três coisas: em qual evento, para quais casos e qual comando rodar. Com isso, a automação determinística deixa de ser um conceito e vira algo que você configura e usa.

Teste rápido

Qual evento de hook permite BLOQUEAR uma ação antes que ela aconteça?

Perguntas frequentes

Quais são os principais eventos de hook?: O início da sessão, o envio de um prompt, o momento antes de uma ferramenta rodar, o momento depois de ela ter sucesso, e o fim da resposta do agente. Esses cobrem a maioria dos casos úteis. Há muitos outros eventos avançados, mas os principais já bastam para começar.
Qual a diferença entre eventos de antes e de depois?: Um evento de antes dispara com a ação ainda por vir, então pode até bloqueá-la, ideal para prevenir. Um evento de depois dispara com a ação concluída, então reage ao resultado, como rodar o formatador ou registrar o que foi feito. Antes previne; depois responde.
Qual evento uso para uma regra de segurança?: O evento de antes de uma ferramenta. Como ele acontece antes de a ferramenta rodar, você pode inspecionar o que o agente vai fazer e, se for algo proibido, impedir que aconteça. É o evento preferido para bloquear comandos perigosos ou proteger arquivos.
Preciso conhecer todos os eventos?: Não. Domine os principais, início, envio de prompt, antes e depois de ferramentas, e fim, que já cobrem a maioria das automações. Os muitos eventos específicos atendem a casos avançados; quando precisar de um, a documentação oficial lista todos com o momento exato em que disparam.
Como escolho o evento certo?: Pergunte-se quando você quer que a automação aconteça. Sempre que a sessão abrir? Evento de início. Antes de algo perigoso? Evento de antes de uma ferramenta. Depois de uma mudança? Evento de depois. O evento é a expressão do momento em que a regra deve valer.

Fontes

Seu progresso fica salvo neste aparelho. Assinantes sincronizam entre os aparelhos.

← O que é um hook Concluir e avançar →