eirUdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZddlmZmZddlmZmZddlmZddlmZmZmZmZmZmZmZmZ ddl Z n #e!$rdZ YnwxYwdd l"m#Z#ej$e%Z&d Z'd Z(d Z)e*Z+d e,d<e j-Z.e j-Z/eGddZ0dddJdZ1dKdZ2dLdZ3dMdZ4dNd&Z5hd'Z6dOd+Z7dPd-Z8dQd/Z9dRd1Z:dSd3Z;dTd4ZedWd:Z?dXd;Z@dYd<ZAdZd=ZBd[d>ZCd?ZDd@e,dA<d\dBZEd]dDZFd^dEZGd_dGZHd`dHZIdadIZJdS)bu# 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: ) annotationsN)contextmanager) dataclassfield)datetimetimezone)Path)AnyCallableDictIteratorListOptionalSetTuple)get_hermes_home<i,zshell-hooks-allowlist.jsonz#Set[Tuple[str, Optional[str], str]] _registeredcxeZdZUdZded<ded<dZded<eZded <edd Z d ed <ddZ ddZ dS) ShellHookSpeczAParsed and validated representation of a single ``hooks:`` entry.streventcommandN Optional[str]matcherinttimeoutF)defaultreprzOptional[re.Pattern]compiled_matcherreturnNonec\t|jtr$|j}|r|nd|_|jrf t j|j|_dS#tj$r3}t d|j|d|_Yd}~dSd}~wwxYwdS)NuFshell hook matcher %r is invalid (%s) — treating as literal equality) isinstancerrstriprecompiler errorloggerwarning)selfstrippedexcs 3/home/div/.hermes/hermes-agent/agent/shell_hooks.py __post_init__zShellHookSpec.__post_init__rs dlC ( ( :|))++H'/988TDL < - -(* 4<(@(@%%%8 - - -'(, c)-%%%%%%%  - - -sA''B)6(B$$B) tool_nameboolcx|jsdS|dS|j|j|duS||jkS)NTF)rr fullmatch)r+r0s r. matches_toolzShellHookSpec.matches_toolsP| 4  5  ,(229==TI IDL((r!r")r0rr!r1) __name__ __module__ __qualname____doc____annotations__rDEFAULT_TIMEOUT_SECONDSrrr r/r4r5r.rrhsKKJJJLLL!G!!!!*G****-2U4e-L-L-LLLLL----" ) ) ) ) ) )r5rF accept_hookscfgOptional[Dict[str, Any]]r?r1r!List[ShellHookSpec]c t|tsgSt||}t|d}|sgSg}ddlm}|}|D]}|j|j|j f}t5|tvr ddd5t|j|j } dddn #1swxYwY| sCt|j|j |s'td|j|j t5|tvr ddd|j|jgt'|t|||td|j|j |j|jdddn #1swxYwY|S)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. hooksr)get_plugin_managerNr>ushell 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$dict_resolve_effective_accept_parse_hooks_blockgethermes_cli.pluginsrErrr_registered_lockr_is_allowlisted_prompt_and_recordr)r*_hooks setdefaultappend_make_callbackaddinfor) r@r?effective_acceptspecs registeredrEmanagerspeckeyalready_allowlisteds r.register_from_configr[s* c4  0lCC swww// 0 0E  &(J655555  ""G z4<6  L Lk!! L L L L L L L#2$*dl"K"K  L L L L L L L L L L L L L L L # % DL7G 'J    k!!        N % %dj" 5 5 < <^D=Q=Q R R R OOC   d # # # KKK DL$,                    s1 B=B==C C  G+B!GG G ctt|tsgSt|dS)zReturn the parsed ``ShellHookSpec`` entries from config without registering anything. Used by ``hermes hooks list`` and ``doctor``.rD)r$rFrHrI)r@s r.iter_configured_hooksr]s5 c4  cggg.. / //r5r"cxt5tddddS#1swxYwYdS)z-Clear the idempotence set. Test-only helper.N)rKrclearr=r5r.reset_for_testsr`s~ s /33 hooks_cfgr c ddlm}t|tsgSg}|D]\}}||vrt jt||dd}|r#t d||dn >  ? '4((  NNEDMM2    (( # #FAs&z1c::D T""" # Lr5rrindexrrtOptional[ShellHookSpec]ct|ts1td||t |jdS|d}t|tr|std||dS|d}|3t|tstd||d}|$|dvr td||||d}|dt} t|}nA#ttf$r-td |||tt}YnwxYw|d kr)td ||tt}|tkr*td |||tt}t|||| S)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.rz?hooks.%s[%d].timeout must be an int (got %r); using default %dsrdz3hooks.%s[%d].timeout must be >=1; using default %dsz2hooks.%s[%d].timeout=%ds exceeds max %ds; clamping)rrrr)r$rFr)r*rmr7rIrr%r<r TypeError ValueErrorMAX_TIMEOUT_SECONDSr)rrurtrr timeout_rawrs r.roro s1 c4  I 5$s)),   tggi  G gs # #7==?? A 5   tggi  G:gs#;#; C 5   u,OOO E 5'5    '')%<==K*k"" z "*** M 5+'>   * *{{ A 51   *$$$ @ 5'#6   &      s/D??;E=<E=>argsr0 session_idparent_session_idrX stdin_jsonDict[str, Any]cddddddd} tjtj|j}n)#t $r}d|jd||d<|cYd}~Sd}~wwxYw|sd |d<|Stj} tj ||d |j d d }n#tj $r1d |d <ttj|z d |d<|cYSt$r d|d<|cYSt$r d|d<|cYSt $r}t#||d<|cYd}~Sd}~wwxYw|j|d<|jpd|d<|jpd|d<ttj|z d |d<|S)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 commandT)inputcapture_outputrtextshellrrzcommand not foundzcommand not executablerrr)shlexsplitospath expanduserrr|time monotonic subprocessrunrTimeoutExpiredroundFileNotFoundErrorPermissionError Exceptionrrrr)rXrresultargvr-t0procs r._spawnrjs F{27--dl;;<< MT\MMMMw  )w   B~ L      $"{$)$.*:*:R*?$C$C ! -w 2w c((w  ?F<{(bF8{(bF8 %dn&6&6&;Q ? ?F  MsM6A A( A#A(#A(B((=D2'D29D2 D2D-'D2-D2'Callable[..., Optional[Dict[str, Any]]]c\d fd }djdjd|_|j|_|S) z>Build the closure that ``invoke_hook()`` will call per firing.kwargsr r!rAc jdvr*|dsdStt j|}|dr/t djj|ddS|dr/t d|djjdS|d}|r/t d jj|dd |d d kr6t d |d jj|dd tj|dS)Nrxr0r(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) rr4rIr_serialize_payloadr)r*rr%debug_parse_response)rrrrXs r. _callbackz!_make_callback.._callbacksp :< < <$$VZZ %<%<== t 4+DJ?? @ @ W:  NN= DL!G*   4 [>  NNH#$dj$,   48""$$   LL= DL&#,    \?a   NNG,T\6$3$<   tz1X;777r5z shell_hook[:])rr r!rA)rrr7r9)rXrs` r.rQrQsU"8"8"8"8"8"8HDtzCCDLCCCI&/I r5rcd|D} ttj}n#t$rd}YnwxYw||dt |dtr|dnd|dp|dpd||d}tj |d t S) zrRender the stdin JSON payload. Unserialisable values are stringified via ``default=str`` rather than dropped.c,i|]\}}|tv||Sr=)_TOP_LEVEL_PAYLOAD_KEYS).0kvs r. z&_serialize_payload..s) R R Rtq!:Q1Q1Qa1Q1Q1Qr5rr0rNrr)hook_event_namer0 tool_inputrcwdextraF) ensure_asciir) rgrr rOSErrorrIr$rFjsondumps)rrextrasrpayloads r.rrsS Rv||~~ R R RF$(**oo !ZZ ,,,6vzz&7I7I4,P,PZfjj(((VZjj..W&**=P2Q2QWUW G :gE3 ? ? ??s A AArc |pd}|sdS tj|}n:#tj$r(td||ddYdSwxYwt |tsdS|dkr|ddkrH|dp|d pd}t |tr|rd|d S|d dkrH|d p|dpd}t |tr|rd|d SdS|d }t |tr|rd |iSdS) 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): %sryactionblockmessagereason)rrdecisioncontext) r%rloadsJSONDecodeErrorr)r*r$rFrIr)rrdatarrs r.rrs l ! ! # #F tz&!!   A 6$3$<   tt  dD ! !t  88H   ( (hhy))ETXXh-?-?E2G'3'' ?G ?")g>>> 88J  7 * *hhx((EDHHY,?,?E2G'3'' ?G ?")g>>>thhy!!G'3$GMMOO$7## 4s13A('A(r c.ttz S)z/Path to the per-user shell-hook allowlist file.)rALLOWLIST_FILENAMEr=r5r.allowlist_pathrs   1 11r5cJ tjt}n&#ttjt f$rdgicYSwxYwt|tsdgiS| d}t|tsg|d<|S)zz"_is_allowlisted..Nss  1d ( EE'NNe # ( EE)   'r5r)ranyrI)rrrs`` r.rLrLLs\   D +r**   r5Iterator[Dict[str, Any]]c#Kt}|jdd||jdz}t Bt 5t}|Vt|dddn #1swxYwYdSt|d5}t j | t j  t}|Vt|t j | t j n6#t j | t j wxYw ddddS#1swxYwYdS)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+)rrr with_suffixrfcntl_allowlist_write_lockrropenflockfilenoLOCK_EXLOCK_UN)r lock_pathrlock_fhs r._locked_update_approvalsrVs AHNN4$N/// ah011I } " ! !!##DJJJ 4  ! ! ! ! ! ! ! ! ! ! ! ! ! ! !  i  9' GNN$$em444 9!##DJJJ 4 K((%- 8 8 8 8EK((%- 8 8 8 8 8999999999999999999s<"BB  B #2E-!D)72E-)3EE--E14E1c|r.t||td||dStjsdSt d|d|d td }n&#ttf$rt YdSwxYw|dvrt||dSdS) 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)rSsysstdinisattyprintrr%lowerEOFErrorKeyboardInterrupt)rrr?answers r.rMrMus (((  w   t 9    u  ! ! !  ! ! !899??AAGGII ' ( uu(((t 5s(3BB?>B?cttd}t5}fd|dgD|gz|d<ddddS#1swxYwYdS)N)rr approved_atscript_mtime_at_approvalcg|]K}t|tr2|dkr|dkI|LS)rrrrs r. z$_record_approval..se   1d## EE'NNe++EE)$$// 0//r5r) _utc_now_isoscript_mtime_isorrI)rrentryrs`` r.rrs#~~$4W$=$=   E " # #t     xx R00   G[s+A))A-0A-ctjtjddS)Ntz+00:00Z)rnowrutc isoformatrr=r5r.rrs3 <8< ( ( ( 2 2 4 4 < .sL   q$'' ,-EE),<,<,G,G ,G,G,Gr5N)rlenrI)rrbeforeafters` r.revoker s " # #'tTXXk2..//    xx R00   [D%&& ''''''''''''''' E>sAA::A>A>) z.shz.bashz.zshz.fishz.pyz.pywz.rbz.plz.luaz.jsz.mjsz.cjsz.tszTuple[str, ...]_SCRIPT_EXTENSIONSc tj|}n#t$r|cYSwxYw|s|S|D]2}|t r|cS3|D]}d|vs|dr|cS |dS)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)rrr|rendswithr! startswith)rpartsparts r._command_script_pathr)s G$$   ::<< !3 4 4 KKK  $;;$//#..;KKK  8Os  &&accept_hooks_argc|rdStjdd}|dvrdS|dd}t |S)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)1trueronhooks_auto_acceptF)renvironrIr%rr1)r@r*envcfg_vals r.rGrGspt *... 3 3 9 9 ; ; A A C CC (((tgg)511G ==r5ctdgD]M}t|tr6|d|kr|d|kr|cSNdS)z2Return the allowlist record for this pair, if any.rrrN)rrIr$rF)rrrs r.allowlist_entry_forr5st    ! !+r 2 2 q$   g%''i  G++HHH 4r5rcPt|}|sdS tj|}t jtj|tj ddS#t$rYdSwxYw)zUISO-8601 mtime of the resolved script path, or ``None`` if the script is missing.Nrrr) r)rrrr fromtimestampgetmtimerrrrr)rrexpandeds r.rrs  ( (D t7%%d++% G  X & &8<   )++ggh,, - ttsBB B%$B%ct|}|sdStj|}tj|sdS t j|}n#t$rYdSwxYwt|o |d|k}|r tj n tj }tj ||S)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)rrrisfilerrr|r1X_OKR_OKaccess)rrr9ris_bare_invocationrequireds r.script_is_executablerAs  ( (D uw!!$''H 7>>( # #u{7## uud7Q4,9rww"'H 9Xx ( ((sA** A87A8ct|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)rXrrrs r.run_oncerD.sD$DJ77J D* % %F&tz6(3CDDF8 Mr5)r@rAr?r1r!rB)r@rAr!rBr6)rar r!rB)rrrurrtr r!rv)rXrrrr!r)rXrr!r)rrrrr!r)rrrrr!rA)r!r )r!r)rrr!r")rrrrr!r1)r!r)rrrrr?r1r!r1)rrrrr!r")r!r)rrr!r)rrr!r)r@rr*r1r!r1)rrrrr!rA)rrr!r)rrr!r1)rXrrrr!r)Kr: __future__rrhrloggingrr&rrrr threadingr contextlibr dataclassesrrrrpathlibr typingr r r r rrrrr ImportErrorhermes_constantsr getLoggerr7r)r<r}rsetrr;LockrKrrr[r]r`rHrorrrQrrrrrrLrrMrrr r!r)rGr5rrArDr=r5r.rQsH333j#"""""    %%%%%%((((((((''''''''LLLLLLLLLLLLLLLLLLLLLLLL EEE-,,,,,  8 $ $147355 8888!9>##' (( #)#)#)#)#)#)#) #)ZHHHHHHV0000----`@@@@NSRR7777t))))X@@@@&////l2222        @9999<####L$LLLL"'6.        )))).s'A,,A65A6