PR #12814: feat(cli): fire on_clarify plugin hook when clarify tool runs

• Repository: NousResearch/hermes-agent
• Author: pedh
• State: open | merged: False
• Link: https://github.com/NousResearch/hermes-agent/pull/12814

Description (problem / solution / changelog)

What does this PR do?

Fires the new on_clarify plugin hook when the agent invokes the clarify tool, so plugins (e.g. a desktop-notifier) can alert the user when the agent is blocked waiting for input.

The hook is invoked inside tools/clarify_tool.py after input validation — not at the agent dispatcher — so:

• It fires only when the tool will actually block on a callback; malformed calls (empty question, missing callback, wrong choices type) short-circuit before the hook is called, so plugins don't get spurious notifications for no-op errors.
• It sees the normalized choices (stripped + trimmed to MAX_CHOICES) that the user will actually be shown, not the raw model output.
• Both the concurrent and sequential tool-dispatch paths in run_agent.py share the same fire-site by construction.

Plugin exceptions are caught and logged as warnings, never propagate to the tool.

For reference, this is the Hermes analogue of Claude Code's AskUserQuestion hook (see Claude Code hooks).

Related Issue

Fixes #12815

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

• hermes_cli/plugins.py: add on_clarify to VALID_HOOKS.
• tools/clarify_tool.py: extend signature with session_id/model/platform (default "", backward-compatible); fire on_clarify after validation and before the platform callback; propagate the new kwargs through the registry handler.
• run_agent.py: pass session_id/model/platform into clarify_tool from both the concurrent (_invoke_tool) and sequential (_execute_tool_calls_sequential) dispatch paths.
• tests/tools/test_clarify_hook.py: 7 new tests covering normalized kwargs, validation gating (empty question, missing callback, invalid choices type), hook-failure isolation, open-ended questions, and VALID_HOOKS registration.
• website/docs/user-guide/features/hooks.md: add on_clarify row to the Quick reference table and a full section with signature, fire-site, use cases, and a macOS desktop-notification example.
• website/docs/user-guide/features/plugins.md: add on_clarify to the "Available hooks" summary table.
• website/docs/guides/build-a-hermes-plugin.md: add on_clarify row (with callback signature) to the hook reference table.
• website/docs/developer-guide/agent-loop.md: note on_clarify fires from inside clarify_tool alongside the interactive-tool exception.

How to Test

1. Run the new and existing clarify tests together:

   pytest tests/tools/test_clarify_hook.py tests/tools/test_clarify_tool.py -q

   Expected: 27 passed.
2. To exercise the hook end-to-end, register a dummy plugin hook and invoke clarify:

   ctx.register_hook("on_clarify", lambda **kw: print("NOTIFY", kw["question"]))

   Then in a Hermes session ask the agent to use the clarify tool. Expected: NOTIFY ... prints before the prompt renders. Invalid args (empty question) should NOT trigger the print.
3. Confirm that plugin exceptions don't break the tool: have the hook raise RuntimeError; the tool should still collect the user's answer.

Checklist

Code

• I've read the Contributing Guide
• My commit messages follow Conventional Commits (feat(cli): ...)
• 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 (Darwin 25.4.0)

Documentation & Housekeeping

• I've updated relevant documentation — added on_clarify section in hooks.md; added rows in plugins.md, build-a-hermes-plugin.md, and a note in agent-loop.md; extended clarify_tool docstring with the new kwargs; fire-and-forget semantics noted inline.
• N/A — no config keys added.
• N/A — no architecture / workflow change.
• Cross-platform: pure-Python additions, no OS-specific code.
• N/A — tool schema for clarify unchanged; new kwargs are plumbing between agent and tool, not part of the model-facing schema.

Screenshots / Logs

$ pytest tests/tools/test_clarify_hook.py tests/tools/test_clarify_tool.py -q
...........................                                              [100%]
27 passed in 1.61s

Changed files

• hermes_cli/plugins.py (modified, +1/-0)
• run_agent.py (modified, +6/-0)
• tests/tools/test_clarify_hook.py (added, +117/-0)
• tools/clarify_tool.py (modified, +30/-1)
• website/docs/developer-guide/agent-loop.md (modified, +4/-0)
• website/docs/guides/build-a-hermes-plugin.md (modified, +1/-0)
• website/docs/user-guide/features/hooks.md (modified, +48/-0)
• website/docs/user-guide/features/plugins.md (modified, +1/-0)