Skip to content

Hermes Plugin and Hook System

The Hermes Plugin and Hook System is an extensibility framework introduced in Hermes Agent v0.11 that transforms plugins from simple observational tools into powerful mechanisms for strategy orchestration and governance^[001-TODO__Hermes_Agent_v0.11_-结构升级与实战工作流解读.md]. By allowing the interception and transformation of internal tool calls and results, this system enables capabilities such as security policy enforcement, audit logging, and data sanitization^[001-TODO__Hermes_Agent_v0.11-_结构升级与实战工作流解读.md].

Core Architecture

The system operates on a Hook-based model, allowing code execution at specific points during the Agent's lifecycle and tool execution flow^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Lifecycle Hooks (Shell)

Shell hooks provide a low-barrier entry point for interacting with the agent's lifecycle^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

  • on-session-start: Triggered when a session initializes^[001-TODO__Hermes_Agent_v0.11_-结构升级与实战工作流解读.md]. This is useful for injecting context, such as git branch names or build numbers, into the agent's environment^[001-TODO__Hermes_Agent_v0.11-_结构升级与实战工作流解读.md].

Tool Execution Hooks

These hooks allow for fine-grained control over the tools the agent attempts to use.

  • pre-tool-call: Triggered immediately before a tool is executed^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
    • Capability: Can block or allow execution^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
    • Use Case: Governance and security. For example, a hook can analyze a command and deny it if it matches a destructive pattern like rm -rf / or DROP TABLE^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • post-tool-call: Triggered after a tool finishes execution^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
    • Use Case: Auditing and logging. Useful for recording actions or generating audit trails^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • transform_tool_result: Allows modification of the data returned from a tool^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • transform_terminal_output: Allows modification of terminal output before it is displayed to the user^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
    • Use Case: Data sanitization (e.g., desensitizing secrets or PII).

Command Registration

Plugins can extend the agent's capabilities by registering new commands^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

  • register_command: Adds custom commands to the agent's interface^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • dispatch_tool: Programmatically triggers specific tools from within a plugin^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Capabilities and Use Cases

The primary function of the hook system is to shift Hermes from a "black box" executor to a manageable platform^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Governance and Security

Organizations can implement strict control over agent behavior without modifying the core codebase^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

  • Command Blocking: Prevent the execution of fatal system commands (e.g., rm -rf, database drops)^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • Path Validation: Restrict file operations (read/write) to specific safe directories using pre-tool-call checks^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Auditing and Compliance

  • Audit Logs: The post-tool-call hook can be used to send every tool invocation to an external logging service for compliance reviews^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

Continuous Integration (CI/CD)

Hooks facilitate the integration of Hermes agents into CI/CD pipelines^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].

  • Context Injection: Use on-session-start to inject pipeline metadata (commit SHA, build ID) into the agent's context^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • Validation: Verify that protected paths or environments are not touched during execution^[001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md].
  • [[Hermes Agent v0.11]]: Overview of the architectural upgrade.
  • [[Hermes Orchestrator]]: Multi-agent delegation system that can be monitored or managed via hooks.
  • [[Hermes Transport Layer]]: The abstraction layer for model providers, which can also be managed via hooks.

Sources

  • 001-TODO__Hermes_Agent_v0.11_-_结构升级与实战工作流解读.md