Hermes Agent Hooks: Block, Log and Control Every Turn (2026 Guide)

Hermes Agent hooks let you run your own code at key moments in every conversation: before a tool runs, before the model is called, when a session starts, when a reply is finished. On 1 November 2026 Nous Research merged a big one into hermes-agent: a pre_llm_call hook can now block a turn before any request reaches the model. That gives privacy and policy checks a proper, supported place to live. Below are the four hook systems, how to add a shell hook in a few lines, how blocking works, and the safety rules. My video is right under this intro.

What are Hermes Agent hooks?

The Event Hooks docs describe four ways to plug your own code into Hermes:

A broken hook is logged and skipped, so it never crashes the agent. But hooks aren’t all passive: some can stop a tool, replace text or end a turn.

The new pre_llm_call block

Before this change, pre_llm_call could only add extra context to your message (that’s how memory and RAG plugins work). The 1 November commit adds a second option: return a block and the turn ends before the model sees anything.

return {"action": "block", "message": "Blocked by policy: prompt contains a customer ID."}

What happens next, from the commit and the updated docs:

• Zero model calls are made for that turn.
• Your block message is shown as the reply, and the transcript keeps a normal user → assistant pair, so --resume still works.
• The prompt is stored as [Message withheld: a pre_llm_call policy hook blocked it.]. Later turns, compaction, session_search and memory providers only ever see that placeholder.
• Titling, external-memory sync and the background memory review are skipped for that turn.
• The first valid block wins. A block with no message is ignored.

Nous calls this the supported place for data-loss-prevention, privacy and policy plugins, which until now had to patch Hermes itself.

How to add a shell hook

Shell hooks are the easiest way in: no Python plugin needed. Add a hooks: block to your profile’s config.yaml:

hooks:
  pre_tool_call:
    - matcher: "terminal"
      command: "~/.hermes/agent-hooks/check-command.sh"
      timeout: 60
      fail_closed: true

Hermes sends your script a JSON payload on stdin and reads JSON back from stdout. The rules from the docs:

• matcher is a regex and only applies to pre_tool_call and post_tool_call.
• timeout defaults to 60 seconds and is capped at 300.
• fail_closed: true (pre_tool_call only) blocks the tool if the script crashes or times out.
• A pre_tool_call script that exits with code 2 blocks the tool, the same as Claude Code and Cursor hooks.
• Both the Hermes shape {"action": "block", "message": ...} and the Claude Code shape {"decision": "block", "reason": ...} are accepted.

Easier option: ask your agent, “Add a shell hook that blocks any terminal command containing rm -rf, then run hermes hooks test pre_tool_call to prove it works.”

What each hook can do

Most hooks just watch. A few can change what happens:

• pre_tool_call: block a tool, rewrite its arguments with {"action": "modify"}, or send it to the human-approval gate with {"action": "approve"}.
• pre_llm_call: inject context into the current message, or now block the turn.
• post_tool_call: run something after a tool, such as auto-formatting a file the agent just wrote.
• pre_verify: keep the agent working at the code-verify step (“run the formatter, then finish”).
• transform_tool_result and transform_llm_output: replace a tool result or the final reply.
• Observers such as on_session_start, subagent_stop, kanban events and streaming hooks.

Gateway hooks are different: they fire on events such as gateway:startup, agent:start, agent:end and command:* in Telegram, Discord, Slack, WhatsApp and Teams, and can’t block anything.

The hermes hooks commands

The first time Hermes sees a new shell hook in a foreground hermes chat, it asks you to approve it and saves your answer to ~/.hermes/shell-hooks-allowlist.json. The gateway, cron and CI never ask, so approve hooks there with --accept-hooks, HERMES_ACCEPT_HOOKS=1, or an allowlist entry.

Safety rules for hooks

Hooks run as you. The docs are direct about it:

• Shell hooks run with your full user credentials, like a cron entry.
• Only use scripts you wrote or fully reviewed, and keep them in ~/.hermes/agent-hooks/.
• Approval keys on the command string, not the file, so editing a script doesn’t ask again. Run hermes hooks doctor to spot edits.
• Gateway hooks in ~/.hermes/hooks/ load with no prompt and no sandbox. Read handler.py before you drop it in.
• A pre_llm_call callback that crashes or runs past 30 seconds is skipped and the turn goes ahead. A policy hook should catch its own errors and return a block when it can’t decide.

My verdict

If you run Hermes for clients or a team, hooks are where your rules belong: block risky commands, keep customer data out of the model, log every session. Start with one shell hook, test it with hermes hooks test, and use the new pre_llm_call block for anything that must never reach a model. That’s the practical way to put Hermes Agent hooks to work.

About Julian Goldie

I’m Julian Goldie — founder of Goldie Agency and the AI Profit Boardroom. I test new AI agents almost every day for 432K+ YouTube subscribers and run Hermes, OpenClaw, OpenCode, Claude and Codex side by side in my own Agent OS. Claim your free strategy session or join the AI Profit Boardroom.

Want another angle? Read the AI Profit Boardroom guide to Hermes Agent Hooks.

FAQ: hermes agent hooks

What are Hermes Agent hooks?

Hooks are your own code or scripts that Hermes runs at set points, such as before a tool call, before the model is called, or when a session starts. There are gateway hooks, plugin hooks, shell hooks and outbound webhooks.

How do I add a shell hook in Hermes?

Add a hooks: block to your profile config.yaml with the event name, an optional matcher and the command to run. Hermes asks you to approve it the first time, then you can check it with hermes hooks test.

Can a Hermes hook block a tool call?

Yes. A pre_tool_call hook can return a block, or a shell hook can exit with code 2. With fail_closed: true, a crashed or timed-out pre_tool_call hook also blocks the tool.

What does the new pre_llm_call block do?

Merged on 1 November 2026, it lets a pre_llm_call hook end a turn before any model request. The block message becomes the reply and the prompt is stored only as a withheld placeholder.

Do gateway hooks work in the CLI?

No. Gateway hooks only fire in the messaging gateway, such as Telegram, Discord or Slack. Use plugin hooks or shell hooks for hooks that work in the CLI too.

Are Hermes hooks safe?

They run with your user permissions, so only use scripts you wrote or reviewed. Editing an approved script does not ask again, so run hermes hooks doctor after changes.

Related reading

• Hermes Agent Cron Job
• Hermes Agent Automation
• Best Hermes Agent Plugins

Last updated November 2026. This page is a living guide to hermes agent hooks — the facts here move fast and it is updated as they do.