Hermes agent hooks are the rules you bolt onto your AI agent so it checks with your policy before it acts, and for a small business that's the difference between an assistant you trust and one you babysit.
On 1 Nov 2026 a new rule type landed on Hermes main: a hook can now refuse a whole request before any AI model sees it.
That matters most to firms that handle client records, card details or anything covered by a confidentiality promise.
Here's what hooks do in plain English, three real ways a shop, a service firm and an agency would use them, and the risks to manage.
Want a second pair of eyes on where AI fits in your business? Book a free call with my team.
Why A Business Owner Should Care About Hooks
An AI agent like Hermes reads your messages, calls tools and sends text to a model provider.
A hook is a small script or plugin that Hermes runs at a set moment in that process.
It can watch, it can add information, and some hooks can say no.
Without hooks, your only safety net is the model's own judgement.
With hooks, you write the rule once and it applies to every chat, every scheduled job and every team member using that profile.
The Four Kinds Of Hook, Without The Jargon
The Hermes Event Hooks documentation splits hooks into four systems.
| Type | What it's for | Can it stop the agent? |
|---|---|---|
| Shell hooks | Drop-in scripts in any language, set in the profile config file | Yes |
| Plugin hooks | Python code inside a Hermes plugin | Yes |
| Gateway hooks | Alerts and logs for Telegram, Discord, Slack, WhatsApp and Teams bots | No |
| Outbound webhooks | Signed messages to your own dashboards or other systems | No |
Most small teams only ever need the first and the last.
Shell hooks set the rules, and outbound webhooks tell your other software what happened.
The New Rule: Stop A Request Before The Model Sees It
The change arrived in commit ad9229c843, authored on 31 Oct and merged to main on 1 Nov 2026.
A hook on the pre_llm_call event runs once at the start of every turn.
It can now answer with a block and a short message.
When it does, Hermes makes zero model calls for that turn, and the person sees your message instead of an AI reply.
The commit itself names the target users: DLP, privacy and policy plugins that used to have to patch Hermes's core code.
The docs' own example message is "Blocked by policy: prompt contains a customer ID", which is about as business-shaped as a code sample gets.
One timing note: it isn't in a tagged release yet, and the latest on the Hermes releases page is v0.22.5 from 23 Oct.
🔥 Want an agent setup your team can't accidentally misuse? Inside the AI Profit Boardroom you get step-by-step video trainings, the installable Agent OS with Hermes ready to go, four coaching calls a week and 3,400+ members running agents in real businesses. → Join the AI Profit Boardroom
Where The Blocked Message Ends Up
Privacy rules are only as good as what gets stored.
A follow-up commit on 1 Nov made Hermes save a blocked request as a fixed placeholder: [Message withheld: a pre_llm_call policy hook blocked it.]
Later turns, conversation summaries, session search, memory providers and the background memory review only ever see that placeholder.
The original wording is kept for display in your own Hermes screens, so you can still see what someone tried to send.
Another fix, commit c0bcfe2bb2, stopped a blocked turn from triggering a background summary call.
So "blocked" really does mean no model saw it.
Use Case 1: A Local Shop That Wants Alerts, Not Surprises
Picture a shop owner who runs Hermes as a Telegram assistant for stock questions and supplier emails.
They don't need blocking first; they need to know when something takes too long or goes wrong.
Gateway hooks are made for that.
The docs include a ready example called "Telegram Alert on Long Tasks", plus a command usage logger and a session-start webhook.
Each one is a folder in ~/.hermes/hooks/ with two files: a HOOK.yaml listing the events and a handler.py.
The owner doesn't write the alert logic from nothing; they copy the example and change the chat it posts to.
The events cover gateway startup, sessions starting, ending and resetting, each agent step and every slash command.
Use Case 2: A Service Firm With Client IDs In Every Message
Now take a bookkeeping or legal firm where staff paste client references into chat all day.
A pre_llm_call shell hook can read the incoming message, spot a client ID pattern and return the block.
// 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"}The staff member sees the policy message straight away, and the model provider never receives the text.
If they retry with the ID removed, a 1 Nov fix makes /retry resend what they typed, so the hook checks it again.
The same firm would add a tool-level rule too, so the agent can't run a risky terminal command or edit files it shouldn't.
Use Case 3: An Agency Running Agents For Several Clients
An agency cares about two things: proof of what the agent did, and keeping each client's work separate.
Shell hook payloads carry a profile field and run with that profile's own home folder, so one script can serve every client profile behind one gateway.
A post_tool_call hook can log every tool run, and a subagent_stop hook can log every child agent that finishes.
Outbound webhooks then push signed events to the agency's dashboard:
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 onlyEach delivery is signed with HMAC-SHA256 when a secret is set, retried once on a connection error or 5xx, and never slows the agent down.
What Works Today, Before The Next Release
You don't have to wait for the new block to put rules in place.
The pre_tool_call event already runs before every single tool the agent uses, from the terminal to web search to file edits.
A rule on that event has three answers available.
- Block: the tool doesn't run, and the agent gets your reason back as an error.
- Approve: the call is sent to a person for a yes or no, and a denial or timeout counts as no.
- Modify: the agent's request is quietly corrected first, for example pointing a file path at the right folder.
If two rules disagree, block always wins over approve.
For most small teams, an approval rule on file edits and a block rule on destructive commands covers the biggest worries on day one.
There's also a gentler option on pre_llm_call that works today: inject a reminder, such as your house rules, into every request instead of blocking it.
What A Block Saves You
A blocked turn makes no inference request, no titling call and no background summary.
So a policy that catches a bad request early also skips the model work that request would have triggered.
I won't put a number on it, because that depends on your provider and your traffic.
The bigger saving is the clean-up you never have to do after a sensitive message reaches an outside service.
📞 Unsure which client data your agents are touching? Book a free SEO strategy session and my team will walk through your setup with you. → Get your free strategy session
The Risks You Need To Manage
- Fail-open is the default. If a shell hook crashes or times out, Hermes logs a warning and carries on, unless it's a tool-call rule set to
fail_closed: true. - A crashing turn-level rule lets the request through. The docs say a
pre_llm_callcallback that raises or times out is skipped, so your script has to return the block itself when it's unsure. - Edited scripts aren't re-approved. Approval is tied to the command text, so changing the script's contents doesn't ask again;
hermes hooks doctorflags the change. - Hooks run with full access. A shell hook has the same rights as the user running Hermes, so only use scripts you wrote or fully reviewed.
- Gateway hooks have no approval step. Whatever sits in the hooks folder loads at gateway start.
Who On Your Team Should Own Hooks
Give hooks to one person, not the whole team.
The Hermes docs say to treat the hooks: block like privileged configuration and review changes to it the way you'd review CI settings.
That owner should run hermes hooks list after every change, which shows each hook's matcher, timeout and approval status.
On a server, they'll also need to pre-approve hooks, because the gateway, cron and CI never show the first-use prompt.
If you're also picking plugins for the same setup, compare them in our best Hermes Agent plugins list.
Is It Worth Setting Up?
Yes, if your agent touches anything you'd be unhappy to see in a third-party log.
The tool-level rules are already well established, with blocking, argument rewriting and a route to human approval.
The turn-level block is the piece that was missing for privacy rules, and it's now on main with three same-day fixes behind it.
For a shop that only wants alerts, gateway hooks are enough today.
For an agency, the outbound webhooks alone justify an afternoon of setup, because every client report can then cite what the agent really did.
The setup cost is small either way: a few lines of config and a script you can copy from the docs.
For a firm with confidential data, the new block is worth planning for now and switching on when it reaches a release.
What To Set Up This Week
- List the three things your agent must never do or send.
- Add the docs' example tool rule that blocks destructive terminal commands.
- Add one outbound webhook so finished turns show up on a dashboard you already check.
- Draft your client-ID pattern for the
pre_llm_callblock, ready for the next Hermes release. - Run
hermes hooks doctorand fix anything it flags.
The plugin side of the same events is documented in the observer hooks reference if your developer wants it.
When you want the Agent OS and the trainings that go with it, join the AI Profit Boardroom, and if you'd like help choosing the rules, book a free strategy session.
Also On Our Network
- 🌐 The six-step operator setup for shell hooks, fail-closed gates and turn blocks
- 🌐 A nine-criterion scorecard on control, safe defaults, consent and privacy
- 🌐 Five copy-paste prompts that set up hooks inside your Agent OS
- 🌐 Which AI model to pair with each hook setup, by real GoldieBench scores
- 🌐 The complete Hermes Agent Hooks guide on the AI Profit Boardroom blog
FAQ: Hermes Agent Hooks For Business
Do I need a developer to use Hermes hooks?
Not for the docs examples. Shell hooks are short scripts in any language set in config.yaml, but someone on the team should own and review them.
Can Hermes stop staff sending client details to the AI model?
Yes, with a pre_llm_call hook that returns a block. On Hermes main since 1 Nov 2026, the turn then makes zero model calls and the person sees your policy message.
What happens if my hook script breaks?
By default Hermes logs a warning and carries on. Tool-call rules can be set to fail_closed so a broken script blocks instead.
Is the new block available in the current Hermes release?
Not yet. It merged to main on 1 Nov 2026, and the latest tagged release is v0.22.5 from 23 Oct.
Can hooks send updates to my own dashboard?
Yes. Outbound webhooks POST signed JSON events, such as finished turns or subagent completions, to any URL you configure.
📺 Video notes + links to the tools 👉
🎥 Learn how I make these videos 👉
🆓 Get a FREE AI Course + Community + 1,000 AI Agents 👉
About Julian
I'm Julian Goldie, an SEO entrepreneur, author and founder of the AI Profit Boardroom, which has 3,400+ members.
I help business owners scale with AI agents, automation and SEO.
- I've built a 7-figure SEO and link building agency, Goldie Agency, with a team of 70+ SEO experts.
- I've grown a YouTube channel to 400,000+ subscribers.
- I wrote "Link Building Mastery".
- My Udemy courses have taught over 29,000 students.
→ Get my best AI training inside the AI Profit Boardroom
Write down your three never-do rules today, and if you want my team to turn them into a plan, book a free strategy session before you switch on Hermes agent hooks.
