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