What does this PR do?

This PR upgrades Hermes plugin hook orchestration to support canonical lifecycle hook names and explicit execution semantics (modifying, claiming, and observe patterns), while preserving backward compatibility for existing plugins.

It solves two core problems:

1. Hook behavior was previously implicit and mostly fire-and-forget, making advanced extension scenarios (blocking/modifying tool calls, reply interception, render-time status customization) harder to implement safely.
2. Legacy hook names were widely used by existing plugins, so introducing clearer naming needed a compatibility bridge.

This approach keeps old plugins working via alias mapping, while introducing a more structured hook runner model aligned with OpenClaw-style lifecycle phases.

Related Issue

#8642
#8643
#4169

Type of Change

• 🐛 Bug fix (non-breaking change that fixes an issue)
• ✨ New feature (non-breaking change that adds functionality)
• 🔒 Security fix
• 📝 Documentation update
• ✅ Tests (adding or improving test coverage)
• ♻️ Refactor (no behavior change)
• 🎯 New skill (bundled or hub)

Changes Made

• Added canonical plugin hook names with compatibility aliases in hermes_cli/plugins.py:
  • pre_tool_call -> before_tool_call
  • post_tool_call -> after_tool_call
  • pre_llm_call -> before_agent_start
• Added hook registration metadata with priority support (HookRegistration) in hermes_cli/plugins.py.
• Added three execution paths in hermes_cli/plugins.py:
  • invoke_hook_modifying(...) for sequential state mutation
  • invoke_hook_claiming(...) for first-handled short-circuit
  • invoke_hook_observe(...) for fire-and-forget observers
• Wired before_tool_call / after_tool_call into tool dispatch in model_tools.py:
  • supports argument mutation and optional blocking before dispatch
  • emits tool duration metadata after execution
• Wired before_agent_start, before_agent_reply, and on_context_window_update into agent lifecycle in run_agent.py.
• Wired on_status_bar_render into status text generation in cli.py so plugins can override rendered footer text.
• Updated hook reference docs in website/docs/user-guide/features/hooks.md.
• Added/updated tests:
  • tests/hermes_cli/test_plugins.py
  • tests/test_model_tools.py
  • tests/cli/test_cli_status_bar.py

Compatibility Notes

This PR is intentionally backward compatible:

• Existing plugins using legacy names (pre_tool_call, post_tool_call, pre_llm_call) continue to work unchanged via alias mapping.
• Legacy invoke_hook(...) remains available.
• New canonical names and execution paths are additive, enabling gradual plugin migration without breakage.

How to Test

1. Run targeted tests:
   • uv run python -m pytest tests/hermes_cli/test_plugins.py tests/test_model_tools.py tests/cli/test_cli_status_bar.py -q
2. Verify compatibility:
   • register a plugin hook with legacy names (e.g. pre_tool_call) and confirm it still executes.
3. Verify new behavior:
   • use before_tool_call to mutate/block args,
   • use before_agent_reply to short-circuit reply,
   • use on_status_bar_render to rewrite status bar text.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (fix(scope):, feat(scope):, etc.)
• I searched for existing PRs to make sure this isn't a duplicate
• My PR contains only changes related to this fix/feature (no unrelated commits)
• I've run pytest tests/ -q and all tests pass
• I've added tests for my changes (required for bug fixes, strongly encouraged for features)
• I've tested on my platform: macOS 15.x

Documentation & Housekeeping

• I've updated relevant documentation (README, docs/, docstrings) — or N/A
• I've updated cli-config.yaml.example if I added/changed config keys — or N/A
• I've updated CONTRIBUTING.md or AGENTS.md if I changed architecture or workflows — or N/A
• I've considered cross-platform impact (Windows, macOS) per the compatibility guide — or N/A
• I've updated tool descriptions/schemas if I changed tool behavior — or N/A

Screenshots / Logs

Targeted test run:

• 62 passed for:
  • tests/hermes_cli/test_plugins.py
  • tests/test_model_tools.py
  • tests/cli/test_cli_status_bar.py