agentos.guide › blog

Hermes Agent Hooks: Add Guardrails, Turn Blocks And Dashboard Events To Your Agent OS With Five Copy-Paste Prompts

By Julian Goldie · 2 November 2026 · agentos.guide

Hermes agent hooks are the guardrail layer of your Agent OS: small scripts and plugins that Hermes runs at fixed points, so a rule you write once is checked on every turn and every tool call.

The newest piece merged to main on 1 Nov 2026, and it lets a pre_llm_call hook end a turn before a single inference request goes out.

This guide gives you a quick start, five prompts to paste into your agent, and a weekly routine to keep the hooks honest.

If you'd like a hand planning the rules for your own business, book a free SEO strategy session with my team.

What Hooks Do Inside An Agent OS

Your Agent OS runs Hermes across chat, scheduled jobs and messaging bots.

Hooks sit underneath all of that.

A tool hook sees every terminal command, file write and web search before it happens.

A turn hook sees every incoming message before the model does.

That makes hooks the right home for anything you'd otherwise have to remember to type into every prompt.

Members of the AI Profit Boardroom get the installable Agent OS, so the profile and config file these hooks live in are already set up.

The Four Hook Types At A Glance

The full contract for each lives in the official Event Hooks docs.

Quick Start: Your First Guardrail In Five Minutes

Start with the destructive-command block, straight from the docs.

hooks:
  pre_tool_call:
    - matcher: "terminal"
      command: "~/.hermes/agent-hooks/block-rm-rf.sh"
      timeout: 5

#!/usr/bin/env bash
# ~/.hermes/agent-hooks/block-rm-rf.sh
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

Make the script executable, open a foreground hermes chat, and approve the hook when Hermes asks.

The answer is saved to ~/.hermes/shell-hooks-allowlist.json, so you're only asked once per event and command.

Then check it with hermes hooks test pre_tool_call --for-tool terminal.

The New Turn Block, In One Minute

Commit ad9229c843, authored on 31 Oct, gives pre_llm_call a veto.

Return a block with a message, and the turn makes zero model calls; the message becomes the reply.

// Block the turn before any inference request (pre_llm_call); both shapes accepted:
{"action": "block", "message": "Blocked by policy: prompt contains a customer ID"}
{"decision": "block", "reason": "Blocked by policy: prompt contains a customer ID"}

Three follow-ups on 1 Nov tightened it.

• Commit 792330dc91: the prompt is stored only as [Message withheld: a pre_llm_call policy hook blocked it.], so compaction, search and memory never read it.
• Commit c0bcfe2bb2: a blocked turn runs no post-turn compaction.
• Commit 4061818385: /retry and /undo use what you typed, so the hook re-checks a retry.

It's not in a tagged release yet; the Hermes releases page lists v0.22.5 from 23 Oct as the latest.

🔥 Want the Agent OS with Hermes and these guardrails ready to install?

Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS, four coaching calls a week and 3,400+ members swapping the hook setups they run.

→ Join the AI Profit Boardroom

Prompt 1: Audit What's Already Running

Paste this before you add anything.

Read the Hermes Event Hooks docs at
https://hermes-agent.nousresearch.com/docs/user-guide/features/hooks
then run `hermes hooks list` and `hermes hooks doctor` on this machine.
Give me a short table: every configured hook, its event, matcher,
timeout, consent status and any doctor warnings.
Don't change any config yet.

Doctor checks the exec bit, allowlist status, mtime drift, JSON output and rough run time for each hook.

Prompt 2: Install The Destructive-Command Block

If you'd rather the agent did the quick start for you, give it this.

Add the "Block destructive terminal commands" shell hook from the
Hermes hooks docs, exactly as written there:
- the pre_tool_call entry with matcher "terminal" and timeout 5 in config.yaml
- the script at ~/.hermes/agent-hooks/block-rm-rf.sh, made executable
Then run `hermes hooks test pre_tool_call --for-tool terminal`
and show me the parsed line. Ask me before approving the hook.

Keep the approval step with you, not the agent; that's the point of a consent prompt.

The test command fires the hook against a synthetic payload, so nothing real gets deleted while you check it.

If you'd rather the rule be a one-liner, the docs also accept a script that writes a reason to stderr and exits with code 2.

Prompt 3: Make Your Security Gates Fail Closed

Shell hooks fail open by default, which suits loggers and not gates.

Find every pre_tool_call shell hook in my config.yaml that acts as a
security gate (secret scans, path checks, destructive-command blocks).
For each one, propose adding `fail_closed: true` and explain in one line
what would change if the script crashed or timed out.
Show me the diff and wait for my yes before writing it.

This is the docs' shape for a fail-closed gate:

hooks:
  pre_tool_call:
    - matcher: "terminal|write_file|patch"
      command: "~/.hermes/agent-hooks/secret-scan.sh"
      timeout: 10
      fail_closed: true

Remember fail_closed only applies to pre_tool_call; elsewhere it's ignored with a warning.

Prompt 4: Draft A Turn-Level Privacy Policy

This prepares the new block without switching it on early.

Draft a pre_llm_call shell hook script that returns
{"action": "block", "message": "Blocked by policy: prompt contains a customer ID"}
when the user message (in .extra.user_message on stdin) matches the
pattern I give you, and {} otherwise. If the script can't parse its input,
make it print the block, not {}. Save it as a draft in
~/.hermes/agent-hooks/ but don't add it to config.yaml until I confirm
my Hermes build includes commit ad9229c843.

The "block on parse failure" line matters.

The docs say a pre_llm_call callback that raises or times out is skipped and the turn goes ahead, so the script itself has to choose the safe answer.

Shell hooks also use their own timeout, 60 seconds by default, rather than the 30-second plugins.hook_callback_timeout that plugins use.

Prompt 5: Send Turn Events To Your Dashboard

Outbound webhooks report; they never steer.

Set up a hooks.outbound entry named ci-notify for on_session_end and
subagent_stop, pointed at the URL I give you, with secret_env set to
HERMES_OUTBOUND_WEBHOOK_SECRET and the secret stored in ~/.hermes/.env.
Then run `hermes hooks list` and confirm the target shows as signed.

The docs' example looks like this:

hooks:
  outbound:
    - name: ci-notify                       # optional label for logs
      url: https://ci.example.com/hermes-events
      events: [on_session_end, subagent_stop]
      secret_env: HERMES_OUTBOUND_WEBHOOK_SECRET   # env var holding the HMAC secret
      timeout: 10                           # per-attempt seconds (1–60)

    - name: tool-monitor
      url: https://metrics.example.com/hooks/hermes
      events: [post_tool_call]
      matcher: "terminal|delegate_task"     # regex, tool-scoped events only

Each delivery has a unique delivery_id inside the signed body, so your dashboard can skip the duplicate when Hermes retries once.

Payloads include tool inputs, so point them only at endpoints you trust, over https://.

📞 Want my team to pick the policies for your Agent OS?

Book a free SEO strategy session and we will go through the data your agents handle and the rules worth writing first.

→ Book your free strategy session

Three More Hooks Worth Adding Once The Gates Are In

Guardrails come first, but hooks also make the agent more useful.

Feed it the repo state. The docs' pre_llm_call example adds uncommitted git status output to every turn, the Hermes equivalent of Claude Code's UserPromptSubmit.

hooks:
  pre_llm_call:
    - command: "~/.hermes/agent-hooks/inject-cwd-context.sh"

Injected text always lands in the user message, never the system prompt, so your prompt cache stays warm.

Tidy what it writes. A post_tool_call hook with the matcher write_file|patch can run a formatter on each file the agent saves.

The agent only sees the formatted version the next time it reads the file.

Log the delegation. A subagent_stop hook can append one JSON line per finished child agent to a log you review.

hooks:
  subagent_stop:
    - command: "~/.hermes/agent-hooks/log-orchestration.sh"

Each of these is a separate approval, because consent is tracked per event and command pair.

Running Hooks On Servers And Scheduled Jobs

Your Agent OS probably runs Hermes on a gateway around the clock, and that changes how consent works.

Only a foreground hermes chat or hermes rl shows the approval prompt.

The gateway, cron, hermes acp and CI never ask, so an unapproved hook simply stays unregistered, with a warning naming the allowlist file it's missing from.

You have three ways round that: the --accept-hooks flag, the HERMES_ACCEPT_HOOKS=1 variable, or hooks_auto_accept: true in config.

I prefer writing the allowlist by hand on servers, so every approved command is visible in one file.

{
  "approvals": [
    {
      "event": "post_llm_call",
      "command": "/home/hermes/.hermes/hooks/my-hook.py"
    }
  ]
}

Changes to the allowlist or the hooks: block reach a running gateway within about 30 seconds, on every profile it serves.

A Weekly Routine To Keep Hooks Honest

1. Run hermes hooks doctor every Monday and read every mtime-drift line, because editing an approved script never re-prompts.
2. After you pull a shared config, run doctor again before the gateway picks anything up.
3. On servers, approve new hooks deliberately: the gateway, cron and CI never prompt, so use the allowlist or --accept-hooks.
4. Grep the logs for blocked_by_plugin_pre_llm_call once the turn block is live, and check each block was intended.
5. Remove anything you don't recognise with hermes hooks revoke <command>.

Treat the hooks: block as privileged configuration, because shell hooks run with your full user credentials.

Adding plugins to the same profile? Read our guide to the best Hermes Agent plugins first.

Developers can find the plugin-side return rules in the observer hooks reference.

For the full Agent OS and the trainings, join the AI Profit Boardroom, and for help choosing your rules, book a free strategy call.

FAQ

Can my agent set up its own Hermes hooks?

It can write the config and scripts from the docs, but keep the first-use approval with you. Only a foreground hermes chat asks, and that prompt is your consent step.

Do hooks run in the Agent OS dashboard chat?

Shell hooks do. They register in CLI, gateway, Desktop, TUI and dashboard chat sessions, using that session profile and allowlist.

When can I use the pre_llm_call block?

It merged to main on 1 Nov 2026. It is not in a tagged release yet, so use a build from main or wait for the next release after v0.22.5.

How do I see which hooks are active?

Run hermes hooks list for matcher, timeout and consent status, and hermes hooks doctor for health checks on each hook.

Final word on Hermes Agent Hooks

Paste Prompt 1 into your agent now, and if you want help deciding what to block, book a free strategy session and bring your Hermes agent hooks list.

Related guides on agentos.guide

→ Hermes Agent Streaming: Cap Stuck Replies In Your Agent OS

→ The Best Hermes Agent Plugins: My Top 10, And Where Each One Fits In Your Agent OS

→ Grok Bot Android: Approve And Steer It In Your Agent OS

→ Grok Bot Windows: Install And Run It In Your Agent OS

📺 Video notes + links to the tools 👉

🎥 Learn how I make these videos 👉

🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉

← all guides on agentos.guide