`gjUdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZddlmZmZddlmZmZddlmZddlmZmZmZmZmZmZmZmZdd l m!Z!m"Z" ddl#Z#dd l%m&Z&dd l'm(Z(ejRe*Z+d Z,d Z-dZ.dZ/e0Z1de2d<e jfZ4e jfZ5eGddZ6dd d3dZ7d4dZ8d5dZ9d6dZ: d7dZ;hdZd:dZ?d;dZ@dd"ZCd?d#ZDd@d$ZEedAd%ZF dBd&ZGdCd'ZHdDd(ZIdEd)ZJd*ZKd+e2d,<dFd-ZL dGd.ZMdHd/ZNdId0ZOdJd1ZP dKd2ZQy#e$$rdZ#YwxYw)Lu Shell-script hooks bridge. Reads the ``hooks:`` block from ``cli-config.yaml``, prompts the user for consent on first use of each ``(event, command)`` pair, and registers callbacks on the existing plugin hook manager so every existing ``invoke_hook()`` site dispatches to the configured shell scripts — with zero changes to call sites. Design notes ------------ * Python plugins and shell hooks compose naturally: both flow through :func:`hermes_cli.plugins.invoke_hook` and its aggregators. Python plugins are registered first (via ``discover_and_load()``) so their block decisions win ties over shell-hook blocks. * Subprocess execution uses ``shlex.split(os.path.expanduser(command))`` with ``shell=False`` — no shell injection footguns. Users that need pipes/redirection wrap their logic in a script. * First-use consent is gated by the allowlist under ``~/.hermes/shell-hooks-allowlist.json``. Non-TTY callers must pass ``accept_hooks=True`` (resolved from ``--accept-hooks``, ``HERMES_ACCEPT_HOOKS``, or ``hooks_auto_accept: true`` in config) for registration to succeed without a prompt. * Registration is idempotent — safe to invoke from both the CLI entry point (``hermes_cli/main.py``) and the gateway entry point (``gateway/run.py``). Wire protocol ------------- **stdin** (JSON, piped to the script):: { "hook_event_name": "pre_tool_call", "tool_name": "terminal", "tool_input": {"command": "rm -rf /"}, "session_id": "sess_abc123", "cwd": "/home/user/project", "extra": {...} # event-specific kwargs } **stdout** (JSON, optional — anything else is ignored):: # Block a pre_tool_call (either shape accepted; normalised internally): {"decision": "block", "reason": "Forbidden command"} # Claude-Code-style {"action": "block", "message": "Forbidden command"} # Hermes-canonical # Inject context for pre_llm_call: {"context": "Today is Friday"} # Silent no-op: Per-event ``extra`` keys ~~~~~~~~~~~~~~~~~~~~~~~~ The ``extra`` object contains every kwarg that is **not** one of the top-level payload keys (``tool_name``, ``args``, ``session_id``, ``parent_session_id``). The tables below list the ``extra`` keys emitted by each built-in hook site. ``post_tool_call`` (emitted from ``model_tools.py``):: result – tool return value (serialised string) status – "ok" | "error" | "blocked" error_type – error category (e.g. "ValueError"), or None error_message – human-readable error text, or None duration_ms – wall-clock time in milliseconds task_id – current task id (empty string if none) tool_call_id – provider tool-call id turn_id – current turn id api_request_id – current API request id middleware_trace – list of dicts from tool middleware chain ``pre_tool_call`` (emitted from ``model_tools.py``):: task_id – current task id (empty string if none) tool_call_id – provider tool-call id turn_id – current turn id api_request_id – current API request id middleware_trace – list of dicts from tool middleware chain ``on_session_start`` (emitted from ``agent/conversation_loop.py``):: model – model name (e.g. "claude-sonnet-4-20250514") platform – platform identifier (e.g. "cli", "whatsapp") ``on_session_end`` (emitted from ``agent/turn_finalizer.py``):: task_id – current task id turn_id – current turn id completed – bool, True when the turn produced a final response interrupted – bool, True when the user interrupted model – model name platform – platform identifier ``subagent_stop`` (emitted from ``tools/delegate_tool.py``):: parent_turn_id – parent agent's current turn id child_session_id – child (subagent) session id child_role – role string of the child agent child_summary – summary of the child's work child_status – exit status string (e.g. "success", "error") duration_ms – wall-clock time of the child run in milliseconds ) annotationsN)contextmanager) dataclassfield)datetimetimezone)Path)AnyCallableDictIteratorListOptionalSetTuple) IS_WINDOWSwindows_hide_flags)get_hermes_home)atomic_replace<i,zshell-hooks-allowlist.jsonzBlocked by shell hook.z#Set[Tuple[str, Optional[str], str]] _registeredcpeZdZUdZded<ded<dZded<eZded <edd Z d ed <ddZ ddZ y) ShellHookSpeczAParsed and validated representation of a single ``hooks:`` entry.streventcommandN Optional[str]matcherinttimeoutF)defaultreprzOptional[re.Pattern]compiled_matchercvt|jtr%|jj}|r|nd|_|jr& t j |j|_yy#tj$r2}tjd|j|d|_Yd}~yd}~wwxYw)NuFshell hook matcher %r is invalid (%s) — treating as literal equality) isinstancerrstriprecompiler#errorloggerwarning)selfstrippedexcs D/root/.hermes/venv/lib/python3.12/site-packages/agent/shell_hooks.py __post_init__zShellHookSpec.__post_init__s dllC (||))+H'/8TDL << -(* 4<<(@% 88 -'(, c)-%%  -s $A33B8(B33B8c|jsy|y|j|jj|duS||jk(S)NTF)rr# fullmatch)r, tool_names r/ matches_toolzShellHookSpec.matches_toolsN||    ,((229=TI IDLL((returnNone)r3rr7bool) __name__ __module__ __qualname____doc____annotations__rDEFAULT_TIMEOUT_SECONDSr rr#r0r4r5r/rrs@K J L!G]!*GS*-24e-L*L-" )r5rF accept_hooksc  t|tsgSddlm}|drtj dgSt ||}t|jd}|sgSg}ddl m }|}|D]}}|j|j|jf} t5| tvr ddd@t!|j|j} ddd sNt#|j|j|s,tj%d |j|jt5| tvr ddd|j&j)|jgj+t-|tj/| |j+|tj d |j|j|j|j0ddd|S#1swY%xYw#1swYxYw) u*Register every configured shell hook on the plugin manager. ``cfg`` is the full parsed config dict (``hermes_cli.config.load_config`` output). The ``hooks:`` key is read out of it. Missing, empty, or non-dict ``hooks`` is treated as zero configured hooks. ``accept_hooks=True`` skips the TTY consent prompt — the caller is promising that the user has opted in via a flag, env var, or config setting. ``HERMES_ACCEPT_HOOKS=1`` and ``hooks_auto_accept: true`` are also honored inside this function so either CLI or gateway call sites pick them up. Returns the list of :class:`ShellHookSpec` entries that ended up wired up on the plugin manager. Skipped entries (unknown events, malformed, not allowlisted, already registered) are logged but not returned. r)env_var_enabledHERMES_SAFE_MODEu6HERMES_SAFE_MODE=1 — shell-hook registration skippedhooks)get_plugin_managerNrAushell hook for %s (%s) not allowlisted — skipped. Use --accept-hooks / HERMES_ACCEPT_HOOKS=1 / hooks_auto_accept: true, or approve at the TTY prompt next run.z9shell hook registered: %s -> %s (matcher=%s, timeout=%ds))r%dictutilsrDr*info_resolve_effective_accept_parse_hooks_blockgethermes_cli.pluginsrGrrr_registered_lockr_is_allowlisted_prompt_and_recordr+_hooks setdefaultappend_make_callbackaddr ) cfgrBrDeffective_acceptspecs registeredrGmanagerspeckeyalready_allowlisteds r/register_from_configr_s* c4  &)* LM 0lC swww/ 0E  &(J6 "G zz4<<6  Lk! L L#2$**dll"K  L #% DLL7G'JJ   k!   NN % %djj" 5 < <^D=Q R OOC   d # KKK DLL$,,    )> ; L L$  s% G63 G61 HB%H6H H cZt|tsgSt|jdS)zReturn the parsed ``ShellHookSpec`` entries from config without registering anything. Used by ``hermes hooks list`` and ``doctor``.rF)r%rHrLrM)rWs r/iter_configured_hooksras' c4  cggg. //r5cbt5tjdddy#1swYyxYw)z-Clear the idempotence set. Test-only helper.N)rOrclearr@r5r/reset_for_testsrd's& s%.c >ddlm}t|tsgSg}|j D]\}}|dvr ||vrot j t||dd}|rtjd||dn/tjd|d jt|~|t|ts+tjd |t|jt|D]&\}}t!|||}||j#|(|S) uNormalise the ``hooks:`` dict into a flat list of ``ShellHookSpec``. Malformed entries warn-and-skip — we never raise from config parsing because a broken hook must not crash the agent. r) VALID_HOOKS) output_spillg333333?)ncutoffu;unknown hook event %r in hooks: config — did you mean %r?z2unknown hook event %r in hooks: config (valid: %s)z, z3hooks.%s must be a list of hook definitions; got %s)rNrfr%rHitemsdifflibget_close_matchesrr*r+joinsortedlisttyper: enumerate_parse_single_entryrT) hooks_cfgrfrY event_nameentries suggestionirawr\s r/rLrL1s% / i & !#E(0## G * *  [ ( 22J#JQ 1  H &*= >  ? '4( NNEDM22  ( #FAs&z1c:D T" #A##J Lr5cZt|ts,tjd||t |j y|j d}t|tr|jstjd||y|j d}|)t|tstjd||d}||dvrtjd||||d}|j dt} t|}|d kr"tjd ||tt}|tkDr#tjd |||tt}t||j|| S#ttf$r&tjd |||tt}YwxYw)Nz;hooks.%s[%d] must be a mapping with a 'command' key; got %srz3hooks.%s[%d] is missing a non-empty 'command' fieldrz5hooks.%s[%d].matcher must be a string regex; ignoring pre_tool_callpost_tool_calluhooks.%s[%d].matcher=%r will be ignored at runtime — the matcher field is only honored for pre_tool_call / post_tool_call. The hook will fire on every %s event.r z?hooks.%s[%d].timeout must be an int (got %r); using default %dsrhz3hooks.%s[%d].timeout must be >=1; using default %dsz2hooks.%s[%d].timeout=%ds exceeds max %ds; clamping)rrrr )r%rHr*r+rqr:rMrr&r?r TypeError ValueErrorMAX_TIMEOUT_SECONDSr)rindexryrr timeout_rawr s r/rsrsfs c4  I 5$s),, ggi G gs #7==? A 5 ggi G:gs#; C 5 u,OO E 5'5  '')%<=K*k"{ A 51 *$$ @ 5'#6 &    + z "* M 5+'> * *s: E552F*)F*>argsr3 session_idparent_session_idc \ddddddd} tjtjj |j }|sd |d<|Stj}tr d tini} tj|f|d |jd dd |}|j(|d<|j*xsd|d<|j,xsd|d<ttj|z d|d<|S#t $r!}d|j d||d<|cYd}~Sd}~wwxYw#tj$r.d |d <ttj|z d|d<|cYSt $r d|d<|cYSt"$r d|d<|cYSt$$r}t'||d<|cYd}~Sd}~wwxYw)uRun ``spec.command`` as a subprocess with ``stdin_json`` on stdin. Returns a diagnostic dict with the same keys for every outcome (``returncode``, ``stdout``, ``stderr``, ``timed_out``, ``elapsed_seconds``, ``error``). This is the single place the subprocess is actually invoked — both the live callback path (:func:`_make_callback`) and the CLI test helper (:func:`run_once`) go through it. NFg) returncodestdoutstderr timed_outelapsed_secondsr)zcommand z cannot be parsed: r)z empty command creationflagsT)inputcapture_outputr textshellrrzcommand not foundzcommand not executablerrr)shlexsplitospath expanduserrrtime monotonicrr subprocessrunr TimeoutExpiredroundFileNotFoundErrorPermissionError Exceptionrrrr)r\ stdin_jsonresultargvr.t0 _popen_kwargsprocs r/_spawnrs F{{277--dll;< )w  B?I_&8&:;rM~~  LL   . ??F<{{(bF8{{(bF8 %dnn&6&;Q ?F  MK $T\\$44GuMw &  $ $"{$)$..*:R*?$C ! -w 2w c(w sMF+'F+8F+ F+F& F+&F+czdfd }djdjd|_|j|_|S)z>Build the closure that ``invoke_hook()`` will call per firing.c jdvr!j|jdsytt j|}|dr0t j djj|dy|dr0t j d|djjy|dj}|r/t jd jj|dd |d d k7r3t j d |d jj|dd tj|dS)Nr{r3r)z+shell hook failed (event=%s command=%s): %srz6shell hook timed out after %.2fs (event=%s command=%s)rrz+shell hook stderr (event=%s command=%s): %sirrz5shell hook exited %d (event=%s command=%s); stderr=%sr) rr4rMr_serialize_payloadr*r+rr&debug_parse_response)kwargsrrr\s r/ _callbackz!_make_callback.._callbacks( ::< <$$VZZ %<= 4+DJJ? @ W: NN= DLL!G*  [> NNH#$djj$,, 8""$  LL= DLL&#,  \?a  NNG,T\\6$3< tzz1X;77r5z shell_hook[:])rr r7Optional[Dict[str, Any]])rrr:r<)r\rs` r/rUrUs>"8H'tzzl!DLL>CI&//I r5c|jDcic]\}}|tvs||}}} ttj}||j dt|j dtr|j dnd|j dxs|j dxsd||d}tj|dt Scc}}w#t $rd}YwxYw) zrRender the stdin JSON payload. Unserialisable values are stringified via ``default=str`` rather than dropped.rr3rNrr)hook_event_namer3 tool_inputrcwdextraF) ensure_asciir!) rk_TOP_LEVEL_PAYLOAD_KEYSrr rOSErrorrMr%rHjsondumps)rrkvextrasrpayloads r/rrs &||~ Rtq!:Q1Qad RF R$((*o!ZZ ,,6vzz&7I4,Pfjj(VZjj.W&**=P2QWUW G ::gE3 ??S sCCC C)(C)cB|xs|}t|tr|r|StS)aReturn a validated string block message, falling back to the default. Accepts two candidate fields (primary wins over secondary) so callers can express field-priority differences between the two hook wire formats without duplicating the type-check logic. )r%r_DEFAULT_BLOCK_MESSAGE)primary secondaryrys r/_block_messager+s%  YCS#&33J4JJr5c|xsdj}|sy tj|}t |tsy|dk(r|jddk(r-dt|jd|jd d S|jd dk(r-dt|jd |jdd Sy|d k(rt|jdxs|jd xsdjj}|d vrW|jdxs|jd }t |tr#|jrd|jd Sy|jd}t |tr|jrd|iSy#tj$rtj d||ddYywxYw)uTranslate stdout JSON into a Hermes wire-shape dict. For ``pre_tool_call`` the Claude-Code-style ``{"decision": "block", "reason": "..."}`` payload is translated into the canonical Hermes ``{"action": "block", "message": "..."}`` shape expected by :func:`hermes_cli.plugins.get_pre_tool_call_block_message`. This is the single most important correctness invariant in this module — skipping the translation silently breaks every ``pre_tool_call`` block directive. For ``pre_llm_call``, ``{"context": "..."}`` is passed through unchanged to match the existing plugin-hook contract. Anything else returns ``None``. rNz3shell hook stdout was not valid JSON (event=%s): %sr|actionblockmessagereason)rrdecision pre_verify>rcontinuercontext) r&rloadsJSONDecodeErrorr*r+r%rHrMrrlower)rrdatarrrs r/rr6s l ! ! #F zz&! dD !  88H  (%.)ATVZV^V^_gVh2ij j 88J 7 *%.(ASUYU]U]^gUh2ij j TXXh'E488J+?E2FLLNTTV * *hhy)?TXXh-?G'3'GMMO",IIhhy!G'3GMMO7## A    A 6$3<  sF++-GGc$ttz S)z/Path to the per-user shell-hook allowlist file.)rALLOWLIST_FILENAMEr@r5r/allowlist_pathrss  1 11r5c" tjtj}t|tsdgiS|jd}t|tsg|d<|S#ttj t f$rdgicYSwxYw)zz"_is_allowlisted..sR  1d ( EE'Ne # ( EE)  ' (sAA r)ranyrM)rrrs`` r/rPrPs2  D +r*  r5c#Kt}|jjdd|j|jdz}t )t 5t}|t|dddyt|dd5}t j|jt j t}|t| t j|jt jdddy#1swYyxYw#ttf$rY&wxYw# t j|jt jw#ttf$rYwwxYwxYw#1swYyxYww)uSerialise read-modify-write on the allowlist across processes. Holds an exclusive ``flock`` on a sibling lock file for the duration of the update so concurrent ``_record_approval``/``revoke`` callers cannot clobber each other's changes (the race Codex reproduced with 20–50 simultaneous writers). Falls back to an in-process lock on platforms without ``fcntl``. Trz.lockNza+zutf-8)encoding)rrr with_suffixrfcntl_allowlist_write_lockrropenflockfilenoLOCK_EXLOCK_UNrIOError)r lock_pathrlock_fhs r/_locked_update_approvalsrs7 AHHNN4$N/ ahh01I } " !!#DJ 4  !  i 0 G GNN$emm4 !#DJ 4   GNN,emm<    ! W%    GNN,emm<W%    sAFD.F3E<9D/2D FDFD,)E<+D,,E</E912E$#E9$E6 3E95E6 6E99E<<FFcb|r$t||tjd||ytjj syt d|d|d tdjj}|dvr t||yy#ttf$r t YywxYw) zDecide whether to approve an unseen ``(event, command)`` pair. Returns ``True`` iff the approval was granted and recorded. zDshell hook auto-approved via --accept-hooks / env / config: %s -> %sTFuf ⚠ Hermes is about to register a shell hook that will run a command on your behalf. Event: z Command: zU Commands run with your full user credentials. Only approve commands you trust.zAllow this hook to run? [y/N]: >yyes) _record_approvalr*rJsysstdinisattyprintrr&rEOFErrorKeyboardInterrupt)rrrBanswers r/rQrQs (  w  99     wy!  !89??AGGI (  ' ( s'BB.-B.c:||tt|d}t5}|jdgDcgc]<}t |t r(|jd|k(r|jd|k(s|>c}|gz|d<dddycc}w#1swYyxYw)N)rr approved_atscript_mtime_at_approvalrrr) _utc_now_isoscript_mtime_isorrMr%rH)rrentryrrs r/r r s#~$4W$=  E " #txx R0 1d#EE'Ne+EE)$/  G[ sBAB 9 B BBctjtjj j ddS)Ntz+00:00Z)rnowrutc isoformatreplacer@r5r/rr s+ <<8<< ( 2 2 4 <   ' E>s0B-B (B BB) z.shz.bashz.zshz.fishz.pyz.pywz.rbz.plz.luaz.jsz.mjsz.cjsz.tszTuple[str, ...]_SCRIPT_EXTENSIONSc tj|}|s|S|D])}|jj t s'|cS|D]}d|vs|j ds|cS|dS#t$r|cYSwxYw)a4Return the script path from ``command`` for doctor / drift checks. Prefers a token ending in a known script extension, then a token containing ``/`` or leading ``~``, then the first token. Handles ``python3 /path/hook.py``, ``/usr/bin/env bash hook.sh``, and the common bare-path form. /~r)rrrrendswithr' startswith)rpartsparts r/_command_script_pathr/'s G$  ::< !3 4K $;$//#.K 8O sA.. A<;A<c4|rytjjddjj }|dvry|jdd}t |t r|St |tr |jj dvSy)aCombine all three opt-in channels into a single boolean. Precedence (any truthy source flips us on): 1. ``--accept-hooks`` flag (CLI) / explicit argument 2. ``HERMES_ACCEPT_HOOKS`` env var 3. ``hooks_auto_accept: true`` in ``cli-config.yaml`` THERMES_ACCEPT_HOOKSr>1onr truehooks_auto_acceptF)renvironrMr&rr%r9r)rWaccept_hooks_argenvcfg_vals r/rKrKBs **... 3 9 9 ; A A CC ((gg)51G'4 '3}}$$&*DDD r5ctjdgD]@}t|ts|jd|k(s)|jd|k(s>|cSy)z2Return the allowlist record for this pair, if any.rrrN)rrMr%rH)rrrs r/allowlist_entry_forr;]sV   ! !+r 2 q$ g%'i G+H  r5c<t|}|sy tjj|}t j tjj |tjjjddS#t$rYywxYw)zUISO-8601 mtime of the resolved script path, or ``None`` if the script is missing.Nrrr) r/rrrr fromtimestampgetmtimerrr r!r)rrexpandeds r/rris~  (D 77%%d+%% GG  X &8<< )+ggh, - sA>B BBct|}|sytjj|}tjj |sy t j |}t|xr|d|k(}|rtjntj}tj||S#t$rYywxYw)uReturn ``True`` iff ``command`` is runnable as configured. For a bare invocation (``/path/hook.sh``) the script itself must be executable. For interpreter-prefixed commands (``python3 /path/hook.py``, ``/usr/bin/env bash hook.sh``) the script just has to be readable — the interpreter doesn't care about the ``X_OK`` bit. Mirrors what ``_spawn`` would actually do at runtime.Fr) r/rrrisfilerrrr9X_OKR_OKaccess)rrr?ris_bare_invocationrequireds r/script_is_executablerGxs  (D ww!!$'H 77>>( #{{7#d7Q4,rww"''H 99Xx (( sB11 B=<B=ct|j|}t||}t|j|d|d<|S)uUFire a single shell-hook invocation with a synthetic payload. Used by ``hermes hooks test`` and ``hermes hooks doctor``. ``kwargs`` is the same dict that :func:`hermes_cli.plugins.invoke_hook` would pass at runtime. It is routed through :func:`_serialize_payload` so the synthetic stdin exactly matches what a real hook firing would produce — otherwise scripts tested via ``hermes hooks test`` could diverge silently from production behaviour. Returns the :func:`_spawn` diagnostic dict plus a ``parsed`` field holding the canonical Hermes-wire-shape response.rparsed)rrrr)r\rrrs r/run_oncerJs?$DJJ7J D* %F&tzz6(3CDF8 Mr5)rWrrBr9r7List[ShellHookSpec])rWrr7rKr6)rtr r7rK)rrrrryr r7zOptional[ShellHookSpec])r\rrrr7Dict[str, Any])r\rr7z'Callable[..., Optional[Dict[str, Any]]])rrrrLr7r)rr rr r7r)rrrrr7r)r7r )r7rL)rrLr7r8)rrrrr7r9)r7zIterator[Dict[str, Any]])rrrrrBr9r7r9)rrrrr7r8)r7r)rrr7r)rrr7r)rWrLr7r9r7r9)rrrrr7r)rrr7r)rrr7r9)r\rrrLr7rL)Rr= __future__rrlrloggingrr'rrr r threadingr contextlibr dataclassesrrrrpathlibr typingr r r r rrrrhermes_cli._subprocess_compatrrr ImportErrorhermes_constantsrrIr getLoggerr:r*r?rrrsetrr>LockrOrrr_rardrLrsrrrUrrrrrrrPrrQr rr&r'r/rKr;rrGrJr@r5r/rZs.gR#    %('LLLH-   8 $11475 08!9>>#' ( #)#) #)ZQ !QQ Qh02j@ @@!$@@NS9x)X@&K6z2  @B# ##/3# #L$L"'O6 +/ 6  ). !/] Es/E//E:9E: