hooks.py 2.0 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445
  1. """``hermes hooks`` subcommand parser."""
  2. from __future__ import annotations
  3. from typing import Callable
  4. def build_hooks_parser(subparsers, *, cmd_hooks: Callable) -> None:
  5. """Attach the ``hooks`` subcommand to ``subparsers``."""
  6. hooks_parser = subparsers.add_parser(
  7. "hooks", help="Inspect and manage shell-script hooks",
  8. description="Inspect shell-script hooks declared in ~/.hermes/config.yaml, "
  9. "test them against synthetic payloads, and manage the first-use "
  10. "consent allowlist at ~/.hermes/shell-hooks-allowlist.json.")
  11. hooks_subparsers = hooks_parser.add_subparsers(dest="hooks_action")
  12. hooks_subparsers.add_parser(
  13. "list", aliases=["ls"],
  14. help="List configured hooks with matcher, timeout, and consent status")
  15. _hk_test = hooks_subparsers.add_parser(
  16. "test", help="Fire every hook matching <event> against a synthetic payload")
  17. _hk_test.add_argument(
  18. "event", help="Hook event name (e.g. pre_tool_call, pre_llm_call, subagent_stop)")
  19. _hk_test.add_argument(
  20. "--for-tool", dest="for_tool", default=None,
  21. help="Only fire hooks whose matcher matches this tool name "
  22. "(used for pre_tool_call / post_tool_call)")
  23. _hk_test.add_argument(
  24. "--payload-file", dest="payload_file", default=None,
  25. help="Path to a JSON file whose contents are merged into the "
  26. "synthetic payload before execution")
  27. _hk_revoke = hooks_subparsers.add_parser(
  28. "revoke", aliases=["remove", "rm"],
  29. help="Remove a command's allowlist entries (a running gateway drops it within about 30 seconds)")
  30. _hk_revoke.add_argument(
  31. "command", help="The exact command string to revoke (as declared in config.yaml)")
  32. hooks_subparsers.add_parser(
  33. "doctor",
  34. help="Check each configured hook: exec bit, allowlist, mtime drift, "
  35. "JSON validity, and synthetic run timing")
  36. hooks_parser.set_defaults(func=cmd_hooks)