O que são lifecycle hooks e por que 54+ deles importam numa codebase grande?

Fala aí, beleza? Um harness de agente apareceu anunciando "54+ lifecycle hooks" e o número virou argumento antes de alguém explicar o que exatamente está sendo contado ali

E o problema nem é o número, é a unidade

Lifecycle hook é conceito velho de framework de front-end, coisa que quem mexe com componente usa faz tempo e nem acha exótico. O que é novo é ver esse mesmo conceito no contexto de agente de código, onde a "vida" que tem ciclo não é um componente na tela, é a sua sessão com o agente

Então bora na ordem certa: primeiro o conceito, depois a discussão de volume

De onde vem esse conceito: o ciclo de vida no front-end

No vídeo da aula 07 do curso de Vue eu explico lifecycle hooks do jeito mais simples que consegui: são eventos que te dão acesso a momentos específicos da execução do componente, e em cada um desses momentos você pode disparar código seu

O componente nasce, aparece na tela, atualiza quando o dado muda e some quando não é mais necessário

Esses momentos acontecem com ou sem você. O hook não inventa o evento, ele só te dá um lugar pra entrar num momento que já ia acontecer de qualquer forma

O exemplo clássico que eu dou na aula é o loader: mostra o carregando assim que o componente é criado, tira quando o dado chega. E tem hook que se ativa antes da criação, bom justamente pra buscar dado do backend antes da tela aparecer vazia

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 116 aulas
• 4 projetos
• 9h 23min

Conhecer formação

Na prática eu montei um componente separado só pro teste (isolar do resto da aplicação ajuda MUITO a entender o recurso), com uma chave de nome no data e um valor placeholder interpolado no template

Aí dentro do hook de componente criado eu simplesmente reatribuo a propriedade, atribuição comum de JavaScript, nada de mágica

O detalhe engraçado: com hot reload a troca é tão rápida que você não vê nada na tela, mas o dado muda de verdade

Pra provar que os eventos acontecem em sequência eu coloquei um segundo hook, posterior ao de criação, trocando o valor de novo. Continuou imperceptível

Solução: setTimeout dentro dos hooks. 1 segundo no primeiro, 2 segundos no seguinte, só pra separar as duas trocas na tela

E aí veio a lição que eu não tinha planejado: o valor atrasado por timeout apareceu por último, fora da ordem dos hooks, e eu tive que ajustar os tempos até a sequência ficar na ordem que eu queria demonstrar

Dá pra fazer tudo isso no JavaScript puro, requisição na mão e DOM na mão? Dá. Mas quando o próprio framework te entrega o ponto de entrada, usar o recurso dele sai mais limpo

A conclusão de lá vale aqui: é combinando vários hooks (carrega dado na criação, ajusta depois da montagem) que a aplicação parece natural pra quem está acessando

O que é o ciclo de vida de um agente de código

Agora troca o componente pela sessão

Se você usa agent de código todo dia, o ciclo é esse: a sessão começa, você manda um prompt, o modelo decide chamar uma ferramenta, a ferramenta responde, o modelo chama outra, e em algum momento o turno para

Cada uma dessas transições é um ponto onde alguém poderia entrar

A documentação de hooks do Claude Code lista os eventos: SessionStart, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification, SubagentStart, SubagentStop, Stop e StopFailure

Onze eventos nomeados. Repara que não é uma lista decorativa, cada nome ali é um momento real do loop

Dois detalhes que mudam a forma de pensar:

O PreToolUse roda antes da execução da chamada de ferramenta, e pode bloquear a chamada. Ou seja, existe um ponto no ciclo onde a ação ainda não aconteceu e ainda dá pra impedir

E a cadência: PreToolUse e PostToolUse disparam a cada chamada de ferramenta dentro do loop do agente. Não é uma vez por sessão, é toda vez

O SessionStart também tem um comportamento que muita gente não espera: ele roda de novo quando você retoma a sessão, com o campo source valendo resume (ou fork, quando se usa --fork-session). Isso abre a porta pra reinjetar contexto na volta em vez de recomeçar do zero

No Codex, os hooks são apresentados como framework de extensibilidade pra injetar scripts próprios dentro do loop do agente. Os exemplos da própria documentação: mandar o chat pra logging, bloquear vazamento de chave de API e rodar validação quando o turno termina

Lá o SessionStart chega com campos como source, session_id, transcript_path, cwd, hook_event_name e model, e o source indica se a origem foi startup, resume ou clear

E tem um comportamento no Stop que é quase contraintuitivo: a decisão block não rejeita o turno. Ela manda o Codex continuar e cria automaticamente um prompt de continuação usando o motivo informado como texto desse novo prompt

Sacou o paralelo com o front-end? Mesmo conceito, outro palco 😀

11 eventos x 54+ hooks: por que os números não se comparam direto

Aqui é onde o marketing costuma escorregar

A leitura honesta é essa: evento é onde dá pra entrar, hook é o que alguém já escreveu pra rodar ali

Um produto com 11 eventos documentados não tem "menos recurso" que um harness com 54+ hooks. São grandezas de natureza diferente, não é placar

E olha que nem entre as fontes do próprio OmO os números batem: o README fala em 54+ (61 com Team Mode), a análise do DeepWiki fala em 58 slots com uns 50 a 51 ativos por padrão. Eu prefiro te mostrar as duas contagens como cada fonte declara do que inventar um total único e sair repetindo por aí

O que exatamente o OmO conta como hook

O oh-my-openagent, também chamado de omo, é mantido no GitHub pelo usuário code-yeongyu, no repositório code-yeongyu/oh-my-openagent

O posicionamento oficial dele é bem direto: agent harness para codebases complexas, mirando Codex e OpenCode

A distribuição é em três edições:

• Ultimate Edition: plugin pro OpenCode, com os 54+ hooks, 11 agentes, 5 MCPs embutidos e Team Mode
• Light Edition: pro Codex CLI, com os componentes portáveis que cabem no sistema de plugins do Codex
• Senpi Edition: standalone, em beta

Essa separação importa mais do que parece. "54+ hooks" é da Ultimate, que é plugin do OpenCode. Não é uma promessa genérica que vale em qualquer agente que você já usa

Os 5 MCPs embutidos incluem websearch (Exa), context7 (documentação) e grep_app (busca no GitHub), injetados em runtime

E tem um detalhe que eu acho o mais saudável do projeto: hooks individuais podem ser desligados globalmente pelo array disabled_hooks no arquivo oh-my-opencode.jsonc, o mesmo mecanismo usado pra desabilitar comandos, skills, MCPs, tools e agentes

Ou seja, o próprio projeto assume que nem todo hook serve pra todo mundo

Por que volume de hooks importa numa codebase grande

Agora o argumento de verdade

Entre os hooks de guarda do OmO estão team-tool-gating, write-existing-file-guard, bash-file-read-guard, webfetch-redirect-guard, prometheus-md-only, rules-injector e tool-pair-validator. A documentação diz que eles existem pra proteger segurança, permissões ou a correção do protocolo do provedor

Pelos nomes, dá pra sacar o tipo de dor que cada categoria endereça:

• escrita em arquivo que já existe (o clássico do agente sobrescrever coisa que não era pra tocar)
• leitura de arquivo por caminho torto dentro do bash, fugindo do fluxo normal de ferramenta
• webfetch seguindo redirect pra um lugar que você não pediu
• regra do repositório que o agente lembra no começo e esquece no meio da sessão
• par de chamadas de ferramenta fora do protocolo, quebrando o contrato com o provedor
• quem pode usar qual ferramenta quando o modo de time está ligado

Em projeto pequeno, cada um desses erros é barato. Você abre o diff, vê a besteira, desfaz e segue a vida

Em codebase grande é outro filme. O erro chega tarde, chega longe do lugar onde nasceu, e às vezes chega em forma de PR aprovado

É a mesma lógica de quando você precisa organizar times grandes com permissões em qualquer ferramenta compartilhada: o custo de um deslize não é local, ele se espalha

E o rules-injector toca num ponto que dói em qualquer equipe: regra combinada que ninguém relembra no meio do trabalho vira regra que não existe. Quem já sofreu com colaboração em automações em equipe conhece bem esse padrão

Então o argumento pró-volume é esse: cada guard é uma checagem que você não precisa fazer com o olho

Mas cabe o contrapeso honesto: volume também é superfície

Cada hook é código rodando dentro do seu loop, com comportamento que você precisa entender quando algo der errado. O disabled_hooks existe justamente porque nem todo hook serve pra todo projeto, e um harness que não te deixa desligar peça é um harness que você não controla

O que isso muda na sua rotina com agente de código

Este post é conceitual, não é tutorial de configuração. E tem um motivo: instrução de um produto não vale pro outro. Menu de um, arquivo de config de outro, evento de um terceiro… misturar isso é receita de você seguir um passo que não existe no seu agente

O que dá pra levar daqui:

Quando aparecer um anúncio de "54+ hooks", faz três perguntas antes de qualquer coisa. Em qual produto isso roda? Em qual edição? E o que cada camada cobre?

No caso do OmO as respostas estão na mesa: Ultimate é plugin do OpenCode, Light é pro Codex CLI, Senpi é standalone em beta, e as camadas são Session, Tool Guard, Transform, Continuation e Skill

A outra coisa é olhar pra dentro do que você já usa hoje. Os eventos de lifecycle são documentados tanto no Claude Code quanto no Codex, então o ciclo do seu agente não é caixa preta

Só de saber que existe um momento antes da chamada de ferramenta (e que ele pode barrar a chamada), e que a retomada de sessão é sinalizada pelo campo source, você já lê os comportamentos do agente com outro olho

Conclusão

Lifecycle hook é ponto de entrada no ciclo de vida, e só isso

No componente, o ciclo é criar, montar, atualizar, destruir. No agente, é sessão que começa, prompt que entra, ferramenta que roda, turno que para. O evento acontece de qualquer jeito, o hook só te dá lugar pra estar lá

Por isso o número sozinho não diz nada. 54+, 61 com Team Mode, 58 slots com uns 50 a 51 ativos por padrão… nada disso significa coisa alguma até você saber quais momentos aquilo cobre

Próximo passo que eu sugiro: abre a documentação de hooks do agente que você já usa, olha a lista de eventos nomeados e marca quais fazem sentido pro seu projeto. É trabalho de dez minutos e vale mais do que sair atrás de harness com contagem alta

até o próximo post! 😀