shell_hooks.py 42 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858
  1. """Shell-script hooks bridge: ``hooks:`` config → first-use consent per ``(event, command)`` →
  2. callbacks on the plugin hook manager, so every ``invoke_hook()`` site dispatches to the scripts.
  3. Wire: stdin JSON ``{hook_event_name, tool_name, tool_input, session_id, cwd, extra}``; optional stdout
  4. JSON ``{"decision"|"action": "block"|"modify", ...}`` / ``{"context": ...}`` via ``_parse_response``.
  5. Exit code 2 blocks a ``pre_tool_call`` even without JSON (Claude-Code / Cursor). Fail open unless ``fail_closed``."""
  6. from __future__ import annotations
  7. import difflib
  8. import json
  9. import logging
  10. import os
  11. import re
  12. import subprocess
  13. import sys
  14. import threading
  15. import time
  16. from contextlib import ExitStack, contextmanager, suppress
  17. from dataclasses import dataclass, field
  18. from datetime import datetime, timezone, UTC
  19. from pathlib import Path
  20. from typing import Any, Callable, Dict, Iterator, List, Optional, Set, Tuple
  21. # split_command_line, not shlex: shlex eats Windows path backslashes.
  22. from hermes_cli._subprocess_compat import IS_WINDOWS, kill_process_tree, split_command_line, windows_hide_flags
  23. try:
  24. import fcntl # POSIX only; Windows falls back to best-effort without flock.
  25. except ImportError: # pragma: no cover
  26. fcntl = None # type: ignore[assignment]
  27. from hermes_constants import get_hermes_home
  28. from utils import atomic_json_write
  29. logger = logging.getLogger(__name__)
  30. DEFAULT_TIMEOUT_SECONDS = 60
  31. MAX_TIMEOUT_SECONDS = 300
  32. ALLOWLIST_FILENAME = "shell-hooks-allowlist.json"
  33. _DEFAULT_BLOCK_MESSAGE = "Blocked by shell hook."
  34. # Exit code that signals "block this action" independent of stdout (Claude Code / Cursor).
  35. BLOCK_EXIT_CODE = 2
  36. # Events whose block directive is honored downstream; exit-2 blocking and fail_closed only apply here.
  37. _BLOCKING_EVENTS = frozenset({"pre_tool_call"})
  38. _TOOL_EVENTS = frozenset({"pre_tool_call", "post_tool_call"})
  39. _STDERR_MESSAGE_LIMIT = 400
  40. _TRUTHY = {"1", "true", "yes", "on"}
  41. # kwargs promoted to top-level payload keys; everything else lands under ``extra``.
  42. _TOP_LEVEL_PAYLOAD_KEYS = {"tool_name", "args", "session_id", "parent_session_id"}
  43. # (home, event, matcher, command) wired in this process: matcher in the key (one script may register
  44. # per-tool under one event), home so multiplexed-gateway profiles can register identical triples.
  45. _registered: set[tuple[str, str, Optional[str], str]] = set()
  46. _registered_lock = threading.Lock()
  47. # Non-POSIX fallback for allowlist read-modify-write; separate from _registered_lock so an allowlist
  48. # write never waits on (or nests inside) a registry update.
  49. _allowlist_write_lock = threading.Lock()
  50. # sync_from_config: read + apply as one step, so an older snapshot never lands after a newer one.
  51. _sync_lock = threading.Lock()
  52. # Consent that lives only in this process (guarded by _sync_lock): (home, event, command) a launch's
  53. # --accept-hooks approved but the allowlist does not hold yet, this process's own --accept-hooks, and
  54. # the skipped hooks already logged.
  55. _launch_consent: set[tuple[str, str, str]] = set()
  56. _process_accept = False
  57. _skip_logged: set[tuple[str, str, str]] = set()
  58. def _home_key() -> str:
  59. return str(get_hermes_home().expanduser().resolve())
  60. def _forget_home_registrations(registry: set[tuple], lock: threading.Lock) -> None:
  61. """Drop the current home's keys only (shared with outbound webhooks): profile A's reload must not drop B."""
  62. home_key = _home_key()
  63. with lock:
  64. registry.difference_update({k for k in registry if k[0] == home_key})
  65. def _entry_matches(e: Any, event: Optional[str], command: str) -> bool:
  66. return isinstance(e, dict) and (event is None or e.get("event") == event) and e.get("command") == command
  67. def _utc_now_iso() -> str:
  68. return datetime.now(tz=UTC).isoformat().replace("+00:00", "Z")
  69. def _payload_fields(kwargs: dict[str, Any]) -> dict[str, Any]:
  70. """Common stdin/POST payload fields (shared with outbound webhooks); key order is wire order."""
  71. try:
  72. cwd = str(Path.cwd())
  73. except OSError:
  74. cwd = ""
  75. from hermes_cli.profiles import get_active_profile_name
  76. from agent.delegation_context import owned_kanban_task
  77. extra = {k: v for k, v in kwargs.items() if k not in _TOP_LEVEL_PAYLOAD_KEYS}
  78. # Resolve in the firing execution before the descendant environment is scrubbed.
  79. # This is payload metadata, never permission for the hook to act as the worker.
  80. extra["kanban_task_id"] = owned_kanban_task()
  81. return {
  82. "tool_name": kwargs.get("tool_name"),
  83. "tool_input": kwargs.get("args") if isinstance(kwargs.get("args"), dict) else None,
  84. "session_id": kwargs.get("session_id") or kwargs.get("parent_session_id") or "",
  85. "cwd": cwd,
  86. # Resolved at fire time: a multiplexed gateway's hook script must know which profile fired it.
  87. "profile": get_active_profile_name(),
  88. "extra": extra,
  89. }
  90. class _ToolMatcherMixin:
  91. """``matcher`` regex handling shared by shell-hook specs and outbound webhook targets."""
  92. _MATCHER_KIND = "shell hook"
  93. matcher: Optional[str]
  94. compiled_matcher: Optional[re.Pattern]
  95. def __post_init__(self) -> None:
  96. # Strip YAML folding whitespace — " terminal" would silently never match.
  97. if isinstance(self.matcher, str):
  98. self.matcher = self.matcher.strip() or None
  99. if self.matcher:
  100. try:
  101. self.compiled_matcher = re.compile(self.matcher)
  102. except re.error as exc:
  103. logger.warning(
  104. "%s matcher %r is invalid (%s) — treating as literal equality", self._MATCHER_KIND, self.matcher, exc,
  105. )
  106. self.compiled_matcher = None
  107. def matches_tool(self, tool_name: Optional[str]) -> bool:
  108. if not self.matcher:
  109. return True
  110. if tool_name is None:
  111. return False
  112. if self.compiled_matcher is None: # regex failed to compile: literal fallback
  113. return tool_name == self.matcher
  114. return self.compiled_matcher.fullmatch(tool_name) is not None
  115. @dataclass
  116. class ShellHookSpec(_ToolMatcherMixin):
  117. """Parsed and validated representation of a single ``hooks:`` entry."""
  118. event: str
  119. command: str
  120. matcher: Optional[str] = None
  121. timeout: int = DEFAULT_TIMEOUT_SECONDS
  122. fail_closed: bool = False
  123. compiled_matcher: Optional[re.Pattern] = field(default=None, repr=False)
  124. # --- Public API ---
  125. def register_from_config(cfg: Optional[dict[str, Any]], *, accept_hooks: bool = False,
  126. interactive: bool = False) -> list[ShellHookSpec]:
  127. """Register every configured shell hook (idempotent); returns the newly wired specs. Skipped
  128. entries (unknown, malformed, not allowlisted, already registered) are logged only.
  129. ``interactive=True`` lets a hook that is not yet allowlisted ask at the terminal; only a
  130. foreground CLI command passes it. Every other caller (gateway startup and profile loads, cron
  131. and managed workers, tui_gateway, force-reload re-registration) never prompts: ``isatty()``
  132. cannot tell a hidden console or ``NUL`` from a person, and a prompt there blocks the event loop
  133. until the liveness watchdog kills the gateway (#120356, #127822)."""
  134. specs, _complete = _hook_specs(cfg)
  135. if not specs:
  136. return []
  137. from hermes_cli.plugins import get_plugin_manager # lazy: avoids import cycle
  138. manager, home_key = get_plugin_manager(), _home_key()
  139. with _registered_lock: # an already-wired hook is never re-asked for (main checked this first)
  140. specs = [spec for spec in specs if _key(home_key, spec) not in _registered]
  141. accept, allowed = _resolve_effective_accept(cfg, accept_hooks), allowlisted_pairs()
  142. # TTY prompt outside the lock; _wire takes the lock and re-checks.
  143. consented = []
  144. for spec in specs:
  145. if _consented(spec, accept, allowed, prompt=interactive):
  146. consented.append(spec)
  147. else:
  148. logger.warning("shell hook for %s (%s) not allowlisted in %s — skipped. Use --accept-hooks / "
  149. "HERMES_ACCEPT_HOOKS=1 / hooks_auto_accept: true, or approve it at a CLI prompt "
  150. "for this profile.", spec.event, spec.command, allowlist_path())
  151. with _registered_lock:
  152. return _wire(manager, home_key, consented)
  153. def sync_from_config(load_cfg: Callable[[], dict[str, Any]]) -> None:
  154. """Bring this home's registered shell hooks in step with its config (``load_cfg()``) and
  155. consent, for a long-lived process (the gateway) that must behave as a new process would: hooks
  156. configured and consented since start register, hooks removed from config or revoked are
  157. unregistered. Consent is the allowlist, an opt-in in force (``hooks_auto_accept`` /
  158. ``HERMES_ACCEPT_HOOKS`` / this process's own ``--accept-hooks``), or a launch's ``--accept-hooks``
  159. whose allowlist write failed (``accept_for_launch``). Never prompts or writes. An empty config
  160. (a loader that failed open), a malformed ``hooks:`` entry or an unreadable allowlist must never
  161. disarm a ``fail_closed`` guard, so each adds but never removes. Config and allowlist are read
  162. under the same lock as the apply, so the last sync to run always applies the newest state."""
  163. from hermes_cli.plugins import get_plugin_manager # lazy: avoids import cycle
  164. with _sync_lock:
  165. cfg = load_cfg()
  166. specs, complete = _hook_specs(cfg)
  167. if specs is None or not cfg:
  168. return
  169. allowlist, readable = _read_allowlist()
  170. allowed = _approved_pairs(allowlist["approvals"])
  171. home_key = _home_key()
  172. # A launch approval the allowlist now holds is the allowlist's to keep (or revoke).
  173. _launch_consent.difference_update({(home_key, *pair) for pair in allowed})
  174. allowed |= {(event, command) for home, event, command in _launch_consent if home == home_key}
  175. accept = _resolve_effective_accept(cfg, False)
  176. wanted = []
  177. for spec in specs:
  178. if accept or (spec.event, spec.command) in allowed:
  179. wanted.append(spec)
  180. elif (home_key, spec.event, spec.command) not in _skip_logged: # once per process, not per open
  181. _skip_logged.add((home_key, spec.event, spec.command))
  182. logger.warning("shell hook for %s (%s) not allowlisted in %s — skipped. Approve it at a CLI "
  183. "prompt for this profile, or use --accept-hooks / HERMES_ACCEPT_HOOKS=1 / "
  184. "hooks_auto_accept: true.", spec.event, spec.command, allowlist_path())
  185. manager = get_plugin_manager()
  186. with _registered_lock:
  187. _wire(manager, home_key, wanted)
  188. if not (readable and complete):
  189. suspended = (home_key, "", "removal")
  190. if suspended not in _skip_logged:
  191. _skip_logged.add(suspended)
  192. logger.warning("shell hooks: %s, so removed or revoked hooks stay registered until it is "
  193. "fixed", "the allowlist is unreadable" if not readable
  194. else "a hooks: entry in config.yaml is malformed")
  195. return
  196. # In-memory consent ends with the hook's config entry, so a removed-and-re-added hook asks again.
  197. configured = {(home_key, spec.event, spec.command) for spec in specs}
  198. _launch_consent.difference_update({c for c in _launch_consent if c[0] == home_key and c not in configured})
  199. keep = {_key(home_key, spec) for spec in wanted}
  200. stale = {k for k in _registered if k[0] == home_key and k not in keep}
  201. _registered.difference_update(stale)
  202. for event in {k[1] for k in stale}:
  203. # Replaced, never edited in place: a concurrent invoke_hook keeps iterating the old list.
  204. manager._hooks[event] = [cb for cb in manager._hooks.get(event, [])
  205. if getattr(cb, "shell_hook_key", None) not in stale]
  206. for _home, event, _matcher, command in stale:
  207. logger.info("shell hook unregistered (removed from config or allowlist): %s -> %s", event, command)
  208. def record_consent_from_config(cfg: Optional[dict[str, Any]], *, accept_hooks: bool = False) -> list[ShellHookSpec]:
  209. """First-use consent without registering anything, for a client whose turns run in a gateway that
  210. has no TTY: the prompt (or an opt-in) for each configured hook not yet allowlisted. The gateway
  211. registers from the same allowlist when the client opens its session. Returns the consented specs."""
  212. specs, _complete = _hook_specs(cfg)
  213. if not specs:
  214. return []
  215. accept, allowed = _resolve_effective_accept(cfg, accept_hooks), allowlisted_pairs()
  216. return [spec for spec in specs if _consented(spec, accept, allowed, prompt=True)]
  217. def accept_for_launch(cfg: Optional[dict[str, Any]]) -> None:
  218. """A launch's ``--accept-hooks`` on the gateway: record every configured hook in the allowlist,
  219. and keep the consent in memory when that write fails, so it still registers
  220. the hook at the next ``sync_from_config`` (main registered it in memory). Only an unsaved approval
  221. is held, so a later ``hermes hooks revoke`` of a saved one takes effect."""
  222. specs = record_consent_from_config(cfg, accept_hooks=True)
  223. if not specs:
  224. return
  225. saved, home_key = allowlisted_pairs(), _home_key()
  226. with _sync_lock:
  227. _launch_consent.update((home_key, spec.event, spec.command) for spec in specs
  228. if (spec.event, spec.command) not in saved)
  229. def accept_for_process() -> None:
  230. """This process's own ``--accept-hooks`` (``hermes gateway run --accept-hooks``): an opt-in in
  231. force for its lifetime, as ``HERMES_ACCEPT_HOOKS`` would be, without exporting that variable to
  232. every tool subprocess."""
  233. global _process_accept
  234. _process_accept = True
  235. def _hook_specs(cfg: Optional[dict[str, Any]]) -> tuple[Optional[list[ShellHookSpec]], bool]:
  236. """``(specs, complete)``: the configured hooks, or ``None`` when this process must run none
  237. (safe worker, safe mode, no config) — the one guard every registrar and the consent path share;
  238. ``complete`` is False when a configured entry was dropped as malformed."""
  239. from agent.safe_worker_policy import safe_worker_enabled
  240. from utils import env_var_enabled
  241. if safe_worker_enabled() or not isinstance(cfg, dict):
  242. return None, True
  243. if env_var_enabled("HERMES_SAFE_MODE"): # hooks are user customizations too — fire zero user-configured code
  244. logger.info("HERMES_SAFE_MODE=1 — shell-hook registration skipped")
  245. return None, True
  246. return _parse_hooks(cfg.get("hooks"))
  247. def _key(home_key: str, spec: ShellHookSpec) -> tuple[str, str, Optional[str], str]:
  248. return (home_key, spec.event, spec.matcher, spec.command)
  249. def _wire(manager: Any, home_key: str, specs: list[ShellHookSpec]) -> list[ShellHookSpec]:
  250. """Register ``specs`` not yet wired for this home; caller holds ``_registered_lock``."""
  251. registered = []
  252. for spec in specs:
  253. key = _key(home_key, spec)
  254. if key in _registered:
  255. continue
  256. callback = _make_callback(spec)
  257. callback.shell_hook_key = key # type: ignore[attr-defined] # identifies it for sync_from_config
  258. manager._hooks.setdefault(spec.event, []).append(callback)
  259. _registered.add(key)
  260. registered.append(spec)
  261. logger.info("shell hook registered: %s -> %s (matcher=%s, timeout=%ds, fail_closed=%s)",
  262. spec.event, spec.command, spec.matcher, spec.timeout, spec.fail_closed)
  263. return registered
  264. def _approved_pairs(approvals: list[Any]) -> set[tuple[str, str]]:
  265. return {(e["event"], e["command"]) for e in approvals
  266. if isinstance(e, dict) and isinstance(e.get("event"), str) and isinstance(e.get("command"), str)}
  267. def allowlisted_pairs() -> set[tuple[str, str]]:
  268. return _approved_pairs(load_allowlist()["approvals"])
  269. def _consented(spec: ShellHookSpec, accept: bool, allowed: set[tuple[str, str]], *, prompt: bool) -> bool:
  270. """Allowlisted, or approved now (opt-in, or a TTY prompt when ``prompt``; recorded); ``allowed``
  271. caches one read."""
  272. pair = (spec.event, spec.command)
  273. if pair in allowed:
  274. return True
  275. if not (accept or prompt):
  276. return False
  277. if not _prompt_and_record(spec.event, spec.command, accept_hooks=accept):
  278. return False
  279. allowed.add(pair)
  280. return True
  281. def iter_configured_hooks(cfg: Optional[dict[str, Any]]) -> list[ShellHookSpec]:
  282. """Parse config hooks without registering (``hermes hooks list`` / doctor)."""
  283. return _parse_hooks_block(cfg.get("hooks")) if isinstance(cfg, dict) else []
  284. def re_register_config_hooks() -> None:
  285. """Re-register after a plugin force-reload cleared the manager's hooks; only this home's keys
  286. are cleared (profile A's reload never drops B), never re-prompts.
  287. ``PluginManager.discover_and_load(force=True)`` unloads via the ownership ledger and clears the
  288. manager's ``_hooks`` dict, which silently drops shell hooks that were registered from ``config.yaml`` at
  289. startup (they are config-owned, not plugin-owned, so the ledger cannot restore them). Clear the
  290. idempotence set and re-run ``register_from_config()`` so hooks are wired again (#60036 / PR #60267;
  291. tracking #64178 — salvaged from PR #64188).
  292. Only the idempotence keys for the *current* Hermes home are cleared — ``discover_and_load(force=True)``
  293. only unloads the manager scoped to that one home, so clearing every home's keys would make a
  294. force-reload in profile A drop profile B's still-live registration from the ledger and duplicate it on
  295. B's next registration call (#92682 review).
  296. """
  297. _forget_home_registrations(_registered, _registered_lock)
  298. from hermes_cli.config import load_config
  299. register_from_config(load_config())
  300. def reset_for_tests() -> None:
  301. """Test-only: clear the idempotence set."""
  302. global _process_accept
  303. with _registered_lock:
  304. _registered.clear()
  305. _launch_consent.clear()
  306. _skip_logged.clear()
  307. _process_accept = False
  308. # --- Config parsing ---
  309. def _parse_hooks_block(hooks_cfg: Any) -> list[ShellHookSpec]:
  310. """Normalise ``hooks:`` into specs; malformed entries warn-and-skip, never raise."""
  311. return _parse_hooks(hooks_cfg)[0]
  312. def _parse_hooks(hooks_cfg: Any) -> tuple[list[ShellHookSpec], bool]:
  313. """``(specs, complete)``: ``complete`` is False when an entry was dropped as malformed (a typo
  314. must not read as a deliberate removal); an absent or empty ``hooks:`` is complete."""
  315. from hermes_cli.plugins import SHELL_UNSUPPORTED_HOOKS, VALID_HOOKS
  316. if hooks_cfg is None:
  317. return [], True
  318. if not isinstance(hooks_cfg, dict):
  319. return [], False
  320. specs: list[ShellHookSpec] = []
  321. complete = True
  322. for event_name, entries in hooks_cfg.items():
  323. if event_name in ("output_spill", "outbound"): # reserved non-event sub-sections under `hooks:`
  324. continue
  325. if event_name in SHELL_UNSUPPORTED_HOOKS: # _parse_response has no channel for these directives — refuse loudly
  326. logger.warning("hook event %r is Python-plugin-only: shell hooks cannot return its directive, "
  327. "so this registration is refused rather than silently ignored", event_name)
  328. continue # well-formed and deliberate: refused, but not a typo that should suspend removal
  329. if event_name not in VALID_HOOKS:
  330. suggestion = difflib.get_close_matches(str(event_name), VALID_HOOKS, n=1, cutoff=0.6)
  331. if suggestion:
  332. logger.warning("unknown hook event %r in hooks: config — did you mean %r?", event_name, suggestion[0])
  333. else:
  334. logger.warning("unknown hook event %r in hooks: config (valid: %s)", event_name, ", ".join(sorted(VALID_HOOKS)))
  335. complete = False
  336. continue
  337. if entries is None:
  338. continue
  339. if not isinstance(entries, list):
  340. logger.warning("hooks.%s must be a list of hook definitions; got %s", event_name, type(entries).__name__)
  341. complete = False
  342. continue
  343. parsed = [_parse_single_entry(event_name, i, raw) for i, raw in enumerate(entries)]
  344. complete = complete and None not in parsed
  345. specs.extend(spec for spec in parsed if spec is not None)
  346. return specs, complete
  347. def _parse_single_entry(event: str, index: int, raw: Any) -> Optional[ShellHookSpec]:
  348. def warn(msg: str, *args: Any) -> None:
  349. logger.warning("hooks.%s[%d]" + msg, event, index, *args)
  350. if not isinstance(raw, dict):
  351. warn(" must be a mapping with a 'command' key; got %s", type(raw).__name__)
  352. return None
  353. command = raw.get("command")
  354. if not isinstance(command, str) or not command.strip():
  355. warn(" is missing a non-empty 'command' field")
  356. return None
  357. matcher = raw.get("matcher")
  358. if matcher is not None and not isinstance(matcher, str):
  359. warn(".matcher must be a string regex; ignoring")
  360. matcher = None
  361. if matcher is not None and event not in _TOOL_EVENTS:
  362. warn(".matcher=%r will be ignored at runtime — the matcher field is only honored for "
  363. "pre_tool_call / post_tool_call. The hook will fire on every %s event.", matcher, event)
  364. matcher = None
  365. try:
  366. timeout = int(raw.get("timeout", DEFAULT_TIMEOUT_SECONDS))
  367. except (TypeError, ValueError):
  368. warn(".timeout must be an int (got %r); using default %ds", raw.get("timeout"), DEFAULT_TIMEOUT_SECONDS)
  369. timeout = DEFAULT_TIMEOUT_SECONDS
  370. if timeout < 1:
  371. warn(".timeout must be >=1; using default %ds", DEFAULT_TIMEOUT_SECONDS)
  372. timeout = DEFAULT_TIMEOUT_SECONDS
  373. elif timeout > MAX_TIMEOUT_SECONDS:
  374. warn(".timeout=%ds exceeds max %ds; clamping", timeout, MAX_TIMEOUT_SECONDS)
  375. timeout = MAX_TIMEOUT_SECONDS
  376. # ``fail_closed`` (canonical) wins over ``failClosed`` (Cursor/Claude-Code compat).
  377. fail_closed = raw.get("fail_closed", raw.get("failClosed", False))
  378. if not isinstance(fail_closed, bool):
  379. warn(".fail_closed must be a boolean (got %r); using default false (fail open)", fail_closed)
  380. fail_closed = False
  381. if fail_closed and event not in _BLOCKING_EVENTS:
  382. warn(".fail_closed=true will be ignored at runtime — fail_closed only applies to blocking-capable "
  383. "events (%s). The hook will fail open on %s like any other hook.", ", ".join(sorted(_BLOCKING_EVENTS)), event)
  384. fail_closed = False
  385. return ShellHookSpec(event=event, command=command.strip(), matcher=matcher, timeout=timeout, fail_closed=fail_closed)
  386. # --- Subprocess callback ---
  387. # Popen failure -> diagnostic; WinError 193 gets its own below, everything else is str(exc).
  388. _POPEN_ERRORS = ((FileNotFoundError, "command not found"), (PermissionError, "command not executable"))
  389. # A hook configured as a bare script path runs on POSIX because the kernel reads its shebang.
  390. # CreateProcess has no such mechanism and answers WinError 193 ("%1 is not a valid Win32
  391. # application") for a text file, so every ``command: "~/.hermes/agent-hooks/x.sh"`` example in
  392. # the hooks docs — the canonical shape — fails on Windows while the same config works everywhere
  393. # else. Map the suffixes that shape uses to their interpreter; unmapped suffixes keep the OS
  394. # failure so a typo still reads as "command not found" rather than a mystery interpreter error.
  395. _WINDOWS_SCRIPT_INTERPRETERS = {".sh": "bash", ".bash": "bash", ".py": "python"}
  396. # WinError 193 raised for a suffix we deliberately do not map.
  397. _NOT_DIRECTLY_EXECUTABLE = "cannot be run directly on Windows (there is no shebang support): start it with its interpreter, e.g. 'bash <path>'"
  398. def _windows_script_argv(argv: list[str]) -> list[str]:
  399. """``argv`` with the interpreter prepended when element 0 is an existing script we can name an
  400. interpreter for; unchanged otherwise, including on POSIX, where the shebang already works."""
  401. suffix = os.path.splitext(argv[0])[1].lower()
  402. kind = _WINDOWS_SCRIPT_INTERPRETERS.get(suffix)
  403. if kind is None or not os.path.isfile(argv[0]):
  404. return argv
  405. if kind == "python":
  406. return [sys.executable, *argv]
  407. # Resolved inside the caller's try: no Git for Windows raises RuntimeError carrying the
  408. # installer's own actionable guidance, which is a better diagnostic than any we could add.
  409. from tools.environments.local import _find_bash
  410. return [_find_bash(), *argv]
  411. def _spawn(spec: ShellHookSpec, stdin_json: str) -> dict[str, Any]:
  412. """The single subprocess site: run ``spec.command`` with ``stdin_json`` on stdin. Same result keys for every outcome."""
  413. result: dict[str, Any] = {"returncode": None, "stdout": "", "stderr": "", "timed_out": False, "elapsed_seconds": 0.0, "error": None}
  414. def failed(error: str) -> dict[str, Any]:
  415. result["error"] = error
  416. return result
  417. try:
  418. argv = split_command_line(os.path.expanduser(spec.command))
  419. except ValueError as exc:
  420. return failed(f"command {spec.command!r} cannot be parsed: {exc}")
  421. if not argv:
  422. return failed("empty command")
  423. t0 = time.monotonic()
  424. # Own process group on POSIX so a timed-out hook's descendants are reaped with it (Windows: kill_process_tree
  425. # / taskkill /T). Hooks that finish in time keep detached helpers alive.
  426. # detached-spawn: ok — awaited hook; its timeout kills the whole group (kill_process_tree)
  427. popen_kwargs: dict[str, Any] = {"creationflags": windows_hide_flags()} if IS_WINDOWS else {"process_group": 0}
  428. # HERMES_HOME follows the routed profile (the import-time environ holds the launch profile's), and
  429. # under multiplexing os.environ carries the DEFAULT profile's secrets, which a secondary's hook
  430. # script must not inherit; single-profile runs keep the process env byte-for-byte as before.
  431. from agent.secret_scope import is_multiplex_active
  432. from tools.environments.local import build_subprocess_env
  433. try:
  434. if IS_WINDOWS:
  435. argv = _windows_script_argv(argv)
  436. proc = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE,
  437. text=True, encoding='utf-8', errors='replace', shell=False,
  438. env=build_subprocess_env(scrub_secrets=is_multiplex_active()), **popen_kwargs)
  439. except Exception as exc:
  440. for cls, msg in _POPEN_ERRORS:
  441. if isinstance(exc, cls):
  442. return failed(msg)
  443. if getattr(exc, "winerror", None) == 193:
  444. # Unmapped suffix (.zsh, .fish, .rb, …) — the raw WinError text is localized, so an
  445. # operator on a non-English Windows could not act on it at all.
  446. return failed(f"{argv[0]!r} {_NOT_DIRECTLY_EXECUTABLE}")
  447. return failed(str(exc))
  448. try:
  449. stdout, stderr = proc.communicate(input=stdin_json, timeout=spec.timeout)
  450. except BaseException as exc:
  451. # BaseException: the hook leads its own process group, so Ctrl+C's SIGINT never reaches it — only we can.
  452. kill_process_tree(proc) # the whole tree — forked helpers holding the pipes would stall the drain
  453. with suppress(Exception):
  454. proc.communicate(timeout=1)
  455. if not isinstance(exc, Exception):
  456. raise
  457. if not isinstance(exc, subprocess.TimeoutExpired): # pragma: no cover — defensive
  458. return failed(str(exc))
  459. result.update(timed_out=True, elapsed_seconds=round(time.monotonic() - t0, 3))
  460. return result
  461. result.update(returncode=proc.returncode, stdout=stdout or "", stderr=stderr or "", elapsed_seconds=round(time.monotonic() - t0, 3))
  462. return result
  463. def _make_callback(spec: ShellHookSpec) -> Callable[..., Optional[dict[str, Any]]]:
  464. """Build the closure that ``invoke_hook()`` will call per firing."""
  465. def _callback(**kwargs: Any) -> Optional[dict[str, Any]]:
  466. from agent.safe_worker_policy import safe_worker_enabled
  467. if safe_worker_enabled():
  468. return None
  469. if spec.event in _TOOL_EVENTS and not spec.matches_tool(kwargs.get("tool_name")):
  470. return None
  471. return _evaluate_result(spec, _spawn(spec, _serialize_payload(spec.event, kwargs)))
  472. _callback.__name__ = _callback.__qualname__ = f"shell_hook[{spec.event}:{spec.command}]"
  473. return _callback
  474. def _fail_closed_block(spec: ShellHookSpec, reason: str) -> dict[str, Any]:
  475. return {"action": "block", "message": f"hook {spec.command} failed closed: {reason}"}
  476. def _evaluate_result(
  477. spec: ShellHookSpec, r: dict[str, Any],
  478. ) -> Optional[dict[str, Any]]:
  479. """Turn a :func:`_spawn` diagnostic dict into the hook's contribution.
  480. Single place that encodes the failure semantics:
  481. * spawn error / timeout — fail open (log + ``None``) unless the spec
  482. is ``fail_closed`` on a blocking-capable event, in which case a
  483. canonical block shape is returned;
  484. * exit code 2 on a blocking-capable event — block, with the message
  485. taken from stdout block JSON, then stderr, then a default
  486. (Claude-Code / Cursor compatible);
  487. * other non-zero exits — warn, then parse stdout normally; a
  488. ``fail_closed`` hook blocks if no directive was produced;
  489. * non-JSON / unparseable stdout on a ``fail_closed`` blocking hook —
  490. block instead of silently contributing nothing.
  491. Shared by the live callback path (:func:`_make_callback`) and the CLI
  492. test helper (:func:`run_once`) so ``hermes hooks test`` reflects
  493. production behaviour exactly.
  494. """
  495. blocking_event = spec.event in _BLOCKING_EVENTS
  496. fail_closed = spec.fail_closed and blocking_event
  497. if r["error"]:
  498. logger.warning("shell hook failed (event=%s command=%s): %s", spec.event, spec.command, r["error"])
  499. elif r["timed_out"]:
  500. logger.warning("shell hook timed out after %.2fs (event=%s command=%s)", r["elapsed_seconds"], spec.event, spec.command)
  501. if r["error"] or r["timed_out"]:
  502. return _fail_closed_block(spec, r["error"] or f"timed out after {spec.timeout}s") if fail_closed else None
  503. stderr = r["stderr"].strip()
  504. if stderr:
  505. logger.debug("shell hook stderr (event=%s command=%s): %s", spec.event, spec.command, stderr[:_STDERR_MESSAGE_LIMIT])
  506. if r["returncode"] == BLOCK_EXIT_CODE and blocking_event:
  507. parsed = _parse_response(spec.event, r["stdout"])
  508. if isinstance(parsed, dict) and parsed.get("action") == "block":
  509. return parsed
  510. message = stderr[:_STDERR_MESSAGE_LIMIT] or _DEFAULT_BLOCK_MESSAGE
  511. logger.info("shell hook exited %d — blocking (event=%s command=%s): %s", BLOCK_EXIT_CODE, spec.event, spec.command, message)
  512. return {"action": "block", "message": message}
  513. # Other non-zero exits: still parse stdout so exit-code failures can carry a block directive.
  514. if r["returncode"] != 0:
  515. logger.warning("shell hook exited %d (event=%s command=%s); stderr=%s",
  516. r["returncode"], spec.event, spec.command, stderr[:_STDERR_MESSAGE_LIMIT])
  517. stdout = (r["stdout"] or "").strip()
  518. parsed = _parse_response(spec.event, stdout)
  519. if parsed is None and fail_closed and r["returncode"] != 0:
  520. return _fail_closed_block(
  521. spec, f"hook exited {r['returncode']} with no directive",
  522. )
  523. if parsed is None and fail_closed and stdout and not _is_json_object(stdout):
  524. # The hook produced output we could not turn into a directive.
  525. # A fail-closed gate must not silently allow the action on
  526. # garbage output (e.g. a stack trace on stdout).
  527. return _fail_closed_block(spec, "unparseable stdout (expected a JSON object)")
  528. return parsed
  529. def _is_json_object(text: str) -> bool:
  530. try:
  531. return isinstance(json.loads(text), dict)
  532. except json.JSONDecodeError:
  533. return False
  534. def _serialize_payload(event: str, kwargs: dict[str, Any]) -> str:
  535. """Render the stdin JSON payload; unserialisable values are stringified."""
  536. return json.dumps({"hook_event_name": event, **_payload_fields(kwargs)}, ensure_ascii=False, default=str)
  537. def _block_message(primary: Any, secondary: Any) -> str:
  538. """Validated string block message (primary wins), falling back to the default."""
  539. raw = primary or secondary
  540. return raw if isinstance(raw, str) and raw else _DEFAULT_BLOCK_MESSAGE
  541. # pre_tool_call dialects in check order — Hermes ``action`` then Claude-Code ``decision`` — as (verb key,
  542. # block-message primary, secondary, modify payload key); both translate to the canonical Hermes shape.
  543. _PRE_TOOL_DIALECTS = (("action", "message", "reason", "args"), ("decision", "reason", "message", "tool_input"))
  544. def _parse_pre_tool_call(data: dict[str, Any]) -> Optional[dict[str, Any]]:
  545. for verb, primary, secondary, _ in _PRE_TOOL_DIALECTS:
  546. if data.get(verb) == "block":
  547. return {"action": "block", "message": _block_message(data.get(primary), data.get(secondary))}
  548. for verb, _, _, payload in _PRE_TOOL_DIALECTS:
  549. if data.get(verb) == "modify" and isinstance(data.get(payload), dict):
  550. return {"action": "modify", "args": data[payload]}
  551. # Hermes-only escalation to the human-approval gate (#92553). Claude-Code's ``decision:
  552. # approve`` means auto-ALLOW, so it is deliberately not mapped onto this.
  553. if data.get("action") == "approve":
  554. directive: dict[str, Any] = {"action": "approve"}
  555. for key in ("message", "rule_key"):
  556. value = data.get(key)
  557. if isinstance(value, str) and value.strip():
  558. directive[key] = value.strip()
  559. return directive
  560. return None
  561. def _parse_pre_verify(data: dict[str, Any]) -> Optional[dict[str, Any]]:
  562. # "continue" (Hermes) / "block" (Claude-Code Stop) both mean keep going; no message is a no-op.
  563. action = str(data.get("action") or data.get("decision") or "").strip().lower()
  564. message = data.get("message") or data.get("reason")
  565. if action in {"continue", "block"} and isinstance(message, str) and message.strip():
  566. return {"action": "continue", "message": message.strip()}
  567. return None
  568. def _parse_context(data: dict[str, Any]) -> Optional[dict[str, Any]]:
  569. context = data.get("context")
  570. return {"context": context} if isinstance(context, str) and context.strip() else None
  571. def _parse_pre_llm_call(data: dict[str, Any]) -> Optional[dict[str, Any]]:
  572. # A turn veto before any inference request, in either dialect (as for pre_tool_call); else context.
  573. for verb, primary, secondary, _ in _PRE_TOOL_DIALECTS:
  574. if data.get(verb) == "block":
  575. return {"action": "block", "message": _block_message(data.get(primary), data.get(secondary))}
  576. return _parse_context(data)
  577. _RESPONSE_PARSERS: dict[str, Callable[[dict[str, Any]], Optional[dict[str, Any]]]] = {
  578. "pre_tool_call": _parse_pre_tool_call, "pre_verify": _parse_pre_verify, "pre_llm_call": _parse_pre_llm_call,
  579. }
  580. def _parse_response(event: str, stdout: str) -> Optional[dict[str, Any]]:
  581. """Translate stdout JSON into a Hermes wire-shape dict, or ``None``."""
  582. stdout = (stdout or "").strip()
  583. if not stdout:
  584. return None
  585. try:
  586. data = json.loads(stdout)
  587. except json.JSONDecodeError:
  588. logger.warning("shell hook stdout was not valid JSON (event=%s): %s", event, stdout[:200])
  589. return None
  590. return _RESPONSE_PARSERS.get(event, _parse_context)(data) if isinstance(data, dict) else None
  591. # --- Allowlist / consent ---
  592. def allowlist_path() -> Path:
  593. """Path to the per-user shell-hook allowlist file."""
  594. return get_hermes_home() / ALLOWLIST_FILENAME
  595. def _read_allowlist() -> tuple[dict[str, Any], bool]:
  596. """``(allowlist, readable)``: the parsed allowlist (an empty skeleton when absent or broken) and
  597. whether it could be trusted; a missing file is readable (nothing approved yet), an unreadable or
  598. malformed one is not."""
  599. try:
  600. raw = json.loads(allowlist_path().read_text(encoding="utf-8-sig"))
  601. except FileNotFoundError:
  602. return {"approvals": []}, True
  603. except (json.JSONDecodeError, OSError, UnicodeDecodeError):
  604. return {"approvals": []}, False
  605. if not isinstance(raw, dict):
  606. return {"approvals": []}, False
  607. readable = isinstance(raw.get("approvals"), list)
  608. if not readable:
  609. raw["approvals"] = []
  610. return raw, readable
  611. def load_allowlist() -> dict[str, Any]:
  612. """Return the parsed allowlist, or an empty skeleton if absent."""
  613. return _read_allowlist()[0]
  614. def save_allowlist(data: dict[str, Any]) -> None:
  615. """Atomic write; on OSError log and carry on (the approval is not saved)."""
  616. p = allowlist_path()
  617. try:
  618. atomic_json_write(p, data, sort_keys=True, mode=0o600)
  619. except OSError as exc:
  620. logger.warning("Failed to persist shell hook allowlist to %s: %s. The approval holds for this process "
  621. "only (a gateway keeps a launch's --accept-hooks until it restarts); a gateway session "
  622. "opened from a CLI prompt skips the hook, and the next run re-prompts.", p, exc)
  623. @contextmanager
  624. def _locked_update_approvals() -> Iterator[dict[str, Any]]:
  625. """Serialise allowlist read-modify-write across processes via a sibling flock file."""
  626. p = allowlist_path()
  627. p.parent.mkdir(parents=True, exist_ok=True)
  628. with ExitStack() as stack:
  629. if fcntl is None: # pragma: no cover — non-POSIX fallback
  630. stack.enter_context(_allowlist_write_lock)
  631. else:
  632. lock_fh = stack.enter_context(open(p.with_suffix(p.suffix + ".lock"), "a+", encoding="utf-8")) # windows-footgun: ok (write/append mode, not a read)
  633. fcntl.flock(lock_fh.fileno(), fcntl.LOCK_EX)
  634. stack.callback(_flock_unlock, lock_fh)
  635. data = load_allowlist()
  636. yield data
  637. save_allowlist(data)
  638. def _flock_unlock(lock_fh: Any) -> None:
  639. with suppress(OSError):
  640. fcntl.flock(lock_fh.fileno(), fcntl.LOCK_UN)
  641. def _prompt_and_record(event: str, command: str, *, accept_hooks: bool) -> bool:
  642. """Approve an unseen ``(event, command)`` pair; True iff granted and recorded."""
  643. if accept_hooks:
  644. _record_approval(event, command)
  645. logger.info("shell hook auto-approved via --accept-hooks / env / config: %s -> %s", event, command)
  646. return True
  647. if not sys.stdin.isatty():
  648. return False
  649. print(
  650. f"\n⚠ Hermes is about to register a shell hook that will run a\n command on your behalf.\n\n"
  651. f" Event: {event}\n Command: {command}\n\n"
  652. f" Commands run with your full user credentials. Only approve\n commands you trust."
  653. )
  654. try:
  655. answer = input("Allow this hook to run? [y/N]: ").strip().lower()
  656. except (EOFError, KeyboardInterrupt):
  657. print() # keep the terminal tidy after ^C
  658. return False
  659. if answer in {"y", "yes"}:
  660. _record_approval(event, command)
  661. return answer in {"y", "yes"}
  662. def _record_approval(event: str, command: str) -> None:
  663. entry = {"event": event, "command": command, "approved_at": _utc_now_iso(), "script_mtime_at_approval": script_mtime_iso(command)}
  664. with _locked_update_approvals() as data:
  665. data["approvals"] = [e for e in data.get("approvals", []) if not _entry_matches(e, event, command)] + [entry]
  666. def revoke(command: str) -> int:
  667. """Remove every allowlist entry for ``command``; returns the count. A gateway unregisters it at its
  668. next allowlist check (``sync_from_config``, about every 30 s) unless an opt-in approves every hook; other live
  669. processes keep it until restart."""
  670. with _locked_update_approvals() as data:
  671. before = len(data.get("approvals", []))
  672. data["approvals"] = [e for e in data.get("approvals", []) if not _entry_matches(e, None, command)]
  673. return before - len(data["approvals"])
  674. _SCRIPT_EXTENSIONS: tuple[str, ...] = (".sh", ".bash", ".zsh", ".fish", ".py", ".pyw", ".rb", ".pl", ".lua", ".js", ".mjs", ".cjs", ".ts")
  675. def _command_script_path(command: str) -> str:
  676. """First token with a script extension, else the first path-like token, else the first token."""
  677. try:
  678. parts = split_command_line(command) or [command]
  679. except ValueError:
  680. return command
  681. return (next((p for p in parts if p.lower().endswith(_SCRIPT_EXTENSIONS)), None)
  682. or next((p for p in parts if "/" in p or p.startswith("~")), None) or parts[0])
  683. def _resolve_effective_accept(cfg: dict[str, Any], accept_hooks_arg: bool) -> bool:
  684. """Any truthy opt-in channel wins: explicit arg, this process's --accept-hooks, HERMES_ACCEPT_HOOKS,
  685. hooks_auto_accept."""
  686. from utils import env_var_enabled
  687. if accept_hooks_arg or _process_accept or env_var_enabled("HERMES_ACCEPT_HOOKS"):
  688. return True
  689. cfg_val = cfg.get("hooks_auto_accept", False)
  690. return cfg_val if isinstance(cfg_val, bool) else isinstance(cfg_val, str) and cfg_val.strip().lower() in _TRUTHY
  691. # --- Introspection (used by `hermes hooks` CLI) ---
  692. def allowlist_entry_for(event: str, command: str) -> Optional[dict[str, Any]]:
  693. """Return the allowlist record for this pair, if any."""
  694. return next((e for e in load_allowlist().get("approvals", []) if _entry_matches(e, event, command)), None)
  695. def script_mtime_iso(command: str) -> Optional[str]:
  696. """ISO-8601 mtime of the resolved script path, or ``None`` if missing."""
  697. path = _command_script_path(command)
  698. try:
  699. mtime = os.path.getmtime(os.path.expanduser(path)) if path else None
  700. except OSError:
  701. return None
  702. return None if mtime is None else datetime.fromtimestamp(mtime, tz=UTC).isoformat().replace("+00:00", "Z")
  703. def script_is_executable(command: str) -> bool:
  704. """Runnable as configured: a bare script needs X_OK, an interpreter-prefixed one only R_OK (as ``_spawn`` does)."""
  705. path = _command_script_path(command)
  706. expanded = os.path.expanduser(path)
  707. try:
  708. argv = split_command_line(command) if path and os.path.isfile(expanded) else None
  709. except ValueError:
  710. return False
  711. return argv is not None and os.access(expanded, os.X_OK if argv and argv[0] == path else os.R_OK)
  712. def run_once(spec: ShellHookSpec, kwargs: dict[str, Any]) -> dict[str, Any]:
  713. """Fire one hook with a synthetic payload (``hermes hooks test`` / doctor) through the production path."""
  714. result = _spawn(spec, _serialize_payload(spec.event, kwargs))
  715. result["parsed"] = _evaluate_result(spec, result)
  716. return result