No instante em que o chat abre, o plugin já precisa saber: o Hermes ganha o hook on_session_open

Nove da manhã. Você abre o Hermes Desktop e retoma o trabalho de ontem no mesmo repo. Seu plugin de memória já guarda a conclusão a que você chegou — qual endpoint estava mal configurado desde o início, qual arquivo de teste acabou sendo perda de tempo. Só que ele não faz ideia de que você voltou. Ele só fica sabendo que uma conversa existe quando você digita a primeira mensagem e ela passa pelo modelo.
O outro caso é pior. Você abre a janela, rola duas telas pelo chat de ontem, fecha. O plugin não escuta nada, porque a mensagem nova que ele esperava nunca chega.
Quem escreve plugin costuma reagir do mesmo jeito: faz polling. Acorda a cada poucos segundos, lista o diretório de sessions, olha os horários de modificação. Funciona, mas é feio — o polling não sabe dizer se você realmente voltou, nem distingue uma session nova de uma reaberta.
on_session_open existe para tapar esse buraco.
Um turno inteiro antes do on_session_start
O Hermes já tinha um hook de nome parecido, o on_session_start. O nome é quase o mesmo, mas o ponto de disparo é bem diferente: aquele dispara dentro do primeiro turno do agent, ou seja, quando uma mensagem real do usuário está prestes a ser processada.
Por isso, quando você reabre um chat salvo, o on_session_start nunca dispara. Mesmo que você continue conversando, o que dispara é “este turno começou”, não “esta session foi aberta”.
on_session_open é a segunda coisa: o momento em que uma session é criada ou aberta, antes de o modelo ver qualquer coisa. A documentação é explícita sobre a intenção — serve para se preparar para uma conversa, por exemplo um plugin de memória que pré-carrega as últimas vinte notas, ou uma barra de status que marca a session como aberta na hora.
O que o ponto de disparo significa de fato
Os detalhes importam, porque são eles que decidem se o seu callback roda duas vezes por um único clique.
Quem dispara é a autoridade de session do gateway: quando uma conexão de cliente se anexa a uma session local à qual ainda não estava anexada, ele dispara uma vez. Isso dá bordas limpas:
- Uma abertura, um disparo. Um cliente que relê o snapshot de uma session que já possui não dispara. Reconectar depois de uma queda de socket não dispara. Você não precisa manter um conjunto de deduplicação.
- Dois clientes abrindo a mesma session disparam duas vezes. São duas aberturas reais, e o plugin deve saber que chegaram duas pessoas.
- Criar e retomar contam, distinguidos pelo
reason:createenquanto a session ainda não tem mensagens,resumequando já existe conversa. - Roda no profile dono da session. Em um gateway que atende vários profiles, os plugins de cada profile veem apenas as suas próprias sessions — sem cruzamento.
- Chats de mensageria não disparam. Telegram, Discord e companhia não têm ação de “abrir”; as sessions deles começam com a primeira mensagem, e ali o
on_session_startcontinua sendo o hook certo.
O payload é pequeno: session_id, platform (cli, tui, desktop, acp e assim por diante) e reason (create ou resume). Nenhum conteúdo de mensagem, nenhuma entrada do usuário — de propósito, para que você nunca precise pensar em privacidade aqui.
Escrevendo um callback: aqueça o cache primeiro
Dentro de um plugin, o registro é igual ao de qualquer outro hook:
# ~/.hermes/plugins/session-warm/__init__.py
_cache = {}
def warm(session_id, platform, reason, **kwargs):
# Cheap preparation only: read files, query a local index, write state
_cache[session_id] = load_recent_notes(limit=20)
def register(ctx):
ctx.register_hook("on_session_open", warm)
Não tire o **kwargs. Campos novos aparecem com o tempo, e uma assinatura fixa acaba esbarrando em um deles e virando TypeError.
O único ponto que merece atenção nesse trecho: o callback roda no gateway, não no cliente. Quando o CLI clássico, a TUI ou o Desktop abre uma session, é o processo do gateway que carrega e executa o código do plugin; o processo do cliente nunca toca em plugins. Isso é uma fronteira de segurança, e também a razão de as linhas de log mostrarem o pid do gateway.
Você não precisa escrever Python. Hooks de shell também suportam este evento:
# ~/.hermes/config.yaml
hooks:
on_session_open:
- command: "~/.hermes/agent-hooks/session-open.sh"
timeout: 10
O script recebe um payload JSON no stdin com esses três campos. Para anexar uma linha de auditoria ou fazer um ping em um serviço local, uma dúzia de linhas de bash resolve.
Depois, teste. O hermes hooks test cobre este evento: ele dispara todos os hooks correspondentes contra um payload sintético e imprime a resposta já interpretada.
hermes hooks test on_session_open
Um orçamento de cinco segundos, e a regra que vem junto
Existe um trade-off de projeto que vale conhecer: abrir a session nunca espera pelos plugins, mas o próximo turno dela espera.
Na prática, o callback é despachado em uma thread própria, então o instante em que você clica em abrir é imediato. Antes de o turno começar de fato, porém, ele espera o callback — até 5 segundos, ou mais se plugins.hook_callback_timeout (padrão de 30 segundos) estiver configurado mais alto. Passado esse limite, o turno segue e o callback continua rodando em segundo plano.
Definir plugins.hook_callback_timeout como 0 significa que os callbacks nunca são abandonados. Mesmo assim o turno espera só 5 segundos: essa configuração quer dizer “não mate callbacks lentos”, não “deixe que eles façam a conversa refém”.
O que leva à regra: mantenha o callback rápido. Ler arquivos locais, uma consulta SQLite, preencher um cache em memória — tudo dentro do orçamento. Chamar um LLM, bater em uma API remota, varrer um repositório — aí você já está adicionando latência à primeira frase do usuário.
Mais dois detalhes:
- Se o callback de uma session ainda está rodando e a mesma session é aberta de novo, a nova abertura se junta a ele e dispara uma única vez quando o primeiro termina, com os dados da abertura mais recente. Um callback travado não consegue empilhar dez threads.
- Se os plugins carregados no profile não tiverem nenhum assinante, nada acontece — nem uma thread.
As falhas são fail-open: uma exceção é registrada no log e ignorada, os callbacks seguintes continuam, e a session abre de qualquer forma.
O que cabe aqui, e o que não cabe
Os bons encaixes são os casos do tipo “a conversa ainda não começou, mas eu quero estar pronto”:
- Aquecimento de memória ou base de conhecimento: puxar as notas e conclusões ligadas a este repo para que a primeira mensagem já se beneficie.
- Estado e sinais: barras de status, dashboards externos, logs de auditoria. “Quem abriu qual session, e quando” é uma linha que operadores realmente querem.
- Credenciais ou diretórios de trabalho por session: plugins que precisam saber a qual projeto uma session pertence antes de escolher uma configuração.
- Limpar sobras da rodada anterior: em uma abertura do tipo
create, descartar rascunhos antigos é mais confiável do que adivinhar.
Os maus encaixes são igualmente claros:
- “A session começou” em plataformas de mensageria — use
on_session_start. - Qualquer coisa que dependa de entrada do usuário; neste ponto não existe nenhuma.
- Qualquer ida e volta de rede medida em centenas de milissegundos.
Uma observação de escopo: sessions iniciadas com --safe-mode ou --ignore-user-config nunca disparam o hook, porque plugins não são carregados nesses modos.
Já dá para usar hoje?
O hook entrou na main em 8 de novembro de 2026 (PR #151120). Conferi o que a v0.23.0 entregou: essa release saiu em 6 de novembro, então este hook não está na v0.23.0. É código exclusivo da main e chegará a uma release estável na próxima versão.
Atualização (10/11/2026): essas mudanças saíram na v0.23.1 (9 de novembro): basta um
hermes update. O « não está na v0.23.0 » acima continua correto; a v0.23.1 fecha a lacuna.
Se você roda a main, já pode usar agora. Se está em uma release estável, escreva o plugin e prove a lógica com hermes hooks test, para que ele funcione no dia em que você atualizar.
Até lá, os hooks mais antigos ainda cobrem parte do terreno: on_session_start para o primeiro turno, mais os hooks de fronteira de session que vimos em as notificações de plugin para sessions compactadas e excluídas. A mesma máquina de despacho também consegue bloquear um turno inteiro antes da chamada ao modelo — veja o hook de política pre_llm_call — e a referência de comandos lista todos os nomes de evento e campos de configuração suportados.
Resumo rápido
O on_session_open preenche uma lacuna bem específica: “a session está aberta, mas nenhuma mensagem chegou ainda”. Os plugins eram cegos exatamente nesse instante. Agora recebem session_id, platform e reason, além de cinco segundos para se preparar. A única regra a lembrar é a que o orçamento implica: faça coisas baratas nesses cinco segundos e deixe as caras para o primeiro turno.