Abstract cyan event streams passing through a yellow approval arch toward a rocky operations hub. — Event hooks are safest when their scope, consent, inputs, and failure behavior are explicit.

Hermes Event Hooks Operations Guide

Hermes provides three hook systems for different lifecycle jobs: gateway hooks, plugin hooks, and shell hooks. The right choice depends on where the behavior must run and whether it needs to observe, transform, or block an action.

Official documentation: https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks

Choose the smallest hook surface

Gateway hooks live under ~/.hermes/hooks/ and react to messaging-gateway events such as startup, session changes, agent steps, and slash commands.
Plugin hooks are registered in code and can run in both CLI and gateway sessions. They fit reusable metrics, tool interception, and guardrails.
Shell hooks are configured in config.yaml and call reviewed scripts for tasks such as context injection, formatting, validation, or blocking.

Use a hook only when an event must trigger behavior automatically. A normal skill or explicit command is easier to inspect when automation is not required.

Safe rollout checklist

[ ] Name the exact lifecycle event and expected payload.
[ ] Keep the handler narrow, fast, and idempotent.
[ ] Store reviewed shell scripts in a dedicated auditable directory.
[ ] Bound network timeouts and avoid putting long work on the event path.
[ ] Redact message bodies, user identifiers, and tool results before external logging.
[ ] Decide whether failure should block, warn, or continue.
[ ] Test with synthetic payloads before relying on live events.

Consent and non-interactive runs

Shell-hook consent is keyed to the event and exact command string. Non-interactive gateway, cron, or CI runs cannot answer a first-use prompt, so operators must establish consent deliberately and verify it rather than assuming a new hook loaded. Script edits are not automatically re-approved because consent follows the command string, not a content hash.

Useful operator checks include hermes hooks list, hermes hooks test <event>, and hermes hooks doctor. The doctor checks details such as executability, consent state, JSON output, modification drift, and rough runtime.

Pitfalls

Treating hook input as trusted because it came through an authenticated gateway.
Writing full prompts, private messages, or credentials to a convenience log.
Running expensive network or agent work synchronously inside a hot lifecycle event.
Auto-accepting hooks broadly without reviewing the scripts they execute.
Assuming a gateway hook also runs in the CLI.
Using a hook to hide business logic that belongs in a visible runbook or skill.

Verification steps

List hooks and confirm the intended event matcher and consent status.
Fire a synthetic event with a clearly fake payload.
Verify the parsed result and any expected side effect.
Run hermes hooks doctor after script edits.
Restart the relevant runtime and confirm one event produces one result.
Inspect logs for private data, duplicate execution, timeouts, and unexpected blocks.