isUdZddlmZddlZddlZddlZddlZddlZddlZddl Z ddl Z ddl Z ddl Z ddl Z ddlmZddlmZmZddlmZmZddlmZddlmZmZmZmZmZmZmZmZ ddl Z n #e!$rdZ YnwxYwdd l"m#Z#dd l$m%Z%ej&e'Z(d Z)d Z*d Z+e,Z-de.d<e j/Z0e j/Z1eGddZ2dddKdZ3dLdZ4dMdZ5dNd Z6dOd'Z7hd(Z8dPd,Z9dQd.Z:dRd0Z;dSd2ZdVd7Z?dWd9Z@edXd;ZAdYd<ZBdZd=ZCd[d>ZDd\d?ZEd@ZFdAe.dB<d]dCZGd^dEZHd_dFZId`dHZJdadIZKdbdJZLdS)cu# 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)atomic_replace<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 6/home/ubuntu/.hermes/hermes-agent/agent/shell_hooks.py __post_init__zShellHookSpec.__post_init__ss dlC ( ( :|))++H'/988TDL < - -(* 4<(@(@%%%8 - - -'(, c)-%%%%%%%  - - -sA''B)6(B$$B) tool_nameboolcx|jsdS|dS|j|j|duS||jkS)NTF)rr! fullmatch)r,r1s r/ matches_toolzShellHookSpec.matches_toolsP| 4  5  ,(229==TI IDL((r"r#)r1rr"r2) __name__ __module__ __qualname____doc____annotations__rDEFAULT_TIMEOUT_SECONDSrrr!r0r5r6r/rrisKKJJJLLL!G!!!!*G****-2U4e-L-L-LLLLL----" ) ) ) ) ) )r6rF accept_hookscfgOptional[Dict[str, Any]]r@r2r"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.pluginsrFrrr_registered_lockr_is_allowlisted_prompt_and_recordr*r+_hooks setdefaultappend_make_callbackaddinfor) rAr@effective_acceptspecs registeredrFmanagerspeckeyalready_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``.rE)r%rGrIrJ)rAs r/iter_configured_hooksr^s5 c4  cggg.. / //r6r#cxt5tddddS#1swxYwYdS)z-Clear the idempotence set. Test-only helper.N)rLrclearr>r6r/reset_for_testsras~ s /33 hooks_cfgr c ddlm}t|tsgSg}|D]\}}||vrt jt||dd}|r#t d||dn >  ? '4((  NNEDMM2    (( # #FAs&z1c::D T""" # Lr6rrindexrruOptional[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 %dsrez3hooks.%s[%d].timeout must be >=1; using default %dsz2hooks.%s[%d].timeout=%ds exceeds max %ds; clamping)rrrr)r%rGr*r+rnr8rJrr&r=r TypeError ValueErrorMAX_TIMEOUT_SECONDSr)rrvrurr timeout_rawrs r/rprp!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=>argsr1 session_idparent_session_idrY 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)rYrresultargvr.t0procs r/_spawnrks 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"rBc 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)Nryr1r)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) rr5rJr_serialize_payloadr*r+rr&debug_parse_response)rrrrYs 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;777r6z shell_hook[:])rr r"rB)rrr8r:)rYrs` r/rRrRsU"8"8"8"8"8"8HDtzCCDLCCCI&/I r6rcd|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!:Q1Q1Qa1Q1Q1Qr6rr1rNrr)hook_event_namer1 tool_inputrcwdextraF) ensure_asciir) rhrr rOSErrorrJr%rGjsondumps)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): %srzactionblockmessagereason)rrdecisioncontext) r&rloadsJSONDecodeErrorr*r+r%rGrJr)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>r6r/allowlist_pathrs   1 11r6cJ tjt}n&#ttjt f$rdgicYSwxYwt|tsdgiS| d}t|tsg|d<|S)zz"_is_allowlisted..Oss  1d ( EE'NNe # ( EE)   'r6r)ranyrJ)rrrs`` r/rMrMMs\   D +r**   r6Iterator[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_approvalsrWs 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*rTsysstdinisattyprintrr&lowerEOFErrorKeyboardInterrupt)rrr@answers r/rNrNvs (((  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//r6r) _utc_now_isoscript_mtime_isorrJ)rrentryrs`` r/rrs#~~$4W$=$=   E " # #t     xx R00   G[s+A))A-0A-ctjtjddS)Ntz+00:00Z)rnowrutc isoformatreplacer>r6r/rrs3 <8< ( ( ( 2 2 4 4 < .sL   q$'' ,-EE),<,<,G,G ,G,G,Gr6N)rlenrJ)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_argcv|rdStjdd}|dvrdS|dd}t |t r|St |tr(|dvSdS)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)renvironrJr&rr%r2r)rAr+envcfg_vals r/rHrHst *... 3 3 9 9 ; ; A A C CC (((tgg)511G'4  '3E}}$$&&*DDD 5r6ctdgD]M}t|tr6|d|kr|d|kr|cSNdS)z2Return the allowlist record for this pair, if any.rrrN)rrJr%rG)rrrs r/allowlist_entry_forr6st    ! !+r 2 2 q$   g%''i  G++HHH 4r6rcPt|}|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/rr s  ( (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}r2X_OKR_OKaccess)rrr:ris_bare_invocationrequireds r/script_is_executablerBs  ( (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)rYrrrs r/run_oncerE3sD$DJ77J D* % %F&tz6(3CDDF8 Mr6)rArBr@r2r"rC)rArBr"rCr7)rbr r"rC)rrrvrrur r"rw)rYrrrr"r)rYrr"r)rrrrr"r)rrrrr"rB)r"r )r"r)rrr"r#)rrrrr"r2)r"r)rrrrr@r2r"r2)rrrrr"r#)r"r)rrr"r)rrr"r)rArr+r2r"r2)rrrrr"rB)rrr"r)rrr"r2)rYrrrr"r)Mr; __future__rrirloggingrr'rrrr threadingr contextlibr dataclassesrrrrpathlibr typingr r r r rrrrr ImportErrorhermes_constantsrutilsr getLoggerr8r*r=r~rsetrr<LockrLrrr\r^rarIrprrrRrrrrrrMrrNrrr!r"r*rHr6rrBrEr>r6r/rSsZ333j#"""""    %%%%%%((((((((''''''''LLLLLLLLLLLLLLLLLLLLLLLL EEE-,,,,,  8 $ $147355 8888!9>##' (( #)#)#)#)#)#)#) #)ZHHHHHHV0000----`@@@@NSRR7777t))))X@@@@&////l2222        @9999<####L$LLLL"'66        )))).s'A,,A65A6