Add Hermes hook support

[Mr-Lucky]

Summary

Add Hermes Agent runtime hook support for AgentGuard.

This PR introduces a Hermes shell-hook integration that maps Hermes pre_tool_call / post_tool_call payloads into AgentGuard’s existing runtime action evaluation engine.

Changes

• Add HermesAdapter for Hermes tool payloads.
• Add skills/agentguard/scripts/hermes-hook.js for Hermes shell-hook execution.
• Add SkillHub-local skills/agentguard/hermes-hooks.yaml template.
• Document Hermes setup in docs/hermes.md, README, and skills/agentguard/SKILL.md.
• Extend auto-scan to include ~/.hermes/skills.
• Add adapter tests and hook subprocess smoke tests.

Notes

Hermes pre_tool_call supports allow/block only, so AgentGuard ask decisions are represented as blocks with a confirmation-oriented message.

SkillHub users must still copy/merge the hook template into ~/.hermes/config.yaml; Hermes does not auto-load hooks from SKILL.md.

Type

• Bug fix
• [✅] New feature / detection rule
• Refactoring
• Documentation

Testing

• [✅] npm run build passes
• [✅] npm test passes (32 tests)
• Manually tested the change

Related Issues

[github-actions]

AgentGuard PR Review

The Hermes hook support introduces a few concrete regressions and security gaps.

1. high — skills/agentguard/scripts/hermes-hook.js (patch 2 hunk around loadEngine() / main())

   • What can go wrong: when the engine cannot be loaded, the hook now blocks every pre_tool_call by default. That is safer than allow-by-default, but it can break Hermes startup/tooling completely if @goplus/agentguard is missing or dist/index.js is absent. More importantly, the hook exits before even attempting to load the package for post_tool_call, so audit hooks can silently stop running whenever the engine is unavailable.
   • Fix: make the fail-closed behavior explicit per hook type and keep post_tool_call audit handling separate from enforcement. If the engine is unavailable, emit a clear stderr error and preserve post-tool_call logging if possible, or document/validate the required package installation before enabling hooks.

2. medium — skills/agentguard/scripts/hermes-hook.js and src/adapters/hermes.ts

   • What can go wrong: browser_* support is inconsistent. The docs/templates originally matched browser_.*, but the hardened patch narrows this to only browser_navigate, while the adapter now rejects browser_click, browser_type, browser_get_images, and browser_vision. If Hermes emits those tool names, AgentGuard will now block them as “unrecognized” even when they are benign/read-only in some workflows, causing unexpected breakage.
   • Fix: either fully enumerate and support all Hermes browser tools in both the hook matcher and adapter mapping, or explicitly document that only browser_navigate is supported and add compatibility checks so other browser tools are not silently misclassified.

3. medium — skills/agentguard/scripts/hermes-hook.js (patch 2 hunk around validatePreToolPayload())

   • What can go wrong: the hook now rejects any pre-tool payload that does not exactly match expected fields. If Hermes changes payload shape or omits fields for valid requests, the hook blocks execution. This is a correctness regression that can turn harmless actions into denial-of-service for the agent.
   • Fix: validate only the fields required for a given tool when they are present, and fall back to AgentGuard policy evaluation instead of hard-failing on every schema deviation. At minimum, gate the strict validation behind a Hermes-versioned contract check.