hooks.py 16 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353
  1. """hermes hooks — inspect and manage shell-script hooks."""
  2. from __future__ import annotations
  3. import json
  4. from pathlib import Path
  5. from typing import Any, Dict, List
  6. def hooks_command(args) -> None:
  7. """Entry point for ``hermes hooks`` — dispatches to the requested action."""
  8. sub = getattr(args, "hooks_action", None)
  9. if not sub:
  10. print("Usage: hermes hooks {list|test|revoke|doctor}")
  11. print("Run 'hermes hooks --help' for details.")
  12. return
  13. handler = _ACTIONS.get(sub)
  14. if handler is None:
  15. print(f"Unknown hooks subcommand: {sub}")
  16. return
  17. handler(args)
  18. # ---------------------------------------------------------------------------
  19. # list
  20. # ---------------------------------------------------------------------------
  21. def _cmd_list(_args) -> None:
  22. from hermes_cli.config import load_config
  23. from agent import outbound_webhooks, shell_hooks
  24. cfg = load_config()
  25. specs = shell_hooks.iter_configured_hooks(cfg)
  26. outbound = outbound_webhooks.iter_configured_targets(cfg)
  27. if not specs and not outbound:
  28. print("No shell hooks or outbound webhooks configured in ~/.hermes/config.yaml.")
  29. print("See `hermes hooks --help` or")
  30. print(" website/docs/user-guide/features/hooks.md")
  31. print("for the config schema and worked examples.")
  32. return
  33. if not specs:
  34. print("No shell hooks configured in ~/.hermes/config.yaml.")
  35. else:
  36. by_event: dict[str, list] = {}
  37. for spec in specs:
  38. by_event.setdefault(spec.event, []).append(spec)
  39. approved = shell_hooks.allowlisted_pairs()
  40. print(f"Configured shell hooks ({len(specs)} total):\n")
  41. for event in sorted(by_event):
  42. print(f" [{event}]")
  43. for spec in by_event[event]:
  44. is_approved = (spec.event, spec.command) in approved
  45. status = "✓ allowed" if is_approved else "✗ not allowlisted"
  46. print(f" - {spec.command}{_matcher_part(spec)} (timeout={spec.timeout}s, {status})")
  47. entry = shell_hooks.allowlist_entry_for(spec.event, spec.command) if is_approved else None
  48. if entry and entry.get("approved_at"):
  49. print(f" approved_at: {entry['approved_at']}")
  50. drift, mtime_at, mtime_now = _mtime_drift(shell_hooks, spec, entry)
  51. if drift is True:
  52. print(
  53. f" ⚠ script modified since approval "
  54. f"(was {mtime_at}, now {mtime_now}) — "
  55. f"run `hermes hooks doctor` to re-validate"
  56. )
  57. print()
  58. if outbound:
  59. print(f"Configured outbound webhooks ({len(outbound)} total):\n")
  60. for target in outbound:
  61. signed = "signed" if target.secret else "UNSIGNED"
  62. print(f" - {target.label}")
  63. print(f" url: {target.url}")
  64. print(f" events: {', '.join(target.events)}{_matcher_part(target)} (timeout={target.timeout}s, {signed})")
  65. print()
  66. def _matcher_part(obj) -> str:
  67. return f" matcher={obj.matcher!r}" if obj.matcher else ""
  68. def _mtime_drift(shell_hooks, spec, entry) -> tuple[bool | None, str, str]:
  69. """``(drift, mtime_at, mtime_now)``: True if the script changed since approval, False if
  70. unchanged, None when either mtime is unknown."""
  71. mtime_now = shell_hooks.script_mtime_iso(spec.command)
  72. mtime_at = entry.get("script_mtime_at_approval")
  73. if not (mtime_now and mtime_at):
  74. return None, mtime_at, mtime_now
  75. if mtime_now > mtime_at:
  76. return True, mtime_at, mtime_now
  77. return (False if mtime_now == mtime_at else None), mtime_at, mtime_now
  78. # ---------------------------------------------------------------------------
  79. # test
  80. # ---------------------------------------------------------------------------
  81. # Synthetic kwargs matching the real invoke_hook() call sites. They go verbatim to
  82. # agent.shell_hooks.run_once() -> the same _serialize_payload() production uses, so the
  83. # stdin a script sees under `hooks test` / `hooks doctor` has the runtime shape.
  84. _DEFAULT_PAYLOADS = {
  85. "pre_tool_call": {
  86. "tool_name": "terminal", "args": {"command": "echo hello"},
  87. "session_id": "test-session", "task_id": "test-task", "tool_call_id": "test-call",
  88. },
  89. "post_tool_call": {
  90. "tool_name": "terminal", "args": {"command": "echo hello"},
  91. "session_id": "test-session", "task_id": "test-task", "tool_call_id": "test-call",
  92. "result": '{"output": "hello"}', "duration_ms": 42,
  93. },
  94. "pre_llm_call": {
  95. "session_id": "test-session", "user_message": "What is the weather?",
  96. "conversation_history": [], "is_first_turn": True, "model": "gpt-4", "platform": "cli",
  97. },
  98. "post_llm_call": {"session_id": "test-session", "model": "gpt-4", "platform": "cli"},
  99. "pre_verify": {
  100. "session_id": "test-session", "platform": "cli", "model": "gpt-4", "coding": True,
  101. "attempt": 0, "final_response": "All done — the change is applied.",
  102. "changed_paths": ["src/app.tsx"],
  103. },
  104. "on_session_start": {"session_id": "test-session"},
  105. "on_session_end": {
  106. "session_id": "test-session", "task_id": "test-task", "turn_id": "test-turn",
  107. "completed": True, "failed": False, "interrupted": False,
  108. "turn_exit_reason": "text_response(stop)", "model": "gpt-4", "platform": "cli",
  109. },
  110. "on_session_finalize": {"session_id": "test-session"},
  111. "on_session_reset": {"session_id": "test-session"},
  112. "on_session_delete": {"session_id": "test-session", "reason": "delete", "profile": "default"},
  113. "pre_api_request": {
  114. "session_id": "test-session", "task_id": "test-task", "platform": "cli",
  115. "model": "claude-sonnet-4-6", "provider": "anthropic",
  116. "base_url": "https://api.anthropic.com", "api_mode": "anthropic_messages",
  117. "api_call_count": 1, "message_count": 4, "tool_count": 12,
  118. "approx_input_tokens": 2048, "request_char_count": 8192, "max_tokens": 4096,
  119. },
  120. "post_api_request": {
  121. "session_id": "test-session", "task_id": "test-task", "platform": "cli",
  122. "model": "claude-sonnet-4-6", "provider": "anthropic",
  123. "base_url": "https://api.anthropic.com", "api_mode": "anthropic_messages",
  124. "api_call_count": 1, "api_duration": 1.234,
  125. "started_at": 1756000000.0, "ended_at": 1756000001.234, "first_chunk_at": 1756000000.512,
  126. "finish_reason": "stop", "message_count": 4, "response_model": "claude-sonnet-4-6",
  127. "usage": {"input_tokens": 2048, "output_tokens": 512}, "context_length": 200000,
  128. "assistant_content_chars": 1200, "assistant_tool_call_count": 0,
  129. # Per-advisor metrics on a MoA turn, None otherwise: MoA returns only the aggregator's
  130. # response, so without this an observer cannot see or price the fan-out.
  131. "moa_references": None,
  132. },
  133. "pre_auxiliary_call": {
  134. "aux_task": "title_generation", "session_id": "test-session", "task_id": "test-task",
  135. "turn_id": "test-turn", "api_request_id": "aux-0123abcd", "platform": "cli",
  136. "model": "claude-haiku-4-5", "provider": "anthropic",
  137. "base_url": "https://api.anthropic.com", "api_mode": "anthropic_messages",
  138. "api_call_count": 1, "retry_count": 0, "streaming": False, "message_count": 2,
  139. "tool_count": 0, "approx_input_tokens": 256, "request_char_count": 1024, "max_tokens": 64,
  140. },
  141. "post_auxiliary_call": {
  142. "aux_task": "title_generation", "session_id": "test-session", "task_id": "test-task",
  143. "turn_id": "test-turn", "api_request_id": "aux-0123abcd", "platform": "cli",
  144. "model": "claude-haiku-4-5", "provider": "anthropic",
  145. "base_url": "https://api.anthropic.com", "api_mode": "anthropic_messages",
  146. "api_call_count": 1, "retry_count": 0, "streaming": False, "api_duration": 0.42,
  147. "started_at": 1756000000.0, "ended_at": 1756000000.42, "finish_reason": "stop",
  148. "response_model": "claude-haiku-4-5", "usage": {"input_tokens": 256, "output_tokens": 12},
  149. "assistant_content_chars": 40, "assistant_tool_call_count": 0, "error": None, "error_type": None,
  150. },
  151. "subagent_stop": {
  152. "parent_session_id": "parent-sess", "child_role": None,
  153. "child_summary": "Synthetic summary for hooks test", "child_status": "completed",
  154. "tool_call_history": [{
  155. "tool_name": "write_file",
  156. "tool_input": {"argument_keys": ["content", "path"], "targets": {"path": "notes/report.txt"}},
  157. "input_bytes": 128, "output_bytes": 32, "status": "ok",
  158. }],
  159. "duration_ms": 1234,
  160. },
  161. }
  162. def _cmd_test(args) -> None:
  163. from hermes_cli.config import load_config
  164. from hermes_cli.plugins import VALID_HOOKS
  165. from agent import shell_hooks
  166. event = args.event
  167. if event not in VALID_HOOKS:
  168. print(f"Unknown event: {event!r}")
  169. print(f"Valid events: {', '.join(sorted(VALID_HOOKS))}")
  170. return
  171. # Synthetic kwargs merged with --for-tool (overrides tool_name) and --payload-file (extra kwargs).
  172. payload = dict(_DEFAULT_PAYLOADS.get(event, {"session_id": "test-session"}))
  173. for_tool = getattr(args, "for_tool", None)
  174. if for_tool:
  175. payload["tool_name"] = for_tool
  176. if getattr(args, "payload_file", None):
  177. try:
  178. custom = json.loads(Path(args.payload_file).read_text(encoding="utf-8-sig"))
  179. if isinstance(custom, dict):
  180. payload.update(custom)
  181. else:
  182. print(f"Warning: {args.payload_file} is not a JSON object; ignoring")
  183. except Exception as exc:
  184. print(f"Error reading payload file: {exc}")
  185. return
  186. specs = [s for s in shell_hooks.iter_configured_hooks(load_config()) if s.event == event]
  187. if for_tool:
  188. specs = [s for s in specs if s.event not in {"pre_tool_call", "post_tool_call"} or s.matches_tool(for_tool)]
  189. if not specs:
  190. print(f"No shell hooks configured for event: {event}")
  191. if for_tool:
  192. print(f"(with matcher filter --for-tool={for_tool})")
  193. return
  194. print(f"Firing {len(specs)} hook(s) for event '{event}':\n")
  195. for spec in specs:
  196. print(f" → {spec.command}")
  197. _print_run_result(shell_hooks.run_once(spec, payload))
  198. print()
  199. def _print_run_result(result: dict[str, Any]) -> None:
  200. if result.get("error"):
  201. print(f" ✗ error: {result['error']}")
  202. elif result.get("timed_out"):
  203. print(f" ✗ timed out after {result['elapsed_seconds']}s")
  204. else:
  205. print(f" exit={result.get('returncode')} elapsed={result.get('elapsed_seconds', 0)}s")
  206. for stream in ("stdout", "stderr"):
  207. text = (result.get(stream) or "").strip()
  208. if text:
  209. print(f" {stream}: {_truncate(text, 400)}")
  210. # run_once always sets ``parsed`` (agent/shell_hooks.py::_evaluate_result), so it is available even
  211. # when the hook errored or timed out. A failing hook's decision is the one thing `hooks test` exists
  212. # to show — failed-open and failed-closed must not render identically (#115968).
  213. parsed = result.get("parsed")
  214. if parsed:
  215. print(f" parsed (Hermes wire shape): {json.dumps(parsed)}")
  216. else:
  217. print(" parsed: <none — hook contributed nothing to the dispatcher>")
  218. def _truncate(s: str, n: int) -> str:
  219. return s if len(s) <= n else s[: n - 3] + "..."
  220. # ---------------------------------------------------------------------------
  221. # revoke / doctor
  222. # ---------------------------------------------------------------------------
  223. def _cmd_revoke(args) -> None:
  224. from agent import shell_hooks
  225. removed = shell_hooks.revoke(args.command)
  226. if removed == 0:
  227. print(f"No allowlist entry found for command: {args.command}")
  228. return
  229. print(f"Removed {removed} allowlist entry/entries for: {args.command}")
  230. print(
  231. "Note: a running gateway stops running it within about 30 seconds (unless "
  232. "--accept-hooks / HERMES_ACCEPT_HOOKS / hooks_auto_accept approves every hook there); "
  233. "other running processes keep it until they restart."
  234. )
  235. def _cmd_doctor(_args) -> None:
  236. from hermes_cli.config import load_config
  237. from agent import shell_hooks
  238. specs = shell_hooks.iter_configured_hooks(load_config())
  239. if not specs:
  240. print("No shell hooks configured — nothing to check.")
  241. return
  242. print(f"Checking {len(specs)} configured shell hook(s)...\n")
  243. problems = 0
  244. for spec in specs:
  245. print(f" [{spec.event}] {spec.command}")
  246. problems += _doctor_one(spec, shell_hooks)
  247. print()
  248. print(f"{problems} issue(s) found. Fix before relying on these hooks." if problems else "All shell hooks look healthy.")
  249. def _doctor_one(spec, shell_hooks) -> int:
  250. problems = 0
  251. # 1. Script exists and is executable
  252. if shell_hooks.script_is_executable(spec.command):
  253. print(" ✓ script exists and is executable")
  254. else:
  255. problems += 1
  256. print(" ✗ script missing or not executable "
  257. "(chmod +x the file, or fix the path)")
  258. # 2. Allowlist status
  259. entry = shell_hooks.allowlist_entry_for(spec.event, spec.command)
  260. if entry:
  261. print(f" ✓ allowlisted (approved {entry.get('approved_at', '?')})")
  262. else:
  263. problems += 1
  264. print(" ✗ not allowlisted — hook will NOT fire at runtime "
  265. "(run with --accept-hooks once, or confirm at the TTY prompt)")
  266. # 3. Mtime drift
  267. if entry and entry.get("script_mtime_at_approval"):
  268. drift, mtime_at, mtime_now = _mtime_drift(shell_hooks, spec, entry)
  269. if drift is True:
  270. problems += 1
  271. print(f" ⚠ script modified since approval "
  272. f"(was {mtime_at}, now {mtime_now}) — review changes, "
  273. f"then `hermes hooks revoke` + re-approve to refresh")
  274. elif drift is False:
  275. print(" ✓ script unchanged since approval")
  276. # 4. JSON smoke test on a synthetic payload — ONLY when already allowlisted. Otherwise doctor
  277. # would execute every script in a freshly-pulled config before the user reviewed it, which
  278. # contradicts the documented workflow ("spot newly-added hooks *before they register*").
  279. if not entry:
  280. print(" ℹ skipped JSON smoke test — not allowlisted yet. "
  281. "Approve the hook first (via TTY prompt or --accept-hooks), "
  282. "then re-run `hermes hooks doctor`.")
  283. elif shell_hooks.script_is_executable(spec.command):
  284. result = shell_hooks.run_once(spec, _DEFAULT_PAYLOADS.get(spec.event, {"extra": {}}))
  285. if result.get("timed_out"):
  286. problems += 1
  287. print(f" ✗ timed out after {result['elapsed_seconds']}s "
  288. f"on synthetic payload (timeout={spec.timeout}s)")
  289. elif result.get("error"):
  290. problems += 1
  291. print(f" ✗ execution error: {result['error']}")
  292. else:
  293. rc = result.get("returncode")
  294. elapsed = result.get("elapsed_seconds", 0)
  295. stdout = (result.get("stdout") or "").strip()
  296. if not stdout:
  297. print(f" ✓ ran clean with empty stdout "
  298. f"(exit={rc}, {elapsed}s) — hook is observer-only")
  299. else:
  300. try:
  301. json.loads(stdout)
  302. print(f" ✓ produced valid JSON on synthetic payload "
  303. f"(exit={rc}, {elapsed}s)")
  304. except json.JSONDecodeError:
  305. problems += 1
  306. print(f" ✗ stdout was not valid JSON (exit={rc}, "
  307. f"{elapsed}s): {_truncate(stdout, 120)}")
  308. return problems
  309. _ACTIONS = {
  310. "list": _cmd_list, "ls": _cmd_list,
  311. "test": _cmd_test,
  312. "revoke": _cmd_revoke, "remove": _cmd_revoke, "rm": _cmd_revoke,
  313. "doctor": _cmd_doctor,
  314. }