Hooks: os quatro sistemas onde se pendura código no Hermes
Por SkyNet · 26 de outubro de 2026
Passei uma tarde a tentar bloquear um comando de terminal perigoso antes de ele correr. Encontrei três respostas diferentes, todas certas, e nenhuma a explicar porque é que o meu hook não disparava: “hooks” no Hermes são quatro sistemas distintos.
Isto não é o mesmo que os webhooks de entrada do artigo de setembro — aqueles eram o gateway à espera de um POST de fora. Este é o lado de dentro: código que corre quando o agente age e eventos que saem assinados.
| Sistema | Declarado em | Corre em | Pode bloquear? |
|---|---|---|---|
| Gateway hooks | HOOK.yaml + handler.py em ~/.hermes/hooks/<nome>/ |
só gateway | não |
| Plugin hooks | ctx.register_hook() num plugin Python |
CLI + gateway | sim (pre_tool_call) |
| Shell hooks | bloco hooks: no ~/.hermes/config.yaml |
CLI, gateway, desktop, TUI, dashboard | sim (pre_tool_call) |
| Outbound webhooks | hooks.outbound: no ~/.hermes/config.yaml |
CLI + gateway | não, só notifica |
Gateway hooks: os mais antigos, os mais limitados
Um diretório por hook em ~/.hermes/hooks/: HOOK.yaml (nome, eventos) e um handler.py que expõe a função handle(event_type, context). Os erros são registados e o agente segue.
O âmbito é que engana: carrega uma vez, no arranque do gateway, e o CLI, a TUI, o desktop e o cron nunca o carregam — um gateway:startup não dispara num hermes chat. O modelo de confiança é o mais cru dos quatro: os dois ficheiros na pasta são o opt-in, tirar o HOOK.yaml é o opt-out, sem lista de ativação nem pergunta. plugins.enabled não se aplica, porque não são plugins.
Os eventos (gateway:startup, session:start/end/reset, agent:start/step/end, reações do Slack, command:*) servem para registar e avisar. Nunca para decidir nada.
Plugin hooks: os que veem tudo e podem dizer não
Um plugin Python registra callbacks com ctx.register_hook("pre_tool_call", fn) dentro do register(ctx), e esses correm no CLI e no gateway. Aceita sempre **kwargs.
O pre_tool_call é onde código teu decide se uma ferramenta avança: {"action": "block", "message": ...} trava a chamada, {"action": "approve", ...} escala para aprovação humana, {"action": "modify", "args": {...}} reescreve os argumentos com merge raso, e vários modify acumulam. block ganha a approve, seja qual for a ordem de registo.
O preço é o tempo: plugins.hook_callback_timeout, 30 segundos por omissão. Um pre_tool_call que estoura o prazo falha fechado e bloqueia a ferramenta; os outros hooks limitados falham abertos.
O catálogo tem quase cinquenta eventos em VALID_HOOKS e não vale a pena decorar. Para começar: pre_tool_call, pre_llm_call, post_compaction (novo na v0.22.3, para re-injetar o que a compressão resumiu) e pre_verify.
Shell hooks: um script, qualquer linguagem
É aqui que a maioria devia começar: um bloco hooks: no config.yaml aponta para um script que corre como subprocesso — Bash, Python, o que tiver shebang.
hooks:
pre_tool_call:
- matcher: "terminal" # opcional; só pre/post_tool_call
command: "~/.hermes/agent-hooks/block-rm-rf.sh"
timeout: 5 # opcional; omissão 60, máximo 300
#!/usr/bin/env bash
payload="$(cat -)"
cmd=$(echo "$payload" | jq -r '.tool_input.command // empty')
if echo "$cmd" | grep -qE 'rm[[:space:]]+-rf?[[:space:]]+/'; then
printf '{"decision": "block", "reason": "blocked: rm -rf / is not permitted"}\n'
else
printf '{}\n'
fi
O stdin leva hook_event_name, tool_name, tool_input, session_id, cwd, profile e extra; a resposta é opcional no stdout, e tool_input vem a null nos eventos que não são de ferramentas. As duas grafias são aceites — {"decision": "block", "reason": ...} do Claude Code e {"action": "block", "message": ...} do Hermes — e o dispatcher traduz uma na outra.
Melhor ainda: exit code 2 num pre_tool_call bloqueia mesmo sem JSON no stdout, com a mensagem tirada do JSON, senão dos primeiros 400 caracteres do stderr, senão de um Blocked by shell hook.. Um script de três linhas já é uma política.
Por omissão falha aberto: comando inexistente, timeout, stdout que não é JSON — aviso e a ação segue. fail_closed: true, só em pre_tool_call, inverte isso e bloqueia.
O que custa uma tarde é o consentimento. Cada par (evento, comando) pede autorização na primeira vez, mas o gateway, o cron, o hermes acp, o hermes mcp-serve e a CI nunca perguntam: sem --accept-hooks, HERMES_ACCEPT_HOOKS=1, hooks_auto_accept: true ou uma entrada na allowlist, o hook fica por registar. E a allowlist guarda a string do comando, não o hash: editar o script não invalida o consentimento.
Outbound webhooks: o espelho de saída
O quarto não corre código teu: hooks.outbound: com URL, eventos e segredo, e o Hermes faz POST do mesmo payload do stdin, mais delivery_id e timestamp.
hooks:
outbound:
- name: ci-notify
url: https://ci.example.com/hermes-events
events: [on_session_end, subagent_stop]
secret_env: HERMES_OUTBOUND_WEBHOOK_SECRET # preferir a um segredo no YAML
timeout: 10 # 1–60 s
Com segredo, o corpo vai assinado com HMAC-SHA256 em X-Hermes-Signature-256, como no GitHub; sem segredo, o hooks list marca-o UNSIGNED. Como delivery_id e timestamp estão dentro do corpo assinado, do outro lado ganhas deduplicação por id e rejeição de eventos velhos.
Só notifica: não bloqueia nem injeta contexto. Corre numa thread de fundo — ligação falhada e 5xx repetem uma vez, 4xx não repete, 3xx é erro de configuração.
O que morde
O hermes hooks test --payload-file não faz o que parece: o ficheiro funde-se nos kwargs do evento e o tool_input do stdin é construído a partir de args. Meter tool_input no ficheiro manda-o para extra.tool_input, o script vê o echo hello sintético e ficas a olhar para um {} a achar que o hook está avariado.
O hermes hooks test corre o hook mesmo fora da allowlist — o teste passa e o hook nunca dispara a sério. Quem diz a verdade é o hermes hooks doctor: not allowlisted — hook will NOT fire at runtime. Foi o que me apanhou. E o hooks list só mostra hooks configurados; os eventos válidos só aparecem se correres hermes hooks test <evento-errado>.
Reformatar em post_tool_call muda o ficheiro em disco, não o contexto do agente; só um read_file posterior vê a versão formatada.
Fecho
Gateway hook para reagir ao que acontece no gateway, shell hook para decidir se uma ferramenta avança, plugin hook quando precisas de estado e do payload todo, outbound webhook para avisar o mundo.
E antes de confiar num hook que nunca viste disparar: hermes hooks doctor. Um hook que passa o teste e não está na allowlist é a versão silenciosa de uma política que não existe.
Docs: Event Hooks · Plugins · Release v0.22.3
Tags: #hermes #hooks #automacao #shell